@sema-agent/server 7.2.0 → 7.4.0

package/dist/http/routes/runs.js

@@ -1,4 +1,6 @@
+import { z } from "zod";
 import { uuidv7, mintCheckpointToken, CheckpointError, validatePendingSteer } from "@sema-agent/core";
+import { redactSecrets } from "../../trace/redact.js";
 import { HttpError, verifiedPrincipal, isUuidV7, encodeCheckpointScope } from "../../security.js";
 import { runInBackground } from "../../runs.js";
 import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../../orchestration/workflow-agent-steer.js";
@@ -6,8 +8,11 @@ import { defaultSubagentTailBus } from "../../fleet/subagent-tail-bus.js";
 import { fleetRunPublisher, fleetRunLabels } from "../../fleet/fleet-bus.js";
 import { composeSupervisorCost, infraCost, infraUsageFromEvents, hasInfraPricing } from "../../observability/cost-taxonomy.js";
 import { cascadeConfig, runMeta } from "../run-meta.js";
+import { createHash } from "node:crypto";
 import { scopedIdempotencyKey } from "../idempotency.js";
 import { streamSseLog } from "../sse-log.js";
+import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
+import { resolveStreamApprovalGate } from "../../tool-approval.js";
 import { normalizeRunEventType } from "../../trace/project.js";
 import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
 import { buildActiveRunConflict } from "../active-run-conflict.js";
@@ -36,6 +41,68 @@ export const ELICIT_RESPOND_RE = /^\/v1\/elicitations\/([^/]+)\/respond$/;
 // §4④: the shell answers the agent's AskUserQuestion here. Same live-only + same-replica shape as elicit.
 export const QUESTION_RESPOND_RE = /^\/v1\/questions\/([^/]+)\/respond$/;
 export const TOOL_APPROVAL_RESPOND_RE = /^\/v1\/tool-approvals\/([^/]+)\/respond$/;
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// #151 车4(design/172 §3.2;稿 = design/151-172-stream-approval/151-car4-design.md,§12 折叠节为准)
+// —— 流内审批卡的 **durable 回决口**。HITL 族第四条,但与上面三条 respond 的辖域正相反:
+//   · 三条 respond = LIVE-ONLY + 同副本(解一个内存里的悬挂 promise;跨副本/窗后一律 404);
+//   · 本条 = 打 `approval_asks` 行的 **CAS**(任何副本都能受理),本副本活体窗只是「顺带同步终局」。
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+export const TASK_ASK_DECISION_RE = /^\/v1\/tasks\/([^/]+)\/asks\/([^/]+)\/decision$/;
+/** 425 的轮询提示秒数(头与体成对,§12-C F37)。 */
+const ASK_PARKING_RETRY_AFTER_SEC = 2;
+/** `decision_actor` 的展示文本上限(171 ActorAssertion 的 `label` 帽,§2)。 */
+const ASK_ACTOR_LABEL_MAX = 256;
+/**
+ * 171 `ActorAssertion` 的 server 侧对齐形(**读**面 schema)。
+ *
+ * 🔴 属主与依赖(稿 §12-D 的施工偏离,如实记账):§12-D 裁「schema 落 `@sema-agent/registry-core`」,
+ * 而该包在本仓的 deps 上钉的是 `^0.16.0`(树上实际解析 0.16.0),`ActorAssertionWire` 要 0.17.1 才有 ——
+ * 抬依赖属于 package.json 面,不在本车的施工辖域(并行车共树)。本车按「用本地类型对齐 wire 形」落地:
+ * 键名/取值域逐字照 171(`{id, label?, verified?}`),**加** `via`(§12-D F7 的审计缺口补丁)。
+ * 依赖抬到 ≥0.17.1 的那一车应把本 schema 换成 registry-core 的同源导出(键集已对齐,零 wire 变更)。
+ *
+ * 读面刻意宽:行是别的进程/别的版本写下的,`verified`/`via` 缺席不是错误(缺席 = 那一版没记),
+ * 形真的不认 ⇒ 调用点省略 `actor` 字段而不是 500(§12-D F12)。
+ *
+ * 🔴 **不加 `.strict()`**(codex 交叉复审 round2 抓获,真 finding,红先验过):写面的 body schema 该严
+ * (未知键 = 调用方写错了,当场告诉他);**读**面严则是自伤 —— 未来某版给 actor 加一个附加字段,这里
+ * 一 `.strict()` 就把**整份** actor 判为不认、连 `id`/`verified` 都一起丢,而那正是本 schema 存在的
+ * 意义。zod 默认剥未知键:已知字段照常投影,附加字段静默丢弃(响应键集因此仍是封闭的)。
+ */
+const AskDecisionActorSchema = z.object({
+    id: z.string().min(1).max(ASK_ACTOR_LABEL_MAX),
+    label: z.string().max(ASK_ACTOR_LABEL_MAX).optional(),
+    verified: z.boolean().optional(),
+    via: z.enum(["owner", "operator"]).optional(),
+});
+/**
+ * 回决 body(稿 §3 + §12-F)。`.strict()` = 未知键当场 400,不静默吞。
+ *
+ * 🔴 `actor` 只收 `label`:`id`/`verified` 恒由 server 铸(171 §5.1 —— **actor 永不参与权限判定**,
+ * 它是审计投影,不是凭证)。调用方给的 id 若被采信,任何持有本 ask 读权的调用方都能把回决记在别人名下。
+ * 🔴 `idempotencyKey` 的形与店门口的 `assertIdempotencyKeyShape` 同规(1–255 且无首尾空白)——
+ * 端点先拒 ⇒ 坏形键永远走不到店(店那道门是最后一道,不是唯一一道)。
+ */
+const AskDecisionBodySchema = z
+    .object({
+    decision: z.enum(["approve", "deny"]),
+    /** 仅 approve 臂有意义;deny 带 = 宽收后忽略(与三条 respond 同姿势)。 */
+    updatedInput: z.unknown().optional(),
+    note: z.string().max(2048).optional(),
+    idempotencyKey: z
+        .string()
+        .min(1)
+        .max(255)
+        .refine((k) => k.trim() === k, { message: "idempotency key must not have leading/trailing whitespace" })
+        .optional(),
+    actor: z.object({ label: z.string().max(ASK_ACTOR_LABEL_MAX) }).strict().optional(),
+})
+    .strict();
+/** 行上的 `decision_actor`(裸 JSON)投成回显形;形不认 ⇒ undefined(调用点省略该键,不 500)。 */
+function projectDecisionActor(raw) {
+    const parsed = AskDecisionActorSchema.safeParse(raw);
+    return parsed.success ? parsed.data : undefined;
+}
 // C2 (core 1.219): steer a still-running Task SUB-AGENT of a run. `:target` = the child's
 // parentToolCallId (spawn-time identity, unique) or its agentName (display name; 409 when ambiguous).
 export const RUN_SUBAGENT_STEER_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/steer$/;
@@ -77,8 +144,36 @@ async function subagentReadGate(req, res, deps, runId) {
     }
     return { run, trusted };
 }
-async function streamRunEvents(req, res, runStore, taskId, staleMs) {
+async function streamRunEvents(req, res, deps, runStore, taskId, staleMs) {
     await streamSseLog(req, res, {
+        // #151 车3 §5.1:durable tail 腿的开流重放 —— 本 run 的未决审批卡按 taskId 读回并投成
+        // `approval_request` preamble 帧(时序=416 判定 + sseHeaders **之后**,见 sse-log.ts 的 hook 顶注)。
+        //
+        // 三条判据都在这几行里:
+        //  · **零写**:只 `listPendingByTask`,不 CAS、不改 expires_at_ms(投影见 buildReplayFrame 顶注);
+        //  · **坏行不炸开流**:形不合的 `card_json` 行跳过 + 一次 warn(不是每行一条,免得一张坏表刷屏);
+        //  · **读面帽**:超 `replayMax` 只投最新 N + 一次 warn。
+        //
+        // 🔴 开关谓词是**必须**的(codex 复审第二轮 high,2026-08-06):原按「关的时候表里本就没行 ⇒
+        // 无需分支」落地,但这个前提在**回滚**下不成立 —— 开着协议的副本(或更新版本)已经落下的
+        // `STREAM_PENDING` 行在关掉开关后**仍在表里**,无谓词的重放腿会把它们照常投上 wire,
+        // 「默认关 = 逐字零变化」(§6.5/§7.2)当场破。谓词同时省掉了关闭态每次开流的一次 store 往返
+        // 与那份 store 故障暴露面。钉:场景9(零帧 **且** 零 store 读 —— 只钉零帧会放过「读了但没投」)。
+        preamble: async (signal) => {
+            if (!deps.config.streamApproval.enabled)
+                return [];
+            const store = deps.backend?.approvalAsk();
+            if (!store)
+                return []; // env-only worker(无 durable backend)= 无 ask 账 ⇒ 无对账基准,诚实缺席
+            const rows = await store.listPendingByTask(taskId, signal);
+            const { frames, skipped, dropped } = buildApprovalPreamble(rows, Date.now(), deps.config.streamApproval.replayMax);
+            if (skipped > 0)
+                deps.logger?.warn?.("approval_preamble_row_skipped", { taskId, skipped, face: "run.events" });
+            if (dropped > 0)
+                deps.logger?.warn?.("approval_preamble_capped", { taskId, dropped, replayMax: deps.config.streamApproval.replayMax, face: "run.events" });
+            return buildApprovalPreambleSseFrames(frames);
+        },
+        onPreambleFailure: (reason, err) => deps.logger?.warn?.("approval_preamble_failed", { taskId, reason, face: "run.events", error: err instanceof Error ? err.message : String(err ?? "") }),
         statusOf: async (id) => {
             const run = await runStore.getRun(id);
             return run ? { status: run.status, updatedAt: run.updatedAt } : undefined;
@@ -240,7 +335,24 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             deps.subagentSteerRegistry, // C2 (core 1.219): register sync-delegation steer handles under this run's taskId
             (m, x) => deps.logger?.info?.(m, x), // emit-target diagnostics for the bg leg's inbox drain
             deps.sendUserFile, // SendUserFile 切片2:file_link 帧走本腿 durable append
-            deps.promptManifests);
+            deps.promptManifests, // [998]②: drained into a durable prompt_assembled event by this leg
+            // #151 车3 刀 3b:bg 腿的审批 ALS(此前这条腿无 ctx ⇒ 每只 ask 恒 "unavailable" ⇒ 恒 park)。
+            // 协议上场判据在**路由层**求值(单一谓词),执行腿只消费布尔——runs.ts 是纯执行面,不读 backend/config。
+            deps.toolApproval
+                ? {
+                    coordinator: deps.toolApproval,
+                    streamApprovalOn: resolveStreamApprovalGate({
+                        toolApprovalEnabled: true,
+                        streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
+                        backend: deps.backend,
+                        parkFacility: deps.checkpointStore !== undefined,
+                    }).active,
+                    // 两个窗旋钮随传:窗=0 的三源判定要在**本腿开始执行的时刻**做(那是 runInBackground 内部),
+                    // 路由层只负责把配置递过去 —— runs.ts 是纯执行面,不读 config。
+                    windowMs: deps.config.streamApproval?.windowMs ?? 0,
+                    windowMarginMs: deps.config.streamAskWindowMarginMs,
+                }
+                : undefined);
             return { status: 202, body: { taskId, sessionId, status: "running" } };
         }, (r) => r.status === 202); // don't cache a transient 409 (session-active, billed nothing) — let a retry re-run (council)
         sendJson(res, resp.status, resp.body);
@@ -274,7 +386,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         if (!runSessionAcceptOk(req, res, run, runMatch[2] ? "run.events" : "run.poll"))
             return; // [1499] accept-phase
         if (runMatch[2]) {
-            await streamRunEvents(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000);
+            await streamRunEvents(req, res, deps, deps.runStore, taskId, deps.config.runStaleSec * 1000);
         }
         else {
             const stale = run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > deps.config.runStaleSec * 1000;
@@ -571,14 +683,25 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const text = body.text;
         const priority = body.priority;
-        // Mint a server-side messageId so the shell can reference this steer (its drop handle once the core queue seam
-        // lands). Honest + stable now even while `priority` is a no-op forward-draft.
-        const messageId = uuidv7();
+        // 🔴 core 5.14.0(#147)之后**必须**把调用方的 Idempotency-Key 接到 core 的 `inputId` 上
+        // (codex 复审 2026-08-06 F4,验真后采纳)。队列化前,重发一条 steer 是 last-writer-wins ⇒ 无害;
+        // 队列化后,「202 丢在路上、客户端照常重试」会**再追加一条**同样的操作员指令,而队列只有
+        // MAX_PENDING_STEER_ENTRIES(=3)个位子 —— 三次重试就把它填满,之后合法转向一律 409 queue_full。
+        // 这条危害是本批的队列改动**引入**的,所以修它属于本批,不是顺手加功能。
+        // 形:与 `POST /v1/runs` 同一条 scoped 口径(source+verified principal+原 key),再 sha256 收成定长
+        // 不透明串 —— core 对 inputId 只限「非空 ≤128 且非保留词」,而 scoped 原串含 \x1f 分隔符且长度无界。
+        // 缺 header ⇒ 完全按旧行为(core 自铸 uuidv7),字节零变化。
+        const steerIdemRaw = headerStr(req.headers["idempotency-key"]);
+        const steerScoped = steerIdemRaw ? scopedIdempotencyKey(steerIdemRaw, source, principal) : undefined;
+        const steerInputId = steerScoped ? `idem-${createHash("sha256").update(steerScoped).digest("hex").slice(0, 32)}` : undefined;
+        // messageId:带 key 时**回同一个** id(重试拿到逐字相同的回执,与「这是同一条指令」一致);
+        // 不带 key 时保持历史的 uuidv7 现铸(壳的引用句柄,drop 动词候 core seam)。
+        const messageId = steerInputId ?? uuidv7();
         // trusted = explicit operator (NOT bare isOperator — its empty-list "true-for-all" would let any caller send a
         // system-authority steer). A normal owner's steer reaches the model as a plain user message (trusted:false).
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         try {
-            validatePendingSteer({ text, trusted }); // throws CheckpointError(steering.invalid_content) on break-out / control chars
+            validatePendingSteer({ text, trusted, ...(steerInputId !== undefined ? { inputId: steerInputId } : {}) }); // throws CheckpointError(steering.invalid_content) on break-out / control chars / bad inputId
         }
         catch (e) {
             if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
@@ -605,6 +728,15 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         // row to "suspended"), and CASes on `status='pending'`, so this lands iff the run is genuinely parked. Read the
         // checkpoint's ACTUAL scope ("_" for a no-principal run) then its token; a missing scope/token/CAS-loss means
         // the checkpoint resolved/expired/never-existed → "no-checkpoint". "no-store" = no checkpoint store wired.
+        // core 5.14.0(#147)队列化后新出的第四态:park 的队列**满了**。core 的界是 fail-loud 的 ——
+        // 越界抛 `steering.queue_full` 而不是驱逐一条已被接受的指令(驱逐 = 把队列本来要消灭的静默丢失
+        // 原样请回来)。所以这条必须有自己的 wire 码,不能折进 `no-checkpoint`(那会谎称「已不再挂起」)。
+        // 另一个新码 `steering.duplicate_input_id` 自本批起**可达**:调用方带 `Idempotency-Key` 时它被接成
+        // core 的 `inputId`(见下),同 key 配不同正文即撞键 ⇒ 409。不带 key 的调用方永远碰不到它。
+        let parkQueueFull;
+        let parkDuplicateKey;
+        /** 每个 durable park 调用点的同一份入参(带上幂等键才让 core 的 inputId 去重真正可达)。 */
+        const steerInput = () => ({ text, trusted, ...(steerInputId !== undefined ? { inputId: steerInputId } : {}) });
         const tryPark = async () => {
             const cs = deps.checkpointStore;
             if (!cs)
@@ -615,8 +747,25 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             const token = await cs.findPendingTokenBySession(run.sessionId, scope);
             if (!token)
                 return "no-checkpoint";
-            return (await cs.setPendingSteer(token, scope, { text, trusted })) ? "parked" : "no-checkpoint";
+            try {
+                return (await cs.setPendingSteer(token, scope, steerInput())) ? "parked" : "no-checkpoint";
+            }
+            catch (e) {
+                if (e instanceof CheckpointError && e.code === "steering.queue_full") {
+                    parkQueueFull = e.message;
+                    return "queue-full";
+                }
+                // 同一个 Idempotency-Key 配**不同**正文 —— core 拒绝(吞掉它就等于把队列要消灭的静默丢失请回来)。
+                // 与 `conflict.ask_idempotency` 同族语义:换一个 key,别复用。
+                if (e instanceof CheckpointError && e.code === "steering.duplicate_input_id") {
+                    parkDuplicateKey = e.message;
+                    return "duplicate-key";
+                }
+                throw e;
+            }
         };
+        const sendQueueFull = () => sendError(res, 409, "steering.queue_full", parkQueueFull ?? "the parked steering queue on this checkpoint is full");
+        const sendDuplicateKey = () => sendError(res, 409, "steering.duplicate_input_id", parkDuplicateKey ?? "this Idempotency-Key is already parked with different steering content — reissue with a fresh key");
         const sendParked = () => sendJson(res, 202, { taskId, status: "suspended", delivery: "queued", messageId, ...(priority ? { priority } : {}), note: "steer parked on the checkpoint — injected when the run resumes" });
         const sendNotRunning = (error) => sendError(res, 409, "steering.not_running", error);
         // (a) Same-replica live path: the run is streaming here → inject now (drained at the next turn boundary).
@@ -638,10 +787,19 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 // Raced: the stream finished between the map lookup and steer(). It may have durably SUSPENDED in the SAME
                 // tick (core already wrote the pending checkpoint) — fall through to the durable park rather than a spurious
                 // 409 (the live→suspended transition window). Only a genuinely-terminal run → not_running.
-                if (await tryPark() === "parked") {
+                const raced = await tryPark();
+                if (raced === "parked") {
                     sendParked();
                     return;
                 }
+                if (raced === "queue-full") {
+                    sendQueueFull();
+                    return;
+                }
+                if (raced === "duplicate-key") {
+                    sendDuplicateKey();
+                    return;
+                }
                 sendNotRunning("run just finished — no longer accepting steers");
                 return;
             }
@@ -657,6 +815,14 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 sendParked();
                 return;
             }
+            if (outcome === "queue-full") {
+                sendQueueFull();
+                return;
+            }
+            if (outcome === "duplicate-key") {
+                sendDuplicateKey();
+                return;
+            }
             sendNotRunning("run is no longer suspended (resolved or expired)");
             return;
         }
@@ -682,13 +848,43 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             }
             // per-session 串行(复审 HIGH:并发双终态 steer 的 tryPark→put 窗口双铸两个 pending park)。
             const prior = wakeParkMints.get(run.sessionId) ?? Promise.resolve();
-            const mintResult = { parked: false };
+            const mintResult = { parked: false, queueFull: false, duplicateKey: false };
+            // wake park 腿的 queue_full:新铸的 task_done checkpoint 队列必空,所以只可能来自「锁内重查撞到
+            // 既有 pending」或「跨副本赢家」两条既有 park 上——两处都要如实报满,不许折成「不接受转向」。
+            const parkOnce = async (t, sc) => {
+                try {
+                    if (await deps.checkpointStore.setPendingSteer(t, sc, steerInput()))
+                        mintResult.parked = true;
+                }
+                catch (e) {
+                    if (e instanceof CheckpointError && e.code === "steering.queue_full") {
+                        parkQueueFull = e.message;
+                        mintResult.queueFull = true;
+                        return;
+                    }
+                    if (e instanceof CheckpointError && e.code === "steering.duplicate_input_id") {
+                        parkDuplicateKey = e.message;
+                        mintResult.duplicateKey = true;
+                        return;
+                    }
+                    throw e;
+                }
+            };
             const job = prior.then(async () => {
                 const cs = deps.checkpointStore;
-                if (await tryPark() === "parked") {
+                const reprobe = await tryPark();
+                if (reprobe === "parked") {
                     mintResult.parked = true;
                     return;
                 } // 锁内重查:前一位刚铸完 → 直接 park 上去
+                if (reprobe === "queue-full") {
+                    mintResult.queueFull = true;
+                    return;
+                }
+                if (reprobe === "duplicate-key") {
+                    mintResult.duplicateKey = true;
+                    return;
+                }
                 const leafId = await Promise.resolve(deps.sessionStorage.getLeafId(run.sessionId)).catch(() => undefined);
                 if (leafId === undefined || leafId === null)
                     return;
@@ -711,12 +907,10 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 const winner = await cs.findPendingTokenBySession(run.sessionId).catch(() => null);
                 if (winner !== null && winner !== wakeToken) {
                     await cs.expire(wakeToken, cpScope).catch(() => undefined);
-                    if (await cs.setPendingSteer(winner, cpScope, { text, trusted }))
-                        mintResult.parked = true;
+                    await parkOnce(winner, cpScope);
                     return;
                 }
-                if (await cs.setPendingSteer(wakeToken, cpScope, { text, trusted }))
-                    mintResult.parked = true;
+                await parkOnce(wakeToken, cpScope);
             });
             const wrapped = job.catch(() => undefined);
             wakeParkMints.set(run.sessionId, wrapped);
@@ -728,6 +922,14 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 if (wakeParkMints.get(run.sessionId) === wrapped)
                     wakeParkMints.delete(run.sessionId);
             }
+            if (mintResult.queueFull) {
+                sendQueueFull();
+                return;
+            }
+            if (mintResult.duplicateKey) {
+                sendDuplicateKey();
+                return;
+            }
             if (mintResult.parked) {
                 sendJson(res, 202, { taskId, status: run.status, delivery: "parked_for_wake", messageId, ...(priority ? { priority } : {}), note: "run already ended — steer parked on a task_done checkpoint; deliver it with POST /v1/sessions/:id/wake" });
                 return;
@@ -1381,10 +1583,340 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.invalid_json", "invalid JSON body");
             return;
         }
-        const { status, body: respBody } = deps.toolApproval.respond(id, principal, body);
+        // #151 车2:respond() 的返回型是 union(store 缺席时同步、在场时 Promise——src/tool-approval.ts 顶注);
+        // await 对两者都是恒等/透传操作,这里统一 await 以兼容两条路径。
+        const { status, body: respBody } = await deps.toolApproval.respond(id, principal, body);
         sendJson(res, status, respBody);
         return;
     }
+    // #151 车4:POST /v1/tasks/:taskId/asks/:askId/decision —— durable 回决(辖域对比见 TASK_ASK_DECISION_RE 顶注)。
+    const askDecisionMatch = req.method === "POST" ? TASK_ASK_DECISION_RE.exec(url) : null;
+    if (askDecisionMatch) {
+        if (rateLimited(req, res))
+            return; // 打的是一行 CAS,不新开模型工作 ⇒ 不过配额门(与三条 respond 同判)
+        // 协议关 / 无 durable backend ⇒ 根本没有可 CAS 的账本。501 fail-loud:静默 404 会把「本部署没接这个
+        // 面」伪装成「你的 ask 不存在」,而这两件事的处置完全相反(改部署 vs 别重试)。
+        //
+        // 🔴 **上场判据 = 单一谓词**(车3 刀 3b 收口)。车4 落地时这里是一份局部的
+        // `enabled ∧ backend ∧ kind !== "local"` 临时执行面,注释里写死了交接条件:「等能力面 `streamApproval`
+        // 那一车,把 `kind === "local"` 换成消费**那一个**谓词并同步删掉本段 —— 两份判据长期并存必然漂」。
+        // 兑现即此:`resolveStreamApprovalGate` 现在同时服务协调器注入(boot/coordinators.ts)、
+        // `/v1/capabilities` 的 `streamApproval` 格与本口的 501 门。判据由三项扩到五项(多了 `toolApproval`
+        // 在场与 **park 设施**在场,§8.4)——本口因此更严:能力面说 false 的部署,这里恒 501,不会出现
+        // 「能力面诚实说没有、端点却收下一批注定无处安放的决议」。
+        const gate = resolveStreamApprovalGate({
+            toolApprovalEnabled: Boolean(deps.toolApproval),
+            streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
+            backend: deps.backend,
+            parkFacility: deps.checkpointStore !== undefined,
+        });
+        const askStore = gate.active ? gate.askStore : undefined;
+        if (!askStore) {
+            sendError(res, 501, "feature.approval_ask_disabled", "the durable stream-approval ask ledger is not enabled on this worker (needs STREAM_APPROVAL_ENABLED plus a DURABLE store backend — the local lane keeps asks in memory and would lose accepted decisions on restart)");
+            return;
+        }
+        // §12-F 前置链(逐字照三条 respond 的先例):rateLimited → principal 门 → readJson → safeParse。
+        // 身份恒取 gatedPrincipal(已验证的那份),**绝不**取可伪造的头 —— 它同时是属主门与 actor 铸造的唯一源。
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && principal === undefined) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        let rawBody;
+        try {
+            rawBody = await readJson(req);
+        }
+        catch {
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        const parsedBody = AskDecisionBodySchema.safeParse(rawBody);
+        if (!parsedBody.success) {
+            sendError(res, 400, "request.body_shape", "invalid ask decision body — expected decision=approve|deny plus optional updatedInput / note / idempotencyKey / actor.label");
+            return;
+        }
+        const body = parsedBody.data;
+        // `updatedInput` 的**在场**判定读原始体:`z.unknown().optional()` 解出来的 undefined 分不清
+        // 「没给这个键」与「给了 undefined」,而 forwarded 位的语义是前者。
+        const hasUpdatedInput = typeof rawBody === "object" && rawBody !== null && "updatedInput" in rawBody;
+        const taskId = askDecisionMatch[1];
+        const askId = askDecisionMatch[2];
+        // 404 三处同文同码(行不存在 / taskId 不属 / 属主门不过)—— 不给存在性谕示是这条门的全部意义,
+        // 三条臂只要文案分岔就等于把「它存在但不是你的」写在 wire 上(decide 面 parity)。
+        const askNotFound = () => sendError(res, 404, "not_found.ask", "no such approval ask under this task (never existed, belongs to another task, or is not yours)");
+        const row0 = await askStore.getAsk(askId);
+        if (!row0 || row0.taskId !== taskId) {
+            askNotFound();
+            return;
+        }
+        // §2 v1 判据 = 行 owner 一致 ∨ 显式 operator。`owner === null`(auth-off 单用户)恒过。
+        // 172 的 `task.approve` 独立动词候 center runtimeCaps 有位后再升级,v1 不 block(稿 §2)。
+        const ownerOk = row0.owner === null || (principal !== undefined && row0.owner === principal);
+        const operatorOk = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        if (!ownerOk && !operatorOk) {
+            askNotFound();
+            return;
+        }
+        // CSRF:本仓无 cookie 面(身份恒来自头/凭证,浏览器不会自动附带)⇒ 不适用(§12-D F8 显式收案)。
+        const actor = {
+            id: principal ?? "_", // auth-off 哨兵,与 durable scope 的 "_" 同字
+            ...(body.actor ? { label: redactSecrets(body.actor.label).slice(0, ASK_ACTOR_LABEL_MAX) } : {}),
+            verified: principal !== undefined, // auth-off 下无「验证」可言,如实 false
+            via: ownerOk ? "owner" : "operator",
+        };
+        // 回放形与首决 200 形同键集,只差 `updatedInputForwarded`(它是本副本活体状态的函数,回放不承诺
+        // 字节等同 —— §12-A 明写)。`actor` 从行上读出、safeParse 不过就省略(F12),不 500。
+        /**
+         * 🔴 见到一条 DECIDED 行 ⇒ **先把本副本活体窗同步到它**,再谈这次请求该拿 200 还是 409
+         * (codex 交叉复审 round4 [high] + round5 [high],两轮真 finding,均红先验过)。
+         *
+         * round4 抓的是回放臂:提交歧义窗自己许诺的处置(带同一把键重试)会走 200 回放,而那只活体卡
+         * 从没被结算过 —— run 一直等到窗到期,端点的头号承诺(「窗内回决 run 不停」)在它自己写下的恢复
+         * 路径上不成立。round5 抓的是同一个洞的另一半:**无幂等键**的那次歧义之后,重试落的是 409 臂,
+         * 那条臂当时同样不结算 —— 同一个 run 照样挂死;跨副本回决的本地输者也是这条臂。
+         *
+         * 收敛后的判据一句话:**响应分类不许决定本地是否结算**。行上有权威决议这件事,与「这次请求算
+         * 重试还是算冲突」完全正交 —— 前者是事实,后者只是这次调用的礼节。
+         *
+         * 三条纪律:①用**行上的**决议,不是这次请求带的(权威是首决,B-2 已钉「异决重试回放首决」);
+         * ②**不**转发这次请求的 `updatedInput`(它没有与幂等键一起持久绑定,转发等于让重试悄悄改写首决
+         * 的载荷);③因此回放恒**省略** `updatedInputForwarded`。协调器缺席/查无条目都是正常(跨副本、
+         * 窗已关),`notifyExternalDecision` 对已结算条目天然幂等(其顶注),故重复调用无害。
+         *
+         * 返回值 = 这行是否是一条**可当权威人决用**的 DECIDED 行。三个合取项(codex round5 [medium] +
+         * round6 [high],两轮各补一半),缺任一项都**既不结算也不作答**,而是记不变量 + 500:
+         *   ① `decision ∈ {approve, deny}` —— 列可空且通用 `transitionAsk` 不强制 decision 载荷,DECIDED
+         *      而无决议是可表示的坏行;把它当 200/409 交出去等于把持久层损坏包装成协议答案(契约是二值)。
+         *   ② `provisional === false` —— `AskRow.provisional` 的语义(§3.0 对账三约束②)就是「这条终态还可能
+         *      被 `resolveProvisional` 版本化收敛掉」。**未定稿的终态不是终态**:照它 `notifyExternalDecision(true)`
+         *      会在持久行还可能被补偿成 VOID 之前就放行一次不可逆工具调用 —— 结算是单向门,不可回收。
+         *   ③ `decidedAtMs !== null` —— 它是响应体与回放形的必备字段,也是「这条决议真的被 decideAsk 落过」
+         *      的印记;为空说明这行不是走回决腿铸出来的。
+         * 三者今天都没有在树上的写者会产生(人决恒走 `decideAsk`,它三项齐备),所以这是**fail-closed 的
+         * 结构性守卫**,不是对某个已知 bug 的补丁 —— 判据是「可表示即须拒」,因为代价不对称:错拒 = 一次
+         * 500,错认 = 一次不可逆放行。
+         */
+        // 判据本身(纯守卫,不结算)—— **三个入口共用一份**:CAS 赢者、CAS 输者重读、幂等预查命中。
+        // 🔴 三入口必须同守(codex round7 [high],真 finding,红先验过):此前只守了后两个,而 `decideAsk`
+        // 的 CAS 谓词只看 `state='STREAM_PENDING'`、既不谓词也不清 `provisional` —— 一条 provisional 的
+        // STREAM_PENDING 行赢下 CAS 就成了 provisional 的 DECIDED 行,赢者臂照样放行。守卫贴在「见到一条
+        // DECIDED 行」这件事上,不贴在「怎么见到的」上,才没有第四个入口能绕过去。
+        // 🔴 `state === "DECIDED"` 是第四个合取项(codex round10 [high]):赢者臂是唯一不先判 state 就调本
+        // 谓词的入口,而 `decideAsk` 提交与回读之间那条行可能已被 `resolveProvisional` 版本化收敛走
+        // (例如 provisional 的 DECIDED 被收敛成 VOID 却**留着** decision/decidedAtMs 元数据)——只验元数据
+        // 会让那条已经不是 DECIDED 的行照样放行。谓词名叫「这条 DECIDED 行权威吗」,那就把 DECIDED 本身
+        // 也验了,四个入口才真的同守。
+        const decidedRowIsAuthoritative = (row) => {
+            if (row.state !== "DECIDED" || row.decision !== "approve" && row.decision !== "deny" || row.provisional || row.decidedAtMs === null) {
+                deps.logger?.error?.("ask_decision_row_not_authoritative", {
+                    taskId,
+                    askId,
+                    state: row.state,
+                    decision: row.decision,
+                    provisional: row.provisional,
+                    decidedAtMs: row.decidedAtMs,
+                });
+                sendError(res, 500, "internal.error", "the stored ask row is DECIDED but is not a usable human decision (missing approve/deny, still provisional, or missing decidedAtMs) — no answer can be given for it");
+                return false;
+            }
+            return true;
+        };
+        const syncLiveFromDecidedRow = (row) => {
+            if (!decidedRowIsAuthoritative(row))
+                return false;
+            deps.toolApproval?.notifyExternalDecision(row.askId, row.decision === "approve");
+            return true;
+        };
+        /** 200 回放形:与首决 200 同键集,只差 `updatedInputForwarded`(§12-A 明写回放不承诺字节等同)。
+         *  调用前提 = 已过 {@link syncLiveFromDecidedRow}(行合形且活体窗已同步)。 */
+        const replayDecided = (row) => {
+            const storedActor = projectDecisionActor(row.decisionActor);
+            sendJson(res, 200, {
+                askId: row.askId,
+                taskId: row.taskId,
+                decision: row.decision,
+                decidedAtMs: row.decidedAtMs,
+                ...(storedActor ? { actor: storedActor } : {}),
+            });
+        };
+        // 终局分派 —— **一律按传进来的这一行**投影,不重读(§12-A:`DecideResult.row` 已是新鲜行;
+        // 补一次确认读只会引入第三个时点,让响应描述的行与 CAS 判定的行再次分家)。
+        const sendTerminal = (row) => {
+            switch (row.state) {
+                case "DECIDED": {
+                    // 结算**先于**响应分类(见 syncLiveFromDecidedRow 顶注:200 与 409 两臂对本地活体窗是同一件事)。
+                    if (!syncLiveFromDecidedRow(row))
+                        return; // 坏行 ⇒ 已答 500
+                    // §12-A 顺序钉:**先**比幂等键。同 key 的两个并发请求都会 miss 上面的预查(那时谁都还没落键),
+                    // 输者重读时若不先比键,会把一次合法重试错报成 409。
+                    if (body.idempotencyKey !== undefined && row.idempotencyKey === body.idempotencyKey) {
+                        replayDecided(row);
+                        return;
+                    }
+                    const first = projectDecisionActor(row.decisionActor);
+                    // 首决回显三件;`note` **不回显**(以请求者可见权限为界的最窄安全形,稿 §5)。
+                    sendError(res, 409, "conflict.ask_decided", "this ask was already decided — the first decision stands and is echoed here", {
+                        decision: row.decision,
+                        decidedAtMs: row.decidedAtMs,
+                        ...(first ? { actor: first } : {}),
+                    });
+                    return;
+                }
+                case "PARKED":
+                    // §12-C:三件坐标,**不含 gateToken** —— checkpointToken 是从不外发的 resume 凭证
+                    // (approval-hmac 的既定不变量);壳按 sessionId 走现行 durable gate 流程。
+                    sendError(res, 410, "gone.ask_parked", "the in-stream window closed and this ask was parked onto the durable approval gate — decide it through that gate for the session echoed here", {
+                        sessionId: row.sessionId,
+                        gateBoundCallId: row.gateBoundCallId,
+                        gateBoundInputHash: row.gateBoundInputHash,
+                    });
+                    return;
+                case "DENIED":
+                case "VOID":
+                    sendError(res, 410, "gone.ask", "this ask reached a terminal state without a human decision (routing failure or batch abort) and can no longer be decided", {
+                        state: row.state,
+                        ...(row.deniedReason !== null ? { deniedReason: row.deniedReason } : {}),
+                    });
+                    return;
+                case "PARKING":
+                    // §12-C F44:PARKING 体**不含** gate 坐标(bindBatch 才写,此刻尚未存在)——只给轮询位置。
+                    res.setHeader("retry-after", String(ASK_PARKING_RETRY_AFTER_SEC));
+                    sendError(res, 425, "parking.ask_retry", "this ask is mid-park — retrying tells you where it finally landed; a retry does NOT queue this decision for acceptance", {
+                        retryAfterSec: ASK_PARKING_RETRY_AFTER_SEC,
+                    });
+                    return;
+                default:
+                    // STREAM_PENDING 出现在这里 = 状态机转移表无回边却回去了(不变量破)。fail-loud 500 且
+                    // **禁重入 CAS**(§12-A F20):重入等于在一个已知不可信的状态上再赌一次。
+                    deps.logger?.error?.("ask_decision_state_invariant", { taskId, askId, state: row.state });
+                    sendError(res, 500, "internal.error", "ask decision hit an impossible row state (a CAS loser re-read a still-pending row) — no decision was recorded");
+                    return;
+            }
+        };
+        // 🔴 **观察到即验权 + 即同步**(codex 交叉复审 round8 [high],真 finding,红先验过)。
+        //
+        // 这是 round4/round5/round8 三轮同一族缺口的收口形。前两轮把结算分别补进了 200 回放臂和 409 冲突臂,
+        // 但**跨 ask 撞键**那条臂在它们之前就 return 了:row0 明明已经是 DECIDED(这次请求已经看见了权威
+        // 决议),却因为幂等键属于另一只 ask 而直接 409 走人 —— 本副本那只活体卡照样挂到窗到期。幂等预查
+        // 本身抛错也同理(冒到外层 500,同样没同步)。
+        //
+        // 根治不是再补第三处调用,而是把这一步提到**观察到这行的那一刻**:凡这次请求手里有一条 DECIDED 行,
+        // 先验它是不是权威决议、再把本地活体窗同步到它,**之后**才谈这次请求该拿 200 / 409 / 500。于是
+        // 「响应分类不许决定本地是否结算」成为结构性成立,而不是靠每条臂各自记得调一次。
+        // (下游 `sendTerminal` 的 DECIDED 臂仍会再调一次:`notifyExternalDecision` 对已结算条目幂等,
+        //  重复调用是无操作 —— 宁可重复,不可遗漏。)
+        if (row0.state === "DECIDED" && !syncLiveFromDecidedRow(row0))
+            return;
+        // ①幂等回放预查(§5-4 + §12-A):命中同 askId 且已 DECIDED ⇒ 直接回放,**不打第二次 CAS**;
+        // 命中另一 askId ⇒ 409(跨 ask 回放会掩盖调用方的键管理缺陷,且 172「禁复用旧同意」排除该解,F23)。
+        if (body.idempotencyKey !== undefined) {
+            const hit = await askStore.getByIdempotencyKey(taskId, body.idempotencyKey);
+            if (hit && hit.askId !== askId) {
+                sendError(res, 409, "conflict.ask_idempotency", "this idempotency key is already bound to a different ask under this task — reuse of a key across asks is refused", {
+                    idempotencyKey: body.idempotencyKey,
+                });
+                return;
+            }
+            if (hit && hit.state === "DECIDED") {
+                if (!syncLiveFromDecidedRow(hit))
+                    return; // 同上:先同步活体窗,坏行 ⇒ 500
+                replayDecided(hit);
+                return;
+            }
+        }
+        if (row0.state !== "STREAM_PENDING") {
+            sendTerminal(row0);
+            return;
+        }
+        // 先读后分派是**优化**不是判权:CAS 仍是唯一权威,输者按它带回的新鲜行分派。
+        //
+        // 🔴 提交歧义窗(§12-A 的「行缺失 ⇒ 500 fail-loud + 日志注明」条款;codex 交叉复审 round2 抓获本
+        // 实现漏了它):`SqlApprovalAskStore.decideAsk` 是「事务提交 → **另起**一次独立 getAsk 读」的形态
+        // (approval-ask-store-sql.ts,commit() 之后那一行)。那次读若失败/读不到行,它抛 —— 而**决议此刻
+        // 可能已经持久了**。裸让它冒到外层兜底 catch 会给调用方一个不带任何线索的 500:他既不知道该不该重
+        // 试,不带幂等键重试还会撞 409(首决已在)。这里把它接住,fail-loud 但**把处置写进文案与日志**:
+        // 带**同一个** idempotencyKey 重试 ⇒ 若决议真已落地,幂等回放路径会 200 把它原样交回。
+        let outcome;
+        try {
+            outcome = await askStore.decideAsk(askId, row0.batchId, {
+                decision: body.decision,
+                decisionActor: actor,
+                decisionNote: body.note ?? null,
+                idempotencyKey: body.idempotencyKey ?? null,
+            });
+        }
+        catch (err) {
+            deps.logger?.error?.("ask_decision_commit_ambiguous", {
+                taskId,
+                askId,
+                hadIdempotencyKey: body.idempotencyKey !== undefined,
+                error: err instanceof Error ? err.message : String(err ?? ""),
+            });
+            // 🔴 处置**按幂等键在场与否分岔**(codex round3 抓获,真 finding):无键的请求根本没有「同一把键」
+            // 可重试,而一次盲重试撞上的是已决行(409),把「可能已批准」错读成「批准冲突」。无键臂如实说
+            // 它做不到,并指出下次怎么做得到 —— 承诺一个不存在的处置比不给处置更坏(过期声明族)。
+            if (body.idempotencyKey !== undefined) {
+                sendError(res, 500, "internal.error", "the ask decision store failed around commit — the decision MAY already be persisted; retry with the same idempotencyKey to replay it instead of colliding with it");
+            }
+            else {
+                sendError(res, 500, "internal.error", "the ask decision store failed around commit — the decision MAY already be persisted, and this request carried no idempotencyKey, so a blind retry cannot be told apart from a first attempt; re-read the ask state before retrying, and send an idempotencyKey next time so retries can replay");
+            }
+            return;
+        }
+        if (!outcome.ok) {
+            // 🔴 同一条纪律施于**输者带回的行**(codex 交叉复审 round9 [high],真 finding,红先验过):
+            // `idempotency_conflict` 臂原先直接 409、把 `outcome.row` 丢掉,而店契约允许该臂带回目标行,
+            // SQL twin 更是在**回滚之后**才读它 —— 那一刻它完全可能已经是别人决出来的 DECIDED。于是又一条
+            // 「已经看见权威决议却不结算」的臂(活体窗挂到窗到期),外加「非权威行被撞键 409 掩盖」。
+            // 放在 reason 分派**之前** ⇒ 三个 reason 一视同仁,不靠每条臂各自记得。至此本 handler 能拿到
+            // AskRow 的**全部四个来源**(row0 / 幂等预查命中 / CAS 赢者行 / CAS 输者行)都在守卫下游。
+            if (outcome.row?.state === "DECIDED" && !syncLiveFromDecidedRow(outcome.row))
+                return;
+            if (outcome.reason === "idempotency_conflict") {
+                sendError(res, 409, "conflict.ask_idempotency", "this idempotency key is already bound to a different ask under this task — reuse of a key across asks is refused", {
+                    idempotencyKey: body.idempotencyKey,
+                });
+                return;
+            }
+            if (outcome.row === null) {
+                askNotFound(); // 并发删(deleteByTask)——行没了,如实 404
+                return;
+            }
+            sendTerminal(outcome.row);
+            return;
+        }
+        // 赢下 CAS **不等于**这行就能放行(codex round7 [high]):`decideAsk` 的谓词只看 `state`,不看也不清
+        // `provisional` —— 赢者臂同样要过那一份权威守卫,否则一条 provisional 行会从这个入口绕过去(结算是
+        // 单向门,而 `resolveProvisional` 事后还可能把它补偿成 VOID)。守卫在**结算之前**。
+        if (!decidedRowIsAuthoritative(outcome.row))
+            return;
+        // 🔴 结算的**每一个入参都取自行**,不取自请求(codex round10 [high]):赢者臂原先用 `askId` 与
+        // `body.decision` 结算 —— 那是本 handler 最后一处「按请求而非按行」的地方。提交与回读之间那条行
+        // 可能已被版本化收敛改写,此时按请求结算 = 放行一个与持久真相相反的决议(结算不可回收)。
+        if (outcome.row.decision !== body.decision) {
+            // 行与本次请求分岔:本地仍按**行**收敛(活体窗恒随持久真相走,哪怕代价是拒),HTTP 侧 fail-loud
+            // —— 调用方提交的那个决议不是最终生效的那个,让他重读而不是以为自己批了。
+            deps.logger?.error?.("ask_decision_row_diverged", { taskId, askId, requested: body.decision, stored: outcome.row.decision });
+            deps.toolApproval?.notifyExternalDecision(outcome.row.askId, outcome.row.decision === "approve");
+            sendError(res, 500, "internal.error", "the ask row was rewritten between commit and read-back — the decision that stands is not the one this request submitted; re-read the ask before acting on it");
+            return;
+        }
+        // 端点已是唯一权威。协调器缺席(TOOL_APPROVAL_ENABLED 关而 askStore 在场)⇒ 联动步
+        // optional 跳过(§12-F F31):没有活体窗要同步,持久终局已经落定。
+        const settled = deps.toolApproval?.notifyExternalDecision(outcome.row.askId, outcome.row.decision === "approve", hasUpdatedInput ? body.updatedInput : undefined).settled ?? 0;
+        // `updatedInputForwarded` 只在**真结算**时发 `true`,其余一律**省略**(从不发 false,照 finishRespond
+        // 先例,§12-F)。它是「本副本活体状态」的函数,故幂等回放不承诺字节等同(§12-A)。
+        const forwarded = outcome.row.decision === "approve" && hasUpdatedInput && settled > 0;
+        sendJson(res, 200, {
+            askId: outcome.row.askId,
+            taskId: outcome.row.taskId,
+            decision: outcome.row.decision,
+            decidedAtMs: outcome.row.decidedAtMs,
+            actor,
+            ...(forwarded ? { updatedInputForwarded: true } : {}),
+        });
+        return;
+    }
     miss.fell = true;
 }
 //# sourceMappingURL=runs.js.map