@sema-agent/server 7.3.0 → 7.5.0

package/dist/approval-reconciler.js

@@ -42,24 +42,82 @@ function withDeadline(op, label, timeoutMs = RECONCILE_STORE_TIMEOUT_MS) {
     ]);
 }
 /**
- * 判据 1 的**硬谓词**(纯函数,§9 C2 + §8 D-2)。
+ * 这只 ask 是不是**祖先冻结 approver 层**在委派 fold 中途铸的那一份(#168 件1④,黑板 [2912]③)。
  *
- * 返回选中的候选,或 `undefined` = 不命中。逐条:
+ * 判别位是**产品自己发的**,不是外部约定:core 的 `withDelegationProvenance` 只包**子代自己那条缝**,
+ * 祖先层那次走未包装的原函数 ⇒ `AskRequest.delegation` 在不在,就是「这一份是哪一层发的」。落到行上,
+ * `delegation.parentToolCallId` 是必填字段,铸行时逐字透传进 `parent_tool_call_id` 列 ⇒ **列非 NULL
+ * ⇔ delegation 在场**(不需要新列,也不需要回 `req` 里再读一次)。
+ *
+ * 第二维 `sourceTaskId !== sessionId` 把「根腿」摘出去:根腿的 `sourceTaskId` 恒等于会话锚(core 给
+ * `AskRequest.sourceTaskId` 填的就是该腿 sessionId),它根本不在任何 fold 里,`parent_tool_call_id`
+ * 为 NULL 是它的常态而不是信号。
+ *
+ * 命中 ⇒ 退出硬相等(判据 1 结构上不命中,行落 ②③④⑤)。实测(test AI 围栏)checkpoint 存的摘要**逐字
+ * 等于子代自己那条缝**、只不等于祖先层那一次 —— 所以收窄到这一层,子代自己的缝照常参与。
+ */
+export function isAncestorFoldMint(ask) {
+    return ask.parentToolCallId === null && ask.sourceTaskId !== ask.sessionId;
+}
+/**
+ * 判据 1 的**硬谓词**(纯函数,§9 C2 + §8 D-2;#168 件1 起返回分类而不是布尔)。
+ *
+ * 逐条:
+ *  - 祖先层 fold 中途铸点 ⇒ 直接退出(见 {@link isAncestorFoldMint});
  *  - `unparseable` 候选直接出局(读不出 ⇒ 不确定 ⇒ 不命中);
- *  - `boundCallId` 必须逐字等于 `ask.toolCallId`(读口已按它查,这里是纵深防御);
- *  - **因果下界**:`cp.createdAtMs >= ask.createdAtMs`(park 不可能早于它要 park 的那次 ask);
- *  - **hash 双等**:两侧都必须在场且相等 —— 任一侧缺席即不命中(禁「能取到时才比」的可选谓词)。
+ *  - **身份三元组**:`sourceTaskId` **相等** ∧ `toolCallId` **相等** ∧ 时间维的**因果下界**
+ *    `candidate.createdAtMs >= ask.createdAtMs`(⚠️ 第三维**不是等式** —— 把它读成等式会让合法的 park
+ *    几乎命不中,行随后落 ②③⑤ 被误判)—— 摘要**不是**身份([2897]③①:
+ *    同 args 的两次调用摘要天然相同,只靠摘要硬相等会把第二次投递并进第一次的票);任一维在候选侧
+ *    缺席(读不出的 blob 没有 `sourceTaskId`)即身份不成立;
+ *  - **hash 双等**:两侧都必须在场且相等,任一侧缺席一律不 bind;禁「能取到时才比」的可选谓词。
+ *    归因分两级(顺序即代码顺序):身份这一层先判 —— 同身份候选为空**且**候选集非空 ⇒ `identity_miss`;
+ *    走到 hash 这一层才把缺席记成**单铸** `single_mint`(见 {@link GateMatchOutcome})。
  *
  * 多候选时的取舍:优先 `status === "pending"`(活着的那张 gate),否则取最早的一条(读口按
  * `created_at ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
  * 一个还能被 resume 的坐标上,对壳更有用。
  */
-export function selectGateCandidate(ask, candidates) {
+export function classifyGateMatch(ask, candidates) {
+    const outcome = classifyGateMatchBeforeFoldVeto(ask, candidates);
+    // 🔴 祖先层否决**排在最后**、而且只否决已经成立的命中(纯减法)。放在最前面判会让这条谓词的每一次
+    // 假阳性(`sourceTaskId ≠ sessionId` 还有别的成因,例如 session-less 的 adhoc 腿)都白白关掉判据 1,
+    // 并把一条本该记成 `single_mint`/`identity_miss` 的行错记成「祖先层铸点」。放在这里,它最坏只是**不
+    // 命中**(与判据 1 的既有 fail-safe 同向),而计数从此只统计「本来会 bind、被这条裁定拦下」的行 ——
+    // 非零读数因此是真信号,不是噪声底。
+    if (outcome.kind === "match" && isAncestorFoldMint(ask))
+        return { kind: "ancestor_fold_mint" };
+    return outcome;
+}
+function classifyGateMatchBeforeFoldVeto(ask, candidates) {
+    // 身份三元组的前两维 + 因果下界(摘要不参与这一层——它是身份之外的**第二道**等式)。
+    const sameIdentity = candidates.filter((c) => c.unparseable !== true && c.sourceTaskId !== null && c.sourceTaskId === ask.sourceTaskId && c.boundCallId === ask.toolCallId && c.createdAtMs >= ask.createdAtMs);
     const askHash = ask.boundInputHash;
+    if (sameIdentity.length === 0) {
+        // 「同身份的 checkpoint 一条都没有」有两种成因,不能混:
+        //  · 候选集**空** ⇒ 这条弧上根本没有对家,只有 ask 侧铸过(或两侧都没铸)= 单铸;
+        //  · 候选集非空 ⇒ 有对家、只是不是这一只(别的 sourceTaskId/callId),或者读不出(`unparseable`,
+        //    「不确定」)。两者都**不是**「只有一侧铸过」这个事实陈述,一律记 `identity_miss`——
+        //    把一条读不出的坏行说成「对家从来不存在」是拿不确定冒充确定。
+        if (candidates.length > 0)
+            return { kind: "identity_miss" };
+        return { kind: "single_mint", side: askHash === null ? "neither" : "ask_only" };
+    }
+    const withHash = sameIdentity.filter((c) => c.boundInputHash !== null);
     if (askHash === null)
-        return undefined; // hash 缺席 = 结构上永不满足判据 1(见 AskRow.boundInputHash 顶注)
-    const matches = candidates.filter((c) => c.unparseable !== true && c.boundCallId === ask.toolCallId && c.createdAtMs >= ask.createdAtMs && c.boundInputHash !== null && c.boundInputHash === askHash);
-    return matches.find((c) => c.status === "pending") ?? matches[0];
+        return { kind: "single_mint", side: withHash.length > 0 ? "checkpoint_only" : "neither" };
+    if (withHash.length === 0)
+        return { kind: "single_mint", side: "ask_only" }; // 同身份的 park 一条摘要都没有
+    const matches = withHash.filter((c) => c.boundInputHash === askHash);
+    const picked = matches.find((c) => c.status === "pending") ?? matches[0];
+    if (picked !== undefined)
+        return { kind: "match", candidate: picked };
+    return { kind: "hash_mismatch", candidates: withHash.length };
+}
+/** {@link classifyGateMatch} 的布尔面(判据 1 命中即返回那条候选)。分类信息由调用方按需另取。 */
+export function selectGateCandidate(ask, candidates) {
+    const outcome = classifyGateMatch(ask, candidates);
+    return outcome.kind === "match" ? outcome.candidate : undefined;
 }
 /** 判据表 v2 的判定(纯函数;顺序 = 设计稿 §9 尾的五臂汇总,注见文件头)。 */
 export function decideReconcileAction(input) {
@@ -119,7 +177,8 @@ export function createApprovalReconciler(deps) {
             }
         }
     };
-    /** 一条 `PARKING` 行的收敛(读事实 → 纯判定 → 一次 CAS)。返回本行落到哪一臂(供统计)。 */
+    /** 一条 `PARKING` 行的收敛(读事实 → 纯判定 → 一次 CAS)。返回本行落到哪一臂 + 判据 1 的分类(供统计;
+     *  `match` 缺席 = 本轮压根没走到判据 1,与「走了但没命中」是两回事,不能记成同一格)。 */
     const reconcileOne = async (ask, nowMs) => {
         // ⓪ 批态**先读**(codex round3 R3-2):它是唯一一个能让本行「结构上再也不可能 bind」的事实,而且是
         //    一次主键读。批已 `ABORTED` 或已绑给**别人** ⇒ 判据 1 的 `bindBatch` 谓词(`ROUTING_UNBOUND`)
@@ -133,9 +192,42 @@ export function createApprovalReconciler(deps) {
         // 判据 1:窄谓词精确查(scope 必填 —— 租户门是读口自己的责任,§8 D-3)。因果下界直接下推成
         // `sinceMs`,SQL 侧就把早于本 ask 的 checkpoint 排掉了(`selectGateCandidate` 里还会再判一次,
         // 纵深防御)。
+        let gateMatch;
         if (checkpoints && !irreversibleBatch) {
+            // 🔴 **已知缺口,登记而不假称已解**(codex 交叉复审 2026-08-07 [high] 一,验真;**先存**,不是本批
+            // 引入):这里的 session 维传的是 `ask.sessionId` = **投递上下文**的会话(`tool-approval.ts` 铸行时
+            // 取 `primary.sessionId`),而委派子代那条腿的 checkpoint 落在**子代自己**的 sessionId 上
+            // (core 铸 `cp.sessionId = 该腿 sessionId`,同值也写进 `cp.sourceTaskId`)。⇒ 子代自己那条 approver
+            // 缝的 park 在 SQL 谓词这一层就被滤掉了,判据 1 对委派腿结构上够不着 —— 黑板 [2912]③「子代自己那条
+            // 缝可以参与硬相等」的那一半,在本仓当前接线下还落不了地(行改走 ②③④⑤,fail-safe)。
+            //
+            // 顺带说清本批**改善**了什么:三元组把 `cp.sourceTaskId === ask.sourceTaskId` 变成硬谓词之后,
+            // 一只子代 ask 再也不可能认领**宿主**腿的 park(同 session 查出来的候选,callId 撞车 + 同 args 摘要
+            // 相同就够了,而 `PARKED` 不可回滚)——那是本批之前真实存在的错配面。
+            //
+            // 修法(未做,需自带判据):把 session 维换成「铸 park 的那条腿的会话」。风险在于 `ask.sourceTaskId`
+            // 有 `?? origin.taskId` 兜底,core 万一不填就会把一个 taskId 当 session 去查(比今天更差),所以
+            // **必须**配一条用真 checkpoint 店、宿主/子代两个不同 sessionId 的端到端钉才动。开题上报。
             const candidates = await withDeadline(checkpoints.findCheckpointCandidatesForAsk(encodeCheckpointScope(ask.owner), ask.sessionId, ask.toolCallId, ask.createdAtMs), "findCheckpointCandidatesForAsk");
-            const match = selectGateCandidate(ask, candidates);
+            gateMatch = classifyGateMatch(ask, candidates);
+            if (gateMatch.kind === "hash_mismatch") {
+                // 留痕不拒(见 ReconcileStats.hashMismatch 顶注):warn 说清成因方向,行继续按 ②③④⑤ 判。
+                try {
+                    logger.warn("approval_reconcile_hash_mismatch", {
+                        askId: ask.askId,
+                        taskId: ask.taskId,
+                        toolCallId: ask.toolCallId,
+                        candidates: gateMatch.candidates,
+                        reason: "ask and checkpoint minted the same bound input under the same (sourceTaskId, toolCallId) identity but the digests differ — " +
+                            "the known causes are deployment-side (a hook/policy mutating an object it still holds a reference to between the two mints, " +
+                            "or a stateful getter returning a fresh value per read), not tampering; this ask keeps its fail-safe route (no park, no denial)",
+                    });
+                }
+                catch {
+                    /* 可观测面绝不成为故障源 */
+                }
+            }
+            const match = gateMatch.kind === "match" ? gateMatch.candidate : undefined;
             if (match) {
                 // 🔴 `bindBatch` 内部**一次**完成 `PARKING→PARKED` + gate 落行 + 兄弟连坐 VOID(§8 A-2:正文
                 // 「先 transitionAsk 再 bindBatch」是死锁形,已作废)。只调它一次。
@@ -146,7 +238,7 @@ export function createApprovalReconciler(deps) {
                 }), "bindBatch");
                 if (res.ok) {
                     revoke(ask, res.voidedSiblings, "superseded_by_park", nowMs);
-                    return "parked";
+                    return { outcome: "parked", match: gateMatch };
                 }
                 // 判别式失败臂(§9 C3):拿到批的**真实**态 + 中选者,降级续判 —— `ABORTED` ⇒ VOID(abort 语义),
                 // `ROUTING_BOUND` 且中选者是兄弟 ⇒ VOID(bind-once 落选者,R2-3),其余按 ②③④⑤。
@@ -162,13 +254,13 @@ export function createApprovalReconciler(deps) {
             case "bind": {
                 // `allowBind: false` 下结构上不可达;留一条防御性 hold,绝不在这里第二次调 bindBatch。
                 await withDeadline(askStore.deferReconcile(ask.askId, "PARKING", ask.version, nowMs), "deferReconcile");
-                return "held";
+                return { outcome: "held", match: gateMatch };
             }
             case "deny": {
                 // 🔴 全仓唯一的 `DENIED` 写点(grep 钉)。归因是判据 2 的**终局证据**,不是超时推断。
                 // CAS 输(行在本轮判定期间被别人收走)= 正常,如实记成 held(没动过行),下轮重扫。
                 const won = await withDeadline(askStore.transitionAsk(ask.askId, "PARKING", "DENIED", { deniedReason: action.reason, updatedAtMs: nowMs }), "transitionAsk(DENIED)");
-                return won ? "denied" : "held";
+                return { outcome: won ? "denied" : "held", match: gateMatch };
             }
             case "void": {
                 // 🔴 codex 交叉复审 C3(2026-08-06 真缺陷):**必须看 CAS 的返回值**。原先无条件记账 + 发撤卡帧
@@ -177,7 +269,7 @@ export function createApprovalReconciler(deps) {
                 // 壳会清掉一张仍然有效、还在等 gate 的卡。输 ⇒ 什么都不做,下轮按新态重判。
                 const won = await withDeadline(askStore.transitionAsk(ask.askId, "PARKING", "VOID", { deniedReason: action.reason, updatedAtMs: nowMs }), "transitionAsk(VOID)");
                 if (!won)
-                    return "held";
+                    return { outcome: "held", match: gateMatch };
                 if (action.reason === VOID_REASONS.ORPHAN_TTL_EXCEEDED) {
                     logger.warn("approval_ask_orphan_voided", { askId: ask.askId, taskId: ask.taskId, ageMs: nowMs - ask.createdAtMs, ttlMs: orphanTtlMs });
                 }
@@ -190,19 +282,34 @@ export function createApprovalReconciler(deps) {
                 // 落选者(R2-3)是**真的**被别人的 park 顶掉 ⇒ 用 `superseded_by_park`;其余单行 VOID 用 `"aborted"`
                 // (两员闭集里唯一诚实的那个,见上注)。
                 revoke(ask, [ask.askId], action.reason === VOID_REASONS.BATCH_BOUND_ELSEWHERE ? "superseded_by_park" : "aborted", nowMs);
-                return "voided";
+                return { outcome: "voided", match: gateMatch };
             }
             case "hold": {
                 // 队列轮转(§8 D-4 / §9 C5):推 `updated_at_ms` 排到队尾。CAS 输(版本已被别人推进)= 正常,
                 // 本轮判定已过期,下轮重来。
                 await withDeadline(askStore.deferReconcile(ask.askId, "PARKING", ask.version, nowMs), "deferReconcile");
-                return "held";
+                return { outcome: "held", match: gateMatch };
             }
         }
     };
     return {
         async runOnce(nowMs) {
-            const stats = { scanned: 0, unmatchableNoHash: 0, parked: 0, denied: 0, voided: 0, held: 0, failed: 0, budgetExhausted: 0, orphansExpired: 0 };
+            const stats = {
+                scanned: 0,
+                unmatchableNoHash: 0,
+                hashMismatch: 0,
+                singleMintAskOnly: 0,
+                singleMintCheckpointOnly: 0,
+                singleMintNeither: 0,
+                ancestorFoldMint: 0,
+                parked: 0,
+                denied: 0,
+                voided: 0,
+                held: 0,
+                failed: 0,
+                budgetExhausted: 0,
+                orphansExpired: 0,
+            };
             // ── 段一:PARKING 判据表 ────────────────────────────────────────────────────────────────
             const parking = await withDeadline(askStore.listByState("PARKING", batchLimit), "listByState(PARKING)");
             stats.scanned = parking.length;
@@ -221,7 +328,7 @@ export function createApprovalReconciler(deps) {
                 if (ask.boundInputHash === null)
                     stats.unmatchableNoHash += 1; // 判据 1 盲区(见字段顶注)
                 try {
-                    const outcome = await reconcileOne(ask, nowMs);
+                    const { outcome, match } = await reconcileOne(ask, nowMs);
                     if (outcome === "parked")
                         stats.parked += 1;
                     else if (outcome === "denied")
@@ -230,6 +337,26 @@ export function createApprovalReconciler(deps) {
                         stats.voided += 1;
                     else
                         stats.held += 1;
+                    // 判据 1 的分类计数(#168 件1②③④)——`match` 缺席 = 本轮没走到判据 1(无 checkpoint 面 /
+                    // 批已不可逆),那既不是 mismatch 也不是单铸,一格都不记。
+                    switch (match?.kind) {
+                        case "hash_mismatch":
+                            stats.hashMismatch += 1;
+                            break;
+                        case "ancestor_fold_mint":
+                            stats.ancestorFoldMint += 1;
+                            break;
+                        case "single_mint":
+                            if (match.side === "ask_only")
+                                stats.singleMintAskOnly += 1;
+                            else if (match.side === "checkpoint_only")
+                                stats.singleMintCheckpointOnly += 1;
+                            else
+                                stats.singleMintNeither += 1;
+                            break;
+                        default:
+                            break; // match / identity_miss / 未走到判据 1:无计数格
+                    }
                 }
                 catch (err) {
                     // 🔴 per-row 隔离(邻居 bg-agent per-scope 先例):一条行的坏 blob / 一次瞬时错误不许饿死同批

package/dist/boot/coordinators.js

@@ -17,7 +17,9 @@ export function createLiveCoordinators(ctx) {
     // `RunnerDeps.onQuestion` (core mounts the AskUserQuestion tool + routes live asks here) AND consumed by the HTTP layer
     // (the `POST /v1/questions/:id/respond` route + the per-run ALS context wraps on the streaming legs). Absent ⇒ core
     // mounts the tool with the headless default (a run never hangs; the model just can't get a live answer).
-    const question = config.askQuestionEnabled ? new QuestionCoordinator() : undefined;
+    // #166 裁2 接线:三旋钮(QUESTION_TTL_MS / QUESTION_MAX_*_PER_RUN)从 config 通到协调器;缺席=构造器
+    // 内建 DEFAULT_QUESTION_THROTTLE,默认值恒等钉在 test/question-unavailable.test.ts。
+    const question = config.askQuestionEnabled ? new QuestionCoordinator(config.questionThrottle) : undefined;
     // [816]/[820]②: the live tool-approval HITL coordinator — the sibling of `question` on core's `RunnerDeps.onAsk`
     // seam (1.290 sync-ask leg). Present ⇒ a policy `ask` on a LIVE streaming leg becomes a `tool_approval` frame the
     // shell renders as the CC three-choice card, answered via POST /v1/tool-approvals/:id/respond.
@@ -41,7 +43,11 @@ export function createLiveCoordinators(ctx) {
         parkFacility: durableEnabled,
     });
     // §8.4:协议**开着**却上不了场 = 合法部署形(不是配置错误)⇒ 一行 **info**(不是 warn),把原因说明白。
-    // 反过来「开关本来就没开」不打日志:那是默认形,每次启动刷一行噪音没有信息量。
+    // 反过来「开关本来就没开」不打日志:显式关掉的部署自己知道为什么关,一行噪音没有信息量。
+    // ⚠️ 读数已反转:总开关默认在树上已是 ON(版本坐标见 config.ts 的 `streamApprovalConfig()` 头注),
+    // 所以这一行在**默认部署**上是常态 —— 任何没有 durable
+    // backend / park 设施的默认部署每次启动都会打一行 `stream_approval_disabled`(每次启动一行,不是每
+    // tick)。写这条判据时的前提「默认形绕开本路径」已不成立;要收紧,收紧点在本 if 而不是在开关处。
     if (config.streamApproval.enabled && !streamApprovalGate.active) {
         logger.info("stream_approval_disabled", {
             reason: streamApprovalGate.reason,
@@ -53,8 +59,12 @@ export function createLiveCoordinators(ctx) {
     }
     const toolApproval = config.toolApprovalEnabled
         ? new ToolApprovalCoordinator({
-            // 协议上场 ⇒ 持久层 + 60s 窗(§7:`STREAM_ASK_WINDOW_MS` **只在开关内**生效,
+            // 协议上场 ⇒ 持久层 + 配置窗(§7:`STREAM_ASK_WINDOW_MS` **只在开关内**生效,
             // `DEFAULT_APPROVAL_TTL_MS` 一个字不动);不上场 ⇒ 两者都不传,窗保持既有 5min(D1 逐字不变)。
+            // ⚠️ 两臂的窗**默认已同长**:窗默认自 7.5.0 起 = 300000 = `DEFAULT_APPROVAL_TTL_MS`(clay 同裁把
+            // 「窗变短」从翻真里摘出去)。原注画的「上场 = 60s / 不上场 = 5min」这个对比在默认配置下不存在
+            // 了,别据它得出「开了协议窗会缩短」的运维结论:上场与否改变的是**持久层与协议帧**,窗只有在
+            // 部署显式设了 `STREAM_ASK_WINDOW_MS` 时才分叉。
             ...(streamApprovalGate.active ? { askStore: streamApprovalGate.askStore, ttlMs: config.streamApproval.windowMs } : {}),
             // 余量旋钮恒传(既有键,窗长三元公式的第二项;legDeadlineMonotonic 缺席时它不参与计算)。
             windowMarginMs: config.streamAskWindowMarginMs,

package/dist/boot/deferred-sandbox-path-env.d.ts

@@ -0,0 +1,99 @@
+import { FileError, StubExecutionEnv, type ExecutionEnv, type ExecutionEnvFactory, type FileInfo, type Result } from "@sema-agent/core";
+/** 哪些 lane 用本模块的代理裁决写门 —— `REMOTE_EXEC` 未设(进程内 host)与显式 `host` 之外的全部。
+ *  与 resolve-spec 的 `hostSemanticsLane` 是同一判别式的两面,取值处**只此一个**(两处各写一份正是漂移的成因)。 */
+export declare function isSandboxPathAdjudicationLane(provider: string | undefined): boolean;
+/** slot 取值的三态。`ok:false` 的两支都是 fail-closed,分开只为让留痕说得出**哪一种**缺席。 */
+export type SandboxPathEnvLookup = {
+    readonly ok: true;
+    readonly env: ExecutionEnv;
+} | {
+    readonly ok: false;
+    readonly reason: "no_session_id" | "unbound";
+};
+/**
+ * per-session 的真 env 登记簿 —— 工厂装饰器写,写门代理读。
+ *
+ * **同键改铸 = 顶替**(不排队、不判歧义)。依据是一条被两道门执法的不变量:一个 session 同时只有一条
+ * 活腿(HTTP 层 `conflict.session_active_run` + core 的 session acquire),而委派子代用的是**另一个**
+ * sessionId。所以工厂为某 session 铸出新 env 的那一刻,同键上还留着的登记按构造已经是死腿——最典型的
+ * 产地是 **park-only 车道**(非 suspendable 的远程 env:durable park 既不 `suspendVM` 也不 `destroy`,
+ * core 的 `teardownOwnedEnv` 在 checkpoint token 在场时整条跳过)。留着它只会让 resume 腿整轮拿不到
+ * 真 env(写门恒 fail-closed);顶替按**实例身份**收口,被顶掉那一方迟到的注销全部落空,不误伤后继。
+ */
+export declare class SandboxPathEnvSlots {
+    /** **弱持有**:登记簿只在「别人还用着这个 env」期间指向它。跑着的任务由 core 强持有(`prepared.ownedEnv`),
+     *  所以在场腿的裁决永远解得出;而一条 park 后再没人来 resume 的死腿,其 env 一旦无人引用即可被回收,
+     *  条目在下一次清扫时消失。强持有会把它们连同各自的 adapter 连接一起钉死到进程结束,并在 4096 条之后
+     *  让**每一个**新 session 拿不到真 env(守卫集下 = 每一次结构化写都 deny)—— 那是一道会自己关上的门。 */
+    private readonly bySession;
+    /** 登记一个刚铸出的 env(同键顶替),返回**幂等**的注销闭包;到达上限而拒收时返回 `undefined`。
+     *  注销按**实例身份**摘除,所以一个迟到的 destroy 不会误伤同键的后继 env。 */
+    bind(sessionId: string, env: ExecutionEnv): (() => void) | undefined;
+    resolve(sessionId: string | undefined): SandboxPathEnvLookup;
+    /** 登记簿规模(上限行为的可观测面;测试与运维探针用)。含尚未清扫的死条目。 */
+    get boundSessions(): number;
+    /** 清掉 env 已被回收的条目。只在触到上限时跑一遍(O(n) 的代价换掉一次拒收)。 */
+    private sweepCollected;
+}
+/** 进程内唯一的登记簿:工厂装饰器(boot/execution-env.ts)与写门 wiring(boot/resolve-spec.ts)分处
+ *  装配链两端,而中间的 core 只肯传 `ExecutionEnvFactoryContext`——两端共享同一个实例是它们唯一的会合点。
+ *  测试要隔离时自建 {@link SandboxPathEnvSlots} 实例注入即可(两个消费点都收可选参)。 */
+export declare const sandboxPathEnvSlots: SandboxPathEnvSlots;
+/** 结构化留痕面(与服务 `logger` 同形,调用处 optional-chain —— 与 remote-scratchpad 装饰器一致)。 */
+export interface SandboxPathEnvLogger {
+    warn?(event: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * 装饰工厂:每铸出一个 env 就按 `ctx.sessionId` 登记(同键顶替,见 {@link SandboxPathEnvSlots}),
+ * 终态时注销。
+ *
+ * 挂**最外层**(装配链尾):内层装饰器可能**换掉**env 实例(worktree 隔离的 `rootEnvAt`)或改写它的
+ * 方法(scratchpad 的 exec/canonicalPath 前置),写门要裁决的是 core 最终拿到手的那一个。
+ *
+ * 生命周期三面(顺序即语义):
+ *  · `destroy` ⇒ 注销。
+ *  · `suspendVM` 成功 ⇒ 注销。core 在挂起时**跳过** destroy(runtask 留着 env 做快照),所以这是可挂起
+ *    车道唯一的及时腾位点:挂起期该 session 没有活腿,登记留着只是白占登记簿容量。
+ *  · `resumeVM` 成功 ⇒ **重新登记**。挂起并不必然终结这一轮:`commitSuspendSaga` 的 checkpoint 写失败
+ *    臂会 `resumeVM` + `postResumeInit` 把**同一个实例**复活,然后作废本次挂起让 run 继续跑
+ *    (core dist 亲读)。只注销不复登记,一次瞬时 checkpoint 故障就会让这条 run 之后每一次写都失去真身
+ *    裁决(方向 fail-closed,但整轮写面被毒死)。复登记幂等:仍在场时是 no-op,所以正常 resume 腿
+ *    (新 env 在工厂处已登记、随后被 core `resumeVM` 复原快照)照旧不动;后继腿已接管该 session 时也不抢回。
+ *
+ * 两个终态面都缺席的 env(五条沙箱 adapter 都不是这一形)照样登记——正确性优先于回收:不登记等于
+ * 让那条 lane 的写门恒 fail-closed。回收兜底=登记簿自己的上限。
+ */
+export declare function withSandboxPathEnvSlot(factory: ExecutionEnvFactory, slots: SandboxPathEnvSlots, logger?: SandboxPathEnvLogger): ExecutionEnvFactory;
+export interface DeferredSandboxPathEnvOptions {
+    /** slot 键。缺席(= 部署没接 authorizer,`main.ts` 不产生这种形)⇒ 转发面恒 fail-closed。 */
+    sessionId: string | undefined;
+    slots: SandboxPathEnvSlots;
+    logger?: SandboxPathEnvLogger;
+}
+/**
+ * 写门用的 ExecutionEnv 代理(见文件头)。fs **读**原语转发 slot 里的真 env,`absolutePath` 保留词法形,
+ * 其余一切(写面 / shell 面 / listDir …)继承 `StubExecutionEnv` 的 `not_supported`。
+ *
+ * **继承而非逐一手写**是刻意的:core 日后给 `ExecutionEnv` 加必填面时,新面会随 `StubExecutionEnv`
+ * 一起到位并保持同一个诚实答案,不会在这里留下一个悄悄编出来的假答案。
+ */
+export declare class DeferredSandboxPathEnv extends StubExecutionEnv {
+    private readonly sessionId;
+    private readonly slots;
+    private readonly logger;
+    /** 每实例一次的留痕闸:裁决面每个写目标要走 3-4 次转发,逐次 warn 会把日志刷成噪声。 */
+    private warned;
+    constructor(opts: DeferredSandboxPathEnvOptions);
+    /** 取真 env;取不到就地铸 fail-closed 错误(并留痕一次)。 */
+    private bound;
+    /** 词法一面,**不**转发 —— 理由见文件头裁定 1。 */
+    absolutePath(path: string): Promise<Result<string, FileError>>;
+    exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+    /** `readLink` 在 `ExecutionEnv` 上是**可选**面。本代理恒定义它,于是 core 永远走不到自己的
+     *  「env 没有 readLink」腿——真 env 缺这一面时由此处答错误,落到 core 同一条 `unresolvedSymlink` 出口,
+     *  裁决结果与那条腿完全一致。 */
+    readLink(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+}
+//# sourceMappingURL=deferred-sandbox-path-env.d.ts.map