niceeval 0.10.3-canary.6 → 0.11.0

package/src/runner/run.test.ts

@@ -1,8 +1,33 @@
 // cases: docs/engineering/testing/unit/experiments-runner.md
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { mkdtemp, rm } from "node:fs/promises";
+
+// 「取锁后重查携带」的读取面计数探针:两个 wrapper 都原样委派给真实实现,只在中间记一笔,
+// 因此对其余用例完全透明。工厂是惰性的——没有任何模块导入被 mock 的模块时它根本不执行,
+// 于是「派发路径上一次全树扫描都不做」这条断言的成本恒为零。
+const readSurfaceCalls = vi.hoisted(() => ({ forCase: 0, perEval: 0 }));
+vi.mock("../results/open.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../results/open.ts")>();
+  return {
+    ...actual,
+    loadLatestResultsForCase: (...args: Parameters<typeof actual.loadLatestResultsForCase>) => {
+      readSurfaceCalls.forCase += 1;
+      return actual.loadLatestResultsForCase(...args);
+    },
+  };
+});
+vi.mock("../view/data.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../view/data.ts")>();
+  return {
+    ...actual,
+    loadLatestResultsPerEval: (...args: Parameters<typeof actual.loadLatestResultsPerEval>) => {
+      readSurfaceCalls.perEval += 1;
+      return actual.loadLatestResultsPerEval(...args);
+    },
+  };
+});
+import { mkdtemp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { judgeProbeTargets, runEvals } from "./run.ts";
 import { defineSandbox, defineSandboxAgent } from "../define.ts";
@@ -19,9 +44,14 @@ import {
   type ExperimentProgressInput,
 } from "./feedback/sink.ts";
 import { drainExperimentTeardowns, pendingExperimentTeardownCount } from "./experiment-cleanup-registry.ts";
+import { computeFingerprint } from "./fingerprint.ts";
+import { locksDirOf, pendingHeldCaseLockCount, type CaseLockRecord } from "./lock.ts";
+import { pendingHeldGateLeaseCount } from "./gate-lease.ts";
+import { slugHashEntryId } from "../shared/entry-file-store.ts";
 import type { CapturedEvalSource } from "./eval-source.ts";
 import type { CarryPlan } from "./fingerprint.ts";
-import type { AgentRun, RunFeedbackPlan, RunOptions } from "./types.ts";
+import { ExperimentFatalError, EvalFatalError } from "../shared/failure-class.ts";
+import type { AgentRun, DiagnosticRecord, RunFeedbackPlan, RunFeedbackState, RunOptions } from "./types.ts";
 import type {
   Agent,
   CommandResult,
@@ -640,9 +670,10 @@ describe("runEvals · budget-exhausted 永久事件按每个被跳过的 attempt
       expect(diag?.count).toBe(3); // 三个 attempt 各发一次,去重折成同一个 key、count 累加到 3
       expect(diag?.data).toMatchObject({ experimentId, spent: 0, unstarted: 3 });
 
-      // reducer 不变量:每条 budget-exhausted 把一个 attempt 从 queued 挪进 completed
-      // (与 assembleInvocationCompletion() 读取 count 折算 InvocationCompletion.unstarted 的口径一致)。
-      expect(coordinator.state).toMatchObject({ total: 3, reused: 0, running: 0, queued: 0, completed: 3 });
+      // reducer 不变量:每条 budget-exhausted 把一个 attempt 从 queued 挪进 skipped —— 没派发就
+      // 没有 verdict,不冒充 passed/failed(与 assembleInvocationCompletion() 读取 count 折算
+      // InvocationCompletion.unstarted 的口径一致)。
+      expect(coordinator.state).toMatchObject({ total: 3, reused: 0, running: 0, queued: 0, passed: 0, failed: 0, errored: 0, skipped: 3 });
     });
   });
 });
@@ -792,8 +823,8 @@ describe("runEvals · 携入数量少于本次请求的 runs 时,差额必须真
       expect(matches[0]!.locator).toBe(staleLocator); // 携入结果原样透传
 
       // 不变量:携入 1 + early-exit 回填 2 == 本次请求的 runs:3,不留没有解释的差额
-      // (queued 必须真正归零,不能停在「还差 2 个不知道去哪」)。
-      expect(coordinator.state).toMatchObject({ total: 3, reused: 1, running: 0, queued: 0, completed: 2 });
+      // (queued 必须真正归零,不能停在「还差 2 个不知道去哪」)。回填的两轮没真跑,进 skipped。
+      expect(coordinator.state).toMatchObject({ total: 3, reused: 1, running: 0, queued: 0, passed: 0, failed: 0, errored: 0, skipped: 2 });
     });
   });
 
@@ -862,7 +893,8 @@ describe("runEvals · 携入数量少于本次请求的 runs 时,差额必须真
       expect(matches.map((r) => r.attempt).sort()).toEqual([0, 1, 2]);
       expect(matches.every((r) => r.verdict === "failed")).toBe(true);
 
-      expect(coordinator.state).toMatchObject({ total: 3, reused: 1, running: 0, queued: 0, completed: 2 });
+      // 差额两次真的跑了,各自落进 failed —— 携入那条的 verdict 留在 reused,不摊进结局项。
+      expect(coordinator.state).toMatchObject({ total: 3, reused: 1, running: 0, queued: 0, passed: 0, failed: 2, errored: 0, skipped: 0 });
       // InvocationSummary 的三条 failed（1 carry + 2 fresh）与终局 handoff 的 FailureNotice 清单同口径。
       // carry 不能只进 summary 计数而从 FAILURES / agent handoff 消失。
       expect(coordinator.state.failures).toHaveLength(3);
@@ -1168,6 +1200,7 @@ describe("runEvals · 实验级 setup/teardown", () => {
         progressEvents.push(input);
       },
       precheck() {},
+      lockWait() {},
       lifecycle() {},
     });
     try {
@@ -1414,6 +1447,7 @@ describe("runEvals · 强杀后的启动自愈(收尾登记的补执行)", () =>
       },
       experimentProgress() {},
       precheck() {},
+      lockWait() {},
       lifecycle() {},
     });
 
@@ -1538,6 +1572,7 @@ describe("runEvals · 强杀后的启动自愈(收尾登记的补执行)", () =>
       },
       experimentProgress() {},
       precheck() {},
+      lockWait() {},
       lifecycle() {},
     });
 
@@ -1599,6 +1634,7 @@ describe("runEvals · 强杀后的启动自愈(收尾登记的补执行)", () =>
       },
       experimentProgress() {},
       precheck() {},
+      lockWait() {},
       lifecycle() {},
     });
 
@@ -1978,3 +2014,2002 @@ describe("runEvals · 全局并发位在退避期间确实让给别的实验", (
     }
   });
 });
+
+// ═══════════════════════ 用例锁与并发 Invocation ═══════════════════════
+// 契约:docs/feature/experiments/architecture.md「并发 Invocation:用例锁」
+// 裁决出处:memory/case-lock-wait-not-skip-ruling.md(撞锁等待而非跳过、粒度是单条用例)
+// 覆盖规范:docs/engineering/testing/unit/experiments-runner.md「用例锁与并发 Invocation」
+//
+// 这里只覆盖 run.ts 对 lock.ts 的调度层接线:取锁时机(携带规划之后、preflight/实验级
+// setup 之前)、等待语义(不占位、elsewhere 计数)、释放后重查携带(carried/dispatched/
+// 部分携入)、执行模式组合(--force)、释放路径(即使合成 errored 结果也要放锁)。心跳续租 /
+// 过期判据 / 接管 rename 互斥等锁原语自身的机制由 lock.test.ts 覆盖,不在这里重复。
+
+function caseLockPath(root: string, experimentId: string, evalId: string): string {
+  // 必须与 lock.ts 私有的 caseLockEntryId 用完全相同的方式构造,否则读写的不是同一个文件。
+  const id = slugHashEntryId(`${experimentId}-${evalId}`, [experimentId, evalId]);
+  return join(locksDirOf(root), `${id}.json`);
+}
+
+/** 直接写一条锁记录,绕开 acquireCaseLock —— 模拟"另一个进程持有/曾经持有这把锁";心跳
+ *  完全由测试摆布,不会被本进程续租,陈旧与否只取决于种下的 heartbeatAt,不依赖真实时间流逝。 */
+async function seedCaseLock(root: string, record: CaseLockRecord): Promise<void> {
+  const dir = locksDirOf(root);
+  await mkdir(dir, { recursive: true });
+  await writeFile(caseLockPath(root, record.experimentId, record.evalId), JSON.stringify(record, null, 2), "utf-8");
+}
+
+function freshLockRecord(experimentId: string, evalId: string, overrides: Partial<CaseLockRecord> = {}): CaseLockRecord {
+  const now = new Date().toISOString();
+  return { experimentId, evalId, pid: 999_111, host: "other-host", startedAt: now, heartbeatAt: now, ...overrides };
+}
+
+function staleLockRecord(experimentId: string, evalId: string, overrides: Partial<CaseLockRecord> = {}): CaseLockRecord {
+  // 落后 CASE_LOCK_STALE_MS(30_000ms)以上 —— 稳稳越过判死边界(严格 `>`,不是 `>=`)。
+  const staleHeartbeat = new Date(Date.now() - 40_000).toISOString();
+  return { experimentId, evalId, pid: 999_222, host: "dead-host", startedAt: staleHeartbeat, heartbeatAt: staleHeartbeat, ...overrides };
+}
+
+/** 共享的 run() helper 不透传 priorResults;用例锁"释放后重查携带"分支专门按
+ *  RunOptions.priorResults 是否为 undefined 分支(force 模式整段跳过重查,见 cli.ts 的
+ *  `flags.force ? undefined : ...`),需要直接控场,故另建一个不影响其它测试的 helper。 */
+async function runWithPriorResults(
+  evals: DiscoveredEval[],
+  agentRuns: AgentRun[],
+  opts: { priorResults?: EvalResult[]; root?: string; signal?: AbortSignal; maxConcurrency?: number } = {},
+): Promise<{ summary: InvocationSummary; root: string }> {
+  const root = opts.root ?? (await makeRoot());
+  const config: Config = {};
+  const runOpts: RunOptions = {
+    config,
+    evals,
+    agentRuns,
+    reporters: [{ reporter: Artifacts(root), name: "artifacts", required: false }],
+    maxConcurrency: opts.maxConcurrency ?? 3,
+    niceevalRoot: root,
+    ...(opts.priorResults !== undefined ? { priorResults: opts.priorResults } : {}),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  };
+  const summary = await runEvals(runOpts);
+  return { summary, root };
+}
+
+async function lockFilesRemaining(root: string): Promise<string[]> {
+  try {
+    return await readdir(locksDirOf(root));
+  } catch {
+    return [];
+  }
+}
+
+/** 锁目录里此刻被哪几条用例持有(条目文件名映回 evalId,按 `candidates` 的给定顺序返回)。
+ *  多开场景的分段点是「对方已经放手」,而这件事只在磁盘上可观测:对方的 attempt 跑完(探针
+ *  记到 started / inFlight 归零)只说明 test() 返回了,锁要到该用例全部 attempt 收尾之后才删。 */
+async function lockedEvalIds(root: string, experimentId: string, candidates: string[]): Promise<string[]> {
+  const files = new Set(await lockFilesRemaining(root));
+  return candidates.filter((id) => files.has(basename(caseLockPath(root, experimentId, id))));
+}
+
+/** 等一个要读磁盘的判据在假时钟上成立。推法与 `advanceOnFakeClock` 的收尾段相同(只喂真实
+ *  轮次、每轮顺手推 1ms 假时钟接住收尾链上的短定时器),但把虚拟时间的消耗压到最低:等待
+ *  期间本进程自己也持着锁,推过 30s 判死线会被对方当成过期锁接管,场景就变了。 */
+async function awaitDiskOnFakeClock(isDone: () => Promise<boolean>, budgetRealMs = 20_000): Promise<void> {
+  const until = realDateNow() + budgetRealMs;
+  while (realDateNow() < until) {
+    if (await isDone()) return;
+    await vi.advanceTimersByTimeAsync(1);
+    await new Promise<void>((resolve) => realSetTimeout(resolve, 5));
+  }
+}
+
+/** 模块装载期抓住的真实 setTimeout / Date.now:`vi.useFakeTimers()` 换掉的是全局绑定,
+ *  这两个函数引用仍指向原生实现,假时钟场景里用它们换真实的宏任务轮次与真实墙钟。 */
+const realSetTimeout = globalThis.setTimeout;
+const realDateNow = Date.now;
+
+/** 把真实事件循环喂到 `isDone()` 成立或真实墙钟预算用完为止。 */
+async function realTicksFor(isDone: () => boolean, budgetMs: number): Promise<void> {
+  const until = realDateNow() + budgetMs;
+  while (!isDone() && realDateNow() < until) {
+    await new Promise<void>((resolve) => realSetTimeout(resolve, 0));
+  }
+}
+
+/**
+ * 假时钟上跨过一段等待窗口(用例锁的 30s 判死线、锁与租约的 10s 轮询周期)的唯一可靠姿势。
+ *
+ * 两条都要满足,少一条就 flaky:
+ * - **分步推,不一步推到底**:轮询链路每一轮都在"定时器回调恢复"和"注册下一轮定时器"之间
+ *   插了真实磁盘 I/O(`readEntryFile` / `claimEntryFile` / `createLockFileExclusive`)。
+ *   `advanceTimersByTimeAsync` 只推进*当前已挂起*的定时器,一次推过整个 30s 窗口会在"看不到
+ *   待处理定时器"的那一刻直接返回,把稍后才补挂上的定时器永远晾着(测试挂到超时,不是变慢)。
+ * - **每步之间按真实墙钟让出宏任务轮次**:`advanceTimersByTimeAsync` 只喂微任务,真实磁盘
+ *   I/O 拿不到轮次就会被饿死。让出的量必须按真实墙钟算而不是固定圈数——并行跑整个测试套件
+ *   时 I/O 慢一个量级,固定圈数在本机够、在负载下必然不够(本条就是这么被抓出来的)。
+ *
+ * 踩坑同源:memory/case-lock-gate-reorders-global-semaphore-queue.md「旁支」。
+ */
+async function advanceOnFakeClock(
+  isDone: () => boolean,
+  stepMs = 10_000,
+  maxSteps = 8,
+  perStepRealMs = 300,
+  tailRealMs = 15_000,
+): Promise<void> {
+  for (let i = 0; i < maxSteps && !isDone(); i++) {
+    await vi.advanceTimersByTimeAsync(stepMs);
+    await realTicksFor(isDone, perStepRealMs);
+  }
+  // 要跨的虚拟窗口到这里都跨过了,剩下的是纯真实 I/O 的收尾进度(取锁、跑 attempt、落盘、
+  // 放锁)。只喂真实轮次,每轮顺手推 1ms 假时钟接住收尾链上可能挂的短定时器——步长必须小,
+  // 否则慢机器上轮数一多会把 attempt 的外层超时也推过去。
+  const until = realDateNow() + tailRealMs;
+  while (!isDone() && realDateNow() < until) {
+    await vi.advanceTimersByTimeAsync(1);
+    await realTicksFor(isDone, 20);
+  }
+}
+
+describe("runEvals · 用例锁: 取锁时机", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("全部 attempt 都可携带的用例不取锁,不真的派发", async () => {
+    const experimentId = "lock-timing-full-carry-exp";
+    const evalId = "carried-eval";
+    const evalDef = makeEval(evalId, () => {
+      throw new Error("carried attempt must not be dispatched");
+    });
+    const agentRun: AgentRun = {
+      agent: makeAgent("agent-lock-timing-carry"),
+      flags: {},
+      runs: 1,
+      earlyExit: true,
+      sandbox: fakeSandboxSpec(),
+      timeoutMs: 5_000,
+      selectedEvalIds: [evalId],
+      experimentId,
+    };
+    // 指纹依赖 evalDef.sourcePath 的文件内容(makeEval 统一指向本测试文件)与 run 的配置字段,
+    // 不依赖 test() 闭包本身 —— 用真实的 computeFingerprint 算,而不是随便编一个字符串,
+    // 才能真的驱动到"指纹匹配"这条携带路径。
+    const fingerprint = await computeFingerprint(evalDef, agentRun);
+    const prior: EvalResult = {
+      id: evalId,
+      experimentId,
+      agent: agentRun.agent.name,
+      verdict: "passed",
+      attempt: 0,
+      fingerprint,
+      startedAt: new Date().toISOString(),
+      durationMs: 1,
+      assertions: [],
+    };
+
+    const { summary, root } = await runWithPriorResults([evalDef], [agentRun], { priorResults: [prior] });
+
+    expect(summary.results).toHaveLength(1);
+    expect(summary.results[0]!.verdict).toBe("passed");
+    // 被静态携带规划筛掉的 (experimentId, evalId) 组合从不出现在 attempts[] 里,天然不会
+    // 走到取锁那一步 —— 磁盘上不该留下任何锁文件。
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  });
+
+  it("等锁用例不触发实验级 setup:等待期间 setup 计数保持 0,接管后才恰好执行一次", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "lock-timing-setup-exp";
+      const evalId = "setup-gated-eval";
+      await seedCaseLock(root, freshLockRecord(experimentId, evalId));
+
+      let setupCalls = 0;
+      let testCalls = 0;
+      const evalDef = makeEval(evalId, () => {
+        testCalls += 1;
+      });
+      const agentRun: AgentRun = {
+        agent: makeAgent("agent-lock-timing-setup"),
+        flags: {},
+        runs: 1,
+        earlyExit: false,
+        sandbox: fakeSandboxSpec(),
+        timeoutMs: 30_000,
+        selectedEvalIds: [evalId],
+        experimentId,
+        setup: () => {
+          setupCalls += 1;
+        },
+      };
+
+      const runPromise = runWithPriorResults([evalDef], [agentRun], { priorResults: [], root });
+
+      // 等到轮询真的挂起下一次心跳定时器(真实磁盘 I/O 已经跑过一轮),此刻还远没到 30s
+      // 判死线:setup 不该被触发,eval 也不该被派发。
+      await vi.waitFor(() => expect(vi.getTimerCount()).toBeGreaterThanOrEqual(1));
+      expect(setupCalls).toBe(0);
+      expect(testCalls).toBe(0);
+      await vi.advanceTimersByTimeAsync(10_000); // 再推一个心跳周期,仍然远短于判死线
+      await vi.waitFor(() => expect(vi.getTimerCount()).toBeGreaterThanOrEqual(1));
+      expect(setupCalls).toBe(0);
+
+      // 继续推过判死线,接管发生 —— setup 此刻才第一次执行。
+      await advanceOnFakeClock(() => setupCalls === 1);
+      expect(setupCalls).toBe(1);
+
+      const { summary } = await runPromise;
+      expect(summary.results).toHaveLength(1);
+      expect(summary.results[0]!.verdict).toBe("passed");
+      expect(setupCalls).toBe(1);
+      expect(testCalls).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("runEvals · 用例锁: 等待语义", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("撞新鲜锁的用例不派发、不占全局并发位;elsewhere/queued 五项恒等式成立;过期后接管并真实派发(无匹配可携带)", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "lock-wait-exp";
+      const evalIdLocked = "locked-eval";
+      const evalIdFree = "free-eval";
+      await seedCaseLock(root, freshLockRecord(experimentId, evalIdLocked));
+
+      let lockedCalls = 0;
+      let freeCalls = 0;
+      const evalLocked = makeEval(evalIdLocked, () => {
+        lockedCalls += 1;
+      });
+      const evalFree = makeEval(evalIdFree, () => {
+        freeCalls += 1;
+      });
+      const agentRun: AgentRun = {
+        agent: makeAgent("agent-lock-wait"),
+        flags: {},
+        runs: 1,
+        earlyExit: false,
+        sandbox: fakeSandboxSpec(),
+        timeoutMs: 30_000,
+        selectedEvalIds: [evalIdLocked, evalIdFree],
+        experimentId,
+      };
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 2, configs: 1, totalAttempts: 2, maxConcurrency: 1 },
+        reused: 0,
+        reusedFailures: [],
+      };
+
+      await withCoordinator(plan, async (coordinator) => {
+        // maxConcurrency: 1(全局唯一名额)——只有在名额紧张到只有一个的情况下,free-eval
+        // 仍能跑完,才证明 locked-eval 的等待确实没有占着这个唯一的全局位;宽松并发会掩盖这一点。
+        const runPromise = runWithPriorResults([evalLocked, evalFree], [agentRun], {
+          priorResults: [],
+          root,
+          maxConcurrency: 1,
+        });
+
+        await vi.waitFor(() => expect(freeCalls).toBe(1));
+        expect(lockedCalls).toBe(0); // 撞锁的用例仍未派发
+        expect(coordinator.state.lockWaits.get(experimentId)?.waiting.has(evalIdLocked)).toBe(true);
+        expect(coordinator.state.elsewhere).toBeGreaterThanOrEqual(1);
+        const mid = coordinator.state;
+        expectCountIdentity(mid);
+
+        // 推过 30s 判死线:种下的心跳没有任何进程真的在续租,过期后必须被接管。
+        // 分步推 + 每步让出真实事件循环,理由见 advanceOnFakeClock 注释。
+        await advanceOnFakeClock(() => lockedCalls === 1);
+        expect(lockedCalls).toBe(1); // 确认真的走到了"接管后派发",不是轮询步数耗尽仍未接管
+
+        const { summary } = await runPromise;
+        expect(summary.results).toHaveLength(2);
+        expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+        expect(coordinator.state.elsewhere).toBe(0);
+        expect(await lockFilesRemaining(root)).toEqual([]);
+        expect(
+          coordinator.state.diagnostics.some((d) => d.key === `lock-taken-over:${experimentId}|${evalIdLocked}`),
+        ).toBe(true);
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("runEvals · 用例锁: 释放后续接", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("指纹匹配携入(carried):产出方落盘终态后来不及释放锁就死掉,续接方接管后直接携入、不重新派发", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-release-carry-exp";
+    const evalId = "carry-release-eval";
+    const producerRun: AgentRun = {
+      agent: makeAgent("agent-lock-release-carry"),
+      flags: {},
+      runs: 1,
+      earlyExit: true,
+      sandbox: fakeSandboxSpec(),
+      timeoutMs: 5_000,
+      selectedEvalIds: [evalId],
+      experimentId,
+    };
+    const producerEval = makeEval(evalId, () => {});
+    // 用真实 run() 走一遍完整调度,把一条正确 fingerprint 的终态结果落到 root 上 ——
+    // 比手工拼 EvalResult 更省事也更可信(fingerprint / artifactBase 这些字段很容易拼错)。
+    const { summary: producerSummary } = await run([producerEval], [producerRun], { root });
+    expect(producerSummary.results[0]!.verdict).toBe("passed");
+
+    // 模拟"产出方刚写完结果、还没来得及释放锁就被强杀":种一把过期锁,而不是等它自然释放。
+    await seedCaseLock(root, staleLockRecord(experimentId, evalId));
+
+    const subjectEval = makeEval(evalId, () => {
+      throw new Error("carried attempt must not be redispatched");
+    });
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 1, configs: 1, totalAttempts: 1, maxConcurrency: 3 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const { summary } = await runWithPriorResults([subjectEval], [producerRun], {
+        priorResults: [],
+        root,
+      });
+
+      expect(summary.results).toHaveLength(1);
+      expect(summary.results[0]!.verdict).toBe("passed");
+      expect(coordinator.state.reused).toBe(1);
+      expect(coordinator.state.elsewhere).toBe(0);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  });
+
+  it("不匹配转自跑(dispatched):磁盘上没有任何终态结果时,接管过期锁后真实派发", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-release-dispatch-exp";
+    const evalId = "dispatch-release-eval";
+    await seedCaseLock(root, staleLockRecord(experimentId, evalId));
+
+    let calls = 0;
+    const evalDef = makeEval(evalId, () => {
+      calls += 1;
+    });
+    const agentRun: AgentRun = {
+      agent: makeAgent("agent-lock-release-dispatch"),
+      flags: {},
+      runs: 1,
+      earlyExit: true,
+      sandbox: fakeSandboxSpec(),
+      timeoutMs: 5_000,
+      selectedEvalIds: [evalId],
+      experimentId,
+    };
+
+    const { summary } = await runWithPriorResults([evalDef], [agentRun], { priorResults: [], root });
+
+    expect(calls).toBe(1);
+    expect(summary.results).toHaveLength(1);
+    expect(summary.results[0]!.verdict).toBe("passed");
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  });
+
+  it("runs 部分携入部分补跑:已有 1 条终态时,续接方 runs:2 只补差额序号,不重跑已携入的序号", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-release-partial-exp";
+    const evalId = "partial-release-eval";
+    const producerRun: AgentRun = {
+      agent: makeAgent("agent-lock-release-partial"),
+      flags: {},
+      runs: 1,
+      earlyExit: false,
+      sandbox: fakeSandboxSpec(),
+      timeoutMs: 5_000,
+      selectedEvalIds: [evalId],
+      experimentId,
+    };
+    const producerEval = makeEval(evalId, () => {});
+    const { summary: producerSummary } = await run([producerEval], [producerRun], { root });
+    expect(producerSummary.results[0]!.verdict).toBe("passed");
+
+    await seedCaseLock(root, staleLockRecord(experimentId, evalId));
+
+    let calls = 0;
+    const subjectEval = makeEval(evalId, () => {
+      calls += 1;
+    });
+    // earlyExit: false —— 携入的 passed 会预置进 passedKeys(见 run.ts 对 lateCarriedResults
+    // 的处理),开着 earlyExit 会让差额序号也被当成"已知会通过"提前省略,测不出"差额真的被
+    // 重新派发"这件事本身。
+    const subjectRun: AgentRun = { ...producerRun, runs: 2, earlyExit: false };
+
+    const { summary } = await runWithPriorResults([subjectEval], [subjectRun], { priorResults: [], root });
+
+    expect(calls).toBe(1); // 只有差额(序号 1)真的跑了一次,序号 0 被携入、没有重跑
+    const results = summary.results.filter((r) => r.id === evalId);
+    expect(results).toHaveLength(2);
+    expect(results.every((r) => r.verdict === "passed")).toBe(true);
+    expect(results.map((r) => r.attempt).sort()).toEqual([0, 1]);
+  });
+});
+
+describe("runEvals · 用例锁: 执行模式组合", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("--force(RunOptions.priorResults 为 undefined)下,等待/接管后不消费携带 —— 即使指纹匹配的终态结果确实存在,也全部自跑", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-force-exp";
+    const evalId = "force-eval";
+    const producerRun: AgentRun = {
+      agent: makeAgent("agent-lock-force"),
+      flags: {},
+      runs: 1,
+      earlyExit: true,
+      sandbox: fakeSandboxSpec(),
+      timeoutMs: 5_000,
+      selectedEvalIds: [evalId],
+      experimentId,
+    };
+    const producerEval = makeEval(evalId, () => {});
+    const { summary: producerSummary } = await run([producerEval], [producerRun], { root });
+    expect(producerSummary.results[0]!.verdict).toBe("passed");
+
+    await seedCaseLock(root, staleLockRecord(experimentId, evalId));
+
+    let calls = 0;
+    const subjectEval = makeEval(evalId, () => {
+      calls += 1;
+    });
+
+    // force 模式:cli.ts 在 --force 时整段不传 priorResults(不是传空数组) —— 这里同样
+    // 省略 priorResults 字段,而不是传 []。
+    const { summary } = await runWithPriorResults([subjectEval], [producerRun], { root });
+
+    expect(calls).toBe(1); // 真正重新派发了一次,不是悄悄吞成携入的旧结果
+    expect(summary.results).toHaveLength(1);
+    expect(summary.results[0]!.verdict).toBe("passed");
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  });
+});
+
+describe("runEvals · 用例锁: 释放路径", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("实验级 setup 抛错、全部 attempt 合成 errored 结果时,锁仍必须被释放", async () => {
+    const experimentId = "lock-setup-fail-exp";
+    const evalId = "setup-fail-eval";
+    const evalDef = makeEval(evalId, () => {});
+    const agentRun: AgentRun = {
+      agent: makeAgent("agent-lock-setup-fail"),
+      flags: {},
+      runs: 1,
+      earlyExit: true,
+      sandbox: fakeSandboxSpec(),
+      timeoutMs: 5_000,
+      selectedEvalIds: [evalId],
+      experimentId,
+      setup: () => {
+        throw new Error("tunnel refused to start");
+      },
+    };
+
+    // 无竞争的全新取锁(没有种任何锁),证明即便本实验一个 attempt 都没有真正派发过 agent
+    // (body 走的是合成 errored 的分支),外层 Effect.ensuring 挂的用例锁释放仍然会触发。
+    const { summary, root } = await runWithPriorResults([evalDef], [agentRun], {});
+
+    expect(summary.results).toHaveLength(1);
+    expect(summary.results[0]!.verdict).toBe("errored");
+    expect(summary.results[0]!.error?.code).toBe("experiment-setup-failed");
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  });
+});
+
+// ─────────────────── 派发探针:「在飞峰值」与「启动集合」的统一观察面 ───────────────────
+// 覆盖规范对用例锁调度的断言面是可观察的调度事实(锁目录条目数、在飞峰值、启动集合),
+// 不是内部信号量的调用次数。下面这组用例统一用「eval 的 test() 里登记自己被真实派发、
+// 然后挂在 barrier 上」取样:barrier 没释放前,「此刻在飞几条」「谁被派发过」在任何时刻
+// 都可读,且被派发两次的用例会在 started 里出现两次(双跑当场可见)。
+
+interface DispatchProbe {
+  /** 真实执行过 test() 的 evalId,按进入顺序;同一个 id 出现两次 = 这条用例被双跑了。 */
+  started: string[];
+  inFlight: number;
+  peak: number;
+}
+
+function newDispatchProbe(): DispatchProbe {
+  return { started: [], inFlight: 0, peak: 0 };
+}
+
+/** 一条挂在 `barrier` 上的 eval:进入 test() 即计入 `probes` 里的每个探针(多开场景要同时
+ *  记进「本侧」与「全局」两个探针),barrier 释放后立刻返回。 */
+function gatedEval(id: string, barrier: Promise<void>, ...probes: DispatchProbe[]): DiscoveredEval {
+  return makeEval(id, async () => {
+    for (const p of probes) {
+      p.started.push(id);
+      p.inFlight += 1;
+      p.peak = Math.max(p.peak, p.inFlight);
+    }
+    await barrier;
+    for (const p of probes) p.inFlight -= 1;
+  });
+}
+
+function makeBarrier(): { barrier: Promise<void>; release: () => void } {
+  let release!: () => void;
+  const barrier = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { barrier, release };
+}
+
+/** 派发探针场景统一用的 AgentRun 骨架:timeoutMs 开得远大于测试里推进的假时钟总量,
+ *  免得「推过锁的 30s 判死线」顺带把在飞 attempt 推成外层超时。 */
+function probeRun(
+  agent: Agent,
+  experimentId: string,
+  selectedEvalIds: string[],
+  extra: Partial<AgentRun> = {},
+): AgentRun {
+  return {
+    agent,
+    flags: {},
+    runs: 1,
+    earlyExit: false,
+    sandbox: fakeSandboxSpec(),
+    timeoutMs: 600_000,
+    selectedEvalIds,
+    experimentId,
+    ...extra,
+  };
+}
+
+/** 等一个只靠真实事件循环就会成立的条件(不需要推假时钟:撞锁挂起、attempt 起跑这些都发生
+ *  在当下)。`vi.waitFor` 只让出真实轮次、**不推假时钟** —— 需要跨虚拟等待窗口的地方一律用
+ *  `advanceOnFakeClock`。真实超时放宽到 30s:并行跑整个测试套件时默认 1s 不够。 */
+async function waitForRealProgress(check: () => void): Promise<void> {
+  await vi.waitFor(check, { timeout: 30_000, interval: 20 });
+}
+
+/** 这组调度用例的 vitest 超时:要么在假时钟上跨 30s 锁判死线 / 10s 租约轮询周期(靠真实
+ *  轮次驱动),要么等两条 runEvals 真的并行推进;并行跑整个测试套件时真实墙钟开销远大于默认 5s。 */
+const SCHEDULING_TEST_TIMEOUT_MS = 60_000;
+
+describe("runEvals · 用例锁: 排队用例不持锁", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("四条用例、全局并发 2:锁目录条目数等于在跑用例数(排队的两条不持锁),收尾后清空", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-queue-exp";
+    const ids = ["q-a", "q-b", "q-c", "q-d"];
+    const { barrier, release } = makeBarrier();
+    const probe = newDispatchProbe();
+    const evals = ids.map((id) => gatedEval(id, barrier, probe));
+    const agentRun = probeRun(makeAgent("agent-lock-queue"), experimentId, ids);
+
+    const runPromise = runWithPriorResults(evals, [agentRun], { priorResults: [], root, maxConcurrency: 2 });
+    try {
+      await waitForRealProgress(() => expect(probe.inFlight).toBe(2));
+
+      // 关键断言:计划里有 4 条,此刻只有 2 条在跑 —— 锁目录也只有 2 条。取锁发生在派发时刻,
+      // 排队中的两条还没摸过锁目录(旧的「计划期一次性全量取锁」在这里会是 4)。
+      expect(await lockFilesRemaining(root)).toHaveLength(2);
+      expect(probe.started).toHaveLength(2);
+    } finally {
+      release();
+    }
+
+    const { summary } = await runPromise;
+    expect(summary.results).toHaveLength(4);
+    expect([...probe.started].sort()).toEqual([...ids].sort());
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: 撞锁转派", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("撞新鲜锁的用例让出全局位,位子转派给下一条没被锁的用例:在飞峰值仍等于全局上限,启动集合是未被锁的那些", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "lock-handoff-exp";
+      const lockedId = "h-locked";
+      const freeIds = ["h-free-1", "h-free-2"];
+      // 被锁的那条排在数组第一位:它一定会先摸到全局位,证明「转派」不是靠运气排在后面。
+      await seedCaseLock(root, freshLockRecord(experimentId, lockedId));
+
+      const { barrier, release } = makeBarrier();
+      const probe = newDispatchProbe();
+      const evals = [lockedId, ...freeIds].map((id) => gatedEval(id, barrier, probe));
+      const agentRun = probeRun(makeAgent("agent-lock-handoff"), experimentId, [lockedId, ...freeIds]);
+
+      let done = false;
+      const runPromise = runWithPriorResults(evals, [agentRun], {
+        priorResults: [],
+        root,
+        maxConcurrency: 2,
+      }).then((r) => {
+        done = true;
+        return r;
+      });
+      try {
+        await waitForRealProgress(() => expect(probe.inFlight).toBe(2));
+
+        // 峰值没有因为一条撞锁就塌成 1:让出来的位子当场被下一条没被锁的用例接手。
+        expect(probe.peak).toBe(2);
+        expect([...probe.started].sort()).toEqual([...freeIds].sort());
+        expect(probe.started).not.toContain(lockedId);
+      } finally {
+        release();
+      }
+
+      // 种下的心跳没人续租,推过 30s 判死线后被接管,这条用例照常补跑。
+      await advanceOnFakeClock(() => done, 10_000, 12);
+      expect(probe.started).toContain(lockedId);
+
+      const { summary } = await runPromise;
+      expect(summary.results).toHaveLength(3);
+      expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: 多开分工", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 两条 runEvals 共用同一个 niceevalRoot(不是各自建一个临时根 —— 那测的是"零竞争各自跑"),
+  // 选择集完全相同:四条用例两边都选,各自全局上限 2,于是两边都必然剩下"第一波没抢到位"的
+  // 第二波。谁跑哪些完全由锁自然分工,不靠测试摆布。
+  //
+  // 两段 barrier 是这条用例的关键:B 的第一波必须先真正收尾、把锁删掉,A 的第二波才会撞上
+  // 一把**空**锁 —— 那正是要钉的路径(取到锁没等过、没接管过,重查携带仍必须发生)。锁的删除
+  // 发生在该用例全部 attempt 收尾之后,所以分段点只能取"锁目录掉回只剩 A 手上的那两条",不能
+  // 取"B 的 test() 跑过了":放早了 A 的第二波撞的是新鲜锁、走挂起窗口,而挂起窗口本来就重查,
+  // 这条用例会绿得毫无意义(见 memory/multi-open-residual-window-closed-by-narrow-read.md)。
+  //
+  // 顺带钉住「携带来源不要求快照收尾」:A 的第二波携入 B 的结果时,B 整批还没跑完(它的两条
+  // 正挂在 A 的锁上等),快照 snapshot.json 尚无 completedAt。
+  it("两条 runEvals 同 root、选择集完全相同:真实派发的用例集不相交、并集覆盖选择集、全局在飞峰值达到两边上限之和,每条用例全局只被真实派发一次", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "multi-open-exp";
+      const firstWave = ["m-1", "m-2"];
+      const secondWave = ["m-3", "m-4"];
+      const ids = [...firstWave, ...secondWave];
+      const agent = makeAgent("agent-multi-open");
+      const sandbox = fakeSandboxSpec();
+
+      const gateA = makeBarrier();
+      const gateB = makeBarrier();
+      const all = newDispatchProbe();
+      const sideA = newDispatchProbe();
+      const sideB = newDispatchProbe();
+      const evalsA = ids.map((id) => gatedEval(id, gateA.barrier, sideA, all));
+      const evalsB = ids.map((id) => gatedEval(id, gateB.barrier, sideB, all));
+      // 指纹只吃 (eval 源码 + experimentId/agent/model/flags/sandbox/strict),不吃 selectedEvalIds
+      // 与 runs —— 两侧指纹相同,携入对方跑出来的那半边才可能发生。
+      const runA = probeRun(agent, experimentId, ids, { sandbox });
+      const runB = probeRun(agent, experimentId, ids, { sandbox });
+
+      let aDone = false;
+      let bDone = false;
+      const pa = runWithPriorResults(evalsA, [runA], { priorResults: [], root, maxConcurrency: 2 }).then((r) => {
+        aDone = true;
+        return r;
+      });
+      await waitForRealProgress(() => expect(sideA.inFlight).toBe(2));
+
+      const pb = runWithPriorResults(evalsB, [runB], { priorResults: [], root, maxConcurrency: 2 }).then((r) => {
+        bDone = true;
+        return r;
+      });
+      await waitForRealProgress(() => expect(sideB.inFlight).toBe(2));
+
+      // ① 两边真实派发的用例集不相交;② 并集覆盖选择集;③ 全局在飞峰值 = 2 + 2。
+      expect([...sideA.started].sort()).toEqual([...firstWave]);
+      expect([...sideB.started].sort()).toEqual([...secondWave]);
+      expect(sideA.started.filter((id) => sideB.started.includes(id))).toEqual([]);
+      expect(all.peak).toBe(4);
+      expect(await lockedEvalIds(root, experimentId, ids)).toEqual(ids);
+
+      // B 的第一波收尾:m-3 / m-4 落盘、锁被删掉,B 剩下的两条仍挂在 A 的锁上等。
+      gateB.release();
+      await awaitDiskOnFakeClock(async () => (await lockedEvalIds(root, experimentId, ids)).length === 2);
+      expect(await lockedEvalIds(root, experimentId, ids)).toEqual(firstWave);
+
+      // A 的第一波收尾 → A 的第二波拿到全局位 → 干干净净地取到 m-3 / m-4 的锁。
+      gateA.release();
+      await advanceOnFakeClock(() => aDone && bDone, 10_000, 12);
+      const [ra, rb] = await Promise.all([pa, pb]);
+
+      // 双跑当场可见:started 不去重(去重恰好会把双跑抹掉),长度必须正好是用例数。
+      expect(all.started).toHaveLength(ids.length);
+      expect([...all.started].sort()).toEqual([...ids]);
+      // 两边到收尾为止都没有再多派发一条:第二波全是携入(排序只为消掉进入 test() 的先后,
+      // 那是调度自由度;条数不排序,双跑会当场把长度顶上去)。
+      expect([...sideA.started].sort()).toEqual([...firstWave]);
+      expect([...sideB.started].sort()).toEqual([...secondWave]);
+      // 两边各自结束时都拿到完整结果集,交集部分只花一份成本。
+      expect(ra.summary.results).toHaveLength(4);
+      expect(rb.summary.results).toHaveLength(4);
+      expect(ra.summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      expect(rb.summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  // 零竞争的最小形态:全程没有任何"碰上别人"的信号——A 起跑时锁目录还不存在,它从没撞过锁、
+  // 没接管过、没等过实验闸名额。对方那条 runEvals 整体 await 到返回(跑完 c-2、落盘、删锁)
+  // 之后才放 barrier,所以 A 的第二波是干干净净地取到一把空锁。任何「有没有碰上别人」的启发式
+  // 在这条路径上都恒假,只有无条件重查才能让 c-2 不被重跑。
+  it("对方跑完并释放锁后干净取到锁:仍必须重查携带 —— c-2 全局只被真实派发一次,携入的那条经一对瞬时 lock_wait 迁进 reused", async () => {
+    const root = await makeRoot();
+    const experimentId = "multi-open-clean-exp";
+    const gatedId = "c-1";
+    const sharedId = "c-2";
+    const agent = makeAgent("agent-multi-open-clean");
+    const sandbox = fakeSandboxSpec();
+    const { barrier, release } = makeBarrier();
+    const all = newDispatchProbe();
+
+    // A:c-1 挂在 barrier 上占住唯一的全局位,c-2 排在队列里(还没摸过锁目录)。
+    const evalsA = [gatedEval(gatedId, barrier, all), gatedEval(sharedId, barrier, all)];
+    const runA = probeRun(agent, experimentId, [gatedId, sharedId], { sandbox });
+    // 对方:只选 c-2,不挂 barrier。
+    const evalsB = [gatedEval(sharedId, Promise.resolve(), all)];
+    const runB = probeRun(agent, experimentId, [sharedId], { sandbox });
+
+    // 反馈计数是进程级的,两条 runEvals 都报进同一个 coordinator:total 取两边之和(A 的 2 条
+    // + 对方的 1 条),五项恒等式必须在这个合计口径上成立。
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 3, configs: 1, totalAttempts: 3, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const pa = runWithPriorResults(evalsA, [runA], { priorResults: [], root, maxConcurrency: 1 });
+      let peerLocator: string | undefined;
+      try {
+        await waitForRealProgress(() => expect(all.inFlight).toBe(1));
+        expect(all.started).toEqual([gatedId]); // c-2 还排着队,没取过锁
+
+        const { summary: peer } = await runWithPriorResults(evalsB, [runB], {
+          priorResults: [],
+          root,
+          maxConcurrency: 1,
+        });
+        expect(peer.results).toHaveLength(1);
+        expect(peer.results[0]!.verdict).toBe("passed");
+        peerLocator = peer.results[0]!.locator;
+        expect(await lockFilesRemaining(root)).toHaveLength(1); // 只剩 A 手上的 c-1
+      } finally {
+        release();
+      }
+
+      const { summary } = await pa;
+
+      expect(all.started.filter((id) => id === sharedId)).toHaveLength(1);
+      expect(all.started).toEqual([gatedId, sharedId]);
+      expect(summary.results).toHaveLength(2);
+      expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      // 携入的是对方那条结果本身(locator 原样透传),不是自己重跑出来的新条目。
+      expect(summary.results.find((r) => r.id === sharedId)!.locator).toBe(peerLocator);
+
+      // 没有等待窗口要关,携入的那条仍必须补一对瞬时的 started/resolved 才能从 queued 迁进
+      // reused —— 少发这一对,五项恒等式当场破。
+      expect(coordinator.state.reused).toBe(1);
+      expect(coordinator.state.elsewhere).toBe(0);
+      expectCountIdentity(coordinator.state);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: 干净取锁下的执行模式组合", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 与「执行模式组合」那条(等待 / 接管后自跑)的区别只有取锁路径:这里是无条件重查刚接管的
+  // 那条干净取锁路径。重查变成无条件之后,`--force` 这道门就是携带与否的唯一判据 —— 漏掉它
+  // 就会在多开下把 force 明确要重跑的用例悄悄吞成携入。
+  it("--force(RunOptions.priorResults 为 undefined)下干净取到锁:对方刚跑完的那条照常自跑,窗口计数不留悬挂", async () => {
+    const root = await makeRoot();
+    const experimentId = "force-clean-exp";
+    const gatedId = "fc-1";
+    const sharedId = "fc-2";
+    const agent = makeAgent("agent-force-clean");
+    const sandbox = fakeSandboxSpec();
+    const { barrier, release } = makeBarrier();
+    const all = newDispatchProbe();
+
+    const evalsA = [gatedEval(gatedId, barrier, all), gatedEval(sharedId, barrier, all)];
+    const runA = probeRun(agent, experimentId, [gatedId, sharedId], { sandbox });
+    const evalsPeer = [gatedEval(sharedId, Promise.resolve(), all)];
+    const runPeer = probeRun(agent, experimentId, [sharedId], { sandbox });
+
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 3, configs: 1, totalAttempts: 3, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      // force 模式:cli.ts 在 --force 时整段不传 priorResults(不是传空数组)——这里同样省略。
+      const pa = runWithPriorResults(evalsA, [runA], { root, maxConcurrency: 1 });
+      try {
+        await waitForRealProgress(() => expect(all.inFlight).toBe(1));
+        const { summary: peer } = await runWithPriorResults(evalsPeer, [runPeer], {
+          priorResults: [],
+          root,
+          maxConcurrency: 1,
+        });
+        expect(peer.results[0]!.verdict).toBe("passed");
+      } finally {
+        release();
+      }
+
+      const { summary } = await pa;
+
+      // 对方跑过一次、A 又跑了一次:这里的两次是**预期**,force 关掉的就是缓存。
+      expect(all.started.filter((id) => id === sharedId)).toHaveLength(2);
+      expect(summary.results).toHaveLength(2);
+      expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      expect(coordinator.state.reused).toBe(0);
+      expect(coordinator.state.elsewhere).toBe(0);
+      expectCountIdentity(coordinator.state);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 实验闸租约跨 runEvals 共享名额", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+    expect(pendingHeldGateLeaseCount()).toBe(0);
+  });
+
+  // 两条 runEvals 各自有独立的进程内信号量,唯一共享的东西是同一个 niceevalRoot 下的租约条目
+  // ——所以「峰值恒为 1」只可能来自跨 runEvals 的名额域。两边故意选不相交的 eval 子集:用例锁
+  // 零交集,限流的只可能是实验闸(这正是 memory/case-lock-dispatch-time-acquire-ruling 里说的
+  // 「双终端选不相交子集跑同一个 maxConcurrency: 1 实验,锁零交集,状态照踩」那个洞)。
+  it("maxConcurrency: 1 的实验:两条 runEvals 同 root 跑不相交用例,该实验全局在飞峰值恒为 1", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "gate-cross-exp";
+      const agent = makeAgent("agent-gate-cross");
+      const sandbox = fakeSandboxSpec();
+      const idsA = ["g-a1", "g-a2"];
+      const idsB = ["g-b1", "g-b2"];
+
+      const all = newDispatchProbe();
+      // 不用 barrier:名额是串行的,挂住任何一条都会把整条链堵死。改用一个假时钟上的
+      // 让步点——两条 attempt 若真的同时持有名额,它们的让步窗口会重叠,峰值当场记成 2。
+      const tickingEval = (id: string): DiscoveredEval =>
+        makeEval(id, async () => {
+          all.started.push(id);
+          all.inFlight += 1;
+          all.peak = Math.max(all.peak, all.inFlight);
+          await new Promise<void>((resolve) => setTimeout(resolve, 1));
+          all.inFlight -= 1;
+        });
+
+      const runA = probeRun(agent, experimentId, idsA, { sandbox, maxConcurrency: 1 });
+      const runB = probeRun(agent, experimentId, idsB, { sandbox, maxConcurrency: 1 });
+
+      let aDone = false;
+      let bDone = false;
+      const pa = runWithPriorResults(idsA.map(tickingEval), [runA], {
+        priorResults: [],
+        root,
+        maxConcurrency: 4,
+      }).then((r) => {
+        aDone = true;
+        return r;
+      });
+      const pb = runWithPriorResults(idsB.map(tickingEval), [runB], {
+        priorResults: [],
+        root,
+        maxConcurrency: 4,
+      }).then((r) => {
+        bDone = true;
+        return r;
+      });
+
+      // 名额交接跨 runEvals 走租约轮询(周期 = 心跳周期),必须分步推假时钟。
+      await advanceOnFakeClock(() => aDone && bDone, 5_000, 40);
+      const [ra, rb] = await Promise.all([pa, pb]);
+
+      expect(all.peak).toBe(1);
+      expect([...all.started].sort()).toEqual([...idsA, ...idsB].sort());
+      expect(ra.summary.results).toHaveLength(2);
+      expect(rb.summary.results).toHaveLength(2);
+      expect([...ra.summary.results, ...rb.summary.results].every((r) => r.verdict === "passed")).toBe(true);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  // 撞满名额只可能是别的 Invocation 占着——本进程自己的并发早被进程内信号量挡住了。不报的话
+  // 面板只剩 `0 running · N queued` 干等,看不出在等谁,更看不出生效名额被对方更小的声明夹低。
+  // 这里让 B 声明 3 却撞上 A 的 declaredN: 1,断言诊断把「生效 1 / 本次声明 3」两个数都说出来。
+  it("撞满名额报 gate-lease-waiting:带上生效名额与本次声明,min-N 夹低时两个数都在", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "gate-wait-notice-exp";
+      const agent = makeAgent("agent-gate-wait");
+      const { barrier, release } = makeBarrier();
+
+      // A 先占住唯一的名额(declaredN: 1)并卡在 barrier 上,B 随后带着 declaredN: 3 进来撞满。
+      const runA = probeRun(agent, experimentId, ["w-a"], { maxConcurrency: 1 });
+      const runB = probeRun(agent, experimentId, ["w-b"], { maxConcurrency: 3 });
+      const probeA = newDispatchProbe();
+
+      const pa = runWithPriorResults([gatedEval("w-a", barrier, probeA)], [runA], {
+        priorResults: [],
+        root,
+        maxConcurrency: 4,
+      });
+      await advanceOnFakeClock(() => probeA.started.length === 1, 5_000, 40);
+
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 1, configs: 1, totalAttempts: 1, maxConcurrency: 4 },
+        reused: 0,
+        reusedFailures: [],
+      };
+      const pb = withCoordinator(plan, async (coordinator) => {
+        let bDone = false;
+        const inner = runWithPriorResults([makeEval("w-b", async () => {})], [runB], {
+          priorResults: [],
+          root,
+          maxConcurrency: 4,
+        }).then((r) => {
+          bDone = true;
+          return r;
+        });
+
+        const waited = (): (typeof coordinator.state.diagnostics)[number] | undefined =>
+          coordinator.state.diagnostics.find((d) => d.code === "gate-lease-waiting");
+        await advanceOnFakeClock(() => waited() !== undefined, 5_000, 40);
+
+        const notice = waited();
+        expect(notice?.severity).toBe("warning");
+        expect(notice?.data).toMatchObject({ experimentId, effectiveN: 1, declaredN: 3 });
+        expect(notice?.message).toContain(experimentId);
+
+        release();
+        await advanceOnFakeClock(() => bDone, 20_000, 80);
+        return inner;
+      });
+
+      await Promise.all([pa, pb]);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: runs > 1 的兄弟 attempt 共享同一把锁", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("自己已持有的直接放行:runs: 3 三条 attempt 同时在飞,锁目录仍只有一条(锁是逐用例的,不是逐 attempt)", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-sibling-hold-exp";
+    const evalId = "sibling-hold-eval";
+    const { barrier, release } = makeBarrier();
+    const probe = newDispatchProbe();
+    const agentRun = probeRun(makeAgent("agent-lock-sibling-hold"), experimentId, [evalId], { runs: 3 });
+
+    const runPromise = runWithPriorResults([gatedEval(evalId, barrier, probe)], [agentRun], {
+      priorResults: [],
+      root,
+      maxConcurrency: 3,
+    });
+    try {
+      await waitForRealProgress(() => expect(probe.inFlight).toBe(3));
+      expect(await lockFilesRemaining(root)).toHaveLength(1);
+    } finally {
+      release();
+    }
+
+    const { summary } = await runPromise;
+    expect(summary.results.map((r) => r.attempt).sort()).toEqual([0, 1, 2]);
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  it("别人持有时整组挂在同一个等待窗口上:只开一条 lock_wait、elsewhere 计为 3 且与 queued 互斥,接管后三条一起派发", async () => {
+    vi.useFakeTimers();
+    try {
+      const root = await makeRoot();
+      const experimentId = "lock-sibling-wait-exp";
+      const evalId = "sibling-wait-eval";
+      await seedCaseLock(root, freshLockRecord(experimentId, evalId));
+
+      let calls = 0;
+      const evalDef = makeEval(evalId, () => {
+        calls += 1;
+      });
+      const agentRun = probeRun(makeAgent("agent-lock-sibling-wait"), experimentId, [evalId], { runs: 3 });
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 1, configs: 1, totalAttempts: 3, maxConcurrency: 3 },
+        reused: 0,
+        reusedFailures: [],
+      };
+
+      await withCoordinator(plan, async (coordinator) => {
+        let done = false;
+        const runPromise = runWithPriorResults([evalDef], [agentRun], {
+          priorResults: [],
+          root,
+          maxConcurrency: 3,
+        }).then((r) => {
+          done = true;
+          return r;
+        });
+
+        await waitForRealProgress(() => expect(coordinator.state.elsewhere).toBe(3));
+        // 三条兄弟共享一次试锁与一个等待窗口:等待条目是「一条用例」而不是「三个 attempt」,
+        // 但 elsewhere 计的是 attempt 数(五项恒等式的口径)。
+        expect(coordinator.state.lockWaits.get(experimentId)?.waiting.size).toBe(1);
+        expect(coordinator.state.queued).toBe(0); // elsewhere 与 queued 互斥
+        const mid = coordinator.state;
+        expectCountIdentity(mid);
+        expect(calls).toBe(0);
+
+        await advanceOnFakeClock(() => done, 10_000, 12);
+        const { summary } = await runPromise;
+
+        expect(calls).toBe(3);
+        expect(summary.results.map((r) => r.attempt).sort()).toEqual([0, 1, 2]);
+        expect(coordinator.state.elsewhere).toBe(0);
+        const end = coordinator.state;
+        expectCountIdentity(end);
+        expect(await lockFilesRemaining(root)).toEqual([]);
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: 释放后重查携带逐 attempt 判定", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 与「用例锁: 释放后续接」那组的区别:那组走的是「撞上过期锁 → 接管」这条路径,重查携带
+  // 顺带在取锁里发生;这里走的是真实的挂起窗口(撞新鲜锁 → elsewhere → 持有方正常释放),
+  // 断言面是 elsewhere 两个方向的迁移本身:命中的序号迁 reused、没命中的序号迁 queued 自跑。
+  // 判定必须逐 attempt(memory/carry-must-be-per-attempt-not-whole-eval-key:按整段 key 判会
+  // 让同 eval 里一个序号的终态连带携入其它序号)。
+  it("磁盘只有序号 0 的终态时:序号 0 从 elsewhere 迁 reused 不重跑,序号 1 迁 queued 自跑", async () => {
+    const root = await makeRoot();
+    const experimentId = "lock-recheck-exp";
+    const evalId = "recheck-eval";
+    const agent = makeAgent("agent-lock-recheck");
+    const sandbox = fakeSandboxSpec();
+
+    // 先用一次真实运行落下序号 0 的 passed 终态(指纹由生产路径自己算,不手工拼)。
+    const producerRun = probeRun(agent, experimentId, [evalId], { sandbox });
+    const { summary: produced } = await run([makeEval(evalId, () => {})], [producerRun], { root });
+    expect(produced.results[0]!.verdict).toBe("passed");
+
+    // 另一条 Invocation 此刻正持有这把锁(心跳新鲜:走等待窗口,不是过期接管)。
+    await seedCaseLock(root, freshLockRecord(experimentId, evalId));
+
+    vi.useFakeTimers();
+    try {
+      let calls = 0;
+      const subjectEval = makeEval(evalId, () => {
+        calls += 1;
+      });
+      const subjectRun = probeRun(agent, experimentId, [evalId], { sandbox, runs: 2 });
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 1, configs: 1, totalAttempts: 2, maxConcurrency: 2 },
+        reused: 0,
+        reusedFailures: [],
+      };
+
+      await withCoordinator(plan, async (coordinator) => {
+        let done = false;
+        const runPromise = runWithPriorResults([subjectEval], [subjectRun], {
+          priorResults: [],
+          root,
+          maxConcurrency: 2,
+        }).then((r) => {
+          done = true;
+          return r;
+        });
+
+        await waitForRealProgress(() => expect(coordinator.state.elsewhere).toBe(2));
+        expect(coordinator.state.reused).toBe(0); // 静态携带规划(priorResults 为空)一条都没命中
+
+        // 持有方正常收尾:锁文件消失 —— 等待窗口下一轮轮询就结束,并重新做一次携带规划。
+        await rm(caseLockPath(root, experimentId, evalId), { force: true });
+        await advanceOnFakeClock(() => done, 10_000, 12);
+        const { summary } = await runPromise;
+
+        expect(calls).toBe(1); // 只有缺的序号 1 自跑,序号 0 是携入
+        expect(coordinator.state.reused).toBe(1); // elsewhere → reused
+        expect(coordinator.state.elsewhere).toBe(0);
+        const end = coordinator.state;
+        expectCountIdentity(end);
+        expect(summary.results.map((r) => r.attempt).sort()).toEqual([0, 1]);
+        expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+        expect(await lockFilesRemaining(root)).toEqual([]);
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  // 同一条逐 attempt 判定,换到干净取锁这条路径上再验一次:两条路径放走的错误类别不同。挂起
+  // 窗口那条错在「迁移数与报进 elsewhere 的条数对不上」;这条错在「补发的那对瞬时 lock_wait
+  // 报了整组而不是只报真正携入的那几条」——没携入的兄弟从没离开过 queued,连它们一起报会在
+  // 两条事件之间把 queued 扣穿(极端时序下兄弟已进 running,那一扣就是负数)。
+  it("干净取锁后只携入对方跑出来的序号 0:序号 1 照常自跑,补发的一对瞬时 lock_wait 只报携入的那一条", async () => {
+    const root = await makeRoot();
+    const experimentId = "clean-recheck-partial-exp";
+    const gatedId = "p-1";
+    const sharedId = "p-2";
+    const agent = makeAgent("agent-clean-recheck-partial");
+    const sandbox = fakeSandboxSpec();
+    const { barrier, release } = makeBarrier();
+    const all = newDispatchProbe();
+    const sideA = newDispatchProbe();
+
+    // A 要两轮;对方只跑了 p-2 的序号 0。
+    const evalsA = [gatedEval(gatedId, barrier, sideA, all), gatedEval(sharedId, barrier, sideA, all)];
+    const runA = probeRun(agent, experimentId, [gatedId, sharedId], { sandbox, runs: 2 });
+    const evalsPeer = [gatedEval(sharedId, Promise.resolve(), all)];
+    const runPeer = probeRun(agent, experimentId, [sharedId], { sandbox });
+
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 3, configs: 1, totalAttempts: 5, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const pa = runWithPriorResults(evalsA, [runA], { priorResults: [], root, maxConcurrency: 1 });
+      try {
+        await waitForRealProgress(() => expect(all.inFlight).toBe(1));
+        expect(sideA.started).toEqual([gatedId]);
+        const { summary: peer } = await runWithPriorResults(evalsPeer, [runPeer], {
+          priorResults: [],
+          root,
+          maxConcurrency: 1,
+        });
+        expect(peer.results.map((r) => r.attempt)).toEqual([0]);
+      } finally {
+        release();
+      }
+
+      const { summary } = await pa;
+
+      // p-1 两轮都自跑;p-2 只补跑缺的那一轮 —— 判定逐 attempt,不按整条用例一刀切。
+      expect(sideA.started.filter((id) => id === sharedId)).toHaveLength(1);
+      expect(sideA.started.filter((id) => id === gatedId)).toHaveLength(2);
+      const shared = summary.results.filter((r) => r.id === sharedId);
+      expect(shared.map((r) => r.attempt).sort()).toEqual([0, 1]);
+      expect(summary.results).toHaveLength(4);
+      expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      expect(coordinator.state.reused).toBe(1); // 只有序号 0 迁进 reused
+      expect(coordinator.state.elsewhere).toBe(0);
+      expectCountIdentity(coordinator.state);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: 取锁后重查携带的读取面", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 无条件重查的前提是这次读盘便宜:它压在「已经握着全局并发位 + 实验闸名额 + 用例锁」的关键
+  // 路径上,回答的是一个 per-case 的问题(这条用例现在还缺哪些 attempt)。用全根扫描回答它会
+  // 随 .niceeval 历史线性变慢且永不收敛,单开也照付——所以读取面的形状本身是契约的一部分:
+  // 按用例数各读一次收窄读取面,一次全树扫描都不做(runs 的兄弟共享同一次,不是按 attempt 数)。
+  it("三条用例 × runs 2:收窄读取面恰好被调用 3 次(按用例数,不按 attempt 数),全树扫描 0 次", async () => {
+    const root = await makeRoot();
+    const experimentId = "read-surface-exp";
+    const ids = ["r-1", "r-2", "r-3"];
+    const sandbox = fakeSandboxSpec();
+
+    // 先落一批历史结果(另一个 agent ⇒ 指纹不同,不会被携入):读取面要在"结果树非空"的前提
+    // 下计数,否则测不出"读了什么"与"读了多大一片"的区别。
+    const historyRun = probeRun(makeAgent("agent-read-surface-history"), experimentId, ids, { sandbox });
+    await run(ids.map((id) => makeEval(id, () => {})), [historyRun], { root });
+
+    let calls = 0;
+    const evals = ids.map((id) =>
+      makeEval(id, () => {
+        calls += 1;
+      }),
+    );
+    const subjectRun = probeRun(makeAgent("agent-read-surface"), experimentId, ids, { sandbox, runs: 2 });
+
+    readSurfaceCalls.forCase = 0;
+    readSurfaceCalls.perEval = 0;
+    const { summary } = await runWithPriorResults(evals, [subjectRun], { priorResults: [], root });
+
+    expect(calls).toBe(6); // 3 条用例 × 2 轮,历史结果指纹不同、一条都没被携入
+    expect(summary.results).toHaveLength(6);
+    expect(readSurfaceCalls.forCase).toBe(ids.length);
+    expect(readSurfaceCalls.perEval).toBe(0);
+    expect(await lockFilesRemaining(root)).toEqual([]);
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+// ═══════════════════════ 止损闸(空间轴消费) ═══════════════════════
+// 覆盖规范:docs/engineering/testing/unit/experiments-runner.md「止损闸(空间轴消费)」
+// 契约:docs/feature/error-classification/README.md「止损语义」、architecture.md「止损执行体」
+//
+// 断言面全部是可观察的调度事实:test() 被真实调用了几次(启动集合)、`summary.results` 有几条、
+// 反馈状态的五项计数与诊断、`snapshot.json` 的实验域诊断。闸的内部形态(latch / AbortController /
+// 检查点次数)不进断言 —— 覆盖规范「观察面与边界」明确不锁内部信号量与 Promise 图。
+
+/** 两条通路共用的折叠键(run.ts 的 haltGateKey);反馈流按 key 取,持久化侧按 code 过滤。 */
+const experimentHaltKey = (experimentId: string): string => `dispatch-halted:experiment:${experimentId}`;
+const evalHaltKey = (experimentId: string, evalId: string): string =>
+  `dispatch-halted:eval:${experimentId}|${evalId}`;
+
+/** 持久化通路:snapshot.json 里该 Experiment 的 dispatch-halted 诊断(可能一条都没有)。 */
+async function snapshotHaltDiagnostics(root: string, experimentId: string): Promise<DiagnosticRecord[]> {
+  const results = await openResults(root);
+  const exp = results.experiments.find((e) => e.id === experimentId);
+  return (exp?.latest.diagnostics ?? []).filter((d) => d.code === "dispatch-halted");
+}
+
+/** 八项计数恒等式(docs/feature/experiments/cli.md):任何一帧都必须成立。 */
+function expectCountIdentity(state: RunFeedbackState): void {
+  expect(state.total).toBe(
+    state.reused +
+      state.running +
+      state.elsewhere +
+      state.queued +
+      state.passed +
+      state.failed +
+      state.errored +
+      state.skipped,
+  );
+}
+
+describe("runEvals · 止损闸: 触发", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 触发(experiment 档)+ 记账 + 不连坐三面一次跑完:全局并发 1 让派发严格串行,被 halt 的
+  // 实验只可能跑掉第一条;同批另一个实验的用例照常跑完,证明闸是按实验隔离的。
+  it("ExperimentFatalError:同实验剩余 attempt 全停、计 unstarted,同批其它实验不连坐;errored 的 error code 不被 scope 改写", async () => {
+    const haltedExp = "halt-trigger-exp";
+    const bystanderExp = "halt-bystander-exp";
+    const startedHalted: string[] = [];
+    const startedBystander: string[] = [];
+    const haltedEvals = ["a-fatal", "a-2", "a-3"].map((id) =>
+      makeEval(id, () => {
+        startedHalted.push(id);
+        if (id === "a-fatal") throw new ExperimentFatalError("shared tunnel is down; run `make tunnel` and retry");
+      }),
+    );
+    // 同批的对照实验:一条抛普通 Error(证明 error code 与 scope 声明无关,两边同为
+    // unexpected-error),另一条照常通过 —— 普通 Error 不落任何闸,这个实验一条都不少跑。
+    const bystanderEvals = ["b-plain-throw", "b-ok"].map((id) =>
+      makeEval(id, () => {
+        startedBystander.push(id);
+        if (id === "b-plain-throw") throw new Error("just a normal failure");
+      }),
+    );
+    const haltedRun = probeRun(makeAgent("agent-halt-trigger"), haltedExp, ["a-fatal", "a-2", "a-3"]);
+    const bystanderRun = probeRun(makeAgent("agent-halt-bystander"), bystanderExp, ["b-plain-throw", "b-ok"]);
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 5, configs: 2, totalAttempts: 5, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const { summary, root } = await runWithPriorResults([...haltedEvals, ...bystanderEvals], [haltedRun, bystanderRun], {
+        priorResults: [],
+        maxConcurrency: 1,
+      });
+
+      // 触发:撞死的那条照常跑完并落账,同实验剩下两条一次都没进过 test()。
+      expect(startedHalted).toEqual(["a-fatal"]);
+      // 不连坐:另一个实验的两条全跑了(其中一条自己也 errored,照样不影响同批第三方)。
+      expect([...startedBystander].sort()).toEqual(["b-ok", "b-plain-throw"]);
+
+      const halted = summary.results.filter((r) => r.experimentId === haltedExp);
+      expect(halted).toHaveLength(1); // 不为没跑过的 attempt 制造 errored 记录
+      expect(halted[0]!.verdict).toBe("errored");
+      const bystander = summary.results.filter((r) => r.experimentId === bystanderExp);
+      expect(bystander).toHaveLength(2);
+      // error code 保持所属阶段的原有值:scope 是路由标记,不改写 AttemptError 的公开形状 ——
+      // 声明了 scope 的那条与只抛普通 Error 的那条 code/phase 完全一致。
+      const plainThrow = bystander.find((r) => r.id === "b-plain-throw")!;
+      expect(halted[0]!.error?.code).toBe(plainThrow.error?.code);
+      expect(halted[0]!.error?.code).toBe("unexpected-error");
+      expect(halted[0]!.error?.phase).toBe(plainThrow.error?.phase);
+
+      // 记账:两条未派发计 unstarted(cli.ts 的 assembleInvocationCompletion 读的就是这条诊断的
+      // data.unstarted,unstarted > 0 即完成状态 incomplete),五项计数恒等式收束时仍成立。
+      const notice = coordinator.state.diagnostics.find((d) => d.key === experimentHaltKey(haltedExp));
+      expect(notice).toBeDefined();
+      expect(notice!.severity).toBe("error");
+      expect(notice!.data?.unstarted).toBe(2);
+      expect(coordinator.state.diagnostics.some((d) => d.key.startsWith("dispatch-halted:eval:"))).toBe(false);
+      expectCountIdentity(coordinator.state);
+      expect(coordinator.state.queued).toBe(0);
+      expect(coordinator.state.elsewhere).toBe(0);
+
+      // 同批其它实验的 snapshot 上不留任何 dispatch-halted。
+      expect(await snapshotHaltDiagnostics(root, bystanderExp)).toEqual([]);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  // 触发(eval 档)+ 诊断双通路:runs: 3 下只停本 eval 剩余的两个 attempt,同实验另一个 eval 的
+  // 三个 attempt 一个不少;两条通路(反馈流通知 / snapshot.json)各自带齐 scope、evalId 与 phase。
+  it("EvalFatalError:只停本 eval 剩余 attempt(同实验另一个 eval 的 3 个 attempt 照跑);双通路的 scope/evalId/phase 同源", async () => {
+    const experimentId = "halt-eval-scope-exp";
+    const message = "fixture corrupted: regenerate data/fixtures";
+    let fatalCalls = 0;
+    let okCalls = 0;
+    const evalFatal = makeEval("f-fatal", () => {
+      fatalCalls += 1;
+      throw new EvalFatalError(message);
+    });
+    const evalOk = makeEval("f-ok", () => {
+      okCalls += 1;
+    });
+    const agentRun = probeRun(makeAgent("agent-halt-eval-scope"), experimentId, ["f-fatal", "f-ok"], { runs: 3 });
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 2, configs: 1, totalAttempts: 6, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const { summary, root } = await runWithPriorResults([evalFatal, evalOk], [agentRun], {
+        priorResults: [],
+        maxConcurrency: 1,
+      });
+
+      expect(fatalCalls).toBe(1); // 序号 1、2 被闸拦下
+      expect(okCalls).toBe(3); // 同实验另一个 eval 完全不受影响
+      expect(summary.results.filter((r) => r.id === "f-fatal")).toHaveLength(1);
+      expect(summary.results.filter((r) => r.id === "f-ok").map((r) => r.attempt).sort()).toEqual([0, 1, 2]);
+
+      // 通路一:运行期反馈流。
+      const notice = coordinator.state.diagnostics.find((d) => d.key === evalHaltKey(experimentId, "f-fatal"));
+      expect(notice).toBeDefined();
+      expect(notice!.code).toBe("dispatch-halted");
+      expect(notice!.message).toContain(message);
+      expect(notice!.data).toMatchObject({ scope: "eval", evalId: "f-fatal", phase: "eval.run" });
+      expect(notice!.data?.unstarted).toBe(2);
+      // 实验闸没落下:同实验其它 eval 的派发不该被 eval 档声明连带停掉。
+      expect(coordinator.state.diagnostics.some((d) => d.key === experimentHaltKey(experimentId))).toBe(false);
+      expectCountIdentity(coordinator.state);
+
+      // 通路二:snapshot.json 的实验域诊断。同源(同一份 message/phase/scope),但各自累计 ——
+      // 反馈流那条含未派发记账刷新的 count,持久化这条只按声明次数折叠(这里只声明过一次)。
+      const persisted = await snapshotHaltDiagnostics(root, experimentId);
+      expect(persisted).toHaveLength(1);
+      expect(persisted[0]).toMatchObject({
+        code: "dispatch-halted",
+        level: "error",
+        phase: "eval.run",
+        data: { scope: "eval", evalId: "f-fatal" },
+      });
+      expect(persisted[0]!.message).toContain(message);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 止损闸: 组合(时间轴先走,空间轴只对终局失败生效)", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 同一份 { retryable: true, scope: "experiment" } 声明,两个方向各一条区分力场景:被重试
+  // 吸收就到不了闸(本例),重试耗尽的终局失败才读 scope(下一例)。
+  it("可重试失败被重试吸收:同一份带 scope 的声明重试成功后不落闸,同实验后续用例照常派发", async () => {
+    vi.useFakeTimers();
+    const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0.9);
+    try {
+      const experimentId = "halt-absorbed-exp";
+      let sendCalls = 0;
+      const agent = defineSandboxAgent({
+        name: "agent-halt-absorbed",
+        send: async () => {
+          sendCalls += 1;
+          // 只有第一次 send 撞限流:退避一次后成功,失败 Turn 从不外泄给 expectOk()。
+          return sendCalls === 1 ? retryableFailureTurn("rate limited, please retry later") : okTurn();
+        },
+      });
+      const started: string[] = [];
+      const evals = ["c-1", "c-2"].map((id) =>
+        makeEval(id, async (t) => {
+          started.push(id);
+          (await t.send("go")).expectOk();
+        }),
+      );
+      const agentRun = probeRun(agent, experimentId, ["c-1", "c-2"], {
+        maxConcurrency: 1,
+        // 实验分类器排在 adapter / 兜底之前:同一段限流文本被认领成「可重试 + 实验级」。
+        classifyFailure: (f) =>
+          f.text.includes("rate limited") ? { retryable: true, reason: "rate_limit", scope: "experiment" } : undefined,
+      });
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 2, configs: 1, totalAttempts: 2, maxConcurrency: 1 },
+        reused: 0,
+        reusedFailures: [],
+      };
+
+      await withCoordinator(plan, async (coordinator) => {
+        let done = false;
+        const runPromise = runWithPriorResults(evals, [agentRun], {
+          priorResults: [],
+          maxConcurrency: 1,
+        }).then((r) => {
+          done = true;
+          return r;
+        });
+
+        await advanceOnFakeClock(() => done, 10_000, 12);
+        const { summary, root } = await runPromise;
+
+        expect([...started].sort()).toEqual(["c-1", "c-2"]); // 闸没落下:第二条照常派发
+        expect(summary.results).toHaveLength(2);
+        expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+        expect(sendCalls).toBe(3); // c-1 失败 1 次 + 重试成功 1 次,c-2 成功 1 次
+        expect(coordinator.state.diagnostics.some((d) => d.key.startsWith("dispatch-halted:"))).toBe(false);
+        expect(await snapshotHaltDiagnostics(root, experimentId)).toEqual([]);
+      });
+    } finally {
+      vi.useRealTimers();
+      randomSpy.mockRestore();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  it("重试耗尽后的终局失败才读 scope:同一份声明在耗尽路径上照常落闸,同实验剩余用例停派发", async () => {
+    vi.useFakeTimers();
+    const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0.9);
+    try {
+      const experimentId = "halt-exhausted-exp";
+      let sendCalls = 0;
+      const agent = defineSandboxAgent({
+        name: "agent-halt-exhausted",
+        send: async () => {
+          sendCalls += 1;
+          return retryableFailureTurn("rate limited, please retry later"); // 永远撞限流,重试必耗尽
+        },
+      });
+      const started: string[] = [];
+      const evals = ["d-1", "d-2"].map((id) =>
+        makeEval(id, async (t) => {
+          started.push(id);
+          (await t.send("go")).expectOk();
+        }),
+      );
+      const agentRun = probeRun(agent, experimentId, ["d-1", "d-2"], {
+        maxConcurrency: 1,
+        classifyFailure: (f) =>
+          f.text.includes("rate limited") ? { retryable: true, reason: "rate_limit", scope: "experiment" } : undefined,
+      });
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 2, configs: 1, totalAttempts: 2, maxConcurrency: 1 },
+        reused: 0,
+        reusedFailures: [],
+      };
+
+      await withCoordinator(plan, async (coordinator) => {
+        let done = false;
+        const runPromise = runWithPriorResults(evals, [agentRun], {
+          priorResults: [],
+          maxConcurrency: 1,
+        }).then((r) => {
+          done = true;
+          return r;
+        });
+
+        // send 级预算封顶 4 次尝试,退避 4.5s / 9s / 18s(Math.random 定量成 0.9)。
+        await advanceOnFakeClock(() => done, 10_000, 20);
+        const { summary } = await runPromise;
+
+        expect(started).toEqual(["d-1"]); // 耗尽后的终局失败落闸:d-2 不再派发
+        expect(sendCalls).toBe(4);
+        expect(summary.results).toHaveLength(1);
+        expect(summary.results[0]!.verdict).toBe("errored");
+        const notice = coordinator.state.diagnostics.find((d) => d.key === experimentHaltKey(experimentId));
+        expect(notice).toBeDefined();
+        expect(notice!.data?.unstarted).toBe(1);
+      });
+    } finally {
+      vi.useRealTimers();
+      randomSpy.mockRestore();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 止损闸: 幂等与不可逆", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("并发三条同时声明同一死因:两条通路各折叠成一条 dispatch-halted、count 累加到 3", async () => {
+    const experimentId = "halt-idempotent-exp";
+    const { barrier, release } = makeBarrier();
+    const probe = newDispatchProbe();
+    const ids = ["i-1", "i-2", "i-3"];
+    // 三条一起挂在同一个 barrier 上:释放的瞬间三条并发抛出同一个实验级声明,这正是
+    // 「并发 attempt 同时声明同一死因」的常态形状。
+    const evals = ids.map((id) =>
+      makeEval(id, async () => {
+        probe.started.push(id);
+        probe.inFlight += 1;
+        probe.peak = Math.max(probe.peak, probe.inFlight);
+        await barrier;
+        probe.inFlight -= 1;
+        throw new ExperimentFatalError("shared credentials expired; refresh .env");
+      }),
+    );
+    const agentRun = probeRun(makeAgent("agent-halt-idempotent"), experimentId, ids);
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 3, configs: 1, totalAttempts: 3, maxConcurrency: 3 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const runPromise = runWithPriorResults(evals, [agentRun], { priorResults: [], maxConcurrency: 3 });
+      try {
+        await waitForRealProgress(() => expect(probe.inFlight).toBe(3));
+      } finally {
+        release();
+      }
+      const { summary, root } = await runPromise;
+
+      expect(summary.results).toHaveLength(3);
+      expect(summary.results.every((r) => r.verdict === "errored")).toBe(true);
+
+      const notices = coordinator.state.diagnostics.filter((d) => d.key.startsWith("dispatch-halted:"));
+      expect(notices).toHaveLength(1); // 三次声明折叠成一条(dedupeKey 相同)
+      expect(notices[0]!.count).toBe(3);
+      expect(notices[0]!.data?.unstarted).toBe(0); // 三条都在飞,一条都没被拦下
+
+      const persisted = await snapshotHaltDiagnostics(root, experimentId);
+      expect(persisted).toHaveLength(1);
+      expect(persisted[0]!.count).toBe(3);
+      expect(persisted[0]!.data).toMatchObject({ scope: "experiment" });
+      expect(persisted[0]!.data?.evalId).toBeUndefined(); // 实验闸没有 evalId
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  it("落闸后在飞 attempt 成功也不重开派发:在飞的照常跑完落账,排队的仍然全停", async () => {
+    const experimentId = "halt-irreversible-exp";
+    const fatal = makeBarrier();
+    const survivor = makeBarrier();
+    const started: string[] = [];
+    const ids = ["n-fatal", "n-survivor", "n-late-1", "n-late-2"];
+    const evals = ids.map((id) =>
+      makeEval(id, async () => {
+        started.push(id);
+        if (id === "n-fatal") {
+          await fatal.barrier;
+          throw new ExperimentFatalError("shared service died mid-run");
+        }
+        if (id === "n-survivor") await survivor.barrier;
+      }),
+    );
+    const agentRun = probeRun(makeAgent("agent-halt-irreversible"), experimentId, ids);
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 4, configs: 1, totalAttempts: 4, maxConcurrency: 2 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const runPromise = runWithPriorResults(evals, [agentRun], { priorResults: [], maxConcurrency: 2 });
+      try {
+        // 全局并发 2:前两条在飞,后两条排队。
+        await waitForRealProgress(() => expect(started).toHaveLength(2));
+        fatal.release();
+        // 等闸真的落下(诊断出现)再放行幸存者,确保它的成功发生在落闸之后。
+        await waitForRealProgress(() =>
+          expect(coordinator.state.diagnostics.some((d) => d.key === experimentHaltKey(experimentId))).toBe(true),
+        );
+      } finally {
+        survivor.release();
+      }
+      const { summary } = await runPromise;
+
+      // 不抢占:在飞的 n-survivor 照常跑完并如实落账(passed);它的成功不重开派发。
+      expect([...started].sort()).toEqual(["n-fatal", "n-survivor"]);
+      expect(summary.results).toHaveLength(2);
+      expect(summary.results.find((r) => r.id === "n-survivor")!.verdict).toBe("passed");
+      expect(summary.results.find((r) => r.id === "n-fatal")!.verdict).toBe("errored");
+      const notice = coordinator.state.diagnostics.find((d) => d.key === experimentHaltKey(experimentId));
+      expect(notice!.data?.unstarted).toBe(2);
+      expectCountIdentity(coordinator.state);
+      expect(coordinator.state.queued).toBe(0);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 止损闸: 不抢占(等待集经 interruption 中止)", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 挂在 elsewhere 上的用例等的是「别人的锁什么时候放」,轮询周期是 10s 心跳。闸落下时它必须
+  // 经既有 interruption 通路当场退出等待集,而不是陪着等满一个周期 —— 所以这条用真实时钟跑,
+  // 断言面是硬墙钟耗时。
+  it("落闸时挂在 elsewhere 的用例立刻退出等待集(远早于 10s 轮询周期),计 unstarted 且五项恒等式不破", async () => {
+    const root = await makeRoot();
+    const experimentId = "halt-elsewhere-exp";
+    const lockedId = "w-locked";
+    await seedCaseLock(root, freshLockRecord(experimentId, lockedId));
+
+    let lockedCalls = 0;
+    const evalLocked = makeEval(lockedId, () => {
+      lockedCalls += 1;
+    });
+    const evalFatal = makeEval("w-fatal", () => {
+      throw new ExperimentFatalError("shared svc down");
+    });
+    const agentRun = probeRun(makeAgent("agent-halt-elsewhere"), experimentId, [lockedId, "w-fatal"]);
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 2, configs: 1, totalAttempts: 2, maxConcurrency: 2 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const startedAt = Date.now();
+      const { summary } = await runWithPriorResults([evalLocked, evalFatal], [agentRun], {
+        priorResults: [],
+        root,
+        maxConcurrency: 2,
+      });
+      const elapsedMs = Date.now() - startedAt;
+
+      // 硬时间断言:锁等待轮询周期是 10s,不走中止通路的话整段至少要拖满一个周期。
+      expect(elapsedMs).toBeLessThan(8_000);
+      expect(lockedCalls).toBe(0); // 等待集里的那条从没被派发
+      expect(summary.results).toHaveLength(1); // 不为没跑过的 attempt 制造 errored 记录
+      expect(summary.results[0]!.id).toBe("w-fatal");
+      expect(summary.results[0]!.verdict).toBe("errored");
+
+      const notice = coordinator.state.diagnostics.find((d) => d.key === experimentHaltKey(experimentId));
+      expect(notice!.data?.unstarted).toBe(1);
+      // elsewhere 收支平账:进过等待集的那条必须被原数报回来,恒等式不留悬空的差额。
+      expect(coordinator.state.elsewhere).toBe(0);
+      expect(coordinator.state.queued).toBe(0);
+      expectCountIdentity(coordinator.state);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 止损闸: teardown 边界", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  it("实验级 teardown 抛声明:降级为普通 teardown 诊断,不落闸", async () => {
+    const experimentId = "halt-exp-teardown";
+    const started: string[] = [];
+    const ids = ["t-1", "t-2"];
+    const evals = ids.map((id) =>
+      makeEval(id, () => {
+        started.push(id);
+      }),
+    );
+    const agentRun = probeRun(makeAgent("agent-halt-exp-teardown"), experimentId, ids, {
+      maxConcurrency: 1,
+      setup: () => {},
+      teardown: () => {
+        throw new ExperimentFatalError("shared db handle leaked; restart the stack");
+      },
+    });
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 2, configs: 1, totalAttempts: 2, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const { summary, root } = await runWithPriorResults(evals, [agentRun], {
+        priorResults: [],
+        maxConcurrency: 1,
+      });
+
+      expect([...started].sort()).toEqual(ids);
+      expect(summary.results).toHaveLength(2);
+      expect(summary.results.every((r) => r.verdict === "passed")).toBe(true);
+      // 降级:只留既有的 teardown 失败诊断,一条 dispatch-halted 都不产生(两条通路都不产生)。
+      const teardownDiag = coordinator.state.diagnostics.find(
+        (d) => d.key === `experiment-teardown-failed:${experimentId}`,
+      );
+      expect(teardownDiag).toBeDefined();
+      expect(teardownDiag!.message).toContain("shared db handle leaked");
+      expect(coordinator.state.diagnostics.some((d) => d.key.startsWith("dispatch-halted:"))).toBe(false);
+      expect(await snapshotHaltDiagnostics(root, experimentId)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  it("per-attempt teardown 抛声明:照常落闸(剩余两条计 unstarted),但 verdict 仍是 passed", async () => {
+    const experimentId = "halt-attempt-teardown";
+    const started: string[] = [];
+    const ids = ["k-1", "k-2", "k-3"];
+    const evals = ids.map((id) =>
+      makeEval(id, () => {
+        started.push(id);
+      }),
+    );
+    // eval.teardown 是 attempt 收尾链的第一段,失败只记诊断、不改判定;空间轴声明照常落闸。
+    evals[0]!.teardown = () => {
+      throw new ExperimentFatalError("shared db handle leaked; restart the stack");
+    };
+    const agentRun = probeRun(makeAgent("agent-halt-attempt-teardown"), experimentId, ids);
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 3, configs: 1, totalAttempts: 3, maxConcurrency: 1 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const { summary, root } = await runWithPriorResults(evals, [agentRun], {
+        priorResults: [],
+        maxConcurrency: 1,
+      });
+
+      expect(started).toEqual(["k-1"]);
+      expect(summary.results).toHaveLength(1);
+      expect(summary.results[0]!.verdict).toBe("passed"); // 落闸不改 verdict
+      expect(summary.results[0]!.diagnostics?.some((d) => d.phase === "eval.teardown")).toBe(true);
+
+      const notice = coordinator.state.diagnostics.find((d) => d.key === experimentHaltKey(experimentId));
+      expect(notice).toBeDefined();
+      expect(notice!.data?.unstarted).toBe(2);
+      expect(notice!.data?.phase).toBe("eval.teardown"); // 触发失败所在的生命周期阶段
+      const persisted = await snapshotHaltDiagnostics(root, experimentId);
+      expect(persisted).toHaveLength(1);
+      expect(persisted[0]!.phase).toBe("eval.teardown");
+      expectCountIdentity(coordinator.state);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+// ─────────────── 用例锁:elsewhere 收支平账的两条回归(五项恒等式的守护) ───────────────
+// 覆盖规范:docs/engineering/testing/unit/experiments-runner.md「用例锁与并发 Invocation」的
+// 「挂起用例……计入独立的 `elsewhere` 计数且与 `queued` 互斥、五项计数恒等式成立」与
+// 「执行模式组合——`--force` 等待后全部自跑」两分句。
+//
+// 上面「执行模式组合」那组走的是过期锁接管路径,压根没进过挂起窗口;这里的三条专测窗口本身
+// 的收支:报进 elsewhere 多少条,收尾就要原数报回多少条 —— 差额挂住即恒等式当场破。
+
+describe("runEvals · 用例锁: --force 撞新鲜锁的挂起窗口", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // bug: --force 下撞**新鲜**锁只发 started 不发 resolved,elsewhere 永久挂住、五项恒等式当场破。
+  // 上面「执行模式组合」那条走的是 stale 锁接管(从没进过挂起窗口),盖不住这个窗口。
+  it("--force + 新鲜锁 + 持有方释放:窗口照常收 resolved,elsewhere 归零、恒等式成立,用例全部自跑", async () => {
+    const root = await makeRoot();
+    const experimentId = "force-fresh-lock-exp";
+    const evalId = "force-fresh-eval";
+    const agent = makeAgent("agent-force-fresh");
+    const sandbox = fakeSandboxSpec();
+
+    // 先落一条指纹匹配的 passed 终态:--force 下它不该被消费,等完窗口照样自跑。
+    const producerRun = probeRun(agent, experimentId, [evalId], { sandbox });
+    const { summary: produced } = await run([makeEval(evalId, () => {})], [producerRun], { root });
+    expect(produced.results[0]!.verdict).toBe("passed");
+
+    // 另一条 Invocation 此刻正持有这把锁(心跳新鲜:走真实的挂起窗口,不是过期接管)。
+    await seedCaseLock(root, freshLockRecord(experimentId, evalId));
+
+    vi.useFakeTimers();
+    try {
+      let calls = 0;
+      const subjectEval = makeEval(evalId, () => {
+        calls += 1;
+      });
+      const plan: RunFeedbackPlan = {
+        shape: { evals: 1, configs: 1, totalAttempts: 1, maxConcurrency: 2 },
+        reused: 0,
+        reusedFailures: [],
+      };
+
+      await withCoordinator(plan, async (coordinator) => {
+        let done = false;
+        // force 模式:cli.ts 在 --force 时整段不传 priorResults(不是传空数组)。
+        const runPromise = runWithPriorResults([subjectEval], [producerRun], { root, maxConcurrency: 2 }).then((r) => {
+          done = true;
+          return r;
+        });
+
+        await waitForRealProgress(() => expect(coordinator.state.elsewhere).toBe(1));
+        expect(coordinator.state.queued).toBe(0); // elsewhere 与 queued 互斥
+        expectCountIdentity(coordinator.state);
+
+        // 持有方正常收尾:锁文件消失,下一轮轮询即结束等待。
+        await rm(caseLockPath(root, experimentId, evalId), { force: true });
+        await advanceOnFakeClock(() => done, 10_000, 12);
+        const { summary } = await runPromise;
+
+        expect(calls).toBe(1); // --force:等完窗口后自跑,不消费磁盘上那条匹配终态
+        expect(coordinator.state.reused).toBe(0);
+        expect(coordinator.state.elsewhere).toBe(0); // 报进去 1 条,原数报了回来
+        expectCountIdentity(coordinator.state);
+        expect(summary.results).toHaveLength(1);
+        expect(summary.results[0]!.verdict).toBe("passed");
+        expect(await lockFilesRemaining(root)).toEqual([]);
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});
+
+describe("runEvals · 用例锁: 等待窗口的 elsewhere 收支平账", () => {
+  afterEach(() => {
+    expect(activeFeedbackSinkCount()).toBe(0);
+    expect(pendingHeldCaseLockCount()).toBe(0);
+  });
+
+  // 报进 elsewhere 的条数必须原数报回:等待期间被中断而提前 settle 的 attempt 会让「本组还剩
+  // 几条没收尾」缩水,收尾时拿当下的剩余条数当迁移数,差额就永远挂在 elsewhere 上。
+  it("挂起期间用户中断:runs: 2 整组报进 elsewhere 的两条被原数报回,elsewhere 归零、恒等式成立", async () => {
+    const root = await makeRoot();
+    const experimentId = "elsewhere-interrupt-exp";
+    const evalId = "elsewhere-interrupt-eval";
+    await seedCaseLock(root, freshLockRecord(experimentId, evalId));
+
+    let calls = 0;
+    const evalDef = makeEval(evalId, () => {
+      calls += 1;
+    });
+    const agentRun = probeRun(makeAgent("agent-elsewhere-interrupt"), experimentId, [evalId], { runs: 2 });
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 1, configs: 1, totalAttempts: 2, maxConcurrency: 2 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const ac = new AbortController();
+      const runPromise = runWithPriorResults([evalDef], [agentRun], {
+        priorResults: [],
+        root,
+        maxConcurrency: 2,
+        signal: ac.signal,
+      });
+
+      await waitForRealProgress(() => expect(coordinator.state.elsewhere).toBe(2));
+      ac.abort();
+      await runPromise;
+
+      // 窗口的收尾事件是被中断唤醒后才发的,可能晚于 runEvals 结算一个事件循环轮次。
+      await waitForRealProgress(() => expect(coordinator.state.elsewhere).toBe(0));
+      expectCountIdentity(coordinator.state);
+      expect(coordinator.state.queued).toBe(2); // 两条都退回 queued(中断路径不派发)
+      expect(calls).toBe(0);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+
+  // 接管 / 多开下补的那对瞬时 started+resolved 只报**真正携入**的那几条:runs > 1 时没携入的
+  // 兄弟从没离开 queued,把整组都报一遍会把 queued 扣穿成负数、reused 多记一条。
+  it("接管后重查携带命中一条:只有那一条走 elsewhere → reused,兄弟照常自跑且 queued 不被扣穿", async () => {
+    const root = await makeRoot();
+    const experimentId = "recheck-partial-count-exp";
+    const evalId = "recheck-partial-count-eval";
+    const agent = makeAgent("agent-recheck-partial-count");
+    const sandbox = fakeSandboxSpec();
+
+    // 先落一条序号 0 的 passed 终态(指纹由生产路径自己算)。
+    const producerRun = probeRun(agent, experimentId, [evalId], { sandbox });
+    const { summary: produced } = await run([makeEval(evalId, () => {})], [producerRun], { root });
+    expect(produced.results[0]!.verdict).toBe("passed");
+
+    // 产出方写完结果还没释放锁就死了:留一把过期锁,续接方接管时重查携带。
+    await seedCaseLock(root, staleLockRecord(experimentId, evalId));
+
+    const { barrier, release } = makeBarrier();
+    const probe = newDispatchProbe();
+    const subjectRun = probeRun(agent, experimentId, [evalId], { sandbox, runs: 2 });
+    const plan: RunFeedbackPlan = {
+      shape: { evals: 1, configs: 1, totalAttempts: 2, maxConcurrency: 2 },
+      reused: 0,
+      reusedFailures: [],
+    };
+
+    await withCoordinator(plan, async (coordinator) => {
+      const runPromise = runWithPriorResults([gatedEval(evalId, barrier, probe)], [subjectRun], {
+        priorResults: [],
+        root,
+        maxConcurrency: 2,
+      });
+      try {
+        // 冻结在「序号 0 已携入、序号 1 正在跑」这一帧上取样 —— 扣穿是瞬时中间态,跑完再看
+        // 计数已经自愈,只有这一帧能证明。
+        await waitForRealProgress(() => {
+          expect(coordinator.state.reused).toBe(1);
+          expect(probe.inFlight).toBe(1);
+        });
+        const mid = coordinator.state;
+        expect(mid.reused).toBe(1); // 只有真正携入的那一条迁进 reused
+        expect(mid.running).toBe(1);
+        expect(mid.queued).toBe(0); // 没携入的兄弟从没离开 queued,不被多扣一次
+        expect(mid.elsewhere).toBe(0);
+        expectCountIdentity(mid);
+      } finally {
+        release();
+      }
+
+      const { summary } = await runPromise;
+      expect(probe.started).toEqual([evalId]); // 只有缺的序号 1 真的派发过
+      expect(summary.results.map((r) => r.attempt).sort()).toEqual([0, 1]);
+      expect(coordinator.state.elsewhere).toBe(0);
+      expectCountIdentity(coordinator.state);
+      expect(await lockFilesRemaining(root)).toEqual([]);
+    });
+  }, SCHEDULING_TEST_TIMEOUT_MS);
+});