@sema-agent/server 1.322.0 → 2.0.0

package/dist/http/server.js

@@ -1,7 +1,7 @@
 import http from "node:http";
 import { once } from "node:events";
 import { createHash } from "node:crypto";
-import { uuidv7, isThinkingLevel, expandTiers, resumeWithVerification, CheckpointError, HAND_TOOL_EFFECTS, canonicalToolName, defaultTaskRegistry, validatePendingSteer, subscribeWorkflow } from "@sema-agent/core";
+import { uuidv7, isThinkingLevel, expandTiers, resumeWithVerification, CheckpointError, HAND_TOOL_EFFECTS, canonicalToolName, defaultTaskRegistry, validatePendingSteer, subscribeWorkflow } from "@sema-agent/core"; // canonicalToolName = core single-source (1.162; replaced the transitional service mirror)
 import { decideParkedAgent, findParkedAgentForCheckpoint } from "../parked-decide.js";
 import { matchCatalogModel } from "../model-select.js";
 import {} from "../sema-registry.js";
@@ -46,19 +46,30 @@ import { cascadeConfig } from "./run-meta.js";
 export { cascadeConfig };
 import { handleImages, createImagesLocal, coarseStatusForState, errorCodeForExit, BAKE_ID_RE, BAKE_EVENTS_RE, BAKE_CANCEL_RE, BAKE_CLAIM_RE, BAKE_INGEST_RE } from "./routes/images.js";
 export { coarseStatusForState, errorCodeForExit };
+// design/158 A9:装配器缝——发送器/身份门下沉到 http/ 叶子模块,routes/* 与 server.ts 共用同一实现
+// (routes/* 绝不可值 import server.ts:那条边会闭合运行时环,见 test/module-cycle-gate.test.ts)。
 import { sendJson, sendError, httpErrorCode, msg } from "./send.js";
 import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, isOperator, explicitOperator } from "./principal-gate.js";
 export { explicitOperatorOk, isOperator, explicitOperator };
+/** 分组入参 → 平铺视图(createHttpServer 的第一件事)。一组都没给 ⇒ 原样返回(存量调用零开销、零形变)。 */
 export function flattenServiceDeps(deps) {
     const { stores, coordinators, seams, observability, governance, deployment, knobs, ...flat } = deps;
     if (!(stores || coordinators || seams || observability || governance || deployment || knobs))
         return deps;
     return { ...stores, ...coordinators, ...seams, ...observability, ...governance, ...deployment, ...knobs, ...flat };
 }
+/** Personalization caps: server-pinned hard limits — a UI may be stricter, never looser. */
 export const MAX_USER_SKILLS = 10;
+/** = core `SKILL_CONTENT_MAX_CHARS`(1MB 加载门,core 1.293 起 invoke 全文零截断、超 1MB 整拒;常量在
+ *  dist/core/runner/synthetic-tools.js:84,未从 core 包根导出,故钉本地孪生+本出处注记)。修7 曾对齐旧
+ *  20k 截断门([845] 飞轮考据:20k 是压缩保留区口径,invoke 时刻用错),core 1.293 撤门后本门跟随回收
+ *  ([853]① 收口)——HTTP 面与引擎加载门同值,超限 400 fail-loud 而非引擎侧整拒后难诊断。 */
 export const MAX_SKILL_CONTENT_CHARS = 1_048_576;
 export const MAX_SYSTEM_PROMPT_CHARS = 16_384;
+/** Cap on a request's `outputSchema` (JSON-serialized) — an uncapped schema bloats the prompt + the per-turn
+ *  validation cost. 32KB comfortably holds a rich nested schema while bounding the abuse surface. */
 export const MAX_OUTPUT_SCHEMA_CHARS = 32_768;
+/** Validate `body.skills` (caps + shape). Returns an error string (→ 400) or null when acceptable. */
 export function validateUserSkills(skills) {
     if (skills === undefined)
         return null;
@@ -78,17 +89,46 @@ export function validateUserSkills(skills) {
     }
     return null;
 }
+/** Verification rounds requested by a caller, clamped to a safe [1,5] (default 2). */
 export function clampVerifyRounds(v) {
     const n = typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : 2;
     return Math.min(5, Math.max(1, n));
 }
 const MAX_BODY = 8 * 1024 * 1024;
+/** Caps on `body.images`: inline base64 `data` is otherwise passed RAW to the
+ *  spec (URL images are SSRF+size-gated by core, inline aren't). The whole JSON body is already ≤ MAX_BODY, but with NO
+ *  COUNT cap a request could carry thousands of tiny images (a decode/processing DoS), and there was no explicit
+ *  per-image error. The two-axis gate belongs in the server (shell carries content, server gates it). */
 const MAX_IMAGES_PER_REQUEST = 20;
-const MAX_IMAGE_BASE64_BYTES = 6 * 1024 * 1024;
+const MAX_IMAGE_BASE64_BYTES = 6 * 1024 * 1024; // a single inline image's base64 ≤ 6 MiB (< MAX_BODY, so REACHABLE — one image can't hog the whole 8 MiB budget); ~4.5 MiB decoded, generous for a screenshot/photo
+// Task Trace API (S1): GET /v1/tasks (list) | /v1/tasks/:id/turns | /v1/tasks/:id/stream. The `:id` group +
+// sub-route are both-or-neither, so a GET /v1/tasks/stream (no :id) does NOT match — the POST sync stream is unshadowed.
+// Hand (executionEnv) tool names core mounts at the runner when an executionEnvFactory is configured — the
+// authoritative set is core `HAND_TOOL_EFFECTS` (root-exported since 1.70). These are NEVER in spec.tools, so
+// the durable-resume satisfiability pre-check must union them when remote exec is on.
 const HAND_TOOL_NAMES = Object.keys(HAND_TOOL_EFFECTS);
+/** [1245] codex-3/4 — the REOPEN-class resume failures: core's runtask reopened the checkpoint (store.reopen,
+ *  dist-read) BEFORE returning this failed result, so the park is STILL PENDING and decidable. Everything
+ *  downstream must treat these as a re-park, never terminal: the durable event log writes `suspended` (not
+ *  `done`), the run row re-parks (keeps task_active), and /decide surfaces retriable:true. A reopen that
+ *  itself failed surfaces as `checkpoint.reopen_failed` — deliberately NOT matched here (terminal). */
 function isCheckpointReopenedFailure(r) {
     return r.status === "failed" && (r.errorCode === "resume.env_failed" || r.errorCode === "resume.tool_unavailable");
 }
+/** The TRUSTED end-user principal for an owner-gated / per-tenant request. On a direct-door worker the
+ *  trusted-header path is OFF (x-agent-principal is client-spoofable), so identity comes from the crypto-VERIFIED
+ *  principal JWT (`x-approval-principal-token`, principal-only proof — no cnf.bnd action binding); otherwise the
+ *  BFF-minted trusted header. undefined when absent/invalid (fail-closed → callers map to 401 / scope "__none__").
+ *  🔴 Use this for ANY endpoint that reads or gates PER-TENANT data — NOT `principalFrom` directly, which trusts
+ *  the spoofable header on a direct door (/v1/usage + the trace owner-gate
+ *  had drifted to a bare principalFrom, unlike the leader/images/approvals identity paths). One source of truth
+ *  so a future per-tenant endpoint can't re-introduce the bypass. The action-BOUND decide/answer paths keep their
+ *  own verifyDirectDoorProof (cnf.bnd) — this is the identity-only twin. */
+// F-fix: a thin delegate to the single source of the verified identity (security.ts `verifiedPrincipal`). Kept as a
+// named alias so the existing call sites read clearly; the JWT logic now lives in one place that createAuthorizer
+// shares, so spec.principal (governance + cost) and these observability/owner sites can never drift apart again.
+/** design/158 A9 装配表(顺序 = 拆分前 `handle()` 里各域出现的先后,逐行同序;真正的 `return` 在 handle 内,
+ *  这里只做**签名一致性**的编译期钉:任何域入口漂了形,是编译红,不是运行时静默 404)。 */
 const ROUTE_DOMAINS = [
     handleTraceUsage,
     handleWorkflows,
@@ -111,17 +151,73 @@ const ROUTE_DOMAINS = [
     handleNotifyWake,
 ];
 void ROUTE_DOMAINS;
+/**
+ * Managed-Agents-style HTTP/SSE service surface.
+ *   GET  /health
+ *   POST /v1/tasks            → run to completion, TaskResult JSON (synchronous)
+ *   POST /v1/tasks/stream     → SSE of TaskEvent, live tokens (synchronous, same instance)
+ *   POST /v1/runs             → async: 202 {taskId, sessionId, status}, runs in background (S1)
+ *   GET  /v1/runs/:id         → run status + result (poll)
+ *   GET  /v1/runs/:id/events  → SSE replay from Last-Event-ID, then tail to terminal (S2)
+ *   POST /v1/sessions/:id/wake→ 501 (resume is implicit: re-issue a task with the same sessionId)
+ */
 export function createHttpServer(rawDeps) {
+    // design/158 A8:分组装配 → 平铺视图。**分组是装配面的形,不是消费面的形**——下面 ~700 处 `deps.x`
+    // 消费点原样保留(平铺入参零形变、零开销:没给任何组时 flatten 原样返回同一个对象)。
     const deps = flattenServiceDeps(rawDeps);
+    // Idempotency-Key dedup for task submission (center review-routing blocker: exactly-once billing). One
+    // cache per server instance, shared by the sync /v1/tasks and async /v1/runs create paths.
     const idemCache = new IdempotencyCache();
+    // In-flight durable runs on THIS instance → their cancel controller. POST /v1/runs/:id/cancel landing here
+    // aborts immediately (fast path); a cancel landing on another replica uses the durable flag + heartbeat poll.
     const inflightRuns = new Map();
+    // [1.207 codex H2] taskIds whose abort came from the CANCEL VERB (fast path or flag poll) — the interactive
+    // legs consult this at settle time to label an abort-shaped failed result `errorCode:"cancelled"` (core's
+    // external-signal abort yields failed WITHOUT an errorCode; first-writer-wins would then pin the unlabeled
+    // form). A genuine completion that raced the abort is NOT relabeled (only status==="failed" gets the code).
+    // Entries are dropped in each leg's finally (same lifecycle as its inflightRuns registration).
     const cancelledViaVerb = new Set();
+    // design/80 seam #2 (preemption): in-flight PREEMPTIBLE runs on THIS instance → their preempt controller (the
+    // graceful-yield twin of inflightRuns' kill). POST /v1/assistant/tasks/:id/preempt landing here aborts it
+    // immediately (fast path → core durably suspends at the next clean turn boundary); a preempt landing on another
+    // replica uses the durable `preempt_requested` flag + heartbeat poll. Only plain-stream + resumed legs register.
     const preemptableRuns = new Map();
+    // design/47 + design/80 D-A (steering): in-flight STEERABLE runs on THIS instance → their live core TaskStream
+    // handle. POST /v1/runs/:id/steer landing here injects a mid-task message via the stream's `steer()` (applied at
+    // the next turn-boundary drain → 200). A run that is NOT here is either durably suspended (→ park the steer on its
+    // checkpoint via setPendingSteer → 202) or streaming on another replica (cross-replica live-steer is a fast-follow,
+    // single-replica today → 409). Only the plain-stream + resumed legs hold a live stream, so only they register
+    // (the verify/cascade legs return a result, not a stream — nothing to steer, parity with preemptableRuns).
     const steerableRuns = new Map();
+    // design/144 wake 半场:终态 steer 铸 park 的 per-session 串行链(复审 HIGH:tryPark→put 非原子,
+    // 并发双 steer 双铸两个 pending park)。单副本部署(本仓 steer 跨副本 seam 同款现实)进程锁即闭环;
+    // 跨副本残窗由 put 后赢家复核收敛兜底(见 (d) 分支),与 cross-replica live-steer 同列 fast-follow。
     const wakeParkMints = new Map();
+    // design/158 A9:两条「裸 number 登记簿」装盒——`let` 拆不出闭包,域模块要自增/自减必须共享同一个对象。
+    // 语义与计数时机逐字不变(uncountedBillableInflight = B-1: sync /v1/tasks + leader bg runs,无 map 身份,
+    // drain 靠它看见;admittedInflight = 修1 的 admission 期计数,见下方注释)。
     const counters = { uncountedBillableInflight: 0, admittedInflight: 0 };
+    // 修1(三路复审 B3 HIGH,迟登记窗):ADMISSION-time in-flight counter. Every non-probe request is counted
+    // SYNCHRONOUSLY in handle()'s first statements (before ANY await — auth/prepareSpec/lease/claim all happen
+    // later) and released once, on whichever of finish/close fires first. Closes the window where a request that
+    // just entered the handler was invisible to inflight() and a SIGHUP idle check (or SIGTERM drain read)
+    // misjudged the replica idle → hardShutdown mid-admission. Deliberately OVERLAPS the leg registries below
+    // (a registered leg counts twice) — every consumer only tests inflight()===0, so overcount is conservative,
+    // never a false-idle.
+    // drain: expose this replica's in-flight leg count as a LIVE getter on the shared drain state. Union of
+    // taskIds (a resumed leg registers in BOTH maps) — bg/resume durable legs (inflightRuns) + live streams
+    // (steerableRuns, sync leg included since 1.78). main.ts polls this after SIGTERM to know when drain is done.
+    // 对抗复查 B-1(CRITICAL):the SYNC /v1/tasks await and the leader background run register in NEITHER map —
+    // a SIGTERM during either read inflight=0 and hard-shut mid-model-work. Count them explicitly (a plain
+    // counter: they have no steer/resume identity to key a map on).
     if (deps.drainState)
         deps.drainState.inflight = () => new Set([...inflightRuns.keys(), ...steerableRuns.keys()]).size + counters.uncountedBillableInflight + counters.admittedInflight + (deps.leaderEndpoint?.inflight?.() ?? 0);
+    // B3 复审(codex HIGH):admission 计数之外再补一条粗粒度活性时钟:任何非探针请求(/health、/metrics*
+    // 除外——探针/抓取是常态噪音)都推进时间戳;SIGHUP 空闲窗要求「inflight 归零 + 活性静默」双满足才关停。
+    // 顺带把 idle-but-live 的 peer(还在 list/浏览的壳)也保住。
+    // ⚠️ 时基契约(三路复审修3):performance.now() 单调域,与 sighup-idle.ts 的 `now` seam 同域——挂钟
+    // (Date.now)跳变(NTP 回拨/夏令时)会把空闲窗判定拉爆。对外报告的 epoch 时间戳(请求日志/drainState.since)
+    // 不受影响,仍走 Date.now。
     let lastBillableActivityAt = performance.now();
     const noteActivity = (url) => {
         if (url === "/health" || url.startsWith("/metrics"))
@@ -130,13 +226,22 @@ export function createHttpServer(rawDeps) {
     };
     if (deps.drainState)
         deps.drainState.lastActivityAt = () => lastBillableActivityAt;
+    // asyncRewake wake 管道(hooks 阶段二挂账兑现):hook-runner 的 ctx.wake 经 main.ts 的 hookWakeBus holder
+    // 到这里——session → 本副本活流(steerableRuns 是 taskId 键,反查经 run 行;活流数=本副本并发数,量小;
+    // wake 是稀有事件[async hook exit 2],逐行 get 可接受)。找到即 steer(操作者 hook 的 stderr,trusted
+    // 与 explicitOperator 同源语义;下个 turn 边界注入)。无活流 → 挂起腿 park fallback(与 HTTP steer 的
+    // tryPark 同一原语:pending checkpoint 是权威,CAS on status='pending';落上=resume 时 core 注入)。
+    // park 也不上 → false(别副本 live/已结束——调用方记账)。
     if (deps.hookWakeBus) {
         deps.hookWakeBus.deliver = async (sessionId, text) => {
+            // hook stderr 不是操作者亲笔——是 hook 脚本运行时输出(可能回显下载物/工具输出),
+            // 【内容】不升 trusted(与 HTTP steer 的非-explicitOperator 姿势一致),且先过同一 validatePendingSteer
+            // 校验(break-out/控制字符即拒,不静默换流)。围栏 provenance 在 main.ts 闭包侧(注入前缀标明来源)。
             try {
                 validatePendingSteer({ text, trusted: false });
             }
             catch {
-                return false;
+                return false; // steering.invalid_content:内容不合法,不投递(调用方按 dropped 记账)
             }
             for (const [tid, stream] of steerableRuns) {
                 try {
@@ -147,9 +252,12 @@ export function createHttpServer(rawDeps) {
                     return true;
                 }
                 catch {
-                    continue;
+                    continue; // not_running race / 行读失败 → 试下一个;全空 → 挂起腿 park
                 }
             }
+            // 挂起腿:任务 durably suspended 时 async hook 才收场(如慢 lint 收尾)——
+            // wake park 到 session 的 pending checkpoint(镜像 POST /v1/runs/:id/steer 的 tryPark:scope/token
+            // 缺失或 CAS 失手=没有真挂起的 checkpoint → false)。resume 时 core 把它作为 pending steer 注入。
             try {
                 const cs = deps.checkpointStore;
                 if (!cs)
@@ -163,12 +271,14 @@ export function createHttpServer(rawDeps) {
                 return await cs.setPendingSteer(token, scope, { text, trusted: false });
             }
             catch {
-                return false;
+                return false; // park 面任何失败=诚实 false(调用方按 dropped 记账),绝不 throw 回 hook 收尾路径
             }
         };
     }
     const server = http.createServer((req, res) => {
         void handle(req, res).catch((err) => {
+            // A typed HttpError (e.g. a malformed JSON body → 400) carries its own status — a client mistake is a
+            // 4xx, not a 500. Everything else is a genuine internal error: log the cause, never echo it (info disclosure).
             if (err instanceof HttpError) {
                 if (!res.headersSent)
                     sendError(res, err.status, httpErrorCode(err.status, err.code), err.message, { ...(err.code ? { code: err.code } : {}), ...(err.extra ?? {}) });
@@ -183,22 +293,38 @@ export function createHttpServer(rawDeps) {
                 res.end();
         });
     });
+    // design/158 A9 装配缝:服务级 ctx 建**一次**(deps 平铺视图 / 跨域运行期登记簿 / 无状态助手 / 单域状态)。
+    // 每请求只再加一格 `req`(见 handle 内)。助手全是 `function` 声明,提升后此处引用安全。
     const routeCtxBase = {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters },
         helpers: { readJson, readRawBody, rateLimited, quotaExceeded, leaseDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
         local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal() },
+        // A9 尾批:提交/续跑「腿」只装引用(实现仍在本闭包里,逐字未动)——tasks/runs 共用 prepareSpec,
+        // approvals/assistant/notify-wake 共用 resume 家族;走这一格才不会造出 routes/* 互相值 import 的环。
         legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, resumePlanReview },
     };
     async function handle(req, res) {
         const startedAt = Date.now();
         const method = req.method ?? "GET";
         const url = (req.url ?? "/").split("?")[0];
-        noteActivity(url);
+        noteActivity(url); // B3: admission-time activity stamp (before any await — no gap for the idle watch to miss)
+        // 修1(三路复审 B3 HIGH):admission-time inflight registration — SYNCHRONOUS, before the first await, so a
+        // request still in its pre-registration phase (auth/prepareSpec/lease/claim) is already visible to
+        // drainState.inflight(). Released exactly once in `record` below (finish/close latch — the same lifecycle
+        // that covers aborted SSE streams). Probes (/health, /metrics*) and CORS preflight stay uncounted (constant
+        // sampling noise must not hold the SIGHUP idle window open).
         const admitted = method !== "OPTIONS" && url !== "/health" && !url.startsWith("/metrics");
         if (admitted)
             counters.admittedInflight++;
+        // Record on whichever of finish/close fires FIRST (a `logged` latch prevents double-count): a client that
+        // aborts (esp. an SSE stream) fires `close` WITHOUT `finish`, so a finish-only handler never counts it —
+        // exactly the abnormal traffic most worth observing. An abort mid-response is logged as 499 (client closed).
         let logged = false;
+        // [854]⑥ 纯观测:tasks/stream 断连(499)日志此前无 task 上下文,排查「谁的流断了」只能对时间戳。
+        // 流路由把 X-Task-Id(earlyDurableTid)stash 到这两个 handle 作用域变量;record 只在 499 行带上——
+        // 不动计费/inflight(admittedInflight 的 latch 语义原样)。detached 标记见 [854]①b(断连宽限 opt-in)。
+        // design/158 A9:每请求局部量收进 reqState(域模块经 ctx.req 读写同一个盒子),ctx = 服务级四格 + 本格。
         const reqState = { streamTaskId: undefined, streamDetached: false, source: null };
         const ctx = { deps: routeCtxBase.deps, registry: routeCtxBase.registry, helpers: routeCtxBase.helpers, local: routeCtxBase.local, legs: routeCtxBase.legs, req: reqState };
         const record = (viaClose) => {
@@ -206,7 +332,7 @@ export function createHttpServer(rawDeps) {
                 return;
             logged = true;
             if (admitted)
-                counters.admittedInflight--;
+                counters.admittedInflight--; // 修1: paired release (latched — one decrement per admitted request)
             const route = routeLabel(method, url);
             const seconds = (Date.now() - startedAt) / 1000;
             const aborted = viaClose && !res.writableEnded;
@@ -225,27 +351,54 @@ export function createHttpServer(rawDeps) {
             return;
         }
         if (req.method === "GET" && url === "/health") {
+            // Sema-registry restart signal: additive, present ONLY when a restart-to-apply slice changed
+            // since boot — so a normal worker's /health shape is unchanged. `restartRequired` is the boolean the
+            // orchestrator polls; `restart` carries which slices + the version + when it first became required.
             const restart = deps.restartState?.();
+            // TOC integration (#1 /health contract — INTEGRATION-DESIGN): identity fields so the shell's Lifecycle
+            // Manager can verify it connected to the RIGHT engine (instance + data dir + config fingerprint + pid/port), not
+            // a stale/wrong one. configHash = a STABLE fingerprint of the restart-relevant config shape (NO secrets — only
+            // model id / backends / data root / provider / port), so the shell detects a config drift without reading values.
             const configHash = createHash("sha256")
                 .update(JSON.stringify({ model: deps.config.model.id, sessionBackend: deps.config.sessionBackend, dbBackend: deps.config.dbBackend, dataRoot: deps.config.localDataRoot, configProvider: deps.config.configProvider, remoteExec: deps.config.remoteExec?.provider, port: deps.config.port }))
                 .digest("hex")
                 .slice(0, 16);
             sendJson(res, 200, {
                 status: "ok",
+                // build self-description — "did the restart actually pick up new code" judgement for the
+                // shell/orchestrator (same source as GET /v1/capabilities.version; absent only if capabilities wiring is).
                 ...(typeof deps.capabilities?.version === "string" ? { version: deps.capabilities.version } : {}),
+                // additive draining flag — k8s readiness / shell Lifecycle Manager摘流 signal. Absent when not draining.
                 ...(deps.drainState?.draining ? { draining: true, ...(deps.drainState.since ? { drainingSince: deps.drainState.since } : {}) } : {}),
+                // S5: additive degradation flag — present ONLY when the boot auto-probe fell back to in-memory, so a
+                // healthy worker's /health shape is unchanged. durable:false = "this replica is NOT persisting although
+                // a DB was configured" (the orchestrator's restart/alarm signal; an in-memory-by-choice worker omits it).
                 ...(deps.storeDegraded ? { durable: false, storeDegraded: true } : {}),
+                // boot ready 门(b):additive — absent = ready(正常形状不变);false = roster 未落地,
+                // 计费提交在 503(orchestrator/壳读此旗决定摘流/重试;编排器侧「pull 成功才 ready」增强不互斥)。
                 ...(deps.modelReady && !deps.modelReady() ? { ready: false, readyReason: "model roster pending (first effective-config pull)" } : {}),
                 model: deps.config.model.id,
-                sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend,
+                sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend, // effective store, not the coerced enum
                 sessions: deps.runner.sessions.size,
                 ...(deps.instanceId ? { instanceId: deps.instanceId } : {}),
+                // 🔴 `dataRoot`/`pid` 是**公开承诺字段**(2026-07-28 起,USAGE「嵌入形契约」段):桌面宿主的
+                // 引擎身份验证(「这个 /health 是不是我起的那个进程」)整个押在这两个键上——pid 必须等于所
+                // spawn 子进程、dataRoot 必须等于所配数据根,缺任一=判外来。localDataRoot 的解析恒回退
+                // `~/.ai-agent`(config.ts,与 DB_BACKEND 无关)⇒ 此条件 spread 实为恒真;改动这两个键的
+                // 在场性/语义前先看 test/health-identity-contract.test.ts。
                 ...(deps.config.localDataRoot ? { dataRoot: deps.config.localDataRoot } : {}),
                 configHash,
                 pid: process.pid,
                 port: deps.config.port,
+                // D-G: a POSITIVE go-live signal that this worker is a crypto-bound direct-door worker (trusted-header
+                // path disabled) — additive, only present when active, so a normal worker's /health shape is unchanged.
+                // Surfaced for the DG-M2 go-live runbook (was previously inferrable only behaviorally via a 401).
                 ...(deps.config.directDoorActive ? { directDoorActive: true } : {}),
                 ...(restart ? { restartRequired: true, restart: { reasons: restart.reasons, version: restart.version, since: restart.since } } : {}),
+                // codex R18 (models-tiers deferral): additive DEGRADED state — the model plane is deferred but no
+                // next-boot handoff exists (LKG not restart-surviving), so no restart is forced and the plane stays
+                // unapplied. Present ⇒ the operator must either mount restart-surviving LKG storage (+ set
+                // CONFIG_LKG_DURABLE) or restart manually after ensuring the candidate will be re-pulled at boot.
                 ...(() => {
                     const stuck = deps.planeDeferredState?.();
                     return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
@@ -253,6 +406,9 @@ export function createHttpServer(rawDeps) {
             });
             return;
         }
+        // Metrics (read-only): authorized by EITHER the full authToken OR a read-only metricsToken — so a
+        // control plane (sema-registry) can pull metrics fleet-wide with one token, never holding each
+        // worker's full authToken. Handled BEFORE the global gate so metricsToken-only callers aren't 401'd.
         if (req.method === "GET" && (url === "/metrics" || url === "/metrics/summary" || url === "/metrics/plan-cache")) {
             if (!deps.metrics) {
                 sendError(res, 404, "feature.metrics_disabled", "metrics disabled");
@@ -269,6 +425,7 @@ export function createHttpServer(rawDeps) {
                 sendJson(res, 200, { model: deps.config.model.id, ...deps.metrics.summarize() });
                 return;
             }
+            // Per-scope objective-recurrence detail (core design/42 handoff). Same token gate as /metrics.
             if (url === "/metrics/plan-cache") {
                 sendJson(res, 200, { scopes: deps.planCacheProbe?.dump() ?? {} });
                 return;
@@ -277,7 +434,14 @@ export function createHttpServer(rawDeps) {
             res.end(deps.metrics.render());
             return;
         }
+        // 鉴权桥预认证:在任何 principal-gated 路由(trace/fleet/workflows/authorizer)读取身份之【前】,
+        // 若 Authorization bearer 形似 registry-JWT 且 verifier 在位,验它——通过则把 sub 挂进 request-local
+        // (setSsoPrincipal),verifiedPrincipal 单一真源随后优先读它(directDoor 与 BFF 两部署同效),并同时写入
+        // principalHeader(小写键)供 principalFrom 直读处使用。验证不通过=不设身份,后续 systemFor 因 bearer 不匹配
+        // 任何静态 token 而 401(恒 generic,R9:错误码只进日志)。非 JWT-形 bearer(静态 token)= looksLikeJwt
+        // 跳过,零开销,既有调用方字节不变。
         if (deps.registryJwtVerifier) {
+            // 只认 Bearer scheme(异源复审 INFO:`Basic a.b.c` 之前会白跑一次 verify + 一条 rejected 记账噪声)。
             const authz = req.headers.authorization ?? "";
             const rawBearer = /^Bearer\s/i.test(authz) ? authz.replace(/^Bearer\s+/i, "") : "";
             if (rawBearer && looksLikeJwt(rawBearer)) {
@@ -285,23 +449,35 @@ export function createHttpServer(rawDeps) {
                 if (v.ok) {
                     setSsoPrincipal(req, v.identity.principal);
                     req.headers[deps.config.principalHeader.toLowerCase()] = v.identity.principal;
+                    // scope claim 也挂 request-local(多租户活动租户;registry-core 0.3.0+ VerifiedIdentity.scope)。
+                    // 用途=审计归因 + 未来 scope 级 quota/过滤的读取地基。同时记一条 info 审计锚(每认证请求一条):
+                    // 此前 principal 入了 owner 但 scope 全程不落任何日志/审计(grep 实证零命中 scope)——补齐。
                     if (v.identity.scope)
                         setSsoScope(req, v.identity.scope);
                     deps.logger?.info?.("auth_bridge_principal_accepted", { principal: v.identity.principal, ...(v.identity.scope ? { scope: v.identity.scope } : {}) });
                 }
             }
         }
+        // design/158 A9 域模块:Task Trace 只读面 + 用量统计面(routes/trace-usage.ts)。
+        // ⚠️ 位置即契约:必须留在下面的全局 service-credential 门**之前**(traceToken-only 调用方否则先被 401)。
         if (await handleTraceUsage(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:S8 自编排 workflow 只读三路(routes/workflows.ts)。
+        // 位置同 trace/fleet:全局 service-credential 门之前,块内 scope 门=这些读的唯一租户边界。
         if (await handleWorkflows(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:MF-Fleet 实时舰队流(routes/fleet.ts)。服务凭据门之前,按 principal 自门。
         if (await handleFleet(req, res, url, ctx))
             return;
+        // Service-credential gate + SOURCE derivation: which system's token authenticated this request.
+        // `source` is set ONLY here, from the credential — a caller cannot claim another system's identity.
         let source = null;
         const anyServiceAuth = Boolean(deps.config.authToken) || Object.keys(deps.config.authTokens ?? {}).length > 0;
         if (anyServiceAuth) {
             const sys = systemFor(req, deps.config);
             if (sys === undefined) {
+                // 鉴权桥:静态 service-token 都不匹配 → 若入口预认证已把一个验过的 registry-JWT principal
+                // 挂进 request-local(ssoVerifiedPrincipal),即用户直连(source="sso");否则无凭据 401。
                 if (ssoVerifiedPrincipal(req)) {
                     source = "sso";
                 }
@@ -314,7 +490,16 @@ export function createHttpServer(rawDeps) {
                 source = sys;
             }
         }
+        // design/158 A9:`source` 的**唯一**赋值段就在上面;域模块经 ctx.req.source 读到同一个值(单向镜像,
+        // 此行之后 handle() 不再改它)。
         reqState.source = source;
+        // Mandatory service token on submission endpoints (center: a worker MUST validate a service-to-service
+        // token on task creation — not "if auth is configured" — else anything in-cluster can submit & bill
+        // directly, bypassing sema-registry's auth/audit). Fail-closed: the POST task/run/leader endpoints refuse
+        // when no authToken is set, unless explicitly opted out for local dev (ALLOW_UNAUTHED_WRITES=true).
+        // The bake door (POST /v1/images/bakes*) is build-host-RCE-capable and authed by the Bearer-token-no-cookie
+        // model (§P2.4b) — it MUST also refuse when no service token is configured (else a forged principal header
+        // alone could reach an operator-gated RCE door).
         if (req.method === "POST" &&
             !anyServiceAuth &&
             !deps.config.allowUnauthedWrites &&
@@ -322,16 +507,31 @@ export function createHttpServer(rawDeps) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions");
             return;
         }
+        // DRAINING — this instance is shutting down gracefully (SIGTERM received, in-flight turns being
+        // waited on). Refuse NEW model-running work (the same billable submit set: task/stream/runs/leader + the
+        // resume-flavored assistant verbs + approvals responds — each starts a model turn) with 503 + Retry-After so
+        // the shell/orchestrator retries against the replacement. Everything else stays open: reads (events/health/
+        // trace), cancel, steer/respond on in-flight runs — those help the drained turns finish, they don't start new ones.
         if (deps.drainState?.draining && req.method === "POST" && isBillableSubmitPath(url)) {
             res.setHeader("retry-after", "15");
+            // errorCode 补齐(2026-07-28 核查:cli 的 pre-stream drain 重试只能靠 `error` 文案字面判型——
+            // SDK 的 code 臂恒 undefined 是死码;server 改文案=对端重试静默失效)。`error:"draining"` 字面
+            // 自此视为**冻结的 wire 契约**(旧消费端判的就是它),errorCode 是机器码正门。
             sendError(res, 503, "draining", "draining", { message: "this instance is draining for shutdown/upgrade — retry against the replacement instance" });
             return;
         }
+        // boot ready 门(b)(E3 workers.model 废除的 fail-closed 半场):registry 部署且无显式 env 模型时,
+        // 首次 effective pull 落 roster 之前 worker 只有占位模型——计费提交打占位=垃圾任务,503 让编排器/壳重试
+        // 到 roster 落地(通常 <秒)。镜像 draining 姿势(同 billable 集合;读面/cancel/steer 全开);/health 带
+        // ready:false 加性旗。env 模型在(操作员显式声明)或非 registry 部署=恒 ready,现有部署零影响。
         if (deps.modelReady && !deps.modelReady() && req.method === "POST" && isBillableSubmitPath(url)) {
             res.setHeader("retry-after", "5");
             sendError(res, 503, "state.model_roster_pending", "model_roster_pending", { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" });
             return;
         }
+        // E6 (review): the operator session-policy PUT is a mutating operator-gated write — apply the SAME fail-closed
+        // no-service-token guard as the POST submit paths (an un-authed worker must not accept policy writes from anything
+        // in-cluster; without it a forged principal header alone could tighten/DoS a session's tools).
         if (req.method === "PUT" &&
             !anyServiceAuth &&
             !deps.config.allowUnauthedWrites &&
@@ -339,62 +539,99 @@ export function createHttpServer(rawDeps) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting session-policy writes");
             return;
         }
+        // design/158 A9:能力/场景/模型目录域(routes/capabilities.ts)。位置=全局 service-credential 门之后、
+        // 任务提交面之前,与拆分前逐行同序。
         if (await handleCapabilities(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:sideQuery 一次性问答面(routes/side-query.ts)。
         if (await handleSideQuery(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:同步提交面 POST /v1/tasks · /v1/tasks/stream(routes/tasks.ts;B3 三腿具名化在内)。
         if (await handleTasks(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:异步 run 面 + run 级动词(routes/runs.ts)。与 tasks 域共用 ctx.legs.prepareSpec。
         if (await handleRuns(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:SVC-5 workflow agent steer(routes/workflows.ts,与上面的只读三路同域)。
         if (await handleWorkflowAgentSteer(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:子代理 / 任务句柄 / 三条 HITL 应答口(routes/runs.ts,与上面的 run 面同域)。
         if (await handleRunVerbs(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:v2 leader 端点(routes/leader.ts)。
         if (await handleLeader(req, res, url, ctx))
             return;
+        // design/158 A9:sandbox-image-pool 控制面(routes/images.ts;bakes 段在 images 段之前的顺序由域模块内部保住)。
         if (await handleImages(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:人在环审批面(durable F4 + legacy)与 assistant-scheduler 三动词
+        // (routes/approvals-assistant.ts)。续跑一律经 ctx.legs 的 resume 家族。
         if (await handleApprovalsAssistant(req, res, url, ctx))
             return;
+        // design/158 A9:观测只读面(routes/observability.ts):/v1/outcomes + /v1/usage。
         if (await handleObservability(req, res, url, ctx))
             return;
+        // design/158 A9:memory 导出/同步 + /v1/policy 只读面(routes/memory-policy.ts)。
         if (await handleMemoryPolicy(req, res, url, ctx))
             return;
+        // design/158 A9:会话/发件链接列表面(routes/sessions-list.ts)。
         if (await handleSessionsList(req, res, url, ctx))
             return;
+        // design/158 A9:单会话面(routes/sessions.ts:init/settings/mcp/head/events/audit/fork/delete/policy/workspace)。
         if (await handleSessions(req, res, url, ctx))
             return;
+        // design/158 A9:2c session-sync 面(routes/session-sync.ts)。
         if (await handleSessionSync(req, res, url, ctx))
             return;
+        // design/158 A9:D-1 通用附件面(routes/attachments.ts)。
         if (await handleAttachments(req, res, url, ctx))
             return;
+        // design/158 A9 域模块:会话外事件注入 / 唤醒(routes/notify-wake.ts)。
         if (await handleNotifyWake(req, res, url, ctx))
             return;
         sendError(res, 404, "not_found.route", "not found");
     }
+    /** Read + validate the body, authorize, and build the spec. Returns null if it already responded. */
     async function prepareSpec(req, res) {
         const body = (await readJson(req));
         if (!body || typeof body.objective !== "string") {
             sendError(res, 400, "request.field_invalid", "missing 'objective' string");
             return null;
         }
+        // [920] 空毒帧第一道门:空/纯空白 objective 会成为持久历史里的空 user 帧——严格网关(anthropic/kimi)
+        // 对空 content 400,且一帧毒全 session(同角色 merge 后残留空 block,存量救不了)。core 半场(装配
+        // 自愈+intake 拒)在修;HTTP 面 fail-loud 是宪法「诚实优先」形:空任务无合法用例,静默吞掉才是坑。
         if (body.objective.trim().length === 0) {
             sendError(res, 400, "request.field_invalid", "objective must not be empty or whitespace-only (an empty user message poisons the session history on strict providers)");
             return null;
         }
+        // jobId (work-view correlation): optional, but if present must be a non-empty string ≤64 chars (the column
+        // width) — reject a malformed one up front rather than silently truncating/dropping it at the INSERT.
         if (body.jobId !== undefined && (typeof body.jobId !== "string" || body.jobId.length === 0 || body.jobId.length > 64)) {
             sendError(res, 400, "request.field_invalid", "jobId must be a non-empty string of at most 64 characters");
             return null;
         }
+        // [#15] sessionId: a client MAY supply an ARBITRARY id (deliberate asymmetry vs fork/delete — see security.ts
+        // `isUuidV7` doc: run-local `--session`, dev anonymous-share ids; the wire contract types sessionId as an opaque
+        // string), but it must fit the `session_id VARCHAR(64)` column. Reject an over-long one up front rather than
+        // 500/truncating at the INSERT (the authorizer's register() runs later in this function, after this block via the
+        // deps.authorize() call — so the cap fires before any INSERT). LENGTH-ONLY — NOT a uuidv7 shape
+        // check (that would break the permissive submit contract); submit stays lenient, fork/delete keep the uuidv7 gate.
         if (typeof body.sessionId === "string" && body.sessionId.length > 64) {
             sendError(res, 400, "request.field_invalid", "sessionId must be at most 64 characters");
             return null;
         }
+        // Personalization caps: once users can edit these, an uncapped prompt/skill body is a
+        // cost hole — reject up front, server-pinned (a UI may be stricter, never looser).
         if (typeof body.systemPrompt === "string" && body.systemPrompt.length > MAX_SYSTEM_PROMPT_CHARS) {
             sendError(res, 400, "request.field_invalid", `systemPrompt must be at most ${MAX_SYSTEM_PROMPT_CHARS} characters`);
             return null;
         }
+        // appendSystemPrompt ([1478] R2 + codex R7 F2): fail-loud SHAPE gate on fresh submits — a defined value must
+        // be a non-empty string within the systemPrompt cap. A non-string/empty value would be silently normalized to
+        // "absent" by resolveSpec's defensive accept (a client serialization bug then runs the task WITHOUT its
+        // product-knowledge block — the silent-drop class again); the cap matches systemPrompt (same prompt surface,
+        // same per-turn cost hole). Stored resume bodies stay on the defensive drop+warn (acceptAppendSystemPrompt).
         if (body.appendSystemPrompt !== undefined) {
             if (typeof body.appendSystemPrompt !== "string" || body.appendSystemPrompt.length === 0) {
                 sendError(res, 400, "request.field_invalid", "appendSystemPrompt must be a non-empty string");
@@ -405,10 +642,23 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // codex F3/R3/R4 (capability honesty): the append-less-pack combos (rider / settings.outputStyle meeting an
+        // already-assembled systemPrompt or a center assembled-identity pack) are adjudicated INSIDE resolveSpec —
+        // it alone derives the effective scenario (principal ruling + defaultScenario) and holds the center-pack
+        // snapshot the provider pick uses, so an HTTP-side probe could disagree with the actual assembly (R4:
+        // scenario mismatch / centerPrompts refresh TOCTOU). This route passes `leg:"fresh"` below, which makes
+        // resolveSpec 400 fail-loud (HttpError, surfaced by the catch around prepareSpec's caller); resume families
+        // omit it and get the drop+warn mirror instead.
+        // [#40 / TOC cwd seam] body.cwd must be an ABSOLUTE host path — fail-loud (a relative cwd would silently resolve
+        // against the SERVICE process cwd, not the user's project — TOC review #12). Whether it is HONORED is separately
+        // gated to the single-user host lane (resolveSpec); validating shape here is independent of that gate.
         if (body.cwd !== undefined && !isValidCwd(body.cwd)) {
             sendError(res, 400, "request.field_invalid", "cwd must be a non-empty absolute host path");
             return null;
         }
+        // design/119 (CC --add-dir) body.additionalDirectories — fail-loud shape on submit (mirrors cwd; each entry is a
+        // host path with the SAME absolute/no-`..` rule). Whether it is HONORED is separately gated to the host lane
+        // (resolveSpec). An empty array is fine (no-op); a non-array or an entry failing the cwd shape is a client error.
         const addDirsRaw = body.additionalDirectories;
         if (addDirsRaw !== undefined) {
             if (!Array.isArray(addDirsRaw)) {
@@ -425,6 +675,9 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // body.settings (client SemaSettings stamp) — fail-loud shape/size caps on submit, matching the sibling
+        // fields' posture (parseTaskSettings is also defensive on every path incl. resume; this 400s a bad submit early
+        // rather than silently coercing — adversarial review). The semantic projection (tighten-only) happens in resolveSpec.
         const settingsRaw = body.settings;
         if (settingsRaw !== undefined && settingsRaw !== null) {
             if (typeof settingsRaw !== "object" || Array.isArray(settingsRaw)) {
@@ -436,6 +689,8 @@ export function createHttpServer(rawDeps) {
                 sendError(res, 400, "request.field_invalid", `settings.outputStyle must be at most ${MAX_SETTINGS_OUTPUT_STYLE_CHARS} characters`);
                 return null;
             }
+            // codex R14: BOTH append carriers fold into ONE spec field (applyTaskSettings: `append\n\nstyle`) — two
+            // individually-valid values can exceed the documented cap combined. One aggregate gate, same bound.
             if (typeof st.outputStyle === "string" &&
                 st.outputStyle.length > 0 &&
                 typeof body.appendSystemPrompt === "string" &&
@@ -453,6 +708,8 @@ export function createHttpServer(rawDeps) {
                     }
                 }
             }
+            // settings.env (R-survey) — fail-loud on submit, parity with outputStyle/permissions (adversarial-review LOW). The
+            // defensive parse `cleanEnvMap` also caps these on every path (resume re-runs WITHOUT this gate), this just 400s a fresh submit.
             const envRaw = st.env;
             if (envRaw !== undefined && envRaw !== null) {
                 if (typeof envRaw !== "object" || Array.isArray(envRaw)) {
@@ -471,10 +728,16 @@ export function createHttpServer(rawDeps) {
                     }
                 }
             }
+            // L2 ultracode (design/111): fail-loud on a non-boolean (parity with the other settings caps; parseTaskSettings
+            // silently ignores non-true on the resume paths the HTTP gate doesn't cover).
             if (st.ultracode !== undefined && typeof st.ultracode !== "boolean") {
                 sendError(res, 400, "request.field_invalid", "settings.ultracode must be a boolean");
                 return null;
             }
+            // settings.hooks(hook-runner 阶段一)— fail-loud on submit(131/132/133 邻居姿势):一个 malformed
+            // hooks 配置被静默丢弃 = 用户以为在生效的 deny 钩子其实没跑(安全预期破坏),必须 400。契约校验 =
+            // registry-core 0.1.51 HooksConfig + 服务侧上限(parseHooksConfig);resume 路径由 parseTaskSettings 防御
+            // (malformed → deferred 报告+warn)。是否 HONOR 另由单用户闸在 resolveSpec 决定(多租户=忽略非 400)。
             if (st.hooks !== undefined && st.hooks !== null) {
                 const hooksParsed = parseHooksConfig(st.hooks);
                 if (!hooksParsed.config) {
@@ -488,6 +751,9 @@ export function createHttpServer(rawDeps) {
             sendError(res, 400, "request.field_invalid", skillsErr);
             return null;
         }
+        // body.images (CC parity): cap COUNT + per-image inline base64 size → 413 (the inline
+        // `data` is otherwise passed raw to the spec; URL images are core-gated). MAX_BODY already bounds total bytes; this
+        // adds the missing count cap (anti decode-DoS) + an explicit per-image 413. Fail-loud parity with the settings caps.
         if (Array.isArray(body.images)) {
             if (body.images.length > MAX_IMAGES_PER_REQUEST) {
                 sendError(res, 413, "request.payload_too_large", `at most ${MAX_IMAGES_PER_REQUEST} images per request`);
@@ -501,6 +767,10 @@ export function createHttpServer(rawDeps) {
                 }
             }
         }
+        // design/112 C1: validate the client context shape + cap each field. The body is untrusted and timeZone/userEmail
+        // flow into core's env block — an object with optional string timeZone/userEmail; reject non-strings / over-long
+        // values (anti-DoS + anti env-block-injection bloat). core additionally validates timeZone semantically (invalid
+        // IANA zone → UTC, never mislabeled). locale was removed in core 1.186 (dead field) so it is not accepted here.
         if (body.clientContext !== undefined) {
             const cc = body.clientContext;
             if (typeof cc !== "object" || cc === null || Array.isArray(cc)) {
@@ -516,6 +786,9 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // §7 P0.5 sandbox image selection: shape-validate here (a non-empty profile string; capabilitiesNeeded a
+        // string[]). The per-principal visibility re-admit + profile→digest resolution happen in resolveSpec (it
+        // holds the imageIndex + the trusted principal); a 400/404 there surfaces via the HttpError catch below.
         if (body.sandboxImageProfile !== undefined && (typeof body.sandboxImageProfile !== "string" || body.sandboxImageProfile.length === 0 || body.sandboxImageProfile.length > 128)) {
             sendError(res, 400, "request.field_invalid", "sandboxImageProfile must be a non-empty string of at most 128 characters");
             return null;
@@ -524,14 +797,23 @@ export function createHttpServer(rawDeps) {
             sendError(res, 400, "request.field_invalid", "capabilitiesNeeded must be an array of strings");
             return null;
         }
+        // capabilitiesNeeded is a constraint ON the selected image — meaningless without a profile to select (it would
+        // otherwise be silently ignored while the task runs the unchecked worker-global default). Adversarial-review LOW.
         if (Array.isArray(body.capabilitiesNeeded) && body.capabilitiesNeeded.length > 0 && (typeof body.sandboxImageProfile !== "string" || body.sandboxImageProfile.length === 0)) {
             sendError(res, 400, "request.field_conflict", "capabilitiesNeeded requires sandboxImageProfile (it constrains the selected image)");
             return null;
         }
+        // §7 P0.5 + the multi-run orchestration gates don't compose in v1: the per-task image binds by sessionId, but
+        // `cascade` strips sessionId per rung and `verify` runs its verifier on a separate session — both would
+        // silently fall back to the worker-global default image. Reject the combo FAIL-LOUD rather than run the wrong
+        // image (adversarial-review round-2 MEDIUM). Lift when core propagates the image binding to those sub-runs.
         if (typeof body.sandboxImageProfile === "string" && body.sandboxImageProfile.length > 0 && (body.cascade === true || body.verify === true)) {
             sendError(res, 400, "request.field_conflict", "sandboxImageProfile is not supported together with cascade/verify in v1 (the per-task image would not bind to the cascade rungs / verifier sub-run)");
             return null;
         }
+        // Structured output (CC --json-schema): a plain JSON-schema OBJECT, size-capped (an uncapped schema is a
+        // prompt-bloat / cost hole, same posture as systemPrompt/skills). Deep schema validity is core's job — a
+        // malformed schema fails the task with a typed core error, not a 400 here. Threaded into spec by resolveSpec.
         if (body.outputSchema !== undefined) {
             if (typeof body.outputSchema !== "object" || body.outputSchema === null || Array.isArray(body.outputSchema)) {
                 sendError(res, 400, "request.field_invalid", "outputSchema must be a JSON Schema object");
@@ -542,10 +824,19 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // E7 (shell-host contract): reasoning-effort selection (the `/effort` picker), mapped to core's ThinkingLevel in
+        // resolveSpec. Validate FAIL-LOUD — a provided-but-unknown level is a 400, never silently dropped (the body.model
+        // silent-drop bug class). The accepted set is core's tier scale; the picker's default set is advertised on
+        // /v1/models (supportedEffortLevels). Absent ⇒ core uses the resolved role's default thinking.
         if (body.reasoningEffort !== undefined && !isThinkingLevel(body.reasoningEffort)) {
             sendError(res, 400, "request.field_invalid", "reasoningEffort must be one of: off, minimal, low, medium, high, xhigh, max");
             return null;
         }
+        // E18 (shell-host contract): resume-at handle shape. A non-empty string ≤64 (the uuidv7 eventId / entry_id column
+        // width). resolveSpec resolves it to a SessionTreeEntry.id (eventId→entryId anchor map) — an unknown handle 4xx's
+        // there. Reject combos core forbids (resumeAt + a fresh verify/cascade leg replaces/strips the session per
+        // rung/sub-run, so resume-at is meaningless there — fail-loud rather than silently branch a session that's about
+        // to be replaced), mirroring the sandboxImageProfile+cascade/verify reject.
         if (body.resumeAt !== undefined) {
             if (typeof body.resumeAt !== "string" || body.resumeAt.length === 0 || body.resumeAt.length > 64) {
                 sendError(res, 400, "request.field_invalid", "resumeAt must be a non-empty message eventId string (≤64 chars)");
@@ -556,6 +847,8 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // [833] rewind exclusive mode: two enum values only, and only riding a resumeAt (alone it qualifies nothing — a
+        // silent no-op is the body.model silent-drop bug class, so fail loud). Absent ⇒ core default "at" (zero regression).
         if (body.resumeAtMode !== undefined) {
             if (body.resumeAtMode !== "at" && body.resumeAtMode !== "before") {
                 sendError(res, 400, "request.field_invalid", 'resumeAtMode must be "at" or "before"');
@@ -566,6 +859,9 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // E12 (shell-host contract): prompt-suggestions opt-in. `true`/`false` or an object `{count?, role?}`. Validate
+        // FAIL-LOUD (a malformed value is a 400, not a silent off — the body.model silent-drop bug class); resolveSpec then
+        // normalizes (and re-normalizes defensively on resume, which skips this HTTP validation).
         if (body.suggestNextPrompts !== undefined && typeof body.suggestNextPrompts !== "boolean") {
             const s = body.suggestNextPrompts;
             if (typeof s !== "object" || s === null || Array.isArray(s)) {
@@ -582,22 +878,33 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // E19 (shell-host contract): rewind-files opt-in must be a boolean (fail-loud, not silently dropped).
         if (body.rewindFiles !== undefined && typeof body.rewindFiles !== "boolean") {
             sendError(res, 400, "request.field_invalid", "rewindFiles must be a boolean");
             return null;
         }
+        // MF-30 memory PAUSE (option B): the per-request write toggle must be a boolean (fail-loud — a malformed value
+        // silently writing to memory when the user asked to pause is exactly the silent-drop bug class).
         if (body.memoryWrite !== undefined && typeof body.memoryWrite !== "boolean") {
             sendError(res, 400, "request.field_invalid", "memoryWrite must be a boolean (false = pause memory writes for this run)");
             return null;
         }
+        // design/114 Phase3: requireExistingSession opt-in must be a boolean (fail-loud — a truthy non-boolean silently
+        // NOT triggering the fail-loud is the very "silent fresh run" this flag exists to prevent).
         if (body.requireExistingSession !== undefined && typeof body.requireExistingSession !== "boolean") {
             sendError(res, 400, "request.field_invalid", "requireExistingSession must be a boolean");
             return null;
         }
+        // §4 (Fork): enableFork opt-in must be a boolean (fail-loud, not silently dropped — mirrors selfOrchestration).
         if (body.enableFork !== undefined && typeof body.enableFork !== "boolean") {
             sendError(res, 400, "request.field_invalid", "enableFork must be a boolean");
             return null;
         }
+        // design/131/132/133 (1.127.0): fresh-submit shape validation for the three new opt-ins — a
+        // malformed value must 400 here, not silently normalize to "off" (the body.model silent-drop bug class).
+        // resolveSpec's normalizers stay defensive for the RESUME path (which re-enters without HTTP validation).
+        // NOTE: `resilience.bypassBreaker=true` from a NON-operator is a shape-valid permission downgrade (dropped
+        // by the normalizer, not a 400) — the field's authz, not its type.
         if (body.resilience !== undefined) {
             const r = body.resilience;
             if (typeof r !== "object" || r === null || Array.isArray(r)) {
@@ -616,6 +923,11 @@ export function createHttpServer(rawDeps) {
             sendError(res, 400, "request.field_invalid", "finalVerification must be a boolean");
             return null;
         }
+        // [854]④: fresh-submit shape validation for per-request 配速 —— 已知三键必须是正整数,否则 400 fail-loud
+        // (body.model silent-drop 同类教训:静默 normalize 成「没配速」正是本件要防的假成功)。0 也拒绝:core 侧
+        // `timeoutSec > 0` 才生效(0=不设墙,会绕过 TASK_TIMEOUT_MAX_SEC 封顶),maxTurns/maxOutputTokens 的 0 无意义。
+        // 枚举外键与 resilience/attachments 同口径:容忍(只校验已知键)。resolveSpec 的 normalizeLimits 对 RESUME
+        // 重放路径保持 defensive(按键 DROP,不 throw)。
         if (body.limits !== undefined) {
             const l = body.limits;
             if (typeof l !== "object" || l === null || Array.isArray(l)) {
@@ -629,6 +941,9 @@ export function createHttpServer(rawDeps) {
                     return null;
                 }
             }
+            // 快审 F2(1.254):deadline 族三 opt-out 在场必须 literal false——"false"/0 等畸形值此前 200 后被
+            // normalizeLimits 静默丢=调用方以为关了其实恒开(B1 同类故障)。fresh fail-loud;resume 重放不过
+            // 此门,normalizeLimits 保持 defensive。
             for (const k of ["deadlineNudge", "callCapByDeadline", "gracefulFinalize"]) {
                 const v = body.limits[k];
                 if (v !== undefined && v !== false) {
@@ -637,6 +952,11 @@ export function createHttpServer(rawDeps) {
                 }
             }
         }
+        // [876] per-task subagents(core 1.295 TaskSpec.agents):fresh-submit 白名单门 fail-loud。与 resilience/
+        // limits 的「容忍未知键」取舍相反 —— agents 是能力定义,静默丢字段=定义被悄悄削(丢一个 denyTools/
+        // isolation 就是放宽),400 点名未知键更安全。permissionMode 有意不纳(core 拍,独立批)——出现按未知键拒。
+        // 形状细则(name 必填且数组内唯一/各字段浅形状/≤32 条)单源在 spec-fields.ts validateTaskAgents;RESUME
+        // 重放不过这道门 → resolveSpec 侧 taskAgentsFromBody defensive(非法项按条 DROP+warn,不砖 resume)。
         if (body.agents !== undefined) {
             const agentsErr = validateTaskAgents(body.agents);
             if (agentsErr) {
@@ -644,14 +964,20 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // [922]①/[915]② interactiveTools(core 1.296 三态旋钮):boolean fail-loud 同邻居姿势。per-run 工具面
+        // 选择(AskUserQuestion/present_plan 挂载判据覆写),无跨租户面 ⇒ 不设租户门;undefined=core 自动判据。
         if (body.interactiveTools !== undefined && typeof body.interactiveTools !== "boolean") {
             sendError(res, 400, "request.field_invalid", "interactiveTools must be a boolean");
             return null;
         }
+        // [854]② retainBackgroundProcesses:boolean fail-loud(邻居姿势 —— 非 boolean 静默变「不驻留」正是
+        // silent-drop 病灶);单用户闸/多租忽略在 resolveSpec(retainBackgroundProcessesFromBody)。
         if (body.retainBackgroundProcesses !== undefined && typeof body.retainBackgroundProcesses !== "boolean") {
             sendError(res, 400, "request.field_invalid", "retainBackgroundProcesses must be a boolean");
             return null;
         }
+        // [1052]② excludeTools/deferTools:数组-of-非空-string fail-loud(邻居姿势——坏形静默丢=工具面照旧,
+        // 调用方以为收窄了却没收=silent-drop 病灶同族)。per-run 收窄无跨租户面 ⇒ 无租户门(interactiveTools 同)。
         for (const key of ["excludeTools", "deferTools"]) {
             const v = body[key];
             if (v !== undefined && (!Array.isArray(v) || v.some((n) => typeof n !== "string" || n.length === 0))) {
@@ -659,6 +985,7 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // [1144]/[1146] promptProfile:枚举 fail-loud(坏值静默丢=调用方以为切了形没切,silent-drop 病灶同族)。
         {
             const v = body.promptProfile;
             if (v !== undefined && v !== "simple" && v !== "classic") {
@@ -666,18 +993,30 @@ export function createHttpServer(rawDeps) {
                 return null;
             }
         }
+        // [865]② fresh-submit 未知模型 400 fail-loud(clay 生产实锤:未知 body.model 静默落 default = 用户不知情
+        // 换模型)。🔴 门目录必须与 resolveSpec 同源 = expandTiers 增广视图(codex H1:裸 config.models 会把合法
+        // 档位词 "pro"/CC alias "sonnet" 当未知 400 误杀——SDK 契约明确允许它们;增广后 matchCatalogModel 对
+        // name/tier 词/alias/id 四形一体裁决)。restart 窗口注记与 main.ts wireCatalog 同款:tiers 热刷新 vs
+        // Runner 构造期快照,门短暂超前=fail-loud 而非静默降级,诚实。"default" 是合法目录键(hasOwn 命中)。
+        // RESUME 重放持久化 body 不过这道门(模型事后被移出目录时砖死 resume 比降级糟)——resolveSpec 侧对未知
+        // ref warn 降级,双层与 [854] limits 同姿势。settings.model 保持 lenient(文档化,picker 路径 =
+        // body.model 才是本病灶面)。
         if (body.model !== undefined) {
             if (typeof body.model !== "string" || body.model.length === 0) {
                 sendError(res, 400, "request.field_invalid", "model must be a non-empty string (a configured catalog name, tier word, or model id)");
                 return null;
             }
-            const bare = deps.config.models ?? {};
+            const bare = deps.config.models ?? {}; // 防御:极简 stub deps 可无 models 域(真 loadConfig 恒有)
             const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
             if (matchCatalogModel(body.model, catalog) === undefined) {
                 sendError(res, 400, "request.unknown_reference", `unknown model "${body.model.slice(0, 120)}" — not in the configured catalog (name, tier word, or id)`, { available: Object.keys(catalog).filter((n) => n !== "default") });
                 return null;
             }
         }
+        // [1479]① compactionModel — the SAME fail-loud posture + gate catalog as body.model (an unknown cheap-gear pick
+        // silently burning the MAIN model's price is exactly the silent-drop bug class this train exists to kill).
+        // RESUME replays skip this gate (resolveSpec drops+warns there — core's resolveModel throws on an unknown ref,
+        // which would brick the resume).
         if (body.compactionModel !== undefined) {
             if (typeof body.compactionModel !== "string" || body.compactionModel.length === 0) {
                 sendError(res, 400, "request.field_invalid", "compactionModel must be a non-empty string (a configured catalog name, tier word, or model id)");
@@ -720,6 +1059,8 @@ export function createHttpServer(rawDeps) {
                 }
             }
         }
+        // 历史复审轴A #3(1.254):verify 环补 cost 顶——cascade 腿一直映 costCeilingMicroUsd,verify 腿漏了
+        // (每轮独立 runTask,总花费此前仅受 maxRounds 约束);同源 body.maxCostUsd,同换算。
         const verify = body.verify === true
             ? {
                 maxRounds: clampVerifyRounds(body.verifyRounds),
@@ -731,6 +1072,9 @@ export function createHttpServer(rawDeps) {
             sendError(res, 400, "request.field_conflict", "verify and cascade are mutually exclusive (verify = adversarial gate; cascade = cheap→strong ladder)");
             return null;
         }
+        // E12: suggestNextPrompts is meaningless on the verify/cascade wrappers — they return a TaskResult, not
+        // a stream with core's post-completion suggestions() pass, so the suggestion event would never be produced. Reject
+        // the combo fail-loud rather than silently accept-and-drop it (mirrors the resumeAt + verify/cascade reject above).
         if (body.suggestNextPrompts && (verify || cascade)) {
             sendError(res, 400, "request.field_conflict", "suggestNextPrompts is not supported with verify or cascade (those return a result, not a streamed run)");
             return null;
@@ -745,18 +1089,62 @@ export function createHttpServer(rawDeps) {
         }
         catch (err) {
             if (err instanceof HttpError) {
+                // Typed rejection: echo the stable `code` + any structured extras (e.g. the scenario
+                // allowlist) beside the human message — machine code on the wire, prose stays with the shell/web.
                 sendError(res, err.status, httpErrorCode(err.status, err.code), err.message, { ...(err.code ? { code: err.code } : {}), ...(err.extra ?? {}) });
                 return null;
             }
             throw err;
         }
     }
+    // design/158 A9:`DecideBinding` 已上提到 `http/wire-types.ts` 叶子(approvals 域模块与 resume 腿同名一形),
+    // 本处仅留指路;形状逐字未变。
+    /**
+     * The VERIFIED fleet scope for a resume publish (TOC review #6 parity with the create paths). Prefer the
+     * crypto-verified `gatedPrincipal(req)` — the SAME identity GET /v1/fleet/stream filters by — on a real HTTP
+     * door; fall back to the checkpoint's own scope (`auth.principal`) only when there is NO request (the internal
+     * D-D SLA deny-sweep, which has no caller to verify). NEVER the spoofable `auth.principal` on a live door:
+     * a spoofed header would re-publish the resumed row under a victim's scope or under "default" (vanishing from
+     * its real owner's stream). Mirrors the sync/create sites' `gatedPrincipal(req, deps.config) ?? "default"`.
+     *
+     * ✅ FIDELITY EDGE — CLOSED by the F-fix (2026-07-01, direct-door principal spoofing). On the REQ-LESS leg (the
+     * internal D-D SLA deny-sweep, `req===undefined`) we fall back to `auth.principal` = the checkpoint's stored scope.
+     * Since the F-fix, createAuthorizer derives `auth.principal` (hence spec.principal, hence the checkpoint scope core
+     * persists at suspend) from `verifiedPrincipal` — the VERIFIED JWT sub on a direct door, the SAME identity the
+     * create path's `gatedPrincipal` tags the row with. So the earlier caveat — a misconfigured direct door where the
+     * raw `x-agent-principal` ≠ the verified sub could surface a swept row under the wrong tenant's /v1/fleet/stream —
+     * is GONE: the checkpoint scope is now always the verified identity, identical to what the create path tagged. The
+     * "TRUE fix" once deferred here (persist the verified principal on the checkpoint at create) is exactly what the
+     * F-fix did upstream at createAuthorizer; the req-less fallback and the create-path scope now agree on every posture.
+     */
     const resumeFleetScope = (req, auth) => req ? (gatedPrincipal(req, deps.config) ?? "default") : (auth.principal ?? "default");
-    async function resumeCheckpoint(sessionId, decision, reason, req, answer, binding, onResumeCommitted) {
+    /**
+     * Durable F4 resume (design/45): map a session → its pending checkpoint token INTERNALLY,
+     * rebuild the taskConfig via the same `resolveSpec` path (from the sessionId-keyed checkpoint_ctx), then
+     * `runner.resume`. The capability token never leaves the service. Updates the parked run row to its new state.
+     */
+    async function resumeCheckpoint(sessionId, decision, reason, req, // absent on the internal D-D SLA deny-sweep (resolveSpec rebuilds auth from the checkpoint, not req)
+    answer, binding, onResumeCommitted) {
         const cs = deps.checkpointStore;
+        // No scope filter here BY DESIGN (council): an operator may view/decide ANY tenant's pending approval.
+        // This load-before-CAS only READS; the definitive multi-tenant guard is the
+        // `AND scope = ?` inside the atomic resolve CAS — a wrong-scope decision can never EXECUTE.
         const token = await cs.findPendingTokenBySession(sessionId);
+        // D-1 approval_stale (opt-in, only when the operator echoed the checkpointToken they saw): if it no longer
+        // matches the current pending — resolved, superseded by a re-mint, or expired — they are deciding a STALE
+        // view. Reject distinctly from the markResuming session-CAS 409 below: the SDK keys ApprovalStaleError on
+        // errorCode:"approval_stale" while the CAS 409 stays bare (→ ConflictError), so the two 409s never collide.
         if (binding?.checkpointToken && binding.checkpointToken !== token) {
             const seen = await cs.get(binding.checkpointToken).catch(() => null);
+            // 🔴 `terminal` 只在该 token **确实属于本会话**时披露(2026-07-26 修)。
+            // 此前是 `seen ? "resolved" : "expired_abort"` —— 而这次 `cs.get` 用的是**调用方给的** token 且
+            // 存储层**没有 scope 谓词**(`WHERE token = ?`,连 status 都不过滤),这一步还跑在下面那个
+            // `if (!token) → 404` **之前**。于是任何持凭据者都能拿一串 token 来问「它在库里吗」:
+            // 命中 ⇒ `terminal:"resolved"`,不命中 ⇒ `terminal:"expired_abort"` —— **一位跨租户存在性 oracle**,
+            // 与本文件自述的「no existence oracle」相反。token 本身不可猜(uuid 级),所以这不是枚举面;
+            // 真实伤害是**泄漏出去的 token 可被免费确认有效性**(从日志/截图/工单捡到一串,不必也不能用它 resume,
+            // 却能确认它对应一条真实 checkpoint 行、以及它是否已被解决)。
+            // 归属不上就**省略这个键**(SDK 侧 `terminal?:` 本来可选)——不撒谎、也不泄露;真实原因照旧进日志。
             const attributable = seen !== null && seen.sessionId === sessionId;
             if (!attributable && seen !== null) {
                 deps.logger?.warn?.("approval_stale_token_foreign", { sessionId, tokenSession: seen.sessionId ?? null });
@@ -771,21 +1159,34 @@ export function createHttpServer(rawDeps) {
             };
         }
         if (!token) {
+            // 🔴 文案与 owner 门那条统一(2026-07-26 修)。此前两句可区分:owner 门拒 ⇒ "approval not found";
+            // 本会话**没有** pending ⇒ 这条更详细的。而 `peekPendingScope` 在没有 pending 时返回 `null`、`null` 被当作
+            // "开放"放过门 ⇒ 两句文案精确区分「这儿有**别人的** pending」与「这儿没有 pending」。
+            // 后果:任何持凭据的租户可逐个 sessionId 判定「此刻有一条别人的待决审批」,拼出一张跨租户的
+            // 「谁正卡在审批上」活动图(时序/规模情报)—— 而本文件自述承诺的正是不给这个。
+            // 统一成同一句;**诊断不丢**,只是挪进日志(部署方有日志权限,外部调用方没有)。
             deps.logger?.info?.("approval_decide_no_pending", { sessionId });
             return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
         }
-        const cpPromise = cs.get(token);
+        // get (checkpoint table) + getCtx (checkpoint_ctx table) are independent — load concurrently (council).
+        const cpPromise = cs.get(token); // throws if the checkpoint format is newer than this build (version guard)
         const ctxPromise = cs.getCtx(sessionId);
         let cp;
         try {
             cp = await cpPromise;
         }
         catch (e) {
-            void ctxPromise.catch(() => { });
+            void ctxPromise.catch(() => { }); // don't leak an unhandled rejection from the parallel load
             return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
         }
         if (!cp)
             return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        // design/153 件3d parked 赎回腿([1574]/[1584]/[1588] core 裁定;src/parked-decide.ts):该 pending
+        // checkpoint 若属于一个 parked 后台子代,decide 必须走 claim→裸 execute(reviveClaim) 链——legacy 腿的
+        // resumeStream 会绕开 bg registry(无 consumeParkedFlip、行永 parked、生命周期分叉),故 parked-first。
+        // 判别 miss(undefined)= 任务级 suspend,原样落到下方 legacy 腿(零回归)。⚠️ 门在 `req !== undefined`:
+        // 内部 D-D SLA deny-sweep(req 缺席)对 parked 子代 cp 保持现状(getCtx null → 409 跳过本 tick)——
+        // 过期 parked 的收割属 reaper 的 expire+reconcileParkedAgents 车道,sweep 不做重活赎回。
         if (req !== undefined && deps.backgroundAgentStore !== undefined && deps.parkedReviveTool !== undefined) {
             const parked = await decideParkedAgent({
                 agentStore: deps.backgroundAgentStore,
@@ -799,14 +1200,20 @@ export function createHttpServer(rawDeps) {
                 token, scope: cp.scope, sessionId: cp.sessionId, pendingAction: cp.pendingAction,
                 decision, ...(reason !== undefined ? { reason } : {}),
                 ...(binding !== undefined ? { binding: { ...(binding.boundCallId !== undefined ? { boundCallId: binding.boundCallId } : {}), ...(binding.boundInputHash !== undefined ? { boundInputHash: binding.boundInputHash } : {}), ...(binding.updatedInput !== undefined ? { updatedInput: binding.updatedInput } : {}) } } : {}),
+                // remember 的 grant 闭包(onResumeCommitted 的唯一现役来源)在 parked 腿以行的 root/host
+                // 会话为锚透传([1591] 候裁② server 修——落子代会话则探针键永不相交,见 grantOnCommit 注);
+                // answer 显式 400(复审 F6)。
                 ...(onResumeCommitted ? { grantRemember: (rootSessionId) => onResumeCommitted(rootSessionId) } : {}),
                 ...(answer !== undefined ? { answerPresent: true } : {}),
             });
             if (parked !== undefined) {
-                void ctxPromise.catch(() => { });
+                void ctxPromise.catch(() => { }); // 并行 ctx 读不再被消费,吞掉可能的 rejection
                 return parked;
             }
         }
+        // Guard the ctx await too (council): if cpPromise resolved but ctxPromise REJECTS (a TiDB blip on the
+        // checkpoint_ctx read), an unguarded await would escape to the generic 500 — inconsistent with the 409 the
+        // cpPromise branch returns for the same class of transient load failure.
         let ctx;
         try {
             ctx = await ctxPromise;
@@ -816,7 +1223,18 @@ export function createHttpServer(rawDeps) {
         }
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        // Rebuild taskConfig via resolveSpec with auth reconstructed from the checkpoint (sessionId + scope).
         const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        // E18: STRIP resumeAt before re-resolving on a durable resume — the leaf is already set by the checkpoint, and
+        // resumeAt + a durable resume is rejected by core (resume_at.conflicts_resume); also avoids re-resolving a stale
+        // anchor (which could 404 if the session was purged). A resume-at run that suspended stored its body with resumeAt.
+        // 对抗评审 2026-07-11(MED):resolveSpec re-runs the ADMISSION gates (scenario/execution ruling — resume does
+        // NOT freeze governance, the established precedent posture; a deny is ALSO a model run, so it is gated too). But an
+        // escaping HttpError here was (a) attributed to the OPERATOR's /decide request as a bare 400/403 — undiagnosable
+        // from that contract — and (b) swallowed by the D-D SLA deny-sweep's catch, silently failing EVERY tick. Fold it
+        // into a typed 409 result instead: the operator sees "this parked task is blocked by a policy change" (retry
+        // after the policy is restored, or let terminal_at abort it); the sweep skips the row this tick (retried next
+        // tick, terminal_at backstop — its documented per-call-failure semantics).
         let spec;
         try {
             spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
@@ -830,14 +1248,33 @@ export function createHttpServer(rawDeps) {
             }
             throw e;
         }
+        // Typed pre-check: the pending tool must still exist in the rebuilt config; a scenario
+        // redeploy that removed it means the approval can no longer be applied — fail clearly, never a 500/silent.
+        // The "hand" tools are NOT in spec.tools — core mounts them at the runner from the executionEnvFactory
+        // (core `HAND_TOOL_EFFECTS`, not re-exported from the package root → mirrored here). When this deployment
+        // has remote exec configured the rebuilt task WILL expose them, so union them in; else gating a hand tool
+        // (the common code-agent case) would always 422 on resume. Keep in sync with core's HAND_TOOL_EFFECTS.
+        // Q6 (core 1.161): canonicalize a PRE-Q6 persisted name (`bash`/`write_file`/…) to its CC-aligned new name
+        // BEFORE matching the rebuilt (post-Q6) tool set — else an in-flight checkpoint suspended before the upgrade
+        // would 422 here before core's own resume shim runs. New names map to themselves (idempotent).
         const pendingTool = cp.pendingAction.toolName;
         const pendingToolCanon = pendingTool ? canonicalToolName(pendingTool) : undefined;
         const availableTools = new Set((spec.tools ?? []).map((t) => t.name));
         if (deps.config.remoteExec)
             for (const name of HAND_TOOL_NAMES)
                 availableTools.add(name);
+        // AskUserQuestion (durable ask, TC-5.4) is ALSO not in spec.tools — core mounts it from `onQuestion`, which
+        // the durable path always sets (QUESTION_AWAITS_RESUME on suspend, the answer closure on resume). Without
+        // this it 422s on resume exactly like a hand tool would. Gated on checkpointStore = durable mode is active.
         if (deps.checkpointStore)
             availableTools.add("AskUserQuestion");
+        // Workflow (codex round-2 on [1245]/[1248]②): `run_workflow` is ALSO mounted at the runner, never in
+        // spec.tools — core mounts it when `spec.selfOrchestration === true` and the deployment wires the workflow
+        // deps (isSelfOrchestrationActive, dist-read). Without this, approving a durably-parked workflow ask
+        // (the new mode-derived leg) 422s here and the suspend can only ever be denied. Same over-approximation
+        // posture as the hand-tools union above (a per-principal allowWorkflows=false revoked between suspend and
+        // approve slips this pre-check; core's own resume path then fails loudly — the pre-check is a UX guard,
+        // not the authority).
         if (spec.selfOrchestration === true && deps.config.selfOrchestrationEnabled) {
             availableTools.add("Workflow");
         }
@@ -847,6 +1284,14 @@ export function createHttpServer(rawDeps) {
                 body: { error: `pending action no longer satisfiable: tool "${pendingToolCanon}" is not in the current task config (scenario changed since suspend)`, errorCode: "conflict.pending_action_unsatisfiable" },
             };
         }
+        // Durable-ask request/state coherence (TC-5.4), all pre-CAS so a mismatched request never consumes the
+        // checkpoint:
+        //  - approving a pending AskUserQuestion REQUIRES body.answer. Without it the resume re-mounts the
+        //    QUESTION_AWAITS_RESUME placeholder, the pending call executes against it and throws QuestionConfigError —
+        //    the operator's question is unrecoverably LOST (checkpoint consumed, no answer ever delivered). Fail the
+        //    request instead; the operator retries with the answer.
+        //  - an answer is only meaningful on an approve of a question gate; on a deny or a non-question gate it
+        //    signals the operator is deciding a different pending action than the one parked — reject, don't guess.
         if (decision === "approve" && pendingTool === "AskUserQuestion" && !answer) {
             return { status: 400, body: { error: "pending action is AskUserQuestion — approve must carry body.answer ({ answers: [{ header, selected: string[], note? }] })", errorCode: "request.field_conflict" } };
         }
@@ -854,8 +1299,18 @@ export function createHttpServer(rawDeps) {
             return { status: 400, body: { error: `body.answer is only valid when approving a pending AskUserQuestion (decision: "${decision}", pending: "${pendingTool ?? "unknown"}")`, errorCode: "request.field_conflict" } };
         }
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        // Durable ask (TC-5.4, core 1.95): the resume re-mounts AskUserQuestion with the operator's answer
+        // closure — the pending call executes against it and the model continues with "The user answered: …".
+        // This OVERRIDES the suspend-side QUESTION_AWAITS_RESUME placeholder resolveSpec just rebuilt. Absent
+        // answer ⇒ config unchanged (an F4 tool approval resumes exactly as before).
         if (answer)
             taskConfig.onQuestion = async () => answer;
+        // D-1 decision-action binding (core 1.101, design/80 §2): echo the boundCallId + boundInputHash the operator
+        // saw back into the outcome — core verifies opaque STRING equality against the persisted suspend-mint values
+        // (fail-closed, PRE-CAS), so "saw action A, resolve B" is rejected. boundInputHash is NEVER recomputed here
+        // (the engine minted it once via canonical-json; a second runtime re-serializing would false-mismatch and
+        // fail-closed reject a legit approval). Legacy callers that omit the fields fall back to the current persisted
+        // values (no human binding — pre-D-1 behavior). resource_limit pendings carry no action → empty (core gate_mismatch).
         const pa = cp.pendingAction;
         const persistedCallId = pa.kind === "tool_approval" ? pa.toolCallId : "";
         const persistedHash = pa.kind === "tool_approval" ? (pa.boundInputHash ?? "") : "";
@@ -867,16 +1322,46 @@ export function createHttpServer(rawDeps) {
             ...(decision === "approve" && binding?.updatedInput !== undefined ? { updatedInput: binding.updatedInput } : {}),
             ...(reason ? { reason } : {}),
         };
+        // Developer-mode verify (1.44) survives suspend/resume (core `resumeWithVerification`, design/51 P1-b): a
+        // task submitted with verify:true that hit an F4 gate must STILL be gated by the adversarial verifier on
+        // completion — a plain resumeStream would silently drop the gate. The flag rides in the persisted ctx.body
+        // (same source the spec was rebuilt from). Like first-run verify it's multi-attempt (not a live stream), so
+        // we await the result + write a single terminal event rather than streaming post-resume deltas.
         const verifyRounds = ctx.body.verify === true
             ? {
                 maxRounds: clampVerifyRounds(ctx.body.verifyRounds),
+                // 快审 F1:resume 腿同样带 cost 顶(persisted body 的 maxCostUsd 同源;cascade 腿同换算)
                 ...(typeof ctx.body.maxCostUsd === "number" && ctx.body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(ctx.body.maxCostUsd * 1e6) } : {}),
             }
             : undefined;
+        // taskId up-front: the resumed leg streams its post-resume events into the SAME durable run log, CONTINUING
+        // the seq past the suspend (core 1.70 `resumeStream`) — so GET /v1/runs/:id/events covers post-resume too,
+        // observability parity with runInBackground (closed by core 1.70).
+        // ── Drive the resume into the durable run log via the SHARED machinery (driveResumeIntoRunLog): markResuming
+        // CAS, the cancel + preempt controllers (same-replica fast path + cross-replica flag polls), the resume
+        // heartbeat, the resumeStream / resumeWithVerification loop, CheckpointError classification, re-suspend vs
+        // terminal drive. This HITL /decide path supplies a `policy_ask` outcome; the scheduler preempt path supplies
+        // a `resource_limit`/continue one — sharing this prevents the two resume entries from drifting.
         return driveResumeIntoRunLog({ token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, verifyRounds, ...(onResumeCommitted ? { onResumeCommitted } : {}) });
     }
+    /**
+     * The resume-drive machinery SHARED by `resumeCheckpoint` (operator /decide, `policy_ask`) and `resumePreempted`
+     * (scheduler resume, `resource_limit`/continue). Given the already-located `token`, the rebuilt
+     * `taskConfig`/`resumeObjective`, the gate-specific `outcome`, and optional `verifyRounds`, it: markResuming-
+     * CASes the parked row to `running` (idempotent across replicas), registers the leg in BOTH `inflightRuns`
+     * (cancel) and `preemptableRuns` (re-preempt) for the same-replica fast path, runs a heartbeat that polls the
+     * durable cancel + preempt flags (cross-replica), resumes via resumeStream / resumeWithVerification threading a
+     * FRESH cancel signal AND a FRESH preemptSignal (so a resumed leg is itself cancel-able + RE-preempt-able —
+     * never the consumed suspend-time signal), classifies a CheckpointError, handles a re-suspend
+     * (setSuspended, keep the lock) vs a terminal (setTerminal), and returns the HTTP {status, body}.
+     */
     async function driveResumeIntoRunLog(args) {
         const { token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds } = args;
+        // 🔴 复审 C2:lease admission for EVERY resume family (/decide, /answer, /plan_review, preempt-resume)
+        // funnels through here — keyed on `principal` = the CHECKPOINT OWNER, the SAME identity the resumed model spend
+        // is billed to via `withPrincipal(principal)` below. The route guards deliberately do NOT lease-gate (they'd
+        // key on the request principal = a possibly-cross-tenant operator). A live lease admits locally; center-judged
+        // exhaustion of the OWNER's budget returns 429 (mirroring leaseDenied's shape); an unreachable center fails open.
         if (deps.fleetLease && principal) {
             const adm = await deps.fleetLease.admit(principal);
             if (!adm.ok) {
@@ -885,22 +1370,48 @@ export function createHttpServer(rawDeps) {
             }
         }
         const taskId = await deps.runStore?.getActiveTaskId(sessionId);
+        // MF-Fleet (TOC review #7): a HITL resume (/decide, /answer, /plan_review, /preempt-resume, /wake) drives the
+        // SAME durable run row that suspended — so it must re-publish to the fleet bus under the SAME runId, or the run
+        // VANISHES from GET /v1/fleet/stream the moment it resumes (the original publisher's row was last touched at
+        // suspend; nothing keeps it live or settles it after). Reuse `taskId` (the existing suspended run id) so the row
+        // RE-APPEARS as the same fleet row; scope = `principal` (the checkpoint/run-owner scope persisted at suspend —
+        // the original submitter, NOT spoofable; matches the run row's owner). rootTaskId = sessionId: the resume's
+        // rebuilt taskConfig carries NO spec.taskId (resolveSpec omits it), so core's canonical taskId == sessionId,
+        // exactly like the sync leg. No-op when no fleetBus / no taskId.
+        // 🔒 scope = `fleetScope` (the VERIFIED `gatedPrincipal(req)` the calling route computed) — the SAME identity
+        // GET /v1/fleet/stream filters by, mirroring the create-path #6 fix. NOT `principal` (= the spoofable
+        // checkpoint/auth header from `principalFrom`): a spoofed header would re-publish the resumed row under a
+        // victim's scope (cross-tenant leak) or under "default" while the real owner's stream filters it OUT (the row
+        // vanishes on resume). Tenant-isolation parity with the stream filter on the direct resume door (TOC review #6).
+        // onForwardEvent parity: core 1.210 added the RunInternals 4th arg to `resumeStream` — the
+        // resume leg now feeds the forward sink like the sync/bg legs (fleet child rows at any depth + the durable
+        // task_progress append; see the resumeStream call in driveResume).
         const fleetPub = taskId && deps.fleetBus
             ? fleetRunPublisher(deps.fleetBus, { runId: taskId, scope: fleetScope, rootTaskId: sessionId, ...fleetRunLabels(resumeObjective) })
             : undefined;
+        // C (TOC adversarial review): settle the resumed fleet row EXACTLY once. A plain Error thrown out of the
+        // resume (not CheckpointError/cancel) hits the catch's `throw e` BEFORE the final onTerminal below → the
+        // re-published row leaks as a stale "running". Route every onTerminal through this guard so the finally can
+        // settle a row no branch reached, without double-settling one that did.
         let fleetSettled = false;
         const settleFleet = (status, residuals) => {
             if (fleetSettled)
                 return;
             fleetSettled = true;
-            fleetPub?.onTerminal(status, residuals);
+            fleetPub?.onTerminal(status, residuals); // [1839]①/(a):真终态帧带残局键(publisher 侧对 parked 再挡一层)
         };
         let result;
+        // [1245] codex-5: the resume.* code ALONE does not prove the reopen landed — installed core (1.330) only
+        // rewrites to checkpoint.reopen_failed when store.reopen returned FALSE; a THROWING reopen (plain DB error)
+        // keeps the resume.* code with the checkpoint still resolved. Confirm against the store before re-parking:
+        // this token pending again ⇒ real re-park; not pending ⇒ fall through to the terminal/done leg; probe error
+        // ⇒ re-park anyway (the safer side under uncertainty: a wrongly-suspended row is reaper-bounded
+        // (reapSuspended), a wrongly-terminal row orphans a live park until TTL — the round-3 bug shape).
         let reopenConfirmedPark = false;
         const confirmCheckpointReopened = async () => {
             const store = deps.checkpointStore;
             if (!store)
-                return true;
+                return true; // durable resume required the store; absence here = cannot confirm → the safer side
             try {
                 return (await store.findPendingTokenBySession(sessionId)) === token;
             }
@@ -908,22 +1419,52 @@ export function createHttpServer(rawDeps) {
                 return true;
             }
         };
+        // Protect the in-flight resume from the reaper: flip the parked row to `running` + heartbeat for the
+        // duration of the resume. The run row otherwise stays `suspended`/updated_at=suspend-time the whole time
+        // (resume neither rewrites the row nor heartbeats), so `reapSuspended` would mark a live resume `failed`
+        // and release its session lock once it crossed the approval TTL. Cleared in the finally below.
         let resumeHeartbeat;
-        let resumeManifestLease = 0;
+        let resumeManifestLease = 0; // [998]②: this leg's tracker lease (assigned at register, checked by the finally's clear)
+        // 1.78 (review LOW, pre-existing): THIS leg's live TaskStream — held so the finally can identity-guard its
+        // steerableRuns deregistration (an unconditional delete could clobber a handle a FASTER sibling leg just
+        // registered under the same taskId across a suspend→fast-resume).
         let resumeStreamRef;
-        let resumeLegLive = false;
+        let resumeLegLive = false; // true only while the resumed leg is live (set at resumeStream, cleared in the finally)
+        // design/122 ③: this leg's subagent-handle unregister thunks — run at leg end (finally), not on settle.
         const subagentHandleEvictions = [];
         let claimedRow = false;
+        // Cancel parity with runInBackground: the resumed leg is registered in `inflightRuns` (same-replica fast
+        // path) and its heartbeat polls the durable cancel flag (cross-replica) — without this a resumed run was
+        // un-cancellable (cancel 202'd + flagged the row, but nothing honored it). markResuming reset the flag,
+        // so only a cancel issued DURING this leg aborts it.
         const cancelCtrl = new AbortController();
+        // stoppedBy — resume leg NOW marked (core 1.256 delivered the mark-by-owner seam): on this
+        // leg core's canonical taskId == sessionId (the rebuilt taskConfig carries no spec.taskId), so a
+        // task-scoped child's owner KEY VALUE coincides with a session-scoped child's — the old `list()` path
+        // couldn't tell them apart (no sessionScoped flag exposed) and took an honest degrade. The seam filters
+        // by the EXPLICIT flag (`skipSessionScoped:true` inside the helper), so only task-scoped children take
+        // the "user" marker; session-scoped ones a cancelled parent deliberately does NOT stop stay unmarked
+        // (CC Backgrounded semantics). Owner = sessionId (this leg's canonical key), NOT the run-row taskId.
         markChildrenStoppedByUserOnAbort(cancelCtrl.signal, sessionId, principal);
+        // design/80 seam #2: a resumed leg is itself preempt-able. Register a FRESH preempt controller (markResuming
+        // also reset preempt_requested), thread a LIVE preemptSignal into the resume taskConfig below, and poll the
+        // durable preempt flag in the heartbeat — so the scheduler can preempt the RESUMED work once it makes
+        // progress. 🔴 Never re-supply the consumed suspend-time signal (core strips a pre-aborted one).
         const preemptCtrl = new AbortController();
         if (taskId && deps.runStore) {
+            // The CAS fails (false) only if the row is no longer `suspended` — the reaper already expired this
+            // approval (and released the session lock), the run is terminal, or a concurrent resume already claimed
+            // it. Bail rather than run a resume whose run row is gone / a sibling owns; the checkpoint reaper expires
+            // the token in the same tick so resumeStream would reject anyway. Closes the window the heartbeat can't.
             claimedRow = await deps.runStore.markResuming(taskId);
             if (!claimedRow)
                 return { status: 409, body: { error: "run is not in a resumable (suspended) state (already resumed, decided, or expired)", errorCode: "conflict.not_resumable" } };
+            // MF-Fleet (#7): the row is now `running` again → re-publish it LIVE to the fleet (re-appears as the same row
+            // that was sitting "waiting" while parked). After onStart only — never if markResuming lost the CAS (a sibling
+            // owns the row). onTerminal at every settle below keeps the row's lifecycle in lock-step with the run-store row.
             fleetPub?.onStart();
             const rs = deps.runStore;
-            const owner = principal ?? null;
+            const owner = principal ?? null; // the resumed run's owner (the original submitter) — single-DB null-safe guard
             inflightRuns.set(taskId, cancelCtrl);
             preemptableRuns.set(taskId, preemptCtrl);
             resumeHeartbeat = setInterval(() => {
@@ -938,75 +1479,137 @@ export function createHttpServer(rawDeps) {
                 }
             }, HEARTBEAT_MS);
             resumeHeartbeat.unref?.();
-            deps.modelUsage?.register(taskId);
-            resumeManifestLease = deps.promptManifests?.register(taskId) ?? 0;
+            deps.modelUsage?.register(taskId); // E8 leak fence: track the resumed leg's brain.calls (sub-tasks excluded); cleared in the finally
+            resumeManifestLease = deps.promptManifests?.register(taskId) ?? 0; // [998]②: the resumed prepare re-fires prompt.assembled — this leg drains its own manifest; lease guards the finally's clear (B-3 window)
         }
+        // codex M2 hook point: the CAS (when a run row exists) is decided above — a lost race already returned 409 and
+        // never reaches here. Awaited BEFORE the model drive so the resumed leg's first ask observes the side-effects.
         if (args.onResumeCommitted)
             await args.onResumeCommitted();
         try {
+            // Wrap in withPrincipal so the resumed leg's LLM spend is attributed to the tenant's CostQuota — parity
+            // with the sync/async paths (council: otherwise maxPrincipalCostUsd is silently bypassed on resume).
             result = await withPrincipal(principal, async () => {
+                // P1 ①② follow-on: drain the async-workflow completion inbox on the RESUME leg — hoisted
+                // ABOVE the verify/stream fork so BOTH resume flavors get it (parity with runs.ts, whose drain runs
+                // "before ANY branch"; review round 2 caught the verify-leg gap). A workflow that finished while this run
+                // sat suspended surfaces as a durable `workflow_complete` event the tailing client replays (at-least-once
+                // + shell runId-dedup). Owner gate = the original submitter (the checkpoint scope) — the identity the
+                // entries were stamped with at enqueue. 🔒 ONLY when a durable log exists (`deps.runStore && taskId`):
+                // without one there is nowhere to persist the frame, and `drain` REMOVES entries — draining there would
+                // EAT the completions. One-shot appender off maxSeq; each branch below re-reads maxSeq, so seq stays safe.
+                // option A: keys this leg already delivered (turn-open drain, loop case OR observer) — hoisted ABOVE the
+                // drain so the drained frames' keys register here too (core [784]④b: the same idle-arrival is also parked
+                // core-side; its pend-drain replay rides the resumed stream as a task_notification event — the loop's key
+                // check below folds that second durable append). codex F1: NotifiedKeys — the observer arm appends
+                // fire-and-forget, so claims carry the write's outcome promise (bg-leg twin's rationale).
                 const resumeNotifiedKeys = new NotifiedKeys();
                 if (deps.runStore && taskId) {
                     const rs0 = deps.runStore;
                     let drainSeq = (await rs0.maxSeq(taskId)) + 1;
                     await emitPendingWorkflowCompletions(deps.workflowCompletionInbox, sessionId, principal ?? null, (frame) => {
                         const { type, ...rest } = frame;
+                        // codex F1 + 修2(三路复审 notify-1):the claim must carry the WRITE OUTCOME, not a pre-resolved
+                        // true — a transient append failure with a `Promise.resolve(true)` claim would fake-suppress the
+                        // stream/core-side replay of the SAME key while the durable row never landed (the un-acked inbox
+                        // entry re-delivers next leg, but this leg's replay was eaten). Mirror of the bg-leg/runs.ts twin.
+                        // codex F2: task_type rides the key (external 帧独立键域 — bg twin's note).
                         const f = frame;
                         const write = rs0.appendEvent(taskId, drainSeq++, type, rest);
                         if (f.type === "task_notification" && f.task_id)
                             resumeNotifiedKeys.set(taskNotificationStreamKey({ task_type: f.task_type, task_id: f.task_id, status: String(f.status), seq: f.seq }), write.then(() => true, () => false));
                         return write;
-                    }, { route: "resume-open", connection: "durable-append", log: (m, x) => deps.logger?.info?.(m, x) });
+                    }, 
+                    // emit-target diagnostics — this drain appends to the resumed run's durable event log
+                    // (a tailing GET /v1/runs/:id/events client replays it; nothing is written to a live socket here).
+                    { route: "resume-open", connection: "durable-append", log: (m, x) => deps.logger?.info?.(m, x) });
                 }
+                // Verify task → resume AND re-gate (core resumeWithVerification): resume the impl, and if it COMPLETES
+                // run the identical adversarial verifier + fix loop; if it re-suspends it comes back failed-with-token
+                // (handled like any re-suspend below). 🔴 Freshness (BUG5, design/53 §2.B): we pass NO `evidence` diff,
+                // so the verifier judges the POST-resume working tree directly — there is no stale pre-suspend diff to
+                // grade, which closes the "approve then plant a backdoor" window by construction.
                 if (verifyRounds !== undefined) {
-                    const vr = await resumeWithVerification(deps.runner, token, outcome, { ...taskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds);
+                    // resumeWithVerification runs the SAME pre-CAS guard + atomic CAS as resume() internally, so a lost
+                    // CAS rejects with CheckpointError before any work — handled by the catch below, same as the stream path.
+                    const vr = await resumeWithVerification(deps.runner, token, outcome, { ...taskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds); // 快审 F1:整对象直传
                     let safe = stripCheckpointToken(vr);
+                    // 🔴 A re-suspend on a LATER gate is NOT terminal: core maps it to status:"failed" +
+                    // verification.unverifiedReason:"suspended" with the checkpoint token still live. Treat it exactly like
+                    // the stream path's suspended branch — write a "suspended" event and return status:"suspended" so the
+                    // outer block calls setSuspended (keeps the session lock + resumable row). Driving it terminal would
+                    // release the lock and orphan the second checkpoint (next /decide → 409, task abandoned).
                     const reSuspended = vr.verification?.unverifiedReason === "suspended";
+                    // [1245] codex-4: reopen-class twin of the stream path (store-confirmed, codex-5) — the checkpoint
+                    // is pending again, so the durable log must record a park, never `done` (the outer row drive
+                    // re-parks via checkpointReopened; the response keeps status:"failed"+retriable, unlike reSuspended
+                    // which surfaces "suspended").
                     const vrReopened = isCheckpointReopenedFailure(vr) && (await confirmCheckpointReopened());
                     if (vrReopened)
                         reopenConfirmedPark = true;
                     if (taskId && deps.runStore) {
                         const rs2 = deps.runStore;
+                        // codex-6/7 (vrReopened leg): EVERYTHING here is observability — best-effort once the reopen is
+                        // confirmed (maxSeq + manifest + usage + suspended event): a thrown append must not rethrow past
+                        // the authoritative row re-park below (stream twin). reSuspended-only keeps its fail-loud shape.
                         try {
                             let seq = (await rs2.maxSeq(taskId)) + 1;
                             const ap = (type, data) => rs2.appendEvent(taskId, seq++, type, data);
-                            await appendPromptManifest(ap, deps.promptManifests, taskId);
+                            await appendPromptManifest(ap, deps.promptManifests, taskId); // [998]②: the verified-resume leg has no stream — persist the re-fired manifest before its terminal/suspend event
                             if (reSuspended || vrReopened) {
-                                await appendModelUsageDelta(ap, deps.modelUsage, taskId);
+                                await appendModelUsageDelta(ap, deps.modelUsage, taskId); // E8: persist pre-re-suspend per-model usage
                                 await ap("suspended", { gate: vr.checkpointGate ?? null, ...(vrReopened ? { reopened: vr.errorCode ?? null } : {}) });
                             }
                             else {
+                                // E8: this verified-resume leg is the run's final done → flush the last delta + SUM model_usage into stats.modelUsage
                                 safe = await attachModelUsage(safe, { append: ap, getEvents: (id, a) => rs2.getEvents(id, a), modelUsage: deps.modelUsage, taskId });
-                                await ap("done", { result: safe });
+                                await ap("done", { result: safe }); // verify is not a live stream → one terminal event
                             }
                         }
                         catch (e) {
                             if (!vrReopened)
-                                throw e;
+                                throw e; // best-effort ONLY on the confirmed-reopen leg — see the boundary note above
                         }
                     }
                     if (reSuspended)
                         return { ...safe, status: "suspended" };
+                    // Count the gate verdict only when the verifier actually ran (a re-suspend never reached it).
                     if (vr.verification?.verdict)
                         deps.metrics?.inc("verifications_total", { verdict: vr.verification.verdict });
                     return safe;
                 }
+                // resumeStream runs the SAME pre-CAS guard + atomic CAS as resume(), then returns a live stream; a
+                // lost CAS rejects (CheckpointError) BEFORE any stream → never re-runs a resolved action.
+                // E23: core's resumeStream is EAGER (runtask.js:1710 — once it resolves the resumed run is already
+                // executing), so the per-run elicitation context MUST exist BEFORE the stream is created, or an inbound MCP
+                // elicitation early in the resumed leg finds no ALS store and fail-closed declines. Hoist the durable-append
+                // machinery, then create + drain the stream INSIDE runWithContext (emit = append → events tail). The owner is
+                // the ORIGINAL submitter (`principal` = the checkpoint scope), NOT the operator who /decided — they answer.
                 const rs = deps.runStore;
                 let seq = rs && taskId ? await rs.maxSeq(taskId) : 0;
                 let text = "";
                 let reasoning = "";
                 const persistThinking = deps.config.traceThinking;
                 const append = (type, data) => (rs && taskId ? rs.appendEvent(taskId, ++seq, type, data) : Promise.resolve());
+                // (resumeNotifiedKeys — this leg's delivered-notification keys — is hoisted above the inbox drain, see top)
+                // E18: anchor POST-resume turns too (a resumed conversation's new messages are rewindable). Same capture as
+                // runInBackground via the SHARED TurnAnchorCapture (only a settled assistant-text turn is anchored — see its
+                // doc). owner = the original submitter (the checkpoint scope), not the operator who /decided. undefined
+                // captureTurnAnchor ⇒ no anchor store / no getLeafId.
                 const anchorOwner = principal ?? null;
                 const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
                 const captureTurnAnchor = deps.resumeAnchorStore && getLeafId
                     ? async (eventId) => { const leaf = await getLeafId(sessionId); if (leaf)
                         await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner); }
                     : undefined;
+                // R8 (CC-parity rewind): USER-message anchor keyed by taskId (parity with the first-run path). A resume leg
+                // rarely commits a new user message, but wiring it is harmless (only `message_committed{role:"user"}` fires it).
                 const captureUserMessageAnchor = deps.resumeAnchorStore && taskId
                     ? async (entryId) => { await deps.resumeAnchorStore.put(sessionId, taskId, entryId, anchorOwner); }
                     : undefined;
                 const anchor = new TurnAnchorCapture(captureTurnAnchor, () => deps.metrics?.inc("resume_anchor_capture_failed"), captureUserMessageAnchor);
+                // Parity with runInBackground (src/runs.ts): the resume leg must capture thinking + per-turn usage too,
+                // else a suspend→resume loses them on post-resume turns. Reasoning flushed before content, redacted.
                 const flush = async () => {
                     if (reasoning) {
                         await append("reasoning", { text: redactSecrets(reasoning) });
@@ -1015,13 +1618,21 @@ export function createHttpServer(rawDeps) {
                     if (text) {
                         await append("text", { text, ...(anchor.firstTextEventId ? { eventId: anchor.firstTextEventId } : {}) });
                         text = "";
-                    }
+                    } // E18: per-message resume handle
                 };
                 const driveResume = async () => {
+                    // (the workflow-completion inbox drain for this leg is hoisted ABOVE the verify/stream fork — see top)
+                    // core 1.210: the resume leg now has the RunInternals seam — fan a subagent's task_progress
+                    // tick (child-isolated stream; the forward sink is its ONLY exit) out to the fleet AND the durable log
+                    // (shared whitelist+redact builder + E2 identity), parity with the sync/bg legs. Fire-and-forget append
+                    // (`++seq` is a sync increment — sink-vs-loop appends get unique seqs); only when a durable log exists.
+                    // false once this leg settles — notifications after that take the durable-inbox path.
                     resumeLegLive = true;
                     const stream = await deps.runner.resumeStream(token, outcome, { ...taskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, {
                         onForwardEvent: (e) => {
                             fleetPub?.onForwardEvent(e);
+                            // S2 live tail(复审 #1:forward sink 有三条腿——resume 腿上 spawn 的 bg 子代同样带
+                            // bgAgentId,漏挂=同副本开流只见 heartbeat)。publish 在 rs/taskId 门之前(tail 独立于账本)。
                             {
                                 const bg = e.bgAgentId;
                                 if (bg !== undefined && defaultSubagentTailBus.hasSubscribers(bg)) {
@@ -1037,31 +1648,47 @@ export function createHttpServer(rawDeps) {
                                 void append("task_progress", taskProgressEventData(e)).catch(() => undefined);
                             }
                             else if (t === "tool_start") {
+                                // C1 (core 1.219): a delegated child's forwarded tool lifecycle — durable via the SAME shared
+                                // whitelist+redact builders as the top stream (parity with the bg leg; deltas not persisted per-chunk).
                                 void append("tool_start", toolStartEventData(e)).catch(() => undefined);
                             }
                             else if (t === "tool_end") {
                                 void append("tool_end", toolEndEventData(e)).catch(() => undefined);
                             }
                         },
+                        // background-completion observer — flip the child's fleet row +
+                        // park an idle-arrival in the durable inbox (workflow-type skipped). Rationale in runs.ts (bg twin).
+                        // core 1.283 `seq` (per-stop-cycle counter) rides into the dedup key + parked entry — sync twin's note.
+                        // 白名单排查(2026-07-24,「彻查 as {} 连环坑」):手写窄类型换 core 真实类型,理由同 runs.ts twin。
                         onTaskNotification: (n) => {
                             if (n.task_type === "workflow")
                                 return;
+                            // S2 复审 #3(sync 腿同注):中途终态信号。
                             if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
                                 defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
                             }
+                            // id-domain alias: flip by payload.sessionId (= the tick's uuid domain), fallback task_id.
                             const hadRow = fleetPub?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false;
                             const parked = !resumeLegLive && Boolean(deps.workflowCompletionInbox && sessionId);
+                            // diagnosability (rationale in runs.ts twin).
                             deps.logger?.info?.("task_notification_observed", { route: "resume", taskId: n.task_id, taskType: n.task_type, status: n.status, hadFleetRow: hadRow, legLive: resumeLegLive, parkedDurable: parked });
                             if (parked) {
+                                // 对抗评审 2026-07-11(MED):log the enqueue failure (false park✓ fingerprint otherwise; sync twin's note).
                                 void deps.workflowCompletionInbox.enqueue(taskNotificationInboxEntry(sessionId, principal ?? null, n, Date.now(), taskId)).catch((err) => deps.logger?.warn?.("park_enqueue_failed", { route: "resume", taskId: n.task_id, err: err instanceof Error ? err.message : String(err) }));
                             }
                             else if (resumeLegLive) {
+                                // option A: teardown-time reap notification → durable display frame NOW (bg-leg twin's note).
+                                // core [784]④a: seq-folded shared key — the seq-less shape reverse-swallowed cycle 2's frame.
+                                // codex F1 (HIGH): fire-and-forget append — claim the key with its REAL outcome so a failed
+                                // write doesn't eat the stream replay of the same key (bg twin's note).
                                 const key = taskNotificationStreamKey(n);
                                 if (resumeNotifiedKeys.get(key) === undefined) {
                                     resumeNotifiedKeys.set(key, append("task_notification", taskNotificationEventData({ notification: n })).then(() => true, () => false));
                                 }
                             }
                         },
+                        // C2 (core 1.219) + design/122 (core 1.225 ③): the resumed leg re-registers sync-delegation steer
+                        // handles under the SAME taskId. NOT evicted on settle (resume legality) — evicted at leg end.
                         ...(deps.subagentSteerRegistry && taskId
                             ? {
                                 onSubagentSpawn: (handle) => {
@@ -1072,17 +1699,17 @@ export function createHttpServer(rawDeps) {
                     });
                     resumeStreamRef = stream;
                     if (taskId)
-                        steerableRuns.set(taskId, stream);
+                        steerableRuns.set(taskId, stream); // the resumed leg is in-flight again → live-steerable (parity with the first-run plain-stream path; taskId-guarded like the finally)
                     if (!taskId || !rs)
-                        return await stream.result();
+                        return await stream.result(); // no durable log to persist into → just drain
                     for await (const ev of stream) {
-                        fleetPub?.onEvent(ev);
-                        await appendPromptManifest(append, deps.promptManifests, taskId);
+                        fleetPub?.onEvent(ev); // MF-Fleet (#7): turn_end → tokens, tool_start → live activity, in-stream task_progress → child row (parity with the sync leg's onEvent)
+                        await appendPromptManifest(append, deps.promptManifests, taskId); // [998]②: the resumed prepare's manifest lands ahead of its first event (runs.ts twin)
                         switch (ev.type) {
                             case "text_delta":
                                 text += ev.delta;
                                 anchor.onText(ev.eventId);
-                                break;
+                                break; // E18: latch first-text eventId = message handle
                             case "reasoning_delta":
                                 if (persistThinking)
                                     reasoning += ev.delta;
@@ -1091,7 +1718,7 @@ export function createHttpServer(rawDeps) {
                                 anchor.onTool();
                                 await flush();
                                 await append("tool_start", toolStartEventData(ev));
-                                break;
+                                break; // E18: tool ran → not anchorable
                             case "tool_end":
                                 await flush();
                                 await append("tool_end", toolEndEventData(ev));
@@ -1102,57 +1729,65 @@ export function createHttpServer(rawDeps) {
                                 await flush();
                                 await append("status", brainStatusEventData(st));
                                 break;
-                            }
+                            } // S4 P0-a: durable brain-liveness observation (rationale in runs.ts twin — flush first so a mid-text reconnect doesn't invert the timeline); design/158 B2: row type aligned to the live frame name ("status", was "brain_status" — ledger-sink.ts twin's note has the full rationale + compat contract); 白名单排查 2026-07-24: 手写字面量换 Parameters<> 防未来漂移
                             case "context_usage":
                                 await flush();
                                 await append("context_usage", contextUsageEventData(ev));
-                                break;
+                                break; /* core 1.414 一等分支;两条口径见 builder 旁注 */
                             case "compacted":
                                 await flush();
                                 await append("compacted", compactedEventData(ev));
-                                break;
+                                break; // MF-18 trigger + core 1.219 attachedFiles/preserved_segment (shared whitelist builder)
                             case "diagnostics":
                                 await flush();
                                 await append("diagnostics", diagnosticsEventData(ev));
-                                break;
+                                break; // core 1.220 design/121: NEW LSP diagnostics (shared whitelist builder, §E1 redact)
                             case "steering_injected":
                                 await flush();
                                 await append("steering_injected", steeringInjectedEventData(ev));
-                                break;
+                                break; // [1550]/[1552]: shared whitelist builder, §E1 redact — resume twin of the sync + ledger-sink legs
                             case "workspace_changed":
                                 await flush();
                                 await append("workspace_changed", workspaceChangedEventData(ev));
-                                break;
+                                break; // [1559]二: cwd move (bash cd/EnterWorktree) — shared whitelist builder, §E1 redact — resume twin of the sync + ledger-sink legs
                             case "message_committed":
                                 await anchor.onMessageCommitted(ev.role, ev.entryId);
-                                break;
+                                break; // R8: USER-message rewind anchor (CC "rewind to the prompt")
                             case "task_progress":
                                 await append("task_progress", taskProgressEventData(ev));
-                                break;
+                                break; // shared whitelist+redact builder (+E2 identity, 1.78) — parity with the runs.ts + sync legs
                             case "task_notification": {
                                 await flush();
+                                // core [784]④a+④b: seq-folded shared key + skip keys this leg already delivered (turn-open inbox
+                                // drain or observer arm) — core's pend-drain replays a double-parked idle arrival as a stream event
+                                // on the resumed leg; appending it again doubles the frame in the durable events tail (sync twin).
+                                // codex F1: await the claiming write's outcome — a failed observer claim must not eat this
+                                // replay (write anyway + promote the key with THIS write's outcome; bg twin's note).
                                 const tnr = ev.notification;
                                 const tnrKey = tnr?.task_id ? taskNotificationStreamKey({ task_type: tnr.task_type, task_id: tnr.task_id, status: String(tnr.status), seq: tnr.seq }) : undefined;
                                 const tnrPrior = tnrKey !== undefined ? resumeNotifiedKeys.get(tnrKey) : undefined;
                                 if (tnrPrior === undefined || !(await tnrPrior)) {
-                                    const write = append("task_notification", taskNotificationEventData(ev));
+                                    const write = append("task_notification", taskNotificationEventData(ev)); // core 1.202 design/115 P2: display projection (shared whitelist+redact builder — parity with the runs.ts + sync legs)
                                     if (tnrKey !== undefined)
-                                        resumeNotifiedKeys.set(tnrKey, write.then(() => true, () => false));
+                                        resumeNotifiedKeys.set(tnrKey, write.then(() => true, () => false)); // stream delivered this key
                                     await write;
                                 }
                                 break;
                             }
                             case "turn_end": {
                                 await flush();
-                                await append("turn_end", turnEndEventData(ev));
+                                await append("turn_end", turnEndEventData(ev)); /* 白名单 builder:此前手写 {usage},剥掉了 stopReason/usageMissing */
                                 await appendModelUsageDelta(append, deps.modelUsage, taskId);
                                 await anchor.onTurnEnd();
                                 break;
-                            }
+                            } // E18: anchor a settled assistant-text turn only
+                            // "done" handled below via result() + the run-row drive (terminal event written once)
                         }
                     }
                     await flush();
                     const r = await stream.result();
+                    // Close the durable stream with the matching terminal event (mirrors runInBackground). Never the
+                    // capability token — only the non-secret gate on a re-suspend.
                     if (r.status === "suspended") {
                         await append("suspended", { gate: r.checkpointGate ?? null });
                         await appendModelUsageDelta(append, deps.modelUsage, taskId);
@@ -1162,19 +1797,34 @@ export function createHttpServer(rawDeps) {
                         await append("needs_review", { gate: r.checkpointGate ?? null });
                         await appendModelUsageDelta(append, deps.modelUsage, taskId);
                         return r;
-                    }
+                    } // D-B: a resumed plan_review re-gated to another review pause
+                    // [1245] codex-4: a CONFIRMED reopen-class failure (core reopened the checkpoint — store-verified,
+                    // codex-5) is NOT terminal: logging `done` here would make the append-only log say terminal while
+                    // the park stays decidable (trace projection + events tailers treat `done` as final and would miss
+                    // the retry). Log the park, keep E8's terminal usage-SUM reserved for genuinely terminal results
+                    // (`checkpoint.reopen_failed` and an unconfirmed reopen stay on the done leg).
                     if (isCheckpointReopenedFailure(r) && (await confirmCheckpointReopened())) {
                         reopenConfirmedPark = true;
+                        // codex-6: best-effort — the ROW re-park below is the authority once the reopen is confirmed. A
+                        // thrown append here would otherwise rethrow past the row drive and strand a `running` row (no
+                        // heartbeat) over a pending park until reapStale; a missing suspended event is merely a log gap
+                        // (nothing terminal was written — tailers keep waiting), strictly recoverable.
                         try {
                             await append("suspended", { gate: null, reopened: r.errorCode ?? null });
                             await appendModelUsageDelta(append, deps.modelUsage, taskId);
                         }
                         catch {
+                            /* row drive is authoritative */
                         }
                         return r;
                     }
-                    const safe = await attachModelUsage(stripCheckpointToken(r), { append, getEvents: (id, a) => rs.getEvents(id, a), modelUsage: deps.modelUsage, taskId });
+                    // E8: terminal — this resumed leg is the run's final done, so flush the last delta + SUM model_usage across
+                    // ALL legs (pre-suspend + post-resume) into stats.modelUsage. setTerminal (below, ~2619) stores this result.
+                    const safe = await attachModelUsage(stripCheckpointToken(r), { append, getEvents: (id, a) => rs.getEvents(id, a), modelUsage: deps.modelUsage, taskId }); // structural fence (strip no-op today)
                     await append("done", { result: safe });
+                    // E12 (shell-host contract): a resumed leg that COMPLETES can also emit post-completion suggestions (parity with the
+                    // first-run path + the completed-only gate). suspended/needs_review returned above; a failed leg is
+                    // skipped here. Redact + persist as a `suggestions` event (UNTRUSTED UI-only, never re-fed to a model).
                     if (taskConfig.suggestNextPrompts && safe.status === "completed") {
                         const suggestions = await stream.suggestions().catch(() => []);
                         if (suggestions.length)
@@ -1189,21 +1839,32 @@ export function createHttpServer(rawDeps) {
         }
         catch (e) {
             if (e instanceof CheckpointError) {
+                // We flipped the row to `running` (claimedRow). Two CheckpointError classes diverge here (D-1, core 1.101):
+                //  • TERMINAL (already_resolved / not_found / gate_mismatch / unsupported_version): the checkpoint is
+                //    consumed or gone — drive the row terminal now (releasing task_active) instead of leaving a zombie
+                //    `running` row for reapStale to mislabel and hold the session lock for ~runStaleSec. (Original case.)
+                //  • RETRIABLE PRE-CAS (invalid_outcome = binding mismatch / reopen_revote = env_failed must replay the
+                //    persisted winner / reopened_concurrently = a concurrent resolve-reopen advanced the rev): the
+                //    checkpoint STAYS pending and the operator re-fetches + re-/decides. Driving the row terminal would
+                //    release task_active and ORPHAN the still-pending checkpoint (next /decide → 404). Re-park it
+                //    `suspended` so the corrected retry can claim it again.
                 const retriable = e.code === "checkpoint.invalid_outcome" ||
                     e.code === "checkpoint.reopen_revote" ||
                     e.code === "checkpoint.reopened_concurrently" ||
-                    e.code === "resume.parent_constraint_missing" ||
-                    e.code === "resume.parent_constraint_mismatch" ||
-                    e.code.startsWith("wake.");
+                    e.code === "resume.parent_constraint_missing" || // 历史复审轴A #4(1.254):core 新增两码同为
+                    e.code === "resume.parent_constraint_mismatch" || // PRE-CAS(checkpoint 保持 pending)——按本块 doctrine 归 retriable;当前 /decide 面只 resume 顶层 checkpoint 应不可达,前瞻补齐防嵌套 resume 面开放时踩中
+                    e.code.startsWith("wake."); // design/144:wake 拒绝(gate_pending/nothing_to_deliver)全是 PRE-CAS,checkpoint 保持 pending——驱 terminal 会孤儿化仍在等的 park
                 if (claimedRow && taskId && deps.runStore) {
+                    // Re-park on the SAME gate family the outcome targeted: a plan_review retry must re-park `needs_review`
+                    // (keep the row's review status + the lock), not `suspended` — else GET /v1/assistant/tasks mislabels it.
                     if (retriable) {
                         await (outcome.gate === "plan_review" ? deps.runStore.setNeedsReview(taskId) : deps.runStore.setSuspended(taskId)).catch(() => undefined);
                         settleFleet(outcome.gate === "plan_review" ? "needs_review" : "suspended");
-                    }
+                    } // MF-Fleet (#7): re-park keeps the row
                     else {
                         await deps.runStore.setTerminal(taskId, "failed", null, e.message).catch(() => undefined);
                         settleFleet("failed");
-                    }
+                    } // MF-Fleet (#7): terminal removes the row
                 }
                 const status = e.code === "checkpoint.not_found" ? 404 : 409;
                 return {
@@ -1211,6 +1872,12 @@ export function createHttpServer(rawDeps) {
                     body: {
                         error: e.message,
                         code: e.code,
+                        // invalid_outcome means DIFFERENT things per gate: for policy_ask it IS the D-1 action-binding
+                        // mismatch; for plan_review/dry_run_review it is a content-sanitize reject (editedPlan/reason carried a
+                        // forbidden tag) — give those a gate-appropriate code so the UI routes to the right recovery, not the
+                        // action-binding flow (adversarial-review medium finding).
+                        // 归一(clay 大改版窗 2026-07-28):errorCode **恒在**——改铸臂保持优先,其余=原码镜像
+                        // (「code 单轨」历史形从此退役;SDK 的 ?? b.code 兜底只为老 server 保留)。
                         errorCode: e.code === "checkpoint.invalid_outcome"
                             ? (outcome.gate === "policy_ask" ? "approval_binding_mismatch" : "resume_outcome_invalid")
                             : e.code,
@@ -1218,55 +1885,93 @@ export function createHttpServer(rawDeps) {
                     },
                 };
             }
+            // Cancelled mid-resume (the abort threw out of the resumed stream): settle the row to the cancelled
+            // terminal (parity with runInBackground) instead of bubbling a 500 that leaves a zombie `running` row
+            // for the reaper. The operator's /decide gets the run's final state, not an opaque error. (A preempt mid-
+            // resume is NOT an abort — it durably suspends and surfaces above as status:"suspended", not here.)
             if (cancelCtrl.signal.aborted) {
                 if (taskId && deps.runStore) {
                     const c = { taskId, sessionId, status: "failed", errorCode: "cancelled", errorMessage: "cancelled by user", stats: { turns: 0, tokens: 0 } };
                     await deps.runStore.setTerminal(taskId, "failed", c, c.errorMessage ?? null).catch(() => undefined);
                 }
-                settleFleet("failed");
+                settleFleet("failed"); // MF-Fleet (#7): a cancel mid-resume settles the row terminal → removed from the fleet
                 return { status: 200, body: { taskId, sessionId, status: "failed", errorCode: "cancelled" } };
             }
+            // C: a plain Error (not CheckpointError, not a cancel) is about to propagate before the post-catch
+            // `settleFleet(result.status)` can run → settle the re-published row to "failed" first so it doesn't leak
+            // as a stale "running" (no-op if a CheckpointError/cancel branch above already settled it).
             settleFleet("failed");
             throw e;
         }
         finally {
             if (taskId) {
+                // [1.207 codex H3] identity-guarded like steerableRuns below — a retriable-CheckpointError re-park
+                // (setSuspended) opens a window where a fast sibling resume markResuming's + registers its OWN
+                // controllers under the same taskId before this finally runs; an unconditional delete killed the
+                // fresh handles (cancel/preempt would 409 "another replica" until re-registration).
                 if (inflightRuns.get(taskId) === cancelCtrl)
                     inflightRuns.delete(taskId);
                 if (preemptableRuns.get(taskId) === preemptCtrl)
                     preemptableRuns.delete(taskId);
+                // Identity-guarded (1.78 review LOW): only delete the handle THIS leg registered (and only if it is
+                // still ours) — a faster sibling resume may have re-registered the same taskId already; never registered
+                // ⇒ nothing of ours to delete.
                 if (resumeStreamRef !== undefined && steerableRuns.get(taskId) === resumeStreamRef)
                     steerableRuns.delete(taskId);
                 for (const evict of subagentHandleEvictions)
-                    evict();
-                deps.modelUsage?.clear(taskId);
-                deps.promptManifests?.clear(taskId, resumeManifestLease);
+                    evict(); // design/122 ③: leg-end handle eviction (identity-guarded)
+                deps.modelUsage?.clear(taskId); // E8: parity with runInBackground's finally — unregister + drop any un-drained accumulation (no leak / no cross-resume contamination)
+                deps.promptManifests?.clear(taskId, resumeManifestLease); // [998]②: lease-guarded (a fast sibling's fresh registration survives our teardown)
             }
             if (resumeHeartbeat)
                 clearInterval(resumeHeartbeat);
-            resumeLegLive = false;
+            resumeLegLive = false; // notifications from here on take the durable-inbox path
         }
+        // A session-CAS conflict can surface as a failed result on resume too — evict the stale warm-cache entry so
+        // the next task on this session re-wakes from TiDB instead of re-conflicting (parity with runInBackground /
+        // sync POST / cascade; the only terminal-result path that was missing this — council).
         evictIfConflict(deps.runner, sessionId, result);
-        const checkpointReopened = reopenConfirmedPark;
+        // [1245] codex-3: the two REOPEN-class resume failures (`resume.env_failed` / `resume.tool_unavailable` —
+        // core dist-read: runtask reopens the checkpoint via store.reopen BEFORE returning this failed result; a
+        // reopen that itself fails surfaces as `checkpoint.reopen_failed`, NOT these codes) leave the checkpoint
+        // PENDING. Driving the row terminal here would release task_active and orphan the still-decidable park
+        // (the exact class the CheckpointError `retriable` branch above re-parks) — e.g. Workflow entitlement
+        // revoked between suspend and approve. Re-park `suspended` so the operator's retry can claim it again.
+        const checkpointReopened = reopenConfirmedPark; // codex-5: store-confirmed inside the resume paths — never inferred from the code alone
+        // Drive the parked run row to its new state (terminal, or re-suspended on a further gate). Strip the token
+        // from the persisted result — structural fence (no-op today; GET /v1/runs/:id reads this row back).
         if (taskId && deps.runStore) {
             if (result.status === "suspended" || checkpointReopened)
                 await deps.runStore.setSuspended(taskId);
             else if (result.status === "needs_review")
-                await deps.runStore.setNeedsReview(taskId);
+                await deps.runStore.setNeedsReview(taskId); // D-B: a resumed leg re-gated to a review pause — re-park, keep the lock
             else
                 await deps.runStore.setTerminal(taskId, result.status, stripCheckpointToken(result), result.errorMessage ?? null);
         }
-        settleFleet(checkpointReopened ? "suspended" : result.status, fleetRunResiduals(result));
+        // MF-Fleet (#7): settle the fleet row in lock-step with the run row — suspended/needs_review KEEP the row (it stays
+        // "waiting"/"awaiting approval"); a terminal status REMOVES it (onTerminal does this mapping). Mirrors the sync leg.
+        settleFleet(checkpointReopened ? "suspended" : result.status, fleetRunResiduals(result)); // [1839]①/(a):终态残局键(parked 时 publisher 不上帧)
+        // Surface the failure code/message to the deciding operator (never the token): a resumed leg that fails
+        // otherwise returns an opaque {status:"failed"} — undiagnosable without a run row (leader sub-workers).
         return {
             status: 200,
             body: {
                 taskId, sessionId, status: result.status,
                 ...(result.errorCode ? { errorCode: result.errorCode } : {}),
                 ...(result.errorMessage ? { errorMessage: redactSecrets(result.errorMessage) } : {}),
-                ...(checkpointReopened ? { retriable: true } : {}),
+                ...(checkpointReopened ? { retriable: true } : {}), // the park is still pending — re-fetch + re-decide
             },
         };
     }
+    /**
+     * design/80 seam #2 (scheduler resume): resume a task that durably SUSPENDED on a `resource_limit` gate — a
+     * scheduler PREEMPT (reason "preempt") or a budget/turns/walltime slice boundary (design/74). Distinct from the
+     * operator `/decide` path (`resumeCheckpoint`, `policy_ask`): there is NO human decision, NO binding, NO answer
+     * — just `{gate:"resource_limit", decision:"continue"}` (core computes the next slice's allowance from the
+     * ledger). 🔴 GATE-KIND GUARD: it REFUSES to resume a `policy_ask`/human gate via this path (that would bypass
+     * the human approval) — a non-resource gate returns 409 and must go through `/decide`. Owner-scoped by the
+     * caller; `scope` is the checkpoint's own (multi-tenant). Returns the HTTP {status, body}.
+     */
     async function resumePreempted(sessionId, req) {
         const cs = deps.checkpointStore;
         const token = await cs.findPendingTokenBySession(sessionId);
@@ -1274,13 +1979,18 @@ export function createHttpServer(rawDeps) {
             return { status: 404, body: { error: "no resumable suspension for this task (already running, resumed, or expired)", errorCode: "not_found.suspension" } };
         let cp;
         try {
-            cp = await cs.get(token);
+            cp = await cs.get(token); // throws if the checkpoint format is newer than this build (version guard)
         }
         catch (e) {
             return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
         }
         if (!cp)
             return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        // 🔴 GATE-KIND GUARD (security): this "continue" path must ONLY advance a resource_limit suspend. A
+        // policy_ask / human / irreversible_ask gate requires a HUMAN decision via POST /v1/approvals/:id/decide —
+        // resuming it here with decision:"continue" would BYPASS the approval. Reject it distinctly (core's resume
+        // gate-match is the fail-closed backstop, but we reject pre-CAS for a clear error + to never consume the
+        // checkpoint). dry_run_review / plan_review likewise are not "continue"-resumable here.
         const gateKind = cp.gate?.kind;
         if (gateKind !== "resource_limit") {
             return { status: 409, body: { error: `task is suspended on a '${gateKind ?? "unknown"}' gate, not a resumable resource/preempt suspension — an approval gate must be decided via POST /v1/approvals/:id/decide`, errorCode: "gate_not_resumable" } };
@@ -1288,27 +1998,38 @@ export function createHttpServer(rawDeps) {
         const ctx = await cs.getCtx(sessionId).catch(() => null);
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        // Rebuild taskConfig via resolveSpec with auth reconstructed from the checkpoint scope (mirrors resumeCheckpoint).
         const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        // E18: STRIP resumeAt before re-resolving on a durable resume — the leaf is already set by the checkpoint, and
+        // resumeAt + a durable resume is rejected by core (resume_at.conflicts_resume); also avoids re-resolving a stale
+        // anchor (which could 404 if the session was purged). A resume-at run that suspended stored its body with resumeAt.
         const spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        // A resource-suspended task that was submitted with verify:true is re-gated on completion (parity with the
+        // HITL path — the flag rides the persisted ctx.body).
         const verifyRounds = ctx.body.verify === true
             ? {
                 maxRounds: clampVerifyRounds(ctx.body.verifyRounds),
+                // 快审 F1:resume 腿同样带 cost 顶(persisted body 的 maxCostUsd 同源;cascade 腿同换算)
                 ...(typeof ctx.body.maxCostUsd === "number" && ctx.body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(ctx.body.maxCostUsd * 1e6) } : {}),
             }
             : undefined;
         return driveResumeIntoRunLog({ token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, verifyRounds });
     }
+    /** design/144 §3:wake 一个 task_done 纯 park——非门决策,解除 park 消费消息续跑。owner 门:非 operator
+     *  只能 wake 自己 scope 的 park(404 无 oracle);core 端 gate_pending/nothing_to_deliver 双拒兜底。 */
     async function resumeWake(sessionId, message, caller, req) {
         const cs = deps.checkpointStore;
         const token = await cs.findPendingTokenBySession(sessionId);
         if (!token)
             return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+        // owner 门先于 get(复审 finding:get 对损坏/新版行会抛,若 gate 在后,非 owner 能用 409 错误详情
+        // 区分「存在但坏」vs「不存在」= 存在性 oracle)。scope 走 peekPendingScope(轻读,不碰行体)。
         const operator = explicitOperatorOk(caller, deps.config.operatorPrincipals);
         if (!operator) {
             const scope = await cs.peekPendingScope(sessionId).catch(() => undefined);
             if (scope !== null && scope !== undefined && scope !== "_" && scope !== caller) {
-                return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+                return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } }; // 无 oracle
             }
         }
         let cp;
@@ -1321,13 +2042,14 @@ export function createHttpServer(rawDeps) {
         if (!cp)
             return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
         if (!operator && cp.scope !== "_" && cp.scope !== caller) {
-            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } }; // 纵深(peek 缺席面兜底)
         }
+        // 预检(core 兜底同码):非纯 park = 有未决门,wake 永不绕审批。
         const gateKind = cp.gate?.kind;
         if (gateKind !== "task_done") {
             return { status: 409, body: { error: `cannot wake: this checkpoint awaits a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry`, errorCode: "wake.gate_pending" } };
         }
-        const trusted = operator;
+        const trusted = operator; // steer 同款:operator 消息可携 <system-reminder> 权威
         if (message !== undefined) {
             try {
                 validatePendingSteer({ text: message, trusted });
@@ -1353,9 +2075,18 @@ export function createHttpServer(rawDeps) {
             taskConfig,
             resumeObjective,
             outcome: { gate: "wake", ...(message !== undefined ? { message: { text: message, trusted } } : {}) },
-            verifyRounds: undefined,
+            verifyRounds: undefined, // wake 续跑不重开 verify 门(原任务已终局;新工作要 verify 走新 run)
         });
     }
+    /**
+     * design/80 D-B: resolve a PRE-ACTION `plan_review` gate (3-state approve | edit | reject) and drive the resumed
+     * leg into the durable run log via the SHARED machinery. DISTINCT from `resumeCheckpoint` (a `policy_ask` tool
+     * approval, allow/deny + binding) and `resumePreempted` (`resource_limit` continue). The `edit` decision carries
+     * the operator's REVISED plan (core threads `editedPlan` into the resumed run). 🔴 GATE-KIND GUARD (security):
+     * refuses any non-`plan_review` gate — an approve/edit/reject must NEVER resolve a tool-approval / resource_limit
+     * suspend (that would bypass the correct /decide allow-deny + action binding). Rejects PRE-CAS so a wrong-gate
+     * call never consumes the checkpoint (core's resume gate-match is the fail-closed backstop).
+     */
     async function resumePlanReview(sessionId, decision, editedPlan, reason, req) {
         const cs = deps.checkpointStore;
         const token = await cs.findPendingTokenBySession(sessionId);
@@ -1363,13 +2094,16 @@ export function createHttpServer(rawDeps) {
             return { status: 404, body: { error: "no pending plan_review for this session (already decided or expired)", errorCode: "not_found.plan_review" } };
         let cp;
         try {
-            cp = await cs.get(token);
+            cp = await cs.get(token); // throws if the checkpoint format is newer than this build (version guard)
         }
         catch (e) {
             return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
         }
         if (!cp)
             return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        // 🔴 GATE-KIND GUARD: a plan_review decision must ONLY resolve a plan_review gate. A human/irreversible_ask
+        // (tool approval) or resource_limit/needs_review gate routed here would let approve/edit/reject bypass the
+        // correct wire (a tool approval needs /decide's allow/deny + action binding; resource_limit needs /resume).
         const gateKind = cp.gate?.kind;
         if (gateKind !== "plan_review") {
             return {
@@ -1383,12 +2117,19 @@ export function createHttpServer(rawDeps) {
         const ctx = await cs.getCtx(sessionId).catch(() => null);
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        // Rebuild taskConfig via resolveSpec with auth reconstructed from the checkpoint scope (mirrors resumeCheckpoint).
         const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        // E18: STRIP resumeAt before re-resolving on a durable resume — the leaf is already set by the checkpoint, and
+        // resumeAt + a durable resume is rejected by core (resume_at.conflicts_resume); also avoids re-resolving a stale
+        // anchor (which could 404 if the session was purged). A resume-at run that suspended stored its body with resumeAt.
         const spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        // A plan_review-suspended task submitted with verify:true is re-gated on completion (parity with the other
+        // resume paths — the flag rides the persisted ctx.body).
         const verifyRounds = ctx.body.verify === true
             ? {
                 maxRounds: clampVerifyRounds(ctx.body.verifyRounds),
+                // 快审 F1:resume 腿同样带 cost 顶(persisted body 的 maxCostUsd 同源;cascade 腿同换算)
                 ...(typeof ctx.body.maxCostUsd === "number" && ctx.body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(ctx.body.maxCostUsd * 1e6) } : {}),
             }
             : undefined;
@@ -1406,26 +2147,39 @@ export function createHttpServer(rawDeps) {
             deps.metrics?.inc("task_tokens_total", {}, result.stats.tokens);
         if (result.stats.cacheHitRate !== undefined)
             deps.metrics?.observe("task_cache_hit_rate", result.stats.cacheHitRate);
+        // ⑤ budget/limit cutoffs (1.37): count failures by their dotted code (budget.precall/exceeded,
+        // limit.timeout/max_turns) so an operator can alert on tenants hitting the cost/token ceiling.
         const code = result.errorCode;
         if (code && (code.startsWith("budget.") || code.startsWith("limit."))) {
             deps.metrics?.inc("budget_exceeded_total", { code });
         }
+        // Developer-mode verification gate (1.44): count the final verdict when this task was verified.
         const verdict = result.verification?.verdict;
         if (verdict)
             deps.metrics?.inc("verifications_total", { verdict });
+        // Cascade (1.45): count the outcome (passed / exhausted) when this task ran the ladder.
         const cascadeOutcome = result.cascadeOutcome;
         if (cascadeOutcome)
             deps.metrics?.inc("cascade_total", { outcome: cascadeOutcome });
+        // Degenerate-repetition salvage classifier (1.59): a/b/unknown — see degenerate-instrument.ts.
         deps.instrumentDegenerate?.(result);
     }
+    /** The terminal-result side-effect trio (metrics, plan-cache recurrence probe, warm-cache eviction) in ONE
+     *  place so a terminal path can't silently omit one (council DESIGN-6 — the omissions caused tracking gaps). */
     function finalizeTaskResult(result, principal, objective, sessionId) {
         recordTaskResult(result);
         deps.planCacheProbe?.record(principal, objective, result.status === "completed");
         evictIfConflict(deps.runner, sessionId, result);
     }
+    /** Per-principal cumulative cost quota: 429 + retry-after when the principal is over for the window.
+     *  No principal → not gated (the rate limiter + REQUIRE_PRINCIPAL still apply). */
     function quotaExceeded(req, res) {
         if (!deps.costQuota)
             return false;
+        // 🔴 F-fix: the VERIFIED principal (gatedPrincipal), never the spoofable header. Spend ACCRUES to the verified
+        // principal (budget.ts `costQuota.add(currentPrincipal())` = auth.principal), so checking a header-keyed bucket
+        // while the verified bucket fills would let a direct-door caller dodge its quota by rotating x-agent-principal.
+        // The sibling rateLimited keys on the socket on a direct door for the same reason — this was its overlooked twin.
         const principal = gatedPrincipal(req, deps.config);
         if (!principal)
             return false;
@@ -1437,6 +2191,12 @@ export function createHttpServer(rawDeps) {
         sendError(res, 429, "limit.cost_quota_exceeded", "cost quota exceeded", { usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec });
         return true;
     }
+    /** lease admission(D4 AP)— the quotaExceeded sibling for lease-enforced principals: first
+     *  touch negotiates with center (single-flight; 409 not-lease-enforced → negative-cached pass-through to
+     *  the local CostQuota path), a live lease admits locally, center-judged exhaustion denies 429+Retry-After
+     *  (same shape as the cost-quota deny), and an unreachable center FAILS OPEN (AP posture — reconciliation
+     *  is the backstop). Keys on the VERIFIED principal only (gatedPrincipal — the quotaExceeded F-fix twin);
+     *  no principal (single-user turnkey) → no lease surface. */
     async function leaseDenied(req, res) {
         if (!deps.fleetLease)
             return false;
@@ -1448,12 +2208,18 @@ export function createHttpServer(rawDeps) {
             return false;
         deps.metrics?.inc("fleet_lease_rejected_total");
         res.setHeader("retry-after", String(adm.retryAfterSec));
+        // E4 定稿:429 带 typed code + center 结构化字段 verbatim 透传(windowType/remaining/resetAt/
+        // isEstimate/pool)——人话文案归壳/web(契约如此),error 串保留旧消费者兼容。
         sendError(res, 429, "quota_exhausted", "budget exhausted (quota lease)", { code: "quota_exhausted", retryAfterSec: adm.retryAfterSec, ...(adm.detail ?? {}) });
         return true;
     }
+    /** Apply the per-principal rate limit; responds 429 and returns true when the caller is over. */
     function rateLimited(req, res) {
         if (!deps.rateLimiter)
             return false;
+        // 🔴 D-G (DeepSeek council Bug#2): on a direct-mode worker x-agent-principal is UNTRUSTED, so keying the limiter
+        // on it lets a client rotate the header to evade its own bucket OR set a victim's principal to poison theirs
+        // (DoS). Key on the socket address instead (the verified principal isn't known until post-body JWT verify).
         const key = (deps.config.directDoorActive ? undefined : principalFrom(req, deps.config)) ?? req.socket.remoteAddress ?? "anon";
         const d = deps.rateLimiter.check(key);
         if (d.allowed)
@@ -1463,6 +2229,14 @@ export function createHttpServer(rawDeps) {
         sendError(res, 429, "limit.rate_exceeded", "rate limit exceeded", { retryAfterSec: d.retryAfterSec });
         return true;
     }
+    /**
+     * §0.5 session-scoped owner scope — the SAME model as GET /v1/sessions, reused by the fork/delete routes so
+     * all three agree on "who may touch this session". A system/traceToken caller is FLEET-WIDE (ops, any session);
+     * a principal caller is PINNED to `gateOwner` (its own). Identity is `gatedPrincipal` (direct-door safe), never
+     * the spoofable header. Caller checks: `!fleetWide && gateOwner===null` ⇒ 401; otherwise compare the session's
+     * stored owner to `gateOwner` (principal path) or allow (fleetWide).
+     */
+    /** Decode a URL path segment, returning null on a malformed %-sequence (a client error → 400, never a 500). */
     function safeDecode(seg) {
         try {
             return decodeURIComponent(seg);
@@ -1471,6 +2245,11 @@ export function createHttpServer(rawDeps) {
             return null;
         }
     }
+    // 🔒 Single source for the fleet-wide (all-tenant) gate. dev-open (no service/trace token ⇒ fleet-wide) is honored
+    // ONLY on a single-user deployment. On MULTI-TENANT (requirePrincipal=true), the ABSENCE of a token must NOT open the
+    // fleet — that would leak every tenant's sessions/runs/fleet rows to ANY caller (HIGH tenant-isolation gap, systematic
+    // audit 2026-06-30). Multi-tenant without a token ⇒ NOT fleet-wide ⇒ owner-gated by principal (and main.ts boot-guards
+    // it to fail FAST). A system authToken or the read-only traceToken still grant fleet-wide on any deployment.
     function isFleetWide(req) {
         const { authToken: at, traceToken: tt } = deps.config;
         const anyAt = Boolean(at) || Object.keys(deps.config.authTokens ?? {}).length > 0;
@@ -1481,6 +2260,11 @@ export function createHttpServer(rawDeps) {
         const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
         return { fleetWide, gateOwner };
     }
+    /** 🔴 WRITE-grade fleet-wide (2026-07-13): the READ-ONLY traceToken must never authorize a
+     *  cross-tenant WRITE (delete/fork/sync import) — isFleetWide deliberately grants it fleet-wide for the trace/
+     *  list READ surfaces, but consuming that same bit on destructive routes turned a read credential into write
+     *  authority. Write routes use THIS gate: dev-open (single-user, no tokens) and the SYSTEM authToken keep their
+     *  authority; a traceToken-only caller falls through to the principal owner gate (or 401). */
     function sessionOwnerScopeForWrite(req) {
         const { authToken: at, traceToken: tt } = deps.config;
         const anyAt = Boolean(at) || Object.keys(deps.config.authTokens ?? {}).length > 0;
@@ -1488,18 +2272,36 @@ export function createHttpServer(rawDeps) {
         const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
         return { fleetWide, gateOwner };
     }
+    /** Reject when the caller's principal does not own the run (null owner = open, dev). */
     function runOwnerOk(req, res, owner) {
+        // 🔴 F-fix: the VERIFIED principal (gatedPrincipal), never the spoofable header — `owner` was persisted from the
+        // verified principal at create, so comparing it to a spoofable header would let a direct-door caller read/cancel a
+        // victim's run (and its event stream) by sending x-agent-principal:<victim> with NO JWT. Same model as
+        // sessionOwnerScope. (BFF/gated: gatedPrincipal === principalFrom, byte-identical.)
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return false;
         }
         if (owner !== null && principal !== owner) {
-            sendError(res, 404, "not_found.run", "run not found");
+            sendError(res, 404, "not_found.run", "run not found"); // don't reveal existence to non-owners
             return false;
         }
         return true;
     }
+    /** [1499] G — session-scoping ACCEPT phase on the run faces ([1498]⑥ soft rollout, 第一拍). principal answers
+     *  "whose data" (authz axis); session answers "which conversation" (content axis, [1493]). These faces deliver
+     *  conversation content (poll/events) or act on a conversation (cancel/steer/compact/detach, subagent
+     *  steer/resume) but were principal-gated only. Enforcement (absent ⇒ 404, subagentOutput-style) needs every
+     *  caller migrated first, so THIS phase 404s ONLY a PRESENT-but-MISMATCHED `?session=`: an honest caller
+     *  asserting its own session never mismatches on its own run — a mismatch IS the accidental cross-session
+     *  touch. Absent ⇒ allowed + warn-once per face (migration observability for the enforcement train). NB the
+     *  operator branch below is only REACHABLE where the preceding owner gate admits the caller: on faces whose
+     *  owner gate carries its own trusted arm (steer/compact/detach/subagent verbs) it is fully live; on the
+     *  runOwnerOk faces (poll/events/cancel — no operator arm, [1498]⑥ ledger) a cross-owner operator 404s at
+     *  the owner gate first, so here it covers only owner-null runs or an operator who IS the owner. Widening
+     *  those owner gates is a deliberate [1498]⑥ decision, not this phase's. A session-unbound run has nothing
+     *  to assert against. */
     const sessionAssertAbsentWarned = new Set();
     function runSessionAcceptOk(req, res, run, face, notFoundError = "run not found") {
         if (!run.sessionId)
@@ -1516,7 +2318,7 @@ export function createHttpServer(rawDeps) {
             return true;
         if (explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals))
             return true;
-        sendError(res, 404, "not_found.run", notFoundError);
+        sendError(res, 404, "not_found.run", notFoundError); // byte-identical to the face's own owner-gate wording (no distinguishable arm)
         return false;
     }
     async function readJson(req) {
@@ -1534,9 +2336,13 @@ export function createHttpServer(rawDeps) {
             return JSON.parse(Buffer.concat(chunks).toString("utf8"));
         }
         catch {
+            // F1 (center K3S report): a malformed body is a client error → 400, not an uncaught 500.
             throw new HttpError(400, "invalid JSON body");
         }
     }
+    /** 2c session-sync: read a RAW request body (binary blob bytes) with a running per-request size cap — the bytes are
+     *  NEVER buffered unboundedly (the §5 "reject, not OOM" guard). Throws HttpError(413) the instant `max` is exceeded
+     *  (mid-stream, before the whole body is in memory). Returns the concatenated Buffer (≤ max). */
     async function readRawBody(req, max) {
         const chunks = [];
         let size = 0;
@@ -1548,11 +2354,25 @@ export function createHttpServer(rawDeps) {
         }
         return Buffer.concat(chunks);
     }
+    /**
+     * design/80 D-D (SLA-timer deny-sweep): resolve-DENY every pending human/irreversible_ask approval past its
+     * deadline (the per-approval SLA) — re-resume each with decision=deny so the model CONTINUES with the denial
+     * (graceful; vs the abort the reaper's expire() gives resource_limit/needs_review). Reuses resumeCheckpoint,
+     * so the markResuming CAS makes it idempotent across replicas (one replica wins each resume) and the parked
+     * run row is driven correctly. A per-call failure (e.g. a redeployed scenario) is swallowed → the row stays
+     * pending and is retried next tick, with the terminal_at backstop as the eventual abort if the deny never
+     * succeeds. Bounded per tick by the store query's LIMIT. Wired into main.ts's reaper.
+     */
     async function denyExpiredApprovals(now) {
         const cs = deps.checkpointStore;
         if (!cs)
             return;
         const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
+        // [1591] 候裁③ 静默臂:parked 后台子代的过期 cp 不走 sweep 的重活赎回(deadline→terminal_at 窗内
+        // 每行每 tick 一条 warn 的噪声源)——其收割属 reaper 的 expire+reconcileParkedAgents 车道。判别在
+        // resume 尝试之前做(省掉注定 409 的整条 ctx/resolveSpec 重建尝试;代价=每过期行两次店读,过期集
+        // 本就被店查询 LIMIT 界住);命中聚合为单条 info 留痕。判别自身故障 ⇒ 按非 parked 处理(保留 warn,
+        // fail-loud 方向)。
         const isParkedOwned = async (sessionId) => {
             if (deps.backgroundAgentStore === undefined)
                 return false;
@@ -1571,6 +2391,9 @@ export function createHttpServer(rawDeps) {
         };
         let parkedSkipped = 0;
         for (const { sessionId } of expired) {
+            // 对抗评审 2026-07-11: log the swallow — a per-tick failure retried forever (e.g. a policy change now folded
+            // into a 409 by resumeCheckpoint, or a redeployed scenario) was fully silent; the row sat pending to its
+            // terminal_at with zero operator-visible signal. Behavior unchanged (skip + retry next tick), now diagnosable.
             if (await isParkedOwned(sessionId)) {
                 parkedSkipped += 1;
                 continue;
@@ -1581,19 +2404,36 @@ export function createHttpServer(rawDeps) {
         if (parkedSkipped > 0)
             deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
     }
+    // Augment the http.Server with the D-D deny-sweep handle (back-compat: all 12 callers keep using the return
+    // value AS an http.Server — listen/close/etc. — while main.ts's reaper reads server.denyExpiredApprovals).
     return Object.assign(server, { denyExpiredApprovals });
 }
+/** SSE: replay durable events after Last-Event-ID, then tail until the run is terminal (or stale). */
+/**
+ * The differences a concrete log (task_run | image_bake) feeds the ONE resumable SSE reader (P2.8). Everything
+ * the reader does — Last-Event-ID/`?from=` resume, the 416 retention boundary, the per-poll concurrent
+ * status+events read, the terminal re-fetch (the terminal event lands in the gap before the status flips), the
+ * stale fallback, the 15-min cap, the 15s idle heartbeat — is provider-agnostic and lives in `streamSseLog`.
+ * 🔴 The task_run provider MUST keep the existing wire bytes EXACTLY (center's relay + 730+ tests depend on it).
+ */
+/** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them (council: the
+ *  guard's inline list had drifted from the handlers and missed `/v1/approvals/:id/decide`, which resumes a run
+ *  via resumeCheckpoint/store.decide → paid tokens). Keep this in sync when adding a billable POST route. */
 function isBillableSubmitPath(url) {
-    return (url === "/v1/side-query" ||
+    return (url === "/v1/side-query" || // [1469] one-shot brain call — runs the model, so it rides every billable-submit gate
         url === "/v1/tasks" ||
         url === "/v1/tasks/stream" ||
         url === "/v1/runs" ||
         url === "/v1/leader" ||
-        ASSISTANT_RESUME_RE.test(url) ||
-        ASSISTANT_PLAN_REVIEW_RE.test(url) ||
-        RUN_SUBAGENT_RESUME_RE.test(url) ||
+        ASSISTANT_RESUME_RE.test(url) || // resource_limit/preempt resume runs the model → BILLABLE (preempt is not)
+        ASSISTANT_PLAN_REVIEW_RE.test(url) || // plan_review approve/edit resumes + runs the model → BILLABLE
+        RUN_SUBAGENT_RESUME_RE.test(url) || // 对抗复查 B-2(HIGH):subagent revive (handle.resume) STARTS model work → BILLABLE
         url.startsWith("/v1/approvals"));
 }
+// ⚠️ SSE 帧纪律(2026-07-12):center BFF 中继凭「data 无 type 字段」识别心跳帧并吞掉
+// (AgentEvent 是 closed oneof 全带 type,故可控)。**未来新增任何 SSE data 帧必须带 type 字段**,否则会被
+// 中继当心跳吞掉、永远到不了前端。heartbeat 帧(`event: heartbeat` + `data: {}`)是唯一豁免。
+/** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`). */
 function routeLabel(_method, url) {
     if (RUN_STEER_RE.test(url))
         return "/v1/runs/:id/steer";
@@ -1618,7 +2458,7 @@ function routeLabel(_method, url) {
     if (BAKE_ID_RE.test(url))
         return "/v1/images/bakes/:id";
     if (url === "/v1/approvals/stream")
-        return "/v1/approvals/stream";
+        return "/v1/approvals/stream"; // native-push SSE — distinct from a /:id decide
     if (/^\/v1\/approvals\/[^/]+$/.test(url))
         return "/v1/approvals/:id";
     if (/^\/v1\/sessions\/[^/]+\/wake$/.test(url))
@@ -1640,9 +2480,13 @@ function routeLabel(_method, url) {
         return url;
     return "other";
 }
+/** CORS v2: allowlist semantics. A SINGLE configured origin keeps the v1 posture
+ *  (echoed unconditionally — non-browser callers see it too, byte-compat); MULTIPLE origins match the
+ *  request's Origin header (echo the matched one, `Vary: Origin` so a shared cache never serves origin-A's
+ *  grant to origin-B; no match ⇒ no allow-origin header ⇒ the browser refuses). Empty list = CORS off. */
 function cors(res, req, origins, principalHeader) {
     if (!origins || origins.length === 0)
-        return;
+        return; // defensive undefined: a hand-built test config may omit the field
     let allow;
     if (origins.length === 1) {
         allow = origins[0];
@@ -1656,6 +2500,8 @@ function cors(res, req, origins, principalHeader) {
         return;
     res.setHeader("access-control-allow-origin", allow);
     res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+    // Include the principal header so a browser front-end that sends it isn't rejected by the OPTIONS preflight
+    // (which would otherwise drop identity → an owner=null session under requirePrincipal=false).
     res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}`);
 }
 //# sourceMappingURL=server.js.map