@sema-agent/server 1.323.0 → 2.0.1

package/dist/http/routes/approvals-assistant.js

@@ -4,9 +4,13 @@ import { redactedPreview } from "../../trace/redact.js";
 import { sleep } from "../sse-log.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, isOperator, explicitOperator } from "../principal-gate.js";
+// design/80 seam #2 (assistant-scheduler): graceful preempt (durable yield) + resource_limit resume of one task.
 export const ASSISTANT_PREEMPT_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/preempt$/;
 export const ASSISTANT_RESUME_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/resume$/;
 export const ASSISTANT_PLAN_REVIEW_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/plan_review$/;
+/** Structural check for an operator-supplied QuestionAnswer (durable ask resume, TC-5.4). Strict on the
+ *  load-bearing shape — `answers[]` non-empty, each `{header: string, selected: string[], note?: string}` —
+ *  so a typo'd payload fails the request instead of resuming the task with an answer the tool can't use. */
 export function isQuestionAnswer(v) {
     if (!v || typeof v !== "object" || Array.isArray(v))
         return false;
@@ -29,15 +33,28 @@ export async function handleApprovalsAssistant(req, res, url, ctx) {
     await handleApprovalsAssistantBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { preemptableRuns } = ctx.registry;
     const { readJson, rateLimited, quotaExceeded } = ctx.helpers;
     const { resumeCheckpoint, resumePreempted, resumePlanReview } = ctx.legs;
+    // Durable F4 (design/45): the approval queue over the CHECKPOINT store. Operators list pending (non-secret)
+    // and decide by the session handle → the service maps session→token INTERNALLY and resumes (token never in
+    // a URL/body/log). Takes precedence over the poll gate when a checkpointStore is wired.
     if (deps.checkpointStore && (url.startsWith("/v1/approvals") || url.startsWith("/v1/assistant"))) {
         const cs = deps.checkpointStore;
-        const principal = gatedPrincipal(req, deps.config);
+        // 🔴 D-G §6: a direct-mode worker NEVER trusts x-agent-principal — NOT EVEN for the READ paths (else a forged
+        // operator header leaks every tenant's pending tool-call args via GET/stream, adversarial HIGH). For reads there
+        // is no per-decision checkpointToken, so identity comes from a verified principal JWT WITHOUT a cnf.bnd; an
+        // absent/invalid token ⇒ undefined principal ⇒ scope "__none__" + operator=false (fail-closed). The POST /decide
+        // path below re-verifies the SAME token WITH cnf.bnd (channel-bound to the action).
+        const principal = gatedPrincipal(req, deps.config); // direct-door safe — identity-only proof; single source of truth (see gatedPrincipal)
         const operator = isOperator(principal, deps.config.operatorPrincipals);
+        // design/80 (native push): SSE stream of pending-approval deltas so the portal SUBSCRIBES ONCE instead of
+        // polling GET /v1/approvals every ~10s. Same operator/owner scope as the list. Must precede the list/decide
+        // matches (the decide regex would otherwise treat "stream" as a sessionId on a POST — but this is GET-only).
         if (req.method === "GET" && url === "/v1/approvals/stream") {
             const scope = operator
                 ? (new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined)
@@ -47,11 +64,15 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
         }
         if (req.method === "GET" && url === "/v1/approvals") {
             const scope = operator
-                ? (new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined)
-                : (principal ?? "__none__");
+                ? (new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined) // operator: all (or ?owner)
+                : (principal ?? "__none__"); // non-operator: only its own scope (never others' pending)
             sendJson(res, 200, { pending: await cs.listPending(scope) });
             return;
         }
+        // exemptions surface — the UI's "本会话不再询问" state (list) + revoke. Same authz shape as
+        // /decide: an explicit operator may inspect any session; otherwise the caller must OWN the session's scope
+        // (peekPendingScope only knows PENDING sessions, so ownership here reads the session store's owner — the
+        // durable authority). Non-owner ⇒ 404 (no existence oracle, decide-route parity).
         {
             const em = /^\/v1\/approvals\/([^/]+)\/exemptions(?:\/([^/]+))?$/.exec(url);
             if (em && (req.method === "GET" || req.method === "DELETE")) {
@@ -72,6 +93,12 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 const operators = deps.config.operatorPrincipals;
                 const isExplicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
                 if (!isExplicitOperator) {
+                    // 🔴 fail-CLOSED owner gate (both reviewers, 2026-07-13): mirror the sibling owner-gated routes
+                    // (session policy/delete) — ownerOf REQUIRED (absent ⇒ 501, never open), a store error PROPAGATES
+                    // (500, never open; the old `.catch(() => undefined)` flipped a DB blip into authorization), and an
+                    // UNKNOWN session (owner === undefined) 404s with no existence oracle. owner === null (ownerless
+                    // anonymous/dev session) stays open — decide-route parity. No uuid shape-gate: this population is
+                    // the checkpoint sessionId space (decide-route parity), not the sessions-API surface.
                     const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
                     if (!ownerOf) {
                         sendError(res, 501, "capability.session_store_required", "approval exemptions require a session-store backend");
@@ -85,7 +112,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 }
                 if (req.method === "GET") {
                     if (exToolName !== undefined) {
-                        sendError(res, 404, "request.route_unsupported", "not found");
+                        sendError(res, 404, "request.route_unsupported", "not found"); // GET is list-only (no per-tool read)
                         return;
                     }
                     sendJson(res, 200, { exemptions: await deps.approvalExemptionStore.list(exSessionId) });
@@ -100,30 +127,67 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
         }
+        // design/80 #2 (assistant-scheduler, design/75 §3): the SINGLE INBOX — one prioritized view of the HITL gates
+        // across ALL of a user's N concurrent durable tasks. = listPending(scope) (already severity-sorted with the
+        // riskDescriptor) ENRICHED with each task's objective so the user knows WHICH of their tasks each gate belongs
+        // to (the missing cross-task aggregation). Scheduling priority = the severity sort; preemption is
+        // a later policy layer. Same owner-scoping as listPending (a non-operator sees only its own tasks' gates).
         if (req.method === "GET" && url === "/v1/assistant/inbox") {
+            // SECURITY (review w16yqkkxv): the assistant inbox is a PER-USER view — ALWAYS scope to a CONCRETE owner,
+            // never a system-wide dump. A non-operator sees its own principal; an operator may inspect ONE owner via
+            // ?owner, else its own. (≠ /v1/approvals, the admin queue, which intentionally lists all.) This removes the
+            // scope=undefined / empty-?owner path that made listPending() return every tenant's pendings unbounded.
             const ownerParam = new URL(req.url ?? "", "http://x").searchParams.get("owner") || undefined;
             const scope = operator && ownerParam ? ownerParam : (principal ?? "__none__");
+            // 🔴 (BUG FIX) the inbox is the documented CheckpointSummary view (gateKind + severity SCALAR +
+            // spentMicroUsd + deadline), NOT the rich operator-queue PendingCheckpoint. It USED to spread listPending()'s
+            // raw rich rows — which carried `riskDescriptor.severity` (an object, not the scalar), the tool input + the
+            // decide binding, and NO gateKind — diverging from the contract + the tasks view (which already projects via
+            // summarizeCheckpoint). Switched to listByScope (the SAME summarizeCheckpoint projection tasks uses) so the
+            // inbox + tasks are consistent; the rich decide-binding lives on /v1/approvals (the operator queue), not here.
             const summaries = await cs.listByScope(scope);
             const inbox = (await Promise.all(summaries.map(async (s) => {
+                // `createdAt` + `toolInput` are now PROJECTED into CheckpointSummary by core's summarizeCheckpoint
+                // (core 1.116.0): listByScope returns them in
+                // ONE query, so the per-entry `cs.get(token)` N+1 is GONE. `objective` lives in the task body
+                // (checkpoint_ctx), not the summary, so it still needs getCtx (best-effort; missing ⇒ null).
                 const ctx = await cs.getCtx(s.sessionId).catch(() => null);
+                // 🔴 STRIP the resume `token` (the unexposed secret capability — resume is by sessionId, never the
+                // token) AND the RAW `toolInput` (core bounds but does NOT redact it — redaction is
+                // the consumer's job). Re-emit the REDACTED `input` instead.
                 const { token: _token, toolInput: _rawToolInput, ...safe } = s;
+                // `input` = a REDACTED preview of the projected (bounded, RAW) tool_input. Only `tool_approval` gates
+                // carry it (resource_limit / plan_review have none ⇒ toolInput undefined ⇒ input null). NOT the old
+                // bug (raw rich row + decide-binding); the decide-binding still lives only on /v1/approvals.
                 const input = s.toolInput != null ? redactedPreview(s.toolInput) : null;
                 return { ...safe, objective: ctx?.body?.objective ?? null, input };
-            }))).sort((a, b) => (b.severity ?? 0) - (a.severity ?? 0));
-            sendJson(res, 200, { inbox });
+            }))).sort((a, b) => (b.severity ?? 0) - (a.severity ?? 0)); // severity DESC (listByScope is created_at ASC; stable → oldest-first within a tier)
+            sendJson(res, 200, { inbox }); // CheckpointSummary (token-stripped) + objective, severity-prioritized — the assistant single inbox
             return;
         }
+        // design/80 #2 (assistant-scheduler): the N-TASKS overview = the cross-task SCHEDULING view. A user's active
+        // durable agent tasks, each joined (when suspended on a HITL gate) with the core scheduler seam
+        // listByScope(scope) → {gateKind, severity, spentMicroUsd, deadline} (core 1.105, ONE query, no N+1). The
+        // result is ordered for triage: blocked-on-a-gate first, then by risk severity DESC, then by budget spent
+        // DESC — i.e. the order a scheduler would advance/escalate them. Same owner-scoping. Needs the run-store.
         if (req.method === "GET" && url === "/v1/assistant/tasks") {
+            // SECURITY (review w16yqkkxv): per-user view — ALWAYS a CONCRETE owner (operator inspects ONE via ?owner,
+            // else its own; non-operator = its own). No scope=undefined → no unbounded cross-tenant listPending()/listRuns.
             const ownerParam = new URL(req.url ?? "", "http://x").searchParams.get("owner") || undefined;
             const scope = operator && ownerParam ? ownerParam : (principal ?? "__none__");
             if (!deps.runStore) {
                 sendJson(res, 200, { tasks: [] });
                 return;
             }
+            // Rich per-gate summary via the core seam (severity + budget) — ONE scoped query, bounded (LIMIT 500).
             const summaries = await cs.listByScope(scope);
             const byGate = new Map(summaries.map((s) => [s.sessionId, s]));
             const runs = await deps.runStore.listRuns({ owner: scope, limit: 100 });
             const tasks = runs
+                // 🔴 wlzq75oac HIGH: a plan_review / dry-run review park persists as status='needs_review' (NOT 'suspended'),
+                // so a running/suspended-only filter DROPPED exactly the HITL-gated tasks §3 promises to surface "needs-
+                // attention first" — the operator could never discover the very plan_review tasks §4c says to resolve.
+                // Same class as the inbox leak (handler vs contract drift). needs_review is a non-terminal park → include it.
                 .filter((r) => r.status === "running" || r.status === "suspended" || r.status === "needs_review")
                 .map((r) => {
                 const s = byGate.get(r.sessionId);
@@ -134,18 +198,32 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { tasks });
             return;
         }
+        // design/80 seam #2: POST /v1/assistant/tasks/:id/preempt — the scheduler's graceful "yield this task"
+        // (durable + resumable; the OPPOSITE of /v1/runs/:id/cancel's kill). Durable cross-replica preempt flag
+        // (the owning instance's heartbeat honors it) + a same-replica preempt-controller fast path. On a direct
+        // worker the caller is the crypto-VERIFIED JWT principal (above) — owner-scoped, no trusted-header bypass.
         const preemptMatch = req.method === "POST" ? ASSISTANT_PREEMPT_RE.exec(url) : null;
         if (preemptMatch) {
             if (rateLimited(req, res) || quotaExceeded(req, res))
-                return;
+                return; // 🔴 复审 C3:preempt is NON-billable
+            // (yields a task, runs no model — see the billable-route classifier) → NO lease gate, else an exhausted
+            // tenant could not stop its own spending.
             if (!deps.runStore) {
                 sendError(res, 501, "capability.run_store_required", "preemption requires the TiDB run store");
                 return;
             }
+            // requirePrincipal parity with the sibling mutating endpoints (runOwnerOk / cancel / runs): 401 before the
+            // lookup when configured (uses the crypto-verified `principal` — never the trusted header on a direct door).
             if (deps.config.requirePrincipal && principal === undefined) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
             }
+            // Precondition: a preempt only durably suspends when the worker opts tasks into resourceSuspend
+            // (RESOURCE_SUSPEND=true) AND has the durable-suspend substrate (a checkpoint store — resolveSpec wires
+            // resourceSuspend ONLY inside the durableEnabled block, so without a checkpoint store the preemptSignal is
+            // never armed) AND core deems the task eligible (remote env + durable tool-results). Reject honestly when the
+            // worker can't preempt at all (e.g. the local in-memory backend has no checkpoint store), rather than 202
+            // "preempting" a signal nothing honors.
             if (!deps.config.resourceSuspend || !deps.checkpointStore) {
                 sendError(res, 501, "feature.preemption_disabled", "preemption not enabled on this worker (needs RESOURCE_SUSPEND=true + a durable checkpoint store)");
                 return;
@@ -156,6 +234,10 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
             }
+            // Owner-gate: an EXPLICIT operator may preempt any tenant's task (preemption is a scheduler action); a
+            // normal caller only its own. 404 (not 403) for a non-owner — no existence oracle (parity with runOwnerOk
+            // + the cancel/decide precedent). NOT the bare isOperator (its empty-list "true-for-all" would let any
+            // caller preempt anyone — same trap the /decide owner-gate avoids).
             const operators = deps.config.operatorPrincipals;
             const explicitOperator = operators.length > 0 && principal !== undefined && operators.includes(principal);
             if (!explicitOperator && run.owner !== null && run.owner !== principal) {
@@ -163,18 +245,25 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             if (run.status === "running") {
+                // Honesty guard (review wtyc7ist3): if THIS replica owns the run (instance match) yet it is NOT in
+                // preemptableRuns, it is a verify/cascade leg — those durably suspend as a FAILED result, so they are
+                // deliberately never registered + never honored (runs.ts). Don't set a dead durable flag or claim
+                // "preempting"; report the honest no-op. (Owned-elsewhere → instanceId mismatch → fall through to the
+                // durable flag so the owning replica's heartbeat honors it iff that leg is eligible — best-effort.)
                 const ownedHere = run.instanceId != null && run.instanceId === deps.instanceId;
                 if (ownedHere && !preemptableRuns.has(taskId)) {
                     sendJson(res, 202, { taskId, status: run.status, note: "task is not preempt-eligible (verify/cascade leg) — preempt is a no-op" });
                     return;
                 }
-                const flagged = await deps.runStore.requestPreempt(taskId, run.owner);
+                // Durable flag FIRST (only flips a still-running row), abort after — if the run suspended/terminal'd in
+                // the getRun→here window the flag affects 0 rows, so re-read and answer by the ACTUAL state.
+                const flagged = await deps.runStore.requestPreempt(taskId, run.owner); // owner guard: single-DB defense-in-depth (owner-gate already enforced above)
                 if (!flagged) {
                     const now = await deps.runStore.getRun(taskId);
                     sendJson(res, 202, { taskId, status: now?.status ?? "failed", note: "task no longer running — preempt is a no-op" });
                     return;
                 }
-                preemptableRuns.get(taskId)?.abort();
+                preemptableRuns.get(taskId)?.abort(); // fast path: preempt landed on the running instance → suspend now
                 sendJson(res, 202, { taskId, status: "preempting", note: "graceful durable yield — the task suspends at the next clean turn boundary if preempt-eligible; resume via POST /v1/assistant/tasks/:id/resume" });
             }
             else if (run.status === "suspended") {
@@ -185,10 +274,13 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             }
             return;
         }
+        // design/80 seam #2: POST /v1/assistant/tasks/:id/resume — resume a task durably SUSPENDED on a
+        // resource_limit gate (a scheduler preempt OR a budget/turns/walltime slice, design/74). NOT an approval
+        // gate (resumePreempted's gate-kind guard 409s a policy_ask — that goes through POST /v1/approvals/:id/decide).
         const resumeMatch = req.method === "POST" ? ASSISTANT_RESUME_RE.exec(url) : null;
         if (resumeMatch) {
             if (rateLimited(req, res) || quotaExceeded(req, res))
-                return;
+                return; // 🔴 复审 C2:lease admitted INSIDE driveResumeIntoRunLog on the CHECKPOINT-OWNER principal (the billed tenant), not the request principal — a cross-tenant operator resume must charge the owner's lease, not the operator's. resume hits TiDB + runs the model
             if (!deps.runStore) {
                 sendError(res, 501, "capability.run_store_required", "resume requires the TiDB run store");
                 return;
@@ -196,7 +288,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             if (deps.config.requirePrincipal && principal === undefined) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
-            }
+            } // parity with sibling mutating endpoints
             const taskId = resumeMatch[1];
             const run = await deps.runStore.getRun(taskId);
             if (!run) {
@@ -209,14 +301,23 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
             }
-            const out = await resumePreempted(run.sessionId, req);
+            const out = await resumePreempted(run.sessionId, req); // gate-kind guard + drive into the run log (shared)
             sendJson(res, out.status, out.body);
             return;
         }
+        // design/80 D-B: POST /v1/assistant/tasks/:id/plan_review — resolve a PRE-ACTION `plan_review` gate, 3-state
+        // (approve | edit | reject). A SIBLING of preempt/resume (a scheduler-resolvable gate with NO bound tool
+        // action — the human reviews the PLAN, not a tool call), NOT the /decide wire (a tool-approval allow/deny +
+        // action binding) and NOT the needs_review wire (never reuse it). `edit` carries the
+        // operator's REVISED plan (core threads `editedPlan` into the resumed run). 🔴 D-G ruling:
+        // a plan_review binds NO action, so on a direct-door worker the self-asserted x-agent-principal is NEVER
+        // trusted — it carries the PRINCIPAL-ONLY proof (verifyDirectDoorProof actionBinding:false = JWT identity +
+        // cnf.bnd + HMAC over {sessionId,decision}, no boundInputHash), then the SAME operator-or-owner gate on the
+        // CRYPTO-VERIFIED principal. On a BFF worker the trusted-header principal owner-gate applies (parity with resume).
         const planReviewMatch = req.method === "POST" ? ASSISTANT_PLAN_REVIEW_RE.exec(url) : null;
         if (planReviewMatch) {
             if (rateLimited(req, res) || quotaExceeded(req, res))
-                return;
+                return; // 🔴 复审 C2:lease admitted in driveResumeIntoRunLog (owner principal). resume hits TiDB + runs the model (approve/edit)
             if (!deps.runStore) {
                 sendError(res, 501, "capability.run_store_required", "plan_review requires the TiDB run store");
                 return;
@@ -224,8 +325,13 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             if (deps.config.requirePrincipal && principal === undefined) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
-            }
+            } // parity with sibling mutating endpoints
             const taskId = planReviewMatch[1];
+            // 3-state decision; `edit` MUST carry the revised plan, `approve`/`reject` must NOT (a stray editedPlan
+            // signals a wrong-gate call — reject, don't drop it). Parsed + validated BEFORE the task is resolved so
+            // every bad-body 400 is existence-INDEPENDENT (depends only on the body). 🔴 wq64gmm5e LOW: getRun's 404
+            // used to fire BEFORE the body/proof — a task-existence oracle (404-vs-401) on a direct-door worker,
+            // divergent from /decide. Now the existence branch comes AFTER and is status-uniform with a bad proof.
             const body = (await readJson(req));
             const decision = body?.decision === "approve" ? "approve" : body?.decision === "edit" ? "edit" : body?.decision === "reject" ? "reject" : undefined;
             if (!decision) {
@@ -244,12 +350,16 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 400, "request.field_invalid", "reason must be a string");
                 return;
             }
+            // 与 /decide 腿同一上限:reason 入签之后,超长只能**拒**(截断产出的字节签名器复现不了 ⇒ 恒 401)。
             if (typeof body.reason === "string" && body.reason.length > MAX_APPROVAL_REASON_CHARS) {
                 sendError(res, 413, "reason_too_large", `reason too large (max ${MAX_APPROVAL_REASON_CHARS} chars)`);
                 return;
             }
             const run = await deps.runStore.getRun(taskId);
             if (!run) {
+                // No such task. On a DIRECT-DOOR worker return the SAME 401 a bad proof gets (parity with /decide): a
+                // missing task is indistinguishable from a bad proof — the caller cannot mint a valid proof for an
+                // unknown sessionId anyway — so existence never leaks. On a BFF worker the trusted-header owner posture 404s.
                 if (deps.config.directDoorActive) {
                     sendError(res, 401, "principal_unverified", "principal proof required");
                     return;
@@ -257,10 +367,15 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
             }
+            // ── D-G principal-only proof (non-action gate): on a direct-door worker derive the CRYPTO-VERIFIED principal
+            // from the signed proof, never the self-asserted header. The envelope binds {sessionId, decision} so a forged
+            // or replayed plan decision is rejected; no boundInputHash (there is no tool action). fail-closed.
             let deciderPrincipal = principal;
             if (deps.config.directDoorActive) {
                 const hdr = (n) => { const h = req.headers[n]; return Array.isArray(h) ? h[0] : h; };
-                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, { sessionId: run.sessionId, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config, { actionBinding: false });
+                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, 
+                // reason 入签:同一条规则也适用于身份绑定腿(两个绑定位为 null,第五位照常参与)。
+                { sessionId: run.sessionId, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config, { actionBinding: false });
                 if (!proof.ok) {
                     sendError(res, proof.status, proof.errorCode, proof.error);
                     return;
@@ -272,7 +387,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             if (!explicitOperator && run.owner !== null && run.owner !== deciderPrincipal) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
-            }
+            } // no existence oracle (verified principal on a direct worker)
             const out = await resumePlanReview(run.sessionId, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, req);
             sendJson(res, out.status, out.body);
             return;
@@ -280,10 +395,12 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
         const m = /^\/v1\/approvals\/([^/]+?)(?:\/decide)?$/.exec(url);
         if (m && req.method === "POST") {
             if (rateLimited(req, res) || quotaExceeded(req, res))
-                return;
+                return; // 🔴 复审 C2:lease admitted in driveResumeIntoRunLog (owner principal). resume hits TiDB — rate-limit (council)
+            // NOTE: the operator gate is checked AFTER the body parse below — D-G's direct door needs the parsed
+            // envelope (checkpointToken + decision) to verify the HMAC before it can derive the deciding principal.
             let sessionId;
             try {
-                sessionId = decodeURIComponent(m[1]);
+                sessionId = decodeURIComponent(m[1]); // a malformed %-sequence is a client error (400), not a 500
             }
             catch {
                 sendError(res, 400, "request.path_malformed", "malformed approval id (invalid percent-encoding)");
@@ -295,6 +412,11 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 400, "request.body_shape", "body must be { decision: 'approve' | 'deny', reason?, answer?, checkpointToken?, boundCallId?, boundInputHash?, updatedInput?, remember? }");
                 return;
             }
+            // `reason` 现在**在签名载荷里**(三方裁 (a),见 security.ts `approvalHmacMessage` 顶注)⇒ 它的形必须先钉死:
+            //  · 非字符串会让规范化编码产出一个签名器不可能复现的消息(对象会被内联进 JSON)—— 此前这条腿
+            //    根本没校验 reason 的类型(plan_review 腿有),入签之后这就成了硬前置。
+            //  · 超长**拒而不截**:服务端截过的字节与签名方签的字节必然不同 ⇒ MAC 恒不匹配,截断只会把一个
+            //    可诊断的 413 变成费解的 401(与 steer 入参上限同一判据:诚实拒绝优于自作主张改写)。
             if (body.reason !== undefined && typeof body.reason !== "string") {
                 sendError(res, 400, "request.field_invalid", "reason must be a string");
                 return;
@@ -303,6 +425,11 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 413, "reason_too_large", `reason too large (max ${MAX_APPROVAL_REASON_CHARS} chars)`);
                 return;
             }
+            // `remember:"session"` — record a per-session per-toolName approval exemption alongside an
+            // approve ("本会话不再询问"). Closed enum (extensible later, e.g. "principal"); deny+remember = 400 (a
+            // "remembered deny" is a different semantic — not smuggled in here); direct-door v1 = 400 (remember is
+            // NOT in the HMAC envelope's signed payload — accepting it unsigned would be a tamper hole; extending
+            // the MAC payload is a v2 with the BFF, see docs/design/APPROVAL-SESSION-EXEMPTION.md).
             let remember = false;
             if (body.remember !== undefined) {
                 if (body.remember !== "session") {
@@ -321,12 +448,20 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                     sendError(res, 501, "capability.store_required", "approval exemptions need a store backend (DB_BACKEND / LOCAL lane)");
                     return;
                 }
+                // 🔴 remember REQUIRES the D-1 decision-binding echo (workflow audit 2026-07-13, my override of the
+                // verify-reject): an unbound decide can consume a gate that was SWAPPED after the operator's GET (see
+                // gate A, approve lands on gate B) — tolerable as a one-shot legacy quirk, NOT as the mint of a
+                // SESSION-PERSISTENT auto-approval for a tool the operator never saw. remember is a NEW contract, so
+                // it can demand the strict calling shape (the BFF already receives boundCallId/checkpointToken on the
+                // pending row). Plain decide without remember keeps the legacy unbound fallback untouched.
                 if (!body.checkpointToken && !body.boundCallId) {
                     sendError(res, 400, "remember_requires_binding", "remember requires the decision binding (echo checkpointToken and/or boundCallId from the pending approval)");
                     return;
                 }
                 remember = true;
             }
+            // Durable ask (TC-5.4): the operator's out-of-band QuestionAnswer rides the approve. Trusted
+            // control-plane input (the model never produces it); malformed = client error, absent = unchanged.
             let answer;
             if (body.answer !== undefined) {
                 if (!isQuestionAnswer(body.answer)) {
@@ -335,12 +470,27 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 }
                 answer = body.answer;
             }
+            // D-1 (design/80) decision-action binding: the operator echoes back the checkpointToken + boundCallId +
+            // boundInputHash they SAW in GET /v1/approvals. The service binds the resume to that exact action (core
+            // verifies opaque equality, fail-closed PRE-CAS) and rejects a stale view distinctly (approval_stale).
+            // All OPTIONAL — a legacy BFF caller that omits them falls back to the current-pending values (deprecated).
             for (const f of ["checkpointToken", "boundCallId", "boundInputHash"]) {
                 if (body[f] !== undefined && typeof body[f] !== "string") {
                     sendError(res, 400, "request.field_invalid", `${f} must be a string (the value surfaced on the pending approval record)`);
                     return;
                 }
             }
+            // 🔴 直连门上拒 `updatedInput`(2026-07-26 修),判据与上面拒 `remember` **逐字同一条**:
+            // 「不在决策证明的签名载荷里」。此前只 `remember` 有这条门,而 `updatedInput` 改写的是
+            // **将被执行的工具实参**(core `runtask.js` 在哈希比对**之后**用 `outcome.updatedInput ?? pendingAction.args`)
+            // ⇒ 同一份 JWT+MAC 对「原 body」与「加了 updatedInput 的 body」**都放行**,而 `boundInputHash` 仍是
+            // 原动作的哈希。直连门的威胁模型就是「线上字节不可信」(否则不需要 HMAC),能改字节的一方
+            // (反代 / 被劫持的客户端)可在操作员批准 `ls` 的同一次决定里换掉实参。
+            // ⚠️ 已亲验的缓解:core 会把改写后的实参**重新过一遍 base tool policy**,所以越权面被限制在策略仍允许的
+            // 范围内、不是任意命令 —— 但那是"减轻",不是"这个字段被签名覆盖了"。
+            // 修法刻意**不是**把它塞进 HMAC 载荷(那要求所有直连门客户端改签名 = 跨仓 wire 变更),而是把**既有的、
+            // 代码自己写下的**判据施加到它漏掉的那个字段上:fail-closed、server 单方面可做、与 `remember` 对称。
+            // BFF/gated 门(头已由上游验过)**不受影响** —— 这条只在 `directDoorActive` 生效。
             if (deps.config.directDoorActive && body.updatedInput !== undefined) {
                 sendError(res, 400, "updated_input_not_in_proof", "updatedInput is not supported on a direct-door worker (not covered by the decision proof)");
                 return;
@@ -351,38 +501,69 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 boundInputHash: body.boundInputHash,
                 updatedInput: body.updatedInput,
             };
+            // ── design/80 D-G: the authorization gate. On a DIRECT-MODE worker the trusted-header path is DISABLED —
+            // every /decide MUST carry the crypto proof (signed principal JWT + cnf.bnd + HMAC envelope), and the
+            // self-asserted x-agent-principal is NEVER consulted. On a normal (BFF) worker, the existing trusted-header
+            // operator gate is byte-identical. Fail-closed: a direct-door failure rejects, never falls back to the header.
             let deciderPrincipal = principal;
             if (deps.config.directDoorActive) {
                 const hdr = (n) => {
                     const h = req.headers[n];
                     return Array.isArray(h) ? h[0] : h;
                 };
-                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, { sessionId, boundCallId: binding.boundCallId, boundInputHash: binding.boundInputHash, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config);
+                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, 
+                // reason 入签(三方裁 (a) + clay 干净切):落账理由属于决定内容,与 decision 同受完整性保护。
+                { sessionId, boundCallId: binding.boundCallId, boundInputHash: binding.boundInputHash, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config);
                 if (!proof.ok) {
                     sendError(res, proof.status, proof.errorCode, proof.error);
                     return;
                 }
-                deciderPrincipal = proof.principal;
+                deciderPrincipal = proof.principal; // the CRYPTO-VERIFIED principal replaces the self-asserted header
             }
+            // Authorization (council finding): an EXPLICIT operator may decide ANY approval; otherwise the
+            // caller must OWN the checkpoint's scope. 🔴 NOT the bare isOperator — its empty-OPERATOR_PRINCIPALS
+            // "true-for-all" would let ANY authenticated caller decide ANOTHER user's checkpoint via a leaked, NON-
+            // credential sessionId+boundInputHash (from a log/screenshot/ticket). A non-owner-non-operator gets 404
+            // (no existence oracle — parity with runOwnerOk + the cancel P0 precedent), never 403.
             const operators = deps.config.operatorPrincipals;
             const explicitOperator = operators.length > 0 && deciderPrincipal !== undefined && operators.includes(deciderPrincipal);
             if (!explicitOperator) {
                 const cpScope = await cs.peekPendingScope(sessionId);
-                const ownsIt = cpScope == null || cpScope === "_" || cpScope === deciderPrincipal;
+                // "_" = the anonymous-submit scope SENTINEL (main.ts writes auth?.principal ?? "_" at suspend) — treat it
+                // like null (open), as the sibling sites already do (the 5040/5599/5653 normalizations). Without this an
+                // anonymous single-user durable worker DEADLOCKS its own approvals (decide → 404 forever; workflow audit
+                // 2026-07-13, confirmed by both verify lenses).
+                const ownsIt = cpScope == null || cpScope === "_" || cpScope === deciderPrincipal; // null/"_" = anonymous/dev (open)
                 if (!ownsIt) {
                     sendError(res, 404, "not_found.approval", "approval not found");
                     return;
                 }
             }
+            // remember: capture the pending gate's toolName BEFORE the resume consumes the row. AskUserQuestion
+            // gates are excluded (the durable-question policy owns them — an exemption row would be dead weight the
+            // ask-gate probe explicitly skips). null toolName (legacy row) ⇒ nothing to remember.
             let rememberToolName = null;
             if (remember) {
+                // [1.202 live 复验抓获] 旧姿势 `listPending(deciderPrincipal ?? "__none__")` 在匿名单用户 lane
+                // (decider 无 principal、checkpoint scope="_" 哨兵)永远滤空 ⇒ remember 结构性失灵(rememberApplied
+                // 恒 false,豁免从不落店)。授权已由上方 owner gate 把过(cpScope null/"_"/相符,同 5040/5599/5653
+                // 的 "_" 归一先例)——这里直接读该 session 的 pending 行拿 toolName,不再按 decider 二次过滤。
                 const tok = await cs.findPendingTokenBySession(sessionId);
                 const cp0 = tok ? await cs.get(tok) : null;
                 const pa0 = cp0?.pendingAction;
                 const tn = pa0 && pa0.kind === "tool_approval" ? pa0.toolName : null;
                 rememberToolName = tn && tn !== "AskUserQuestion" ? tn : null;
             }
+            // grant timing(codex M2,1.294 isExempt 同腿生效):grant 挪进 onResumeCommitted——markResuming CAS
+            // 赢了(decide 已被接受、并发 sibling 已输)之后、模型腿驱动**之前**落店,所以 resumed leg 自己的下一个
+            // ask 就能命中豁免(gate isExempt + ask 政策层探针都实时读店);旧姿势 await 整条 resume 腿(可跑数分钟)
+            // 之后才 grant,同腿第二次同工具 ask 必再 park 一轮。输掉 CAS(409)/stale(404)⇒ 钩不触发,绝不留
+            // 豁免;CAS 赢后模型腿再失败 ⇒ 豁免保留(operator 的 approve+remember 意图在 accept 时已成立,与
+            // 「grant 失败不回滚 approve」同向)。grant 失败只 warn 不阻断 resume,响应带 rememberApplied 如实。
             let rememberApplied = false;
+            // overrideSessionId([1591] 候裁② server 修):parked 赎回腿把 grant 锚改到行的 root/host 会话
+            // (部署侧豁免探针闭包统一捕获 host 会话键——落子代会话则键永不相交,rememberApplied 会是假话)。
+            // legacy 任务腿不传 override,行为逐字不变。
             const grantOnCommit = remember && deps.approvalExemptionStore && rememberToolName
                 ? async (overrideSessionId) => {
                     const grantSessionId = overrideSessionId ?? sessionId;
@@ -408,8 +589,13 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
         sendError(res, 404, "not_found.route", "not found");
         return;
     }
+    // Human-in-the-loop approval gate (F4). Operators list/decide; the running task polls the row.
     if (deps.approvalStore && url.startsWith("/v1/approvals")) {
         const store = deps.approvalStore;
+        // 🔴 D-G belt (defense-in-depth): this LEGACY block authorizes /approvals via the trusted x-agent-principal
+        // header (no crypto). On a direct-door worker that path must NEVER be live — the boot invariant already forces
+        // DURABLE_APPROVAL (so checkpointStore owns /approvals above and we never reach here), but if a direct-door
+        // worker ever fell through to here, fail closed rather than expose the header-trusting path.
         if (deps.config.directApprovalDoor) {
             sendError(res, 503, "approval_door_unconfigured", "approvals are served by the direct door on this worker");
             return;
@@ -417,10 +603,14 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
         if (req.method === "GET" && url === "/v1/approvals") {
             const principal = principalFrom(req, deps.config);
             if (isOperator(principal, deps.config.operatorPrincipals)) {
+                // operator: may filter by any ?owner (or list all). scope is owner-sourced, so the operator's ?owner
+                // filter IS the scope filter; an unfiltered operator list is cross-tenant BY DESIGN (operator queue).
                 const owner = new URL(req.url ?? "", "http://x").searchParams.get("owner") ?? undefined;
                 sendJson(res, 200, { pending: owner ? await store.listPending(owner, owner) : await store.listPendingAll() });
             }
             else {
+                // non-operator: only ITS OWN pending (ignore any ?owner spoof) — never others' tool-call args. scope =
+                // the caller's principal (owner-sourced), so the single-DB read guard isolates it at the SQL layer too.
                 sendJson(res, 200, { pending: principal ? await store.listPending(principal, principal) : [] });
             }
             return;
@@ -429,12 +619,19 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
         if (m) {
             const id = m[1];
             if (req.method === "GET") {
+                // The row carries the full tool-call args (commands/paths/contents of a high-risk op). The list
+                // endpoint deliberately scopes non-operators to their OWN pending ("never others' tool-call args");
+                // a by-id GET must enforce the same boundary, else any token-holder who learns an id reads another
+                // tenant's args. Operators see all; everyone else only their own. 404 (not 403) to non-owners so
+                // existence isn't revealed — symmetric with runOwnerOk.
                 const principal = principalFrom(req, deps.config);
                 if (deps.config.requirePrincipal && !principal) {
                     sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                     return;
                 }
                 const operator = isOperator(principal, deps.config.operatorPrincipals);
+                // Operators read across tenants (scope-agnostic getById); a non-operator reads ONLY its own scope so the
+                // single-DB read guard fires at the SQL layer (no cross-tenant args even if it learns an id).
                 const row = operator ? await store.getById(id) : principal != null ? await store.get(id, principal) : undefined;
                 if (!row || (!operator && row.owner !== null && row.owner !== principal)) {
                     sendError(res, 404, "not_found.approval", "approval not found");
@@ -444,6 +641,12 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             if (req.method === "POST") {
+                // Deciding (approve/deny) is OPERATOR-ONLY — a requester approving its own high-risk op would
+                // defeat the F4 gate. (Legacy/unset OPERATOR_PRINCIPALS → the service token is the boundary — but
+                // ONLY on a single-tenant deployment: under REQUIRE_PRINCIPAL the empty-list true-for-all would let
+                // ANY tenant decide ANOTHER tenant's approval [the durable /decide got
+                // this hardening earlier and this legacy leg never did] — multi-tenant demands an EXPLICIT
+                // operator list, same posture as the durable twin.)
                 const principal = principalFrom(req, deps.config);
                 const operatorOk = deps.config.requirePrincipal
                     ? explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals)
@@ -458,6 +661,9 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.body_shape", "body must be { decision: 'approve' | 'deny', reason? }");
                     return;
                 }
+                // The operator decides ACROSS tenants by design (the F4 operator queue), so we bind the decide CAS to the
+                // row's OWN scope (read scope-agnostically first) rather than the operator's principal — the scope<=>?
+                // clause then becomes an exact, consistent guard instead of a cross-tenant bypass. Unknown id ⇒ 409.
                 const target = await store.getById(id);
                 if (!target) {
                     sendError(res, 409, "conflict.approval_settled", "approval already decided or not found");
@@ -476,10 +682,32 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
+/** Server-side poll cadence for the native-push approvals stream. The CLIENT subscribes ONCE and never polls;
+ *  the server diffs at this cadence (TiDB has no LISTEN/NOTIFY) and pushes deltas. 3s < the ~10s client poll it
+ *  replaces, so the operator sees a new suspend faster AND the portal loses its polling loop. (Each SSE
+ *  connection runs its OWN poll loop — fine for a handful of operators; a shared fan-out poll is a future
+ *  optimization if the operator count grows.) */
 const APPROVALS_STREAM_POLL_MS = 3000;
+/**
+ * GET /v1/approvals/stream (design/80 native push): SSE — pushes pending-approval deltas so the portal
+ * SUBSCRIBES ONCE instead of polling GET /v1/approvals every ~10s (better UX: near-real-time + no client poll
+ * loop). Polls listPending(scope) and diffs against the prior snapshot: `pending` for a new suspend, `resolved`
+ * for a decided/expired/gone one. Cross-replica BY CONSTRUCTION — the poll reads the SHARED checkpoint table,
+ * so a suspend on ANY replica is seen by an operator streaming on a DIFFERENT replica. A transient DB blip
+ * heartbeats + retries (never kills the stream); a 15-min cap + req-close end it (parity with streamTaskTrace).
+ * Poll-granularity caveat: a pending that resolves AND re-suspends on the same (session,toolCallId) within one
+ * interval shows no delta — acceptable (the live snapshot is always eventually correct; no decision is missed).
+ */
 export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_STREAM_POLL_MS) {
+    // JSON-encode the (sessionId, toolCallId) pair so distinct pendings can NEVER collide into one Map key,
+    // regardless of what a caller-supplied sessionId contains (any single-char delimiter — space OR even NUL — is
+    // injectable by an adversarial id, masking/wrong-removing an approval card; adversarial finding). JSON escaping
+    // makes every distinct (sessionId, toolCallId) pair a distinct key.
     const keyOf = (p) => JSON.stringify([p.sessionId, p.toolCallId ?? null]);
     sseHeaders(res);
+    // Each data payload ALSO carries a `type` field mirroring the SSE event name — so a client can dispatch on
+    // `data.type` without relying on the SSE `event:` line (some proxies strip event names; `onmessage` ignores
+    // named events). The SSE event name stays for native EventSource addEventListener.
     res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", version: 1, mode: "approvals-delta", pollMs: APPROVALS_STREAM_POLL_MS })}\n\n`);
     let closed = false;
     req.on("close", () => { closed = true; });
@@ -494,6 +722,7 @@ export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_ST
             pending = await cs.listPending(scope);
         }
         catch {
+            // a transient TiDB blip must NOT kill the subscription — heartbeat + retry next tick (fail-soft)
             if (!res.writableEnded)
                 res.write(`event: heartbeat\ndata: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
             await sleep(pollMs);
@@ -501,6 +730,7 @@ export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_ST
         }
         const cur = new Map(pending.map((p) => [keyOf(p), p]));
         if (first) {
+            // initial snapshot so a freshly-subscribed portal renders the current queue immediately (no first-poll gap)
             for (const p of pending)
                 res.write(`event: pending\ndata: ${JSON.stringify({ type: "pending", ...p })}\n\n`);
             res.write(`event: synced\ndata: ${JSON.stringify({ type: "synced", count: pending.length })}\n\n`);
@@ -509,10 +739,10 @@ export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_ST
         else {
             for (const [k, p] of cur)
                 if (!prev.has(k))
-                    res.write(`event: pending\ndata: ${JSON.stringify({ type: "pending", ...p })}\n\n`);
+                    res.write(`event: pending\ndata: ${JSON.stringify({ type: "pending", ...p })}\n\n`); // a new suspend
             for (const [k, p] of prev)
                 if (!cur.has(k))
-                    res.write(`event: resolved\ndata: ${JSON.stringify({ type: "resolved", sessionId: p.sessionId, toolCallId: p.toolCallId })}\n\n`);
+                    res.write(`event: resolved\ndata: ${JSON.stringify({ type: "resolved", sessionId: p.sessionId, toolCallId: p.toolCallId })}\n\n`); // decided/expired/gone
         }
         prev = cur;
         if (Date.now() - start > MAX_MS) {