@sema-agent/server 7.2.0 → 7.4.0

package/dist/approval-reconciler.js

@@ -0,0 +1,307 @@
+import { DENY_REASONS, VOID_REASONS } from "./approval-deny-reasons.js";
+import { buildRevokeFrame } from "./approval-card.js";
+import { encodeCheckpointScope } from "./security.js";
+/** 判据 2 的「非 suspended 终局」词表(§8 A-1;`RunRecord["status"]` = `"running" | TaskStatus`,
+ *  TaskStatus = completed|blocked|failed|suspended|needs_review)。`suspended`/`needs_review`/`running`
+ *  都不是终局 ⇒ 落判据 3 保持。 */
+const TERMINAL_RUN_STATUS = new Set(["completed", "failed", "blocked"]);
+/** core 给「被取消」的 run 打的 `errorCode`(§9 C3 的取消判别键)。 */
+const CANCELLED_ERROR_CODE = "cancelled";
+/**
+ * 🔴 收敛器每一次 store/读口调用的墙钟上限(codex 交叉复审 round3 R3-2,2026-08-06 真缺陷)。
+ *
+ * 为什么必须有:`runOnce` 被 reaper 腿的 **in-flight 守卫**包着(一次只跑一轮)。一个挂死的依赖
+ * (checkpoint 店 / run 店 / ask 店任意一个黑洞化)会让 `runOnce` 永不返回 ⇒ 守卫从此再不放行 ⇒
+ * **全部** approval 行的对账永久停摆,而这正是本模块存在的目的(崩溃恢复)。超时后单行进 per-row
+ * catch(warn + 计数 + 留在原态下轮重试),其余行照常推进 —— 一条坏依赖不许饿死整段扫描。
+ * 10s:远大于任何健康查询,又远小于 reaper tick 的实际容忍度。
+ */
+const RECONCILE_STORE_TIMEOUT_MS = 10_000;
+/**
+ * 🔴 **每段**扫描的墙钟预算(codex 交叉复审 round4 R4-2,2026-08-06 验真)。
+ *
+ * 单看 per-call deadline 是不够的:行是**串行**处理的,一个黑洞化的依赖会让每行都吃满
+ * {@link RECONCILE_STORE_TIMEOUT_MS}。默认 batch=200 时 `runOnce` 要跑掉半小时量级,上帽 10000 行更是
+ * 一天量级 —— 而 reaper 的 in-flight 守卫在这期间会**跳过每一个 tick**,孤儿段(段二)甚至一次都轮不到。
+ * 于是「一个依赖挂了」被放大成「整个对账面停摆数小时」,正好是本模块要防的那件事。
+ *
+ * 修法:**每段各自**一份预算(不是共享一份)——段一吃光也绝不影响段二开跑(孤儿代打是崩溃恢复的兜底,
+ * 优先级不比判据表低)。超预算即停本段,剩下的行下轮接着扫(`deferReconcile` 的队列轮转保证「下轮」
+ * 真的能轮到新行),并记一条 warn。
+ */
+const RECONCILE_SEGMENT_BUDGET_MS = 30_000;
+/** 给一次读/写套墙钟上限(超时以 Error 拒绝,由 per-row catch 接住)。定时器 `unref`,绝不持住进程;
+ *  竞速输的那一路由 `Promise.race` 自己的 handler 接住,不会变成 unhandled rejection。 */
+function withDeadline(op, label, timeoutMs = RECONCILE_STORE_TIMEOUT_MS) {
+    return Promise.race([
+        op,
+        new Promise((_resolve, reject) => {
+            const t = setTimeout(() => reject(new Error(`approval reconcile ${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            t.unref?.();
+        }),
+    ]);
+}
+/**
+ * 判据 1 的**硬谓词**(纯函数,§9 C2 + §8 D-2)。
+ *
+ * 返回选中的候选,或 `undefined` = 不命中。逐条:
+ *  - `unparseable` 候选直接出局(读不出 ⇒ 不确定 ⇒ 不命中);
+ *  - `boundCallId` 必须逐字等于 `ask.toolCallId`(读口已按它查,这里是纵深防御);
+ *  - **因果下界**:`cp.createdAtMs >= ask.createdAtMs`(park 不可能早于它要 park 的那次 ask);
+ *  - **hash 双等**:两侧都必须在场且相等 —— 任一侧缺席即不命中(禁「能取到时才比」的可选谓词)。
+ *
+ * 多候选时的取舍:优先 `status === "pending"`(活着的那张 gate),否则取最早的一条(读口按
+ * `created_at ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
+ * 一个还能被 resume 的坐标上,对壳更有用。
+ */
+export function selectGateCandidate(ask, candidates) {
+    const askHash = ask.boundInputHash;
+    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];
+}
+/** 判据表 v2 的判定(纯函数;顺序 = 设计稿 §9 尾的五臂汇总,注见文件头)。 */
+export function decideReconcileAction(input) {
+    const { ask, candidates, run, batchState, nowMs, adhocGraceMs, orphanTtlMs } = input;
+    // ① identity ∧ hash 双等
+    if (input.allowBind !== false) {
+        const match = selectGateCandidate(ask, candidates);
+        if (match) {
+            return { kind: "bind", gate: { gateToken: match.token, gateBoundCallId: match.boundCallId, gateBoundInputHash: match.boundInputHash } };
+        }
+    }
+    // 批已 ABORTED = 取消腿走过 ⇒ abort 语义(§9 C3),与 run 终局与否无关:批一旦 ABORTED,这只 ask 的
+    // 投递面已经被整批撤掉,再判 run 状态没有意义。
+    if (batchState === "ABORTED")
+        return { kind: "void", reason: VOID_REASONS.BATCH_ABORTED };
+    // 🔴 bind-once 落选者(codex round2 R2-3):批已绑给**别人** ⇒ 本行结构上再也赢不了 `bindBatch`。
+    // 它是**当下就可判**的终局(VOID),不是「等等看」——落 hold 会让它滞留到 run 终局,然后被判据 2 误报
+    // 成路由失败。判据要求 `boundAskId` 真的读到且不是自己:读不到(null)时不据此下判(未知 ≠ 落选)。
+    if (batchState === "ROUTING_BOUND" && input.batchBoundAskId != null && input.batchBoundAskId !== ask.askId) {
+        return { kind: "void", reason: VOID_REASONS.BATCH_BOUND_ELSEWHERE };
+    }
+    // ② run 终局分臂
+    if (run !== null && TERMINAL_RUN_STATUS.has(run.status)) {
+        if (run.status === "failed" && run.errorCode === CANCELLED_ERROR_CODE) {
+            return { kind: "void", reason: VOID_REASONS.RUN_CANCELLED };
+        }
+        return { kind: "deny", reason: DENY_REASONS.ROUTING_FAILURE };
+    }
+    // ④ adhoc 双谓词(§8 C-2):结构判别 + 窗过 + 宽限。**不是** DENIED(约束②禁超时 denial)。
+    if (run === null && ask.sessionId === ask.taskId && nowMs > ask.expiresAtMs + adhocGraceMs) {
+        return { kind: "void", reason: VOID_REASONS.ADHOC_LEG_NO_DURABLE_DOMAIN };
+    }
+    // ⑤ 遗孤最终可判(§8 A-1 放宽形):量 immutable 的 createdAtMs。放在 ③ 之前判 —— 它是**所有**
+    // 「本轮判不出终局」的行的共同兜底,包括 run 一直在跑的那一支。
+    if (nowMs - ask.createdAtMs >= orphanTtlMs)
+        return { kind: "void", reason: VOID_REASONS.ORPHAN_TTL_EXCEEDED };
+    // ③ else:保持 PARKING(候下轮;执行器负责 deferReconcile 排队尾)。`candidates` 在这一臂被显式忽略
+    // ——判据 1 已经判过且没命中,这里不做任何「差不多算匹配」的兜底。
+    void candidates;
+    return { kind: "hold" };
+}
+export function createApprovalReconciler(deps) {
+    const { askStore, checkpoints, runs, logger, metrics, batchLimit, pendingGraceMs, adhocGraceMs, orphanTtlMs, emitRevoke } = deps;
+    /** 撤卡帧发射(live only;失败 catch + warn,**绝不回滚 CAS** —— 帧是通知,真源是行)。空名单不发。 */
+    const revoke = (row, askIds, reason, nowMs) => {
+        if (askIds.length === 0 || !emitRevoke)
+            return;
+        try {
+            emitRevoke(buildRevokeFrame(row.batchId, askIds, reason, nowMs), { owner: row.owner, sessionId: row.sessionId, taskId: row.taskId });
+        }
+        catch (err) {
+            try {
+                logger.warn("approval_revoke_emit_failed", { batchId: row.batchId, count: askIds.length, err: err instanceof Error ? err.message : String(err) });
+            }
+            catch {
+                // 可观测面自身绝不能变成故障源(reapers.ts createThrottledReaperCatch 同款纪律)。
+            }
+        }
+    };
+    /** 一条 `PARKING` 行的收敛(读事实 → 纯判定 → 一次 CAS)。返回本行落到哪一臂(供统计)。 */
+    const reconcileOne = async (ask, nowMs) => {
+        // ⓪ 批态**先读**(codex round3 R3-2):它是唯一一个能让本行「结构上再也不可能 bind」的事实,而且是
+        //    一次主键读。批已 `ABORTED` 或已绑给**别人** ⇒ 判据 1 的 `bindBatch` 谓词(`ROUTING_UNBOUND`)
+        //    注定不成立 ⇒ 跳过 checkpoint/run 两次读**结论不变**,却少挂两个可能黑洞化的依赖(原先的次序下,
+        //    一条挂死的 checkpoint 店会把这类**当下就可判**的行连同整个 `runOnce` 一起拖住,再经 reaper 的
+        //    in-flight 守卫把后续所有 tick 一并封死)。
+        const batchRow = await withDeadline(askStore.getBatch(ask.batchId), "getBatch");
+        let batchState = batchRow?.state ?? "MISSING";
+        let batchBoundAskId = batchRow?.boundAskId ?? null;
+        const irreversibleBatch = batchState === "ABORTED" || (batchState === "ROUTING_BOUND" && batchBoundAskId !== null && batchBoundAskId !== ask.askId);
+        // 判据 1:窄谓词精确查(scope 必填 —— 租户门是读口自己的责任,§8 D-3)。因果下界直接下推成
+        // `sinceMs`,SQL 侧就把早于本 ask 的 checkpoint 排掉了(`selectGateCandidate` 里还会再判一次,
+        // 纵深防御)。
+        if (checkpoints && !irreversibleBatch) {
+            const candidates = await withDeadline(checkpoints.findCheckpointCandidatesForAsk(encodeCheckpointScope(ask.owner), ask.sessionId, ask.toolCallId, ask.createdAtMs), "findCheckpointCandidatesForAsk");
+            const match = selectGateCandidate(ask, candidates);
+            if (match) {
+                // 🔴 `bindBatch` 内部**一次**完成 `PARKING→PARKED` + gate 落行 + 兄弟连坐 VOID(§8 A-2:正文
+                // 「先 transitionAsk 再 bindBatch」是死锁形,已作废)。只调它一次。
+                const res = await withDeadline(askStore.bindBatch(ask.batchId, ask.askId, {
+                    gateToken: match.token,
+                    gateBoundCallId: match.boundCallId,
+                    gateBoundInputHash: match.boundInputHash,
+                }), "bindBatch");
+                if (res.ok) {
+                    revoke(ask, res.voidedSiblings, "superseded_by_park", nowMs);
+                    return "parked";
+                }
+                // 判别式失败臂(§9 C3):拿到批的**真实**态 + 中选者,降级续判 —— `ABORTED` ⇒ VOID(abort 语义),
+                // `ROUTING_BOUND` 且中选者是兄弟 ⇒ VOID(bind-once 落选者,R2-3),其余按 ②③④⑤。
+                batchState = res.batchState;
+                batchBoundAskId = res.boundAskId ?? null;
+            }
+        }
+        // run 行只在批**还可能**让本行走下去时才读(不可逆批态下它对结论零影响,见 ⓪)。
+        const run = runs && !irreversibleBatch ? ((await withDeadline(runs.getRun(ask.taskId), "getRun")) ?? null) : null;
+        // 判据 1 已经在上面单独判过(命中即 `bindBatch`,不命中/绑失败都落这里)⇒ `allowBind: false`。
+        const action = decideReconcileAction({ ask, candidates: [], run, batchState, batchBoundAskId, nowMs, adhocGraceMs, orphanTtlMs, allowBind: false });
+        switch (action.kind) {
+            case "bind": {
+                // `allowBind: false` 下结构上不可达;留一条防御性 hold,绝不在这里第二次调 bindBatch。
+                await withDeadline(askStore.deferReconcile(ask.askId, "PARKING", ask.version, nowMs), "deferReconcile");
+                return "held";
+            }
+            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";
+            }
+            case "void": {
+                // 🔴 codex 交叉复审 C3(2026-08-06 真缺陷):**必须看 CAS 的返回值**。原先无条件记账 + 发撤卡帧
+                // ——本行若在判定与写入之间被另一个副本 `bindBatch` 收成 PARKED,这次 CAS 干净地输,行**没有**
+                // 被翻成 VOID,而帧却告诉壳「这张卡作废了」⇒ 直接违反撤卡帧守恒(名单 ≡ 真被翻成 VOID 的集合),
+                // 壳会清掉一张仍然有效、还在等 gate 的卡。输 ⇒ 什么都不做,下轮按新态重判。
+                const won = await withDeadline(askStore.transitionAsk(ask.askId, "PARKING", "VOID", { deniedReason: action.reason, updatedAtMs: nowMs }), "transitionAsk(VOID)");
+                if (!won)
+                    return "held";
+                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 });
+                }
+                // 单行 VOID 也是撤卡:壳上那张卡必须消失(名单 = 这一行自己)。
+                // reason 取 `"aborted"`:v1 的闭集只有两员,而 `"superseded_by_park"` 的字面语义是「**被别人的
+                // park 连坐**」——②④⑤ 三条臂(run 取消 / 批 ABORTED / adhoc 无对账域 / 遗孤 TTL)都不是那回事,
+                // 硬套会把归因写成谎。`"aborted"`(这条腿死了)是两员里唯一诚实的那个;真正的细分归因在**行上**
+                // (`denied_reason` 落的是 VOID_REASONS 的具体值),帧只负责让壳清卡。
+                // (存疑登记:v2 若要让壳按成因分渲,给 reason 闭集加一个 `"voided"` 成员即可,属 wire 加员。)
+                // 落选者(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";
+            }
+            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 {
+        async runOnce(nowMs) {
+            const stats = { scanned: 0, unmatchableNoHash: 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;
+            const parkingDeadline = Date.now() + RECONCILE_SEGMENT_BUDGET_MS; // R4-2:段一预算
+            for (const ask of parking) {
+                if (Date.now() >= parkingDeadline) {
+                    stats.budgetExhausted += 1;
+                    try {
+                        logger.warn("approval_reconcile_budget_exhausted", { segment: "PARKING", processed: stats.parked + stats.denied + stats.voided + stats.held + stats.failed, scanned: stats.scanned, budgetMs: RECONCILE_SEGMENT_BUDGET_MS });
+                    }
+                    catch {
+                        /* 可观测面绝不成为故障源 */
+                    }
+                    break; // 剩下的行下轮接着扫(队列轮转保证轮得到),绝不霸着 in-flight 守卫不放
+                }
+                if (ask.boundInputHash === null)
+                    stats.unmatchableNoHash += 1; // 判据 1 盲区(见字段顶注)
+                try {
+                    const outcome = await reconcileOne(ask, nowMs);
+                    if (outcome === "parked")
+                        stats.parked += 1;
+                    else if (outcome === "denied")
+                        stats.denied += 1;
+                    else if (outcome === "voided")
+                        stats.voided += 1;
+                    else
+                        stats.held += 1;
+                }
+                catch (err) {
+                    // 🔴 per-row 隔离(邻居 bg-agent per-scope 先例):一条行的坏 blob / 一次瞬时错误不许饿死同批
+                    // 其余 199 行。失败响亮(warn + 计数),行留在 PARKING 下轮重试。
+                    stats.failed += 1;
+                    try {
+                        logger.warn("approval_reconcile_row_failed", { askId: ask.askId, taskId: ask.taskId, err: err instanceof Error ? err.message : String(err) });
+                    }
+                    catch {
+                        /* 可观测面绝不成为故障源 */
+                    }
+                }
+            }
+            // ── 段二:孤儿 STREAM_PENDING 代打 expire(§1.3 + §8 D-1.1 宽限)──────────────────────────
+            // 🔴 **不是第五竞争者**:它就是窗到期竞争者在崩溃后的补位,同一 CAS 同一转移。宽限保证活属主的
+            // 本地 timer 常态必胜(reaper 退回纯崩溃兜底),不与在场闭包抢。
+            const pending = await withDeadline(askStore.listByState("STREAM_PENDING", batchLimit), "listByState(STREAM_PENDING)");
+            const orphanDeadline = Date.now() + RECONCILE_SEGMENT_BUDGET_MS; // R4-2:段二**独立**预算(段一吃光也照跑)
+            for (const row of pending) {
+                if (Date.now() >= orphanDeadline) {
+                    stats.budgetExhausted += 1;
+                    try {
+                        logger.warn("approval_reconcile_budget_exhausted", { segment: "STREAM_PENDING", expired: stats.orphansExpired, scanned: pending.length, budgetMs: RECONCILE_SEGMENT_BUDGET_MS });
+                    }
+                    catch {
+                        /* 同上 */
+                    }
+                    break;
+                }
+                if (row.expiresAtMs + pendingGraceMs >= nowMs)
+                    continue; // 窗未过 / 还在宽限内:属主在场,不碰
+                try {
+                    const res = await withDeadline(askStore.expireAsk(row.askId, row.batchId), "expireAsk(orphan)");
+                    if (!res.won)
+                        continue; // 干净地输 = 属主刚刚赢了,正常
+                    stats.orphansExpired += 1;
+                    revoke(row, res.voidedSiblings, "superseded_by_park", nowMs);
+                }
+                catch (err) {
+                    stats.failed += 1;
+                    try {
+                        logger.warn("approval_orphan_expire_failed", { askId: row.askId, taskId: row.taskId, err: err instanceof Error ? err.message : String(err) });
+                    }
+                    catch {
+                        /* 同上 */
+                    }
+                }
+            }
+            // 判据 1 盲区响亮化:有行结构上无法命中就每 tick 报一次(不是每行一次——刷屏没有信息量)。
+            // 静默地把「没法比」当成「比过了、不匹配」正是这条要治的病(它下游就是一个不诚实的 DENIED)。
+            if (stats.unmatchableNoHash > 0) {
+                try {
+                    logger.warn("approval_reconcile_rows_unmatchable", {
+                        rows: stats.unmatchableNoHash,
+                        scanned: stats.scanned,
+                        reason: "bound_input_hash is NULL — criterion 1 (identity ∧ hash) cannot match; rows fall through to the run-terminal / adhoc / orphan arms",
+                    });
+                }
+                catch {
+                    /* 可观测面绝不成为故障源 */
+                }
+            }
+            // 健康 tick 保持安静(邻居 reapCount 同姿势):只有真动了行才记一条。
+            if (stats.parked + stats.denied + stats.voided + stats.orphansExpired > 0) {
+                metrics?.inc("approval_reconciled_total", { outcome: "parked" }, stats.parked);
+                metrics?.inc("approval_reconciled_total", { outcome: "denied" }, stats.denied);
+                metrics?.inc("approval_reconciled_total", { outcome: "void" }, stats.voided);
+                metrics?.inc("approval_reconciled_total", { outcome: "orphan_expired" }, stats.orphansExpired);
+                logger.info("approval_reconcile_swept", { ...stats });
+            }
+            return stats;
+        },
+    };
+}
+//# sourceMappingURL=approval-reconciler.js.map

package/dist/boot/coordinators.d.ts

@@ -26,6 +26,7 @@ export declare function createLiveCoordinators(ctx: LiveCoordinatorsCtx): {
     question: QuestionCoordinator | undefined;
     toolApproval: ToolApprovalCoordinator | undefined;
     durableEnabled: boolean;
+    streamApprovalGate: import("../tool-approval.js").StreamApprovalGate;
     sendUserFileEmitter: SendUserFileEmitter | undefined;
     sendFileLedger: import("../plugins/send-file-ledger.js").SendFileLedger | undefined;
     sendUserFileToolSpec: import("@sema-agent/core").ToolSpec<import("typebox").TSchema> | undefined;

package/dist/boot/coordinators.js

@@ -1,6 +1,6 @@
 import { ElicitationCoordinator } from "../elicitation.js";
 import { QuestionCoordinator } from "../question.js";
-import { ToolApprovalCoordinator } from "../tool-approval.js";
+import { ToolApprovalCoordinator, resolveStreamApprovalGate } from "../tool-approval.js";
 import { SendUserFileEmitter, SEND_USER_FILE_MAX_BYTES, sendUserFileTool } from "../capabilities/send-user-file-tool.js";
 import { createSandboxFileSend, TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
 import { createSendUserFileIssuer } from "../plugins/send-user-file.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.
@@ -25,11 +27,44 @@ export function createLiveCoordinators(ctx) {
     // `spec.onAsk = boundAsk(ctx)`(server.ts 装配点)——core 继承链把闭包冻给委派子代,**bg/嵌套子代的
     // ask 浮到宿主 live 流**(带 sourceTaskId);真正无宿主流的腿(durable-submit/headless resume)才留
     // 「unavailable → durable park;无 park 设施 core fail-closed deny」。durable 部署 G1 语义不变。
-    const toolApproval = config.toolApprovalEnabled ? new ToolApprovalCoordinator() : undefined;
     // [1.294 G1] durable 姿势必须在 runnerDeps 字面量之前可判(onAsk 的「在场性」本身就是 core suspendAsk 的
     // 分路条件,不能再靠闭包惰性读)——判据与 checkpointStore 的构造条件同源(backend?.checkpoint 存在 ∧
     // DURABLE_APPROVAL;store 本体已上移至 subRunner 构造前,[1535] 断点② 双 Runner 挂载)。
+    // 🔴 #151 车3 刀 3b:本行**上移**到协调器构造之前 —— 它同时是流内审批协议的「park 设施在场性」判据
+    //    (§8.4),而协调器要在构造那一刻就知道自己带不带 askStore。位置即契约的原约束(必须在 RunnerDeps
+    //    字面量之前)不变,只是又提前了几行。
     const durableEnabled = backend?.checkpoint !== undefined && config.durableApproval === true;
+    // #151 车3 刀 3b(设计稿 §2.3 + §8.4):协议上场判据走**单一谓词**(与 /v1/capabilities 的
+    // `streamApproval` 格、与回决端点的 501 门同一个符号,见 resolveStreamApprovalGate 顶注)。
+    const streamApprovalGate = resolveStreamApprovalGate({
+        toolApprovalEnabled: config.toolApprovalEnabled === true,
+        streamApprovalEnabled: config.streamApproval.enabled,
+        backend,
+        parkFacility: durableEnabled,
+    });
+    // §8.4:协议**开着**却上不了场 = 合法部署形(不是配置错误)⇒ 一行 **info**(不是 warn),把原因说明白。
+    // 反过来「开关本来就没开」不打日志:那是默认形,每次启动刷一行噪音没有信息量。
+    if (config.streamApproval.enabled && !streamApprovalGate.active) {
+        logger.info("stream_approval_disabled", {
+            reason: streamApprovalGate.reason,
+            backendKind: backend?.kind ?? null,
+            checkpointStore: backend?.checkpoint !== undefined,
+            durableApproval: config.durableApproval === true,
+            toolApproval: config.toolApprovalEnabled === true,
+        });
+    }
+    const toolApproval = config.toolApprovalEnabled
+        ? new ToolApprovalCoordinator({
+            // 协议上场 ⇒ 持久层 + 60s 窗(§7:`STREAM_ASK_WINDOW_MS` **只在开关内**生效,
+            // `DEFAULT_APPROVAL_TTL_MS` 一个字不动);不上场 ⇒ 两者都不传,窗保持既有 5min(D1 逐字不变)。
+            ...(streamApprovalGate.active ? { askStore: streamApprovalGate.askStore, ttlMs: config.streamApproval.windowMs } : {}),
+            // 余量旋钮恒传(既有键,窗长三元公式的第二项;legDeadlineMonotonic 缺席时它不参与计算)。
+            windowMarginMs: config.streamAskWindowMarginMs,
+            // X-2 写侧准入门两帽(协议未上场时门本身不参与,见 ToolApprovalCoordinator.admit)。
+            admitMaxPerTask: config.streamApproval.admitMaxPerTask,
+            admitMaxPerOwner: config.streamApproval.admitMaxPerOwner,
+        })
+        : undefined;
     // SendUserFile(真 CC 契约,clay 2026-07-14)两种 lane 形态,其余缺席=诚实(工具不进 roster):
     //  - host lane:本地盘读+服务端上传,【单用户 only】——host 多租户=任意路径读→公网 URL 的 exfil 面,
     //    clay 拍永久关死,不留口子。路径=绝对或相对 process.cwd(用户目录语义,与 CC 一致)。
@@ -92,6 +127,6 @@ export function createLiveCoordinators(ctx) {
             : rawSend;
         return sendUserFileTool({ send, emitter: sendUserFileEmitter });
     })();
-    return { elicitation, question, toolApproval, durableEnabled, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec };
+    return { elicitation, question, toolApproval, durableEnabled, streamApprovalGate, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec };
 }
 //# sourceMappingURL=coordinators.js.map

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