niceeval 0.13.1 → 0.13.2

package/dist/runner/run.cjs

@@ -33,7 +33,7 @@ const node_os_1 = require("node:os");
 const contracts_ts_1 = require("../plugin/contracts.cjs");
 const teardown_registry_ts_1 = require("./teardown-registry.cjs");
 const lock_ts_1 = require("./lock.cjs");
-const gate_lease_ts_1 = require("./gate-lease.cjs");
+const shared_state_lease_ts_1 = require("./shared-state-lease.cjs");
 const record_ts_1 = require("./record.cjs");
 const runner_producer_ts_1 = require("../o11y/record/runner-producer.cjs");
 const sandbox_reuse_ts_1 = require("./sandbox-reuse.cjs");
@@ -48,6 +48,40 @@ function feedbackIdentity(a) {
 function feedbackWho(a) {
     return (0, types_ts_1.runWho)({ agentName: a.run.agent.name, model: a.run.model, experimentId: a.run.experimentId });
 }
+const SHARED_BUILD_FAILURE_DIAGNOSTIC = "sandbox-build-failed";
+function sharedBuildFailureRoot(error) {
+    const codeMatch = /\bERR_[A-Z0-9_]+\b/u.exec(error.message);
+    const code = codeMatch?.[0] ?? error.code;
+    const focused = codeMatch === null
+        ? error.message.slice(-600)
+        : error.message.slice(codeMatch.index, codeMatch.index + 600);
+    return { code, message: focused.trim() || error.message.slice(-600).trim() || error.code };
+}
+function sharedBuildFailureDetail(a, error) {
+    const failureId = error.origin.scope === "run"
+        ? error.origin.timingNodeId
+        : `${error.code}:${a.evalDef.id}`;
+    const root = sharedBuildFailureRoot(error);
+    let message = root.message;
+    const encode = () => JSON.stringify({
+        schema: "niceeval.shared-build-failure/v1",
+        failureId,
+        evalId: a.evalDef.id,
+        attemptOrdinal: a.attempt,
+        phase: "sandbox.image.build",
+        errorCode: root.code,
+        message,
+        ...(root.code === "ERR_PNPM_IGNORED_BUILDS"
+            ? { remediation: "pnpm-allow-builds" }
+            : {}),
+    });
+    let encoded = encode();
+    while (new TextEncoder().encode(encoded).byteLength > 1000 && message.length > 0) {
+        message = message.slice(0, Math.floor(message.length * 0.75));
+        encoded = encode();
+    }
+    return encoded;
+}
 function attemptIdentityKey(experimentId, agentName, model, evalId) {
     return JSON.stringify([experimentId, agentName, model ?? null, evalId]);
 }
@@ -210,7 +244,7 @@ function runEvals(opts) {
             return failure === undefined ? [] : [failure];
         }));
         if (opts.onCurrentRecordReusePlan !== undefined) {
-            yield* opts.onCurrentRecordReusePlan({ reused: reusedAttempts.length, reusedFailures });
+            yield* opts.onCurrentRecordReusePlan({ reused: reusedAttempts.length, reusedFailures, runIds });
         }
         else {
             // Direct library callers have no feedback coordinator. Preserve their
@@ -395,6 +429,11 @@ function runEvals(opts) {
         const judgePrecheckFailures = new Map();
         {
             const uniquePairs = [...new Map(attempts.map((a) => [(0, fingerprint_ts_1.cacheKey)(a.run, a.evalDef.id), a])).entries()];
+            const plannedByPair = new Map();
+            for (const attempt of attempts) {
+                const pairKey = (0, fingerprint_ts_1.cacheKey)(attempt.run, attempt.evalDef.id);
+                plannedByPair.set(pairKey, (plannedByPair.get(pairKey) ?? 0) + 1);
+            }
             const { targets, evalKeys } = judgeProbePlan(uniquePairs.map(([id, a]) => ({
                 id,
                 judge: a.judge,
@@ -410,13 +449,35 @@ function runEvals(opts) {
                 const failedByKey = new Map();
                 for (const target of targets) {
                     const err = yield* (0, judge_ts_1.probeJudgeEffect)(target.judge, opts.signal);
-                    if (err)
+                    if (err) {
                         failedByKey.set(target.key, err);
+                    }
                 }
                 for (const [pairKey, key] of evalKeys) {
                     const err = failedByKey.get(key);
-                    if (err !== undefined)
-                        judgePrecheckFailures.set(pairKey, err);
+                    if (err === undefined)
+                        continue;
+                    judgePrecheckFailures.set(pairKey, err);
+                    const pair = uniquePairs.find(([candidate]) => candidate === pairKey)?.[1];
+                    if (pair === undefined)
+                        continue;
+                    const planned = plannedByPair.get(pairKey) ?? 1;
+                    // No Attempt exists yet, so this pair-owned warning is the stable
+                    // machine projection: identity and terminal counts travel in data,
+                    // without fabricating a locator-addressable eval event.
+                    (0, sink_ts_1.reportDiagnostic)({
+                        key: `judge-precheck-failed:${pairKey}`,
+                        code: "judge-precheck-failed",
+                        severity: "error",
+                        message: err,
+                        data: {
+                            phase: "judge.precheck",
+                            ...(pair.run.experimentId === undefined ? {} : { experimentId: pair.run.experimentId }),
+                            evalId: pair.evalDef.id,
+                            planned,
+                            errored: planned,
+                        },
+                    });
                 }
                 (0, sink_ts_1.reportPrecheck)({
                     status: failedByKey.size > 0 ? "failed" : "done",
@@ -614,6 +675,8 @@ function runEvals(opts) {
         const sandboxSem = yield* effect_1.Effect.makeSemaphore(opts.maxConcurrency);
         // 相同 provider physical identity 共享一个按需池；不从 AgentRun 重选 template。
         const reusePools = new Map();
+        /** A terminal Experiment freezes its own registry before physical stop. */
+        const frozenReusePoolRuns = new Set();
         // A physical Sandbox number is Run-wide, not pool-local: distinct Eval
         // Groups may materialize identical provider plans concurrently and must not
         // both report `reuseSandbox: 1` for different instances.
@@ -650,6 +713,9 @@ function runEvals(opts) {
             if (key === undefined || a.plan._tag !== "Sandbox") {
                 return effect_1.Effect.succeed({ _tag: "Fresh" });
             }
+            if (frozenReusePoolRuns.has(a.run)) {
+                return effect_1.Effect.die(new Error("Sandbox reuse registry was frozen before this Attempt could acquire a pool."));
+            }
             let bySpec = reusePools.get(a.run);
             if (bySpec === undefined) {
                 bySpec = new Map();
@@ -690,20 +756,31 @@ function runEvals(opts) {
             }
             return effect_1.Effect.succeed({ _tag: "Reuse", pool });
         };
-        // 两级并发闸:全局(opts.maxConcurrency)+ 实验级(AgentRun.maxConcurrency,可选)。
-        // 实验级闸让「有共享状态、必须串行」的实验(如跨 eval 累积记忆,maxConcurrency: 1)只在
-        // 自己内部排队,同批其它实验照常并发。它的名额域跨 Invocation 共用(见 gate-lease.ts 与
-        // docs/feature/experiments/architecture.md「并发 Invocation:用例锁」末条),所以名额不是
-        // 进程内信号量而是磁盘上的逐槽租约——多开不叠加 N,`maxConcurrency: 1` 的临界区声明在
-        // 多开下同样成立。全局位反过来是每条 Invocation 私有的吞吐旋钮,仍是进程内信号量。
+        /**
+         * Pool ownership is Experiment-scoped, not Invocation-scoped. The last
+         * Attempt settlement freezes this registry before stop starts, so no late
+         * acquire can create another physical Sandbox between pool stop and the
+         * Experiment hook's checkpoint/teardown work.
+         */
+        const freezeReusablePoolsForRun = (run) => effect_1.Effect.sync(() => {
+            frozenReusePoolRuns.add(run);
+        }).pipe(effect_1.Effect.zipRight(effect_1.Effect.forEach([...(reusePools.get(run)?.values() ?? [])], (pool) => pool.freeze(), { concurrency: "unbounded", discard: true })));
+        const stopReusablePoolsForRun = (run) => effect_1.Effect.gen(function* () {
+            const exits = yield* effect_1.Effect.forEach([...(reusePools.get(run)?.values() ?? [])], (pool) => effect_1.Effect.exit(pool.stop()), { concurrency: "unbounded" });
+            const failures = [];
+            for (const exit of exits) {
+                if (effect_1.Exit.isFailure(exit))
+                    failures.push(effect_1.Cause.squash(exit.cause));
+            }
+            if (failures.length > 0) {
+                return yield* effect_1.Effect.fail(new AggregateError(failures, "Sandbox reuse pool cleanup failed."));
+            }
+        });
+        // 两级并发闸:全局(opts.maxConcurrency)+ 实验级(AgentRun.maxConcurrency,可选)。两者都只
+        // 属于本 Invocation；跨 Invocation 的共享外部状态由 sharedState 租约另行保护，不能把
+        // `maxConcurrency` 误当成跨进程临界区。
         const globalSem = yield* effect_1.Effect.makeSemaphore(opts.maxConcurrency);
-        // 实验闸在进程内先垫一层同名额的信号量,再去取租约。两个原因:
-        // ① 名额在本进程内部交接是即时的(Effect 信号量把 permit 直接递给排队的下一个 attempt),
-        //    不必等租约轮询的下一个周期——单开是绝大多数场景,不该为跨进程协调付整整一个轮询周期
-        //    的空转;② 同实验同时去拍磁盘的 attempt 至多 N 个,不让 runs 展开出的一大批兄弟一起
-        //    轮询。它只会更严、不会更松:permit 数恒等于该实验 resolved 的 N,真正的名额权威仍是
-        //    租约(跨 Invocation 共用、min-N 收紧)。裸 run(没有 experimentId、没有可共享的名额域)
-        //    就只有这一层,不产生任何跨进程协调。
+        // 实验闸是 Invocation 内信号量：同实验的 attempt 即时交接 permit，同批其它实验不受影响。
         const gateLocalSems = new Map();
         for (const run of effectiveAgentRuns) {
             if (run.maxConcurrency !== undefined) {
@@ -754,7 +831,7 @@ function runEvals(opts) {
         };
         const expLifecycles = new Map();
         for (const a of attempts) {
-            if (!a.run.setup && !a.run.teardown)
+            if (!a.run.setup && !a.run.teardown && !a.run.sharedState)
                 continue;
             const cell = expLifecycles.get(a.run);
             if (cell) {
@@ -766,9 +843,18 @@ function runEvals(opts) {
                 expLifecycles.set(a.run, {
                     state: { _tag: "Dormant", pendingAttempts: new Set([a]) },
                     mutex: yield* effect_1.Effect.makeSemaphore(1),
+                    physicalCleanupFailures: [],
                 });
             }
         }
+        const recordFreshSandboxCleanupFailure = (run, failure) => {
+            if (run.sharedState === undefined)
+                return;
+            const cell = expLifecycles.get(run);
+            if (cell === undefined)
+                return;
+            cell.physicalCleanupFailures.push(failure);
+        };
         // 实验域诊断累积器(docs/runner.md「实验域诊断持久化」):只接无法归属单 Attempt 的实验
         // 事实——ctx.diagnostic、teardown failed/late、budget-unenforceable。相同 dedupeKey 只在
         // 同一个 experimentId 桶内折叠 count;不同 Experiment 各自独立累计,不跨来源合并。裸 run
@@ -818,10 +904,74 @@ function runEvals(opts) {
             list.push(record);
             experimentDiagnostics.set(input.experimentId, list);
         };
+        /**
+         * Owner tokens are an explicit inspection capability, not ordinary Runner
+         * feedback. Keep both the live feedback event and the durable Run diagnostic
+         * limited to the key and recovery obligation; `exp --teardown` is the only
+         * public surface that renders immutable owner evidence.
+         */
+        const reportSharedStateRecoveryRequired = (input) => {
+            const key = input.run.sharedState?.key ?? "";
+            const message = (0, index_ts_1.t)("runner.sharedStateRecoveryRequired", { key }).trimEnd();
+            (0, sink_ts_1.reportDiagnostic)({
+                key: `state-lease-recovery-required:${key || input.experimentId}`,
+                code: "state-lease-recovery-required",
+                severity: "warning",
+                message,
+                data: {
+                    experimentId: input.experimentId,
+                    sharedStateKey: key,
+                    reason: input.reason,
+                },
+            });
+            recordExperimentDiagnostic({
+                experimentId: input.run.experimentId,
+                code: "state-lease-recovery-required",
+                level: "warning",
+                message,
+                phase: input.phase,
+                data: { sharedStateKey: key, reason: input.reason },
+            });
+        };
+        /**
+         * A blocked sharedState acquisition is normal contention. It is deliberately
+         * an info notice and deliberately does not enter a Run's durable diagnostic
+         * list: there is no cleanup obligation and no owner evidence to expose.
+         */
+        const acquireSharedStateClaim = (run, experimentId) => effect_1.Effect.gen(function* () {
+            const sharedState = run.sharedState;
+            if (sharedState === undefined) {
+                return yield* effect_1.Effect.die(new Error("Attempted to acquire an undeclared sharedState lease."));
+            }
+            const processIdentity = sharedStateProcessIdentity ?? (yield* (0, shared_state_lease_ts_1.currentProcessIdentityEffect)());
+            sharedStateProcessIdentity = processIdentity;
+            const acquired = yield* (0, shared_state_lease_ts_1.acquireSharedStateLeaseEffect)(coordinationRoot, sharedState.key, {
+                experimentId,
+                pid: process.pid,
+                host: currentHost,
+                processIdentity,
+            }, {
+                ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+                onWaitStart: () => {
+                    const message = (0, index_ts_1.t)("runner.sharedStateWaiting", { key: sharedState.key }).trimEnd();
+                    (0, sink_ts_1.reportDiagnostic)({
+                        key: `state-lease-waiting:${sharedState.key}`,
+                        code: "state-lease-waiting",
+                        severity: "info",
+                        message,
+                        data: { experimentId, sharedStateKey: sharedState.key },
+                    });
+                },
+            });
+            return acquired.claim;
+        });
         // 强杀后的收尾兜底(docs/feature/experiments/architecture.md「强杀后的收尾兜底」)的磁盘登记
         // 挂在本地协调根下,与留存注册表 `.niceeval/sandboxes/` 同一个根（默认 cwd/.niceeval，
         // 与 attempt.ts 的 `coordinationRoot` 兜底同一口径）。
         const currentHost = (0, node_os_1.hostname)();
+        // Establish process identity lazily: only a configured sharedState opts in
+        // to this fail-closed cross-process coordination requirement.
+        let sharedStateProcessIdentity;
         const makeExperimentHookContext = (run, phase) => {
             const experimentId = run.experimentId;
             return {
@@ -869,6 +1019,35 @@ function runEvals(opts) {
                 return setup;
             throw new Error("Experiment setup completed without recording its terminal outcome.");
         };
+        const releaseSharedStateLease = (run, cell, cleanupSucceeded) => effect_1.Effect.suspend(() => {
+            const claim = cell.sharedStateClaim;
+            return effect_1.Effect.sync(() => claim).pipe(effect_1.Effect.flatMap((heldClaim) => {
+                const claim = heldClaim;
+                if (claim === undefined)
+                    return effect_1.Effect.void;
+                const experimentId = run.experimentId ?? run.agent.name;
+                const recoveryRequired = (reason) => effect_1.Effect.sync(() => {
+                    reportSharedStateRecoveryRequired({
+                        run,
+                        experimentId,
+                        reason,
+                        phase: "experiment.teardown",
+                    });
+                });
+                if (!cleanupSucceeded()) {
+                    // A retained lease is a durable recovery obligation, not a reason
+                    // to leave a daemon heartbeat/timer behind after this Invocation.
+                    // `abandon` cannot delete or rewrite the record.
+                    cell.sharedStateClaim = undefined;
+                    return claim.abandon.pipe(effect_1.Effect.catchAll(() => effect_1.Effect.void), effect_1.Effect.zipRight(recoveryRequired("cleanup-failed")));
+                }
+                // Once release starts its heartbeat is interrupted. Do not retain a
+                // stale in-memory claim after a failed compare-owner mutation; its
+                // durable record is deliberately left for explicit recovery.
+                cell.sharedStateClaim = undefined;
+                return claim.release.pipe(effect_1.Effect.catchAll(() => recoveryRequired("release-failed")));
+            }));
+        });
         const runExperimentTeardown = (run, cell) => effect_1.Effect.uninterruptibleMask((restore) => cell.mutex.withPermits(1)(effect_1.Effect.gen(function* () {
             const current = cell.state;
             // setup 时点没走到就没有收尾义务；已完成与在飞状态分别复用自己的确定 Effect。
@@ -887,52 +1066,106 @@ function runEvals(opts) {
                 setup: current.setup,
                 completion,
             };
+            let cleanupSucceeded = true;
             const teardown = effect_1.Effect.gen(function* () {
-                // 强清可能先取得收尾执行权；必须等 setup 的 Effect 结算后再清理。
-                yield* awaitSetup(current.setup);
-                if (!run.teardown)
-                    return;
-                (0, sink_ts_1.reportExperimentHook)({ experimentId, hook: "teardown", status: "started" });
-                const startedAt = Date.now();
-                const ctx = makeExperimentHookContext(run, "experiment.teardown");
-                yield* (0, cleanup_timeout_ts_1.cleanupCallback)(() => run.teardown(ctx)).pipe(effect_1.Effect.matchEffect({
-                    onSuccess: () => effect_1.Effect.sync(() => {
-                        (0, sink_ts_1.reportExperimentHook)({
-                            experimentId,
-                            hook: "teardown",
-                            status: "done",
-                            durationMs: Date.now() - startedAt,
-                        });
-                    }),
-                    onFailure: (error) => effect_1.Effect.sync(() => {
-                        (0, sink_ts_1.reportExperimentHook)({
-                            experimentId,
-                            hook: "teardown",
-                            status: "failed",
-                            durationMs: Date.now() - startedAt,
-                        });
-                        // teardown 失败只作运行级诊断，不改任何已产出的 verdict。
-                        const message = (0, index_ts_1.t)("runner.experimentTeardownFailed", {
-                            experimentId,
-                            message: error instanceof Error ? error.message : String(error),
-                        }).trimEnd();
-                        (0, sink_ts_1.reportDiagnostic)({
-                            key: `experiment-teardown-failed:${experimentId}`,
-                            code: "experiment-teardown-failed",
-                            severity: "warning",
-                            message,
-                            data: { experimentId },
-                        });
-                        recordExperimentDiagnostic({
-                            experimentId: run.experimentId,
-                            code: "experiment-teardown-failed",
-                            level: "warning",
-                            message,
-                            phase: "experiment.teardown",
-                        });
-                    }),
-                }));
-                // 这个 Experiment 真正走完 teardown（不论成败）的时刻。
+                // A failed setup still has teardown obligations. Capture its outcome
+                // rather than short-circuiting the physical pool/provider cleanup.
+                yield* effect_1.Effect.exit(awaitSetup(current.setup));
+                // Last Attempt settle -> freeze registry -> stop every reusable pool
+                // (Sandbox lifecycle teardown + provider finalizer) -> author hook.
+                // Stop failures are recorded but never skip later cleanup.
+                const pools = yield* effect_1.Effect.exit(freezeReusablePoolsForRun(run).pipe(effect_1.Effect.zipRight(stopReusablePoolsForRun(run))));
+                if (effect_1.Exit.isFailure(pools)) {
+                    cleanupSucceeded = false;
+                    const message = `Sandbox reuse cleanup failed before Experiment teardown: ${String(effect_1.Cause.squash(pools.cause))}`;
+                    (0, sink_ts_1.reportDiagnostic)({
+                        key: `sandbox-reuse-cleanup-failed:${experimentId}`,
+                        code: "sandbox-reuse-cleanup-failed",
+                        severity: "warning",
+                        message,
+                        data: { experimentId },
+                    });
+                    recordExperimentDiagnostic({
+                        experimentId: run.experimentId,
+                        code: "sandbox-reuse-cleanup-failed",
+                        level: "warning",
+                        message,
+                        phase: "experiment.teardown",
+                    });
+                }
+                // Fresh Sandbox Scopes close inside their owning Attempt and have
+                // therefore already reached a real terminal state by the time the
+                // final Attempt settles. Runtime converts hook/provider failures into
+                // diagnostics to preserve the remaining finalizers, so consult the
+                // Experiment cell's physical ledger before deciding whether its
+                // sharedState lease can be released.
+                if (cell.physicalCleanupFailures.length > 0) {
+                    cleanupSucceeded = false;
+                    const details = cell.physicalCleanupFailures
+                        .map((failure) => `${failure.stage}: ${failure.error.message}`)
+                        .join("; ");
+                    const message = `Fresh Sandbox cleanup failed before Experiment teardown: ${details}`;
+                    (0, sink_ts_1.reportDiagnostic)({
+                        key: `sandbox-fresh-cleanup-failed:${experimentId}`,
+                        code: "sandbox-fresh-cleanup-failed",
+                        severity: "warning",
+                        message,
+                        data: { experimentId, failureCount: cell.physicalCleanupFailures.length },
+                    });
+                    recordExperimentDiagnostic({
+                        experimentId: run.experimentId,
+                        code: "sandbox-fresh-cleanup-failed",
+                        level: "warning",
+                        message,
+                        phase: "experiment.teardown",
+                    });
+                }
+                if (run.teardown) {
+                    (0, sink_ts_1.reportExperimentHook)({ experimentId, hook: "teardown", status: "started" });
+                    const startedAt = Date.now();
+                    const ctx = makeExperimentHookContext(run, "experiment.teardown");
+                    yield* (0, cleanup_timeout_ts_1.cleanupCallback)(() => run.teardown(ctx)).pipe(effect_1.Effect.matchEffect({
+                        onSuccess: () => effect_1.Effect.sync(() => {
+                            (0, sink_ts_1.reportExperimentHook)({
+                                experimentId,
+                                hook: "teardown",
+                                status: "done",
+                                durationMs: Date.now() - startedAt,
+                            });
+                        }),
+                        onFailure: (error) => effect_1.Effect.sync(() => {
+                            cleanupSucceeded = false;
+                            (0, sink_ts_1.reportExperimentHook)({
+                                experimentId,
+                                hook: "teardown",
+                                status: "failed",
+                                durationMs: Date.now() - startedAt,
+                            });
+                            // Teardown failure never skips subsequent release handling, but
+                            // it makes automatic lease release unsafe.
+                            const message = (0, index_ts_1.t)("runner.experimentTeardownFailed", {
+                                experimentId,
+                                message: error instanceof Error ? error.message : String(error),
+                            }).trimEnd();
+                            (0, sink_ts_1.reportDiagnostic)({
+                                key: `experiment-teardown-failed:${experimentId}`,
+                                code: "experiment-teardown-failed",
+                                severity: "warning",
+                                message,
+                                data: { experimentId },
+                            });
+                            recordExperimentDiagnostic({
+                                experimentId: run.experimentId,
+                                code: "experiment-teardown-failed",
+                                level: "warning",
+                                message,
+                                phase: "experiment.teardown",
+                            });
+                        }),
+                    }));
+                }
+                // This Experiment has reached its terminal cleanup point whether its
+                // individual cleanup steps succeeded or failed.
                 experimentCompletedAt.set(experimentId, new Date().toISOString());
             }).pipe(effect_1.Effect.ensuring(cell.mutex.withPermits(1)(effect_1.Effect.gen(function* () {
                 const state = cell.state;
@@ -946,15 +1179,37 @@ function runEvals(opts) {
                 if (run.experimentId) {
                     yield* (0, teardown_registry_ts_1.removeTeardownRegistrationIfPresentEffect)(coordinationRoot, (0, teardown_registry_ts_1.teardownEntryId)(run.experimentId, process.pid)).pipe(effect_1.Effect.ignore);
                 }
-            }))));
-            const settle = effect_1.Effect.exit(restore(teardown)).pipe(effect_1.Effect.flatMap((exit) => effect_1.Deferred.done(completion, exit)), effect_1.Effect.asVoid);
-            yield* restore(settle).pipe(effect_1.Effect.forkIn(invocationScope));
+            }))), 
+            // Include both the cleanup body and its lifecycle-registration
+            // finalizer in this decision. A failure while unregistering the
+            // teardown ownership is still an incomplete cleanup and must retain
+            // the sharedState lease; release itself remains outside this check.
+            effect_1.Effect.onExit((exit) => effect_1.Exit.isFailure(exit)
+                ? effect_1.Effect.sync(() => {
+                    cleanupSucceeded = false;
+                })
+                : effect_1.Effect.void), 
+            // Lease release happens only when all prior cleanup was successful.
+            // Otherwise the durable owner token remains for the public explicit
+            // recovery command; the CLI exit sweep is not allowed to erase it.
+            // Read `cleanupSucceeded` only when this finalizer executes. Passing
+            // its current boolean while constructing the pipeline would capture
+            // the initial `true` and could release after a later teardown failure.
+            effect_1.Effect.ensuring(effect_1.Effect.suspend(() => releaseSharedStateLease(run, cell, () => cleanupSucceeded))));
+            // The initiating waiter may be interrupted, but the one published
+            // cleanup fiber must still advance through every later cleanup stage.
+            // `cleanupCallback` remains explicitly interruptible for its own
+            // bounded timeout; this mask only prevents a caller's cancellation from
+            // skipping pool stop or Experiment teardown entirely.
+            const settle = effect_1.Effect.exit(effect_1.Effect.uninterruptible(teardown)).pipe(effect_1.Effect.flatMap((exit) => effect_1.Deferred.done(completion, exit)), effect_1.Effect.asVoid);
+            yield* settle.pipe(effect_1.Effect.forkIn(invocationScope));
             return completion;
         })).pipe(effect_1.Effect.flatMap((completion) => completion === undefined ? effect_1.Effect.void : restore(effect_1.Deferred.await(completion)))));
         /**
          * 启动自愈:本实验触发 setup 之前,先核对磁盘上是否有它自己的遗留登记——上一次运行同一
          * experimentId 被强杀、来不及删除。同宿主且 pid 已死才是遗留义务;pid 活或异宿主可能是
-         * 并发 run,不触碰。先原子删登记拿到执行权,再补执行一次它的 teardown(新进程语义:
+         * 并发 run,不触碰。sharedState caller 必须已先取得同 key exact authority；再原子删登记拿到执行权,
+         * 再补执行一次它的 teardown(新进程语义:
          * ctx.selectedEvalIds 从登记恢复,不依赖已丢失的 setup 产物)。失败只记诊断,不阻断、
          * 不重试本次 run 的调度——recovery 补偿的是上一次的泄漏,不是这一次的前提条件。
          */
@@ -1039,123 +1294,174 @@ function runEvals(opts) {
                 }
             });
         });
+        // Startup recovery can exist even when every Attempt is carried (or there
+        // are no selected Attempts), so it cannot borrow an ExperimentLifecycleCell.
+        // Each selected run instead gets an independent completion gate; the first
+        // real setup awaits the same gate before it can claim or initialize state.
+        const startupRecoveryCompletions = new Map();
+        const startupRecoveryCompletionsToAwait = [];
         const ensureExperimentSetup = (a) => {
             const cell = expLifecycles.get(a.run);
-            return effect_1.Effect.uninterruptibleMask((restore) => cell.mutex.withPermits(1)(effect_1.Effect.gen(function* () {
-                const current = cell.state;
-                if (current._tag === "Active" || current._tag === "TearingDown")
-                    return current.setup;
-                if (current._tag === "TornDown")
-                    return undefined;
-                if (current._tag === "UntriggeredComplete") {
-                    return yield* effect_1.Effect.die(new Error("Experiment lifecycle cannot be triggered after all attempts settled."));
-                }
-                const run = a.run;
-                const experimentId = run.experimentId ?? run.agent.name;
-                const completion = yield* effect_1.Deferred.make();
-                // 先写 Active、再登记和启动 worker：随后任何 attempt 或强清都会复用同一个 Effect 完成点。
-                cell.state = {
-                    _tag: "Active",
-                    pendingAttempts: current.pendingAttempts,
-                    setup: { _tag: "InProgress", completion },
-                };
-                if (run.teardown) {
-                    yield* (0, experiment_cleanup_registry_ts_1.registerExperimentTeardown)(experimentId, () => runExperimentTeardown(run, cell));
-                }
-                let setupStartedAt;
-                const setupBody = effect_1.Effect.gen(function* () {
-                    // 上一进程的遗留收尾先补做，再原子写入本次登记；两步都先于 setup。
-                    if (run.teardown && run.experimentId) {
-                        yield* recoverOrphanedTeardownRegistration(run, experimentId);
-                        yield* (0, teardown_registry_ts_1.writeTeardownRegistrationEffect)(coordinationRoot, {
-                            experimentId: run.experimentId,
-                            selectedEvalIds: run.selectedEvalIds,
-                            pid: process.pid,
-                            host: currentHost,
-                            startedAt: new Date().toISOString(),
-                        }).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.sync(() => {
-                            const message = (0, index_ts_1.t)("runner.teardownRegistrationWriteFailed", {
-                                experimentId,
-                                message: error instanceof Error ? error.message : String(error),
-                            }).trimEnd();
-                            (0, sink_ts_1.reportDiagnostic)({
-                                key: `teardown-registration-write-failed:${experimentId}`,
-                                code: "teardown-registration-write-failed",
-                                severity: "warning",
-                                message,
-                                data: { experimentId },
-                            });
-                            recordExperimentDiagnostic({
-                                experimentId: run.experimentId,
-                                code: "teardown-registration-write-failed",
-                                level: "warning",
-                                message,
-                                phase: "experiment.setup",
-                            });
-                        })));
+            return effect_1.Effect.uninterruptibleMask((restore) => {
+                const startupRecovery = startupRecoveryCompletions.get(a.run);
+                return (startupRecovery === undefined ? effect_1.Effect.void : restore(effect_1.Deferred.await(startupRecovery))).pipe(effect_1.Effect.zipRight(cell.mutex.withPermits(1)(effect_1.Effect.gen(function* () {
+                    const current = cell.state;
+                    if (current._tag === "Active" || current._tag === "TearingDown")
+                        return current.setup;
+                    if (current._tag === "TornDown")
+                        return undefined;
+                    if (current._tag === "UntriggeredComplete") {
+                        return yield* effect_1.Effect.die(new Error("Experiment lifecycle cannot be triggered after all attempts settled."));
                     }
-                    if (!run.setup)
-                        return;
-                    setupStartedAt = Date.now();
-                    (0, sink_ts_1.reportExperimentHook)({ experimentId, hook: "setup", status: "started" });
-                    const ctx = makeExperimentHookContext(run, "experiment.setup");
-                    const value = yield* effect_1.Effect.tryPromise({
-                        try: () => Promise.resolve().then(() => run.setup(ctx)),
-                        catch: (error) => error,
-                    });
-                    const returned = value;
-                    if (typeof returned === "function") {
-                        // tsx 旧式 setup cleanup 只在 author callback 边界适配；主错误说明迁移方向。
-                        yield* (0, cleanup_timeout_ts_1.cleanupCallback)(returned).pipe(effect_1.Effect.catchAll(() => effect_1.Effect.void));
-                        return yield* effect_1.Effect.fail(new Error((0, index_ts_1.t)("runner.setupReturnedCleanup", {
-                            layer: `ExperimentDef.setup (${experimentId})`,
-                            hint: "ExperimentDef.teardown",
-                        }).trimEnd()));
+                    const run = a.run;
+                    const experimentId = run.experimentId ?? run.agent.name;
+                    if (run.sharedState && cell.sharedStateClaim === undefined) {
+                        cell.sharedStateClaim = yield* restore(acquireSharedStateClaim(run, experimentId));
                     }
-                    (0, sink_ts_1.reportExperimentHook)({
-                        experimentId,
-                        hook: "setup",
-                        status: "done",
-                        durationMs: Date.now() - (setupStartedAt ?? Date.now()),
-                    });
-                });
-                const setupWorker = setupBody.pipe(effect_1.Effect.matchEffect({
-                    onSuccess: () => replaceSetup(cell, { _tag: "Succeeded" }),
-                    onFailure: (error) => effect_1.Effect.sync(() => {
+                    const completion = yield* effect_1.Deferred.make();
+                    // 先写 Active、再登记和启动 worker：随后任何 attempt 或强清都会复用同一个 Effect 完成点。
+                    cell.state = {
+                        _tag: "Active",
+                        pendingAttempts: current.pendingAttempts,
+                        setup: { _tag: "InProgress", completion },
+                    };
+                    if (run.teardown || run.sharedState) {
+                        yield* (0, experiment_cleanup_registry_ts_1.registerExperimentTeardown)(experimentId, () => runExperimentTeardown(run, cell));
+                    }
+                    let setupStartedAt;
+                    const setupBody = effect_1.Effect.gen(function* () {
+                        // startup gate 已补做已有遗留收尾；sharedState 时此处已经持有同 key exact authority。
+                        // 再核对一次可覆盖 gate 之后才出现的孤儿登记，随后原子写入本次登记；两步都先于 setup。
+                        if (run.teardown && run.experimentId) {
+                            yield* recoverOrphanedTeardownRegistration(run, experimentId);
+                            yield* (0, teardown_registry_ts_1.writeTeardownRegistrationEffect)(coordinationRoot, {
+                                experimentId: run.experimentId,
+                                selectedEvalIds: run.selectedEvalIds,
+                                pid: process.pid,
+                                host: currentHost,
+                                startedAt: new Date().toISOString(),
+                            }).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.sync(() => {
+                                const message = (0, index_ts_1.t)("runner.teardownRegistrationWriteFailed", {
+                                    experimentId,
+                                    message: error instanceof Error ? error.message : String(error),
+                                }).trimEnd();
+                                (0, sink_ts_1.reportDiagnostic)({
+                                    key: `teardown-registration-write-failed:${experimentId}`,
+                                    code: "teardown-registration-write-failed",
+                                    severity: "warning",
+                                    message,
+                                    data: { experimentId },
+                                });
+                                recordExperimentDiagnostic({
+                                    experimentId: run.experimentId,
+                                    code: "teardown-registration-write-failed",
+                                    level: "warning",
+                                    message,
+                                    phase: "experiment.setup",
+                                });
+                            })));
+                        }
+                        if (!run.setup)
+                            return;
+                        setupStartedAt = Date.now();
+                        (0, sink_ts_1.reportExperimentHook)({ experimentId, hook: "setup", status: "started" });
+                        const ctx = makeExperimentHookContext(run, "experiment.setup");
+                        const value = yield* effect_1.Effect.tryPromise({
+                            try: () => Promise.resolve().then(() => run.setup(ctx)),
+                            catch: (error) => error,
+                        });
+                        const returned = value;
+                        if (typeof returned === "function") {
+                            // tsx 旧式 setup cleanup 只在 author callback 边界适配；主错误说明迁移方向。
+                            yield* (0, cleanup_timeout_ts_1.cleanupCallback)(returned).pipe(effect_1.Effect.catchAll(() => effect_1.Effect.void));
+                            return yield* effect_1.Effect.fail(new Error((0, index_ts_1.t)("runner.setupReturnedCleanup", {
+                                layer: `ExperimentDef.setup (${experimentId})`,
+                                hint: "ExperimentDef.teardown",
+                            }).trimEnd()));
+                        }
                         (0, sink_ts_1.reportExperimentHook)({
                             experimentId,
                             hook: "setup",
-                            status: "failed",
+                            status: "done",
                             durationMs: Date.now() - (setupStartedAt ?? Date.now()),
                         });
-                    }).pipe(effect_1.Effect.zipRight(replaceSetup(cell, {
-                        _tag: "Failed",
-                        error: { ...(0, attempt_ts_1.errorFromThrown)(error, "experiment.setup"), code: "experiment-setup-failed" },
-                    }))),
-                }), effect_1.Effect.onExit((exit) => {
-                    const recordUnexpectedExit = effect_1.Exit.isFailure(exit)
-                        ? replaceSetup(cell, {
+                    });
+                    const setupWorker = setupBody.pipe(effect_1.Effect.matchEffect({
+                        onSuccess: () => replaceSetup(cell, { _tag: "Succeeded" }),
+                        onFailure: (error) => effect_1.Effect.sync(() => {
+                            (0, sink_ts_1.reportExperimentHook)({
+                                experimentId,
+                                hook: "setup",
+                                status: "failed",
+                                durationMs: Date.now() - (setupStartedAt ?? Date.now()),
+                            });
+                        }).pipe(effect_1.Effect.zipRight(replaceSetup(cell, {
                             _tag: "Failed",
-                            error: {
-                                ...(0, attempt_ts_1.errorFromThrown)(effect_1.Cause.squash(exit.cause), "experiment.setup"),
-                                code: "experiment-setup-failed",
-                            },
-                        })
-                        : effect_1.Effect.void;
-                    return recordUnexpectedExit.pipe(effect_1.Effect.zipRight(effect_1.Deferred.done(completion, exit)), effect_1.Effect.asVoid);
-                }));
-                yield* restore(setupWorker).pipe(effect_1.Effect.forkIn(invocationScope));
-                return cell.state.setup;
-            })).pipe(effect_1.Effect.flatMap((setup) => setup === undefined ? effect_1.Effect.void : restore(awaitSetup(setup)))));
+                            error: { ...(0, attempt_ts_1.errorFromThrown)(error, "experiment.setup"), code: "experiment-setup-failed" },
+                        }))),
+                    }), effect_1.Effect.onExit((exit) => {
+                        const recordUnexpectedExit = effect_1.Exit.isFailure(exit)
+                            ? replaceSetup(cell, {
+                                _tag: "Failed",
+                                error: {
+                                    ...(0, attempt_ts_1.errorFromThrown)(effect_1.Cause.squash(exit.cause), "experiment.setup"),
+                                    code: "experiment-setup-failed",
+                                },
+                            })
+                            : effect_1.Effect.void;
+                        return recordUnexpectedExit.pipe(effect_1.Effect.zipRight(effect_1.Deferred.done(completion, exit)), effect_1.Effect.asVoid);
+                    }));
+                    yield* restore(setupWorker).pipe(effect_1.Effect.forkIn(invocationScope));
+                    return cell.state.setup;
+                })).pipe(effect_1.Effect.flatMap((setup) => setup === undefined ? effect_1.Effect.void : restore(awaitSetup(setup))))));
+            });
         };
-        // 自愈是「选中实验」的启动期职责，不是首个派发 attempt 的副作用：全携带使 attempts 为空时，
-        // 仍必须补上上一进程强杀遗留的收尾。无 teardown 的新定义无法安全补执行，交由 CLI 提醒。
-        const recoveredExperimentIds = new Set();
+        const hasOrphanedTeardownRegistration = (run) => effect_1.Effect.suspend(() => {
+            if (!run.experimentId || !run.teardown)
+                return effect_1.Effect.succeed(false);
+            return (0, teardown_registry_ts_1.readTeardownRegistrationsEffect)(coordinationRoot).pipe(effect_1.Effect.map((registrations) => registrations.some(({ entry }) => entry.experimentId === run.experimentId && (0, teardown_registry_ts_1.isOrphanedTeardownRegistration)(entry, currentHost))), 
+            // A missing or unreadable registration directory must never invent an
+            // orphan cleanup obligation. The normal setup path still records a
+            // diagnostic if it cannot write this Invocation's own registration.
+            effect_1.Effect.catchAll(() => effect_1.Effect.succeed(false)));
+        });
+        /**
+         * Startup self-heal remains a selected-Experiment responsibility even for a
+         * full-carry / zero-Attempt Invocation. For sharedState it first obtains the
+         * exact current key's authority. Thus an active or recovering generation is
+         * waited on, never implicitly torn down or replaced.
+         */
+        const recoverStartupOrphanedTeardown = (run, experimentId) => effect_1.Effect.gen(function* () {
+            if (!(yield* hasOrphanedTeardownRegistration(run)))
+                return;
+            if (run.sharedState === undefined) {
+                yield* recoverOrphanedTeardownRegistration(run, experimentId);
+                return;
+            }
+            const claim = yield* acquireSharedStateClaim(run, experimentId);
+            yield* recoverOrphanedTeardownRegistration(run, experimentId).pipe(effect_1.Effect.ensuring(claim.release.pipe(effect_1.Effect.catchAll(() => effect_1.Effect.sync(() => {
+                reportSharedStateRecoveryRequired({
+                    run,
+                    experimentId,
+                    reason: "startup-recovery-release-failed",
+                    phase: "experiment.teardown",
+                });
+            })))));
+        });
+        const startupRecoveryByExperimentId = new Map();
         for (const run of effectiveAgentRuns) {
-            if (!run.experimentId || !run.teardown || recoveredExperimentIds.has(run.experimentId))
+            if (!run.experimentId || !run.teardown)
                 continue;
-            recoveredExperimentIds.add(run.experimentId);
-            yield* recoverOrphanedTeardownRegistration(run, run.experimentId);
+            let completion = startupRecoveryByExperimentId.get(run.experimentId);
+            if (completion === undefined) {
+                const createdCompletion = yield* effect_1.Deferred.make();
+                completion = createdCompletion;
+                startupRecoveryByExperimentId.set(run.experimentId, createdCompletion);
+                startupRecoveryCompletionsToAwait.push(createdCompletion);
+                const recovery = recoverStartupOrphanedTeardown(run, run.experimentId).pipe(effect_1.Effect.exit, effect_1.Effect.flatMap((exit) => effect_1.Deferred.done(createdCompletion, exit)), effect_1.Effect.asVoid);
+                yield* recovery.pipe(effect_1.Effect.forkIn(invocationScope));
+            }
+            startupRecoveryCompletions.set(run, completion);
         }
         const settleExperimentAttempt = (a) => {
             const cell = expLifecycles.get(a.run);
@@ -1569,53 +1875,6 @@ function runEvals(opts) {
             if (claim !== undefined)
                 caseClaimsAwaitingPublication.push(claim);
         })));
-        /**
-         * 实验闸的取位:声明了 `maxConcurrency` 的实验从**跨 Invocation 共用**的逐槽租约取名额
-         * (gate-lease.ts);未声明的实验不走租约、不产生任何跨进程协调。取位在全局位之前——等名额
-         * 的 attempt 不占别的实验的并发位。返回 undefined 表示等待期间被中断,这条 attempt 就此放弃。
-         */
-        /**
-         * 撞满实验闸名额时报一条 info:名额域跨 Invocation,所以「等」的对象是别的进程,用户无从
-         * 从本进程的面板推断。生效名额与本次声明分开报——两者不等就是 min-N 夹低了(别的运行声明了
-         * 更小的 maxConcurrency),这是「我明明写了 3 却只跑 1 条」的唯一解释,不说清就只能去翻锁目录。
-         * 按实验折叠:同一实验的一堆 attempt 会前后脚撞上同一批持有者,不该刷屏。
-         */
-        const reportGateLeaseWait = (experimentId, declaredN, holders) => {
-            const effectiveN = holders.reduce((n, h) => Math.min(n, h.declaredN), declaredN);
-            const who = [...new Set(holders.map((h) => `pid ${h.pid}@${h.host}`))].join(", ") || "another run";
-            (0, sink_ts_1.reportDiagnostic)({
-                key: `gate-lease-waiting:${experimentId}`,
-                code: "gate-lease-waiting",
-                severity: "info",
-                message: (0, index_ts_1.t)("runner.gateLeaseWaiting", { experimentId, effectiveN, declaredN, holders: who }).trimEnd(),
-                data: { experimentId, effectiveN, declaredN },
-            });
-        };
-        const acquireGateLease = (experimentId, maxConcurrency) => effect_1.Effect.uninterruptibleMask((restore) => restore((0, gate_lease_ts_1.acquireGateSlotEffect)(coordinationRoot, experimentId, maxConcurrency, lockIdentity, {
-            // 撞满名额只发生在「别的 Invocation 正占着这个实验的位子」——本进程自己的并发早被
-            // gateLocalSems 挡在这一层之前了。不报的话面板就只剩 `0 running · N queued` 干等,
-            // 看不出在等什么、等谁,也看不出生效名额被对方更小的声明夹低了(min-N)。
-            onWaitStart: (holders) => reportGateLeaseWait(experimentId, maxConcurrency, holders),
-        })).pipe(effect_1.Effect.map(({ claim, takenOver, takenOverFrom }) => {
-            if (takenOver) {
-                const message = (0, index_ts_1.t)("runner.coordinationRecovered", { experimentId }).trimEnd();
-                (0, sink_ts_1.reportDiagnostic)({
-                    key: `${types_ts_1.COORDINATION_RECOVERED_CODE}:concurrency-slot:${experimentId}|${claim.slot}`,
-                    code: types_ts_1.COORDINATION_RECOVERED_CODE,
-                    severity: "info",
-                    message,
-                    data: {
-                        experimentId,
-                        resource: "concurrency-slot",
-                        slot: claim.slot,
-                        ...(takenOverFrom !== undefined
-                            ? { previousPid: takenOverFrom.pid, previousHost: takenOverFrom.host }
-                            : {}),
-                    },
-                });
-            }
-            return claim;
-        })));
         const withGlobalSlot = (haltSignal, use) => effect_1.Effect.uninterruptibleMask((restore) => {
             const state = { held: false };
             const release = effect_1.Effect.suspend(() => state.held
@@ -1641,24 +1900,11 @@ function runEvals(opts) {
                 ? restore(use({ release, reacquire }))
                 : effect_1.Effect.succeed({ kind: "recheck" })), effect_1.Effect.ensuring(release));
         });
-        /**
-         * 实验闸(② 道许可)的持有作用域:名额与 attempt **同生命周期**——从这里持有到执行体收尾
-         * (teardown 链、沙箱销毁)之后才归还,turn 退避等内部等待一律不释放
-         * (docs/runner.md「调度:有界并发」)。撞用例锁挂起是唯一的例外:那时执行体以 `suspend`
-         * 正常返回,作用域退出、名额归还,挂起结束后重新取——挂起的用例不占名额,否则同实验的
-         * 持锁方(可能就在另一条 Invocation 里)会被自己的等待方饿死。
-         */
+        /** Invocation 内实验闸的持有作用域。它只限制此 Invocation 的 attempt，不取得任何
+         * 跨进程资源；共享外部状态必须由 `sharedState` 生命周期租约保护。 */
         const withExperimentGate = (a, use) => {
-            const { maxConcurrency, experimentId } = a.run;
             const localSem = gateLocalSems.get(a.run);
-            if (maxConcurrency === undefined || localSem === undefined)
-                return use;
-            if (experimentId === undefined)
-                return localSem.withPermits(1)(use);
-            const leased = effect_1.Effect.uninterruptibleMask((restore) => effect_1.Effect.raceFirst(restore(acquireGateLease(experimentId, maxConcurrency)).pipe(effect_1.Effect.map((claim) => ({ kind: "acquired", claim }))), restore(haltAwait(a)).pipe(effect_1.Effect.as({ kind: "halted" }))).pipe(effect_1.Effect.flatMap((lease) => lease.kind === "halted"
-                ? effect_1.Effect.succeed({ kind: "recheck" })
-                : restore(use).pipe(effect_1.Effect.ensuring(lease.claim.release.pipe(effect_1.Effect.ignore))))));
-            return localSem.withPermits(1)(leased);
+            return localSem === undefined ? use : localSem.withPermits(1)(use);
         };
         // earlyExit:为每个 key 各建一个 AbortController。某 attempt 通过或 errored 时 abort 它,
         // 让并发进行中的同 key attempt 通过 signal 尽早退出,而不只是等排队的才能被跳过。
@@ -1669,9 +1915,11 @@ function runEvals(opts) {
                 evalAbortControllers.set(a.key, new AbortController());
             }
         }
-        // 有界派发:forEach 的 worker 数就是 maxConcurrency，不先给全部 Slot 建 fiber。
-        // worker 内仍按止损闸、实验闸、全局 permit、用例锁的顺序取得资源；退避可以占住
-        // 这个有界 worker，避免为了补位再造一层无界 scheduler。
+        // 所有 Slot 都先成为轻量 coordination fiber。执行资源仍由实验闸、globalSem 与
+        // provider lane 严格有界；但 sharedState / predecessor / lock 等待绝不能占住一个
+        // 有限 forEach worker，否则同 key waiter 会饿死持有者的后继 Slot，形成环形等待。
+        // 因而这里必须 unbounded：它只放大 suspendable fibers，不放大 Agent、Sandbox 或
+        // provider 的物理并发。
         // runAttemptEffect 只把「执行错误」收进 EvalResult.error(不 fail),
         // 但中断(Ctrl+C / kill)照常向上传播 —— 所以一条挂掉不会中断其它 attempt,而中断能停掉全部。
         //
@@ -1732,7 +1980,8 @@ function runEvals(opts) {
                 }
                 const budget = a.run.budget;
                 if (budget !== undefined) {
-                    // 只看已完成 attempt 的实测花费(见上方 BudgetState 注释),到顶就跳过新 attempt,
+                    // 只看已完成 attempt 的价目表估算成本(见上方 BudgetState 注释；observed
+                    // usage.costUSD 不参与),到顶就跳过新 attempt,
                     // 没到顶就立即放行——不等待、不做预测性节流。
                     const s = budgetState(budgetKey);
                     if (s.spent >= budget) {
@@ -1809,6 +2058,15 @@ function runEvals(opts) {
                                 : undefined;
                 if (blockedError !== undefined)
                     cancelReuseAttempt(a, true);
+                if (buildFailure !== undefined) {
+                    recordExperimentDiagnostic({
+                        experimentId: a.run.experimentId,
+                        code: SHARED_BUILD_FAILURE_DIAGNOSTIC,
+                        level: "error",
+                        message: sharedBuildFailureDetail(a, buildFailure),
+                        phase: "sandbox.queue",
+                    });
+                }
                 // A scheduler-admitted Attempt owns a durable identity before any
                 // attempt-owned sandbox, Agent, or Eval work begins. Reservation
                 // failure is invocation-fatal at the Record publish gate.
@@ -1929,6 +2187,13 @@ function runEvals(opts) {
                             // 到达调度器,不走错误通道向上传播——attempt fiber 的 E 保持 never,`errored`
                             // 仍是 eval runner 的合法结果而不是调度失败(architecture.md「Effect 边界」)。
                             onFailureClass: (declaration) => closeHaltGate(a, declaration),
+                            ...(a.run.sharedState !== undefined && poolSelection._tag === "Fresh"
+                                ? {
+                                    onFreshSandboxCleanupFailure: (failure) => {
+                                        recordFreshSandboxCleanupFailure(a.run, failure);
+                                    },
+                                }
+                                : {}),
                             onSealedEvaluation: (sealed) => recordCoordinator.noteSealedOrMarkIncomplete(recordedAttempt, sealed),
                         });
                     if (lease) {
@@ -2062,9 +2327,11 @@ function runEvals(opts) {
                 // 「报告回调串行化」不一致。
                 yield* reportMutex.withPermits(1)((0, report_ts_1.emitReporterEvent)(reporters, { type: "eval:complete", result }));
             });
-            // ③ 全局并发位 → ④ 派发时刻试锁 → preflight → 实验级 setup → body。
-            // 独占串行 provider(如 local):同一 provider 名的所有 attempt 共享一把 permit=1 的锁,
-            // 包在全局位之外(见上面 exclusiveSemFor 的注释)。
+            // ③ 全局并发位 → sharedState（如声明，先于 Eval lock）→ 派发时刻试锁 → preflight
+            // → 实验级 setup → provider/Sandbox/body。
+            // 独占串行 provider(如 local):同一 provider 名的所有 attempt 共享一把 permit=1 的锁。
+            // sharedState 获取与 Experiment setup 都是宿主协调，不能让等待者占着该 Provider lane；
+            // permit 只包真正触及 provider、Sandbox 与 Attempt body 的执行段。
             const exclusiveSem = exclusiveSemFor(a.plan);
             const arriveAtDispatchWave = dispatchWaveArrive.get(a);
             const dispatch = withGlobalSlot(haltAwait(a), (slot) => effect_1.Effect.gen(function* () {
@@ -2073,6 +2340,18 @@ function runEvals(opts) {
                 // 不在上面的竞速覆盖范围里(竞速只包全局位),闸可能正是在那段时间落下的。
                 if (checkDispatchHalt(a).halted)
                     return { kind: "recheck" };
+                // sharedState 的等待不得先占 Eval lock 或全局并发位，也不得运行 setup / 创建
+                // Sandbox。拿到租约后这个 Invocation 仍继续自己在本轮已形成的 plan，不采用别的
+                // Run 在等待期间发布的 attempt。
+                if (a.run.sharedState) {
+                    const proceed = yield* preflight;
+                    if (!proceed)
+                        return { kind: "done" };
+                    authorizedReuseAttempts.add(a);
+                    yield* slot.release;
+                    yield* ensureExperimentSetup(a);
+                    yield* slot.reacquire;
+                }
                 // 派发时刻取锁:授位之后才试,非阻塞。撞上别人持有的新鲜锁就把这个位子连同实验闸
                 // 名额一起还回去(返回 "suspend"),由外层转入 elsewhere 挂起;位子当场空出来,
                 // 排队中的下一条没被锁的用例接手。
@@ -2080,15 +2359,17 @@ function runEvals(opts) {
                     const outcome = yield* tryAcquireCase(caseState);
                     if (outcome.kind === "busy")
                         return { kind: "suspend", window: outcome.window };
-                    if (yield* recordCoordinator.adoptLatePublishedAttempt(a)) {
+                    if (!a.run.sharedState && (yield* recordCoordinator.adoptLatePublishedAttempt(a))) {
                         return { kind: "done" };
                     }
                 }
-                const proceed = yield* preflight;
-                if (!proceed)
-                    return { kind: "done" };
-                authorizedReuseAttempts.add(a);
-                if (a.run.setup || a.run.teardown) {
+                if (!a.run.sharedState) {
+                    const proceed = yield* preflight;
+                    if (!proceed)
+                        return { kind: "done" };
+                    authorizedReuseAttempts.add(a);
+                }
+                if (!a.run.sharedState && (a.run.setup || a.run.teardown)) {
                     // 实验级 setup:第一个通过派发许可的 attempt 真正执行,其余等同一个 memoized
                     // Effect completion（作者 setup 失败收进 lc.setupFailed，由 body 合成 errored 结果）。
                     // 等它的时候让出全局并发位(docs/runner.md「调度:有界并发」——内部等待一律让位,
@@ -2097,10 +2378,16 @@ function runEvals(opts) {
                     yield* ensureExperimentSetup(a);
                     yield* slot.reacquire;
                 }
-                yield* body(slot);
-                return { kind: "done" };
+                const physicalBody = body(slot).pipe(effect_1.Effect.as({ kind: "done" }));
+                if (exclusiveSem === undefined)
+                    return yield* physicalBody;
+                // 保持原来的物理资源获取顺序：exclusive provider → 全局位 → body。先还全局位
+                // 再等 provider，避免一个已完成 sharedState/setup 协调、却仍在排 exclusive lane 的
+                // attempt 饿死其它 provider；拿到 lane 后才回补全局位，Sandbox 与 body 因而仍在两把
+                // permit 的保护中。中断时两个作用域各自归还自己实际持有的 permit。
+                yield* slot.release;
+                return yield* exclusiveSem.withPermits(1)(slot.reacquire.pipe(effect_1.Effect.zipRight(physicalBody)));
             }));
-            const guarded = exclusiveSem ? exclusiveSem.withPermits(1)(dispatch) : dispatch;
             // 许可链的循环外壳:撞锁挂起的用例解决后从 ① 重新走一遍(实验闸名额与全局位都要
             // 重新取,不能拿着别人在等的名额干等)。
             const pipeline = effect_1.Effect.gen(function* () {
@@ -2127,8 +2414,9 @@ function runEvals(opts) {
                         accountDispatchHalted(a, halt.gate);
                         return;
                     }
-                    // ② 实验闸 → ③ 全局位 → ④ 用例锁 → preflight → body
-                    const outcome = yield* withExperimentGate(a, guarded);
+                    // ② Invocation 内实验闸 → ③ 全局位 → sharedState / 生命周期协调 → Eval lock
+                    // → exclusive provider permit（如声明）→ body。
+                    const outcome = yield* withExperimentGate(a, dispatch);
                     if (outcome.kind === "done")
                         return;
                     // 许可获取被落下的闸打断:许可已随作用域归还,回到 ① 让上面的检查点记账。
@@ -2145,10 +2433,10 @@ function runEvals(opts) {
             const orderedPipeline = predecessor === undefined
                 ? wavePipeline
                 : predecessor.pipe(effect_1.Effect.flatMap(() => wavePipeline));
-            // 实验级 teardown 结算:每个 attempt 收尾(含被 preflight 跳过、被中断的、被用例锁
+            // 实验级 teardown / sharedState lease 结算:每个 attempt 收尾(含被 preflight 跳过、被中断的、被用例锁
             // 被 preflight 跳过、被中断的)都从身份集合移除；最后一个触发 ExperimentDef.teardown。ensuring
             // 在中断路径同样执行，重复 finalizer 也不会让状态下溢。
-            const withExpLifecycle = !a.run.setup && !a.run.teardown
+            const withExpLifecycle = !a.run.setup && !a.run.teardown && !a.run.sharedState
                 ? orderedPipeline
                 : orderedPipeline.pipe(effect_1.Effect.ensuring(settleExperimentAttempt(a).pipe(effect_1.Effect.orDie)));
             // 用例锁释放:这个 key 的全部 attempt(真实派发的与被 late-carry 跳过的)都 settle 后
@@ -2163,7 +2451,7 @@ function runEvals(opts) {
                 return withWaveLifecycle;
             const releaseSuccessor = groupedReleases.get(a);
             return withWaveLifecycle.pipe(effect_1.Effect.ensuring(releaseSuccessor));
-        }, { concurrency: opts.maxConcurrency, discard: true }).pipe(
+        }, { concurrency: "unbounded", discard: true }).pipe(
         // 中断(用户 Ctrl+C):finalizer 已在中断过程中跑完(容器已停),这里只是把它咽下,
         // 好让流程走到 summarize / onInvocationComplete,用已完成的 results 出一份部分汇总,而不是抛栈。
         // 判据是 `isInterruptedOnly` 而不是 `isInterrupted`:一条 fiber 的缺陷会连带中断兄弟 fiber,
@@ -2180,6 +2468,18 @@ function runEvals(opts) {
         const exit = yield* effect_1.Effect.exit(opts.signal === undefined
             ? dispatchEffect
             : effect_1.Effect.raceFirst(dispatchEffect, interruptOnAbort(opts.signal)));
+        // A full-carry / zero-Attempt invocation has no dispatch fiber that could
+        // await startup recovery. Seal its selected-Experiment obligation here; for
+        // normal runs the per-setup gate above has already awaited the same Deferred.
+        const startupRecoveryExit = yield* effect_1.Effect.exit(opts.signal === undefined
+            ? effect_1.Effect.forEach(startupRecoveryCompletionsToAwait, effect_1.Deferred.await, {
+                concurrency: "unbounded",
+                discard: true,
+            })
+            : effect_1.Effect.raceFirst(effect_1.Effect.forEach(startupRecoveryCompletionsToAwait, effect_1.Deferred.await, {
+                concurrency: "unbounded",
+                discard: true,
+            }), interruptOnAbort(opts.signal)));
         // provenance 在这里齐全:没有任何 attempt 依赖的 key 也照样跑完并留下自己那条记录,
         // 中断路径下同批构建随 signal 收束成 cancelled,不把 run.json 的 sandboxBuilds 落空。
         if (runningBuilds !== undefined) {
@@ -2261,6 +2561,14 @@ function runEvals(opts) {
                 return yield* effect_1.Effect.failCause(exit.cause).pipe(effect_1.Effect.ensuring(sweepExperimentTeardowns().pipe(effect_1.Effect.orDie)));
             }
         }
+        if (effect_1.Exit.isFailure(startupRecoveryExit)) {
+            if (effect_1.Cause.isInterruptedOnly(startupRecoveryExit.cause)) {
+                interrupted = true;
+            }
+            else {
+                return yield* effect_1.Effect.failCause(startupRecoveryExit.cause).pipe(effect_1.Effect.ensuring(sweepExperimentTeardowns().pipe(effect_1.Effect.orDie)));
+            }
+        }
         if (interrupted)
             (0, sink_ts_1.reportInterrupted)();
         yield* sweepExperimentTeardowns();