@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/routes/tasks.js

@@ -16,6 +16,8 @@ export async function handleTasks(req, res, url, ctx) {
     await handleTasksBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(A9 的唯一改动:去缩进;B3 的唯一改动:
+ *  给两个匿名 `idemCache.run` 回调与三条驱动腿起名)。裸 `return;` = 「本域已应答」;走到函数尾才是「没匹配上」。 */
 async function handleTasksBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { idemCache, inflightRuns, cancelledViaVerb, steerableRuns, counters } = ctx.registry;
@@ -24,15 +26,23 @@ async function handleTasksBody(req, res, url, ctx, miss) {
     const reqState = ctx.req;
     const source = ctx.req.source;
     if (req.method === "POST" && (url === "/v1/tasks" || url === "/v1/tasks/stream")) {
+        // Idempotency-Key replay BEFORE the rate/quota gates (council blocker): a retry with a known key must get
+        // the SAME response, not a fresh 429 because the window filled meanwhile. No-op without a key / on a miss.
         const rawIdem = headerStr(req.headers["idempotency-key"]);
+        // Scope by identity only when there IS a key (BL-3) — avoids reading the principal header on every
+        // submit, and keeps the no-key path independent of principal config.
+        // F-fix: scope on the VERIFIED principal (gatedPrincipal) — on a direct door a spoofable header would let a
+        // caller poison/collide another principal's idempotency cache. (BFF/gated: identical to principalFrom.)
         const idemKey = rawIdem ? scopedIdempotencyKey(rawIdem, source, gatedPrincipal(req, deps.config)) : undefined;
         const cached = idemKey ? idemCache.peek(idemKey) : undefined;
         if (cached) {
             if (url === "/v1/tasks/stream") {
+                // The cached entry may be IN-FLIGHT (a retry arriving during the original stream) → set up the heartbeat
+                // BEFORE awaiting so a long wait doesn't idle-timeout, then replay the terminal result.
                 sseHeaders(res);
                 const hb = setInterval(() => {
                     if (!res.writableEnded)
-                        res.write(`event: heartbeat\ndata: {}\n\n`);
+                        res.write(`event: heartbeat\ndata: {}\n\n`); // real frame (not an SSE comment) — a per-frame-parsing BFF drops comments, so downstream saw a zero-frame window; EventSource clients without a heartbeat listener ignore it (zero break)
                 }, 15_000);
                 try {
                     const resp = await cached;
@@ -55,32 +65,70 @@ async function handleTasksBody(req, res, url, ctx, miss) {
         const prepared = await prepareSpec(req, res);
         if (!prepared)
             return;
+        // withPrincipal threads the caller's identity through the run so the cost tracer attributes spend
+        // (incl. council/team sub-tasks) to this principal's cumulative quota.
         const principal = prepared.auth?.principal;
         if (url === "/v1/tasks/stream") {
             if (prepared.verify || prepared.cascade) {
                 sendError(res, 400, "request.field_conflict", "verify / cascade are not supported on /v1/tasks/stream (both are multi-attempt, not a single stream) — use /v1/tasks or /v1/runs");
                 return;
             }
+            // R8 (CC parity, fixed for the AgentEvent contract — workflow re-review #2): mint the durable rewind
+            // handle (taskId) BEFORE the SSE headers so it rides as an `X-Task-Id` RESPONSE HEADER. The shell reads it even
+            // on a Ctrl+C before `done`, WITHOUT an out-of-contract `run_started` data frame (the SDK AgentEvent stream is a
+            // CLOSED oneOf; a synthetic data frame makes exhaustive consumers assertNever-throw). createRun below CLAIMS this id.
             const earlyDurableTid = deps.runStore && prepared.spec.sessionId ? uuidv7() : undefined;
+            // [854]①b per-request opt-in 断连宽限:请求头 `x-detach-on-disconnect: true`(选头不选 body 字段——
+            // 这是本条连接的传输层语义,不该进持久化 body / 不该随 resume 重放;与 idempotency-key 同类)。
+            // 默认行为不动:交互 Esc = 断连即杀的反 token-burn 契约保留(下方 onDisconnect 的 abort 路径)。
+            // opt-in 后 client 断连不 abort,run 转后台跑完,结果按既有 durable 路径可查(X-Task-Id → GET /v1/runs/:id)。
+            // 无 durable 账本(无 runStore 或无 sessionId)时 400 fail-loud 而非静默忽略:忽略 = 断连仍杀 run,
+            // 与 caller 声明的语义相反;就算不杀,跑完的结果也无处可查(纯烧 token)—— body.model silent-drop 同类,
+            // 「不做临时方案」判 400 是真版。SSE 头未发,还能干净 400。
             const detachOnDisconnect = headerStr(req.headers["x-detach-on-disconnect"]) === "true";
             if (detachOnDisconnect && earlyDurableTid === undefined) {
                 sendError(res, 400, "request.precondition_unmet", "x-detach-on-disconnect requires a durable run (a run store + sessionId) — without one the detached result would be unqueryable");
                 return;
             }
-            reqState.streamTaskId = earlyDurableTid;
+            reqState.streamTaskId = earlyDurableTid; // [854]⑥: 499 断连日志带 task 上下文(record 只在 aborted 行读它)
+            // E8 双腿对齐:detach 腿的 modelUsage 归因键(sessionId 域)——声明在此层,leak-fence clear 在本层 finally。
             let usageKey;
+            // [854]①b/⑥:opt-in 一被受理就置 detached 标记(而非等断连时置)——record 的 res 'close' listener
+            // 注册在 onDisconnect 之前,断连时 record 先跑;在这里置位才能让 499 行真带上 detached:true。
+            // 语义不变:opt-in 受理后的任何断连都是 detach(run 不杀)。
             reqState.streamDetached = detachOnDisconnect;
             sseHeaders(res, earlyDurableTid ? { "x-task-id": earlyDurableTid } : undefined);
+            // G15([1833]/[1840]§五):taskId 一等信号进流首帧——浏览器 EventSource 与部分代理面读不到响应头,
+            // 消费端此前只能靠 x-task-id(cli liveClient 亲测取头)。meta 帧与头同源同条件(durable 腿才有 id,
+            // 无 durable ⇒ 头/帧同缺席,不铸空值);sessionId 同帧(server 铸新 session 时 caller 需要它绑定)。
+            // additive:未知 event 型按 SSE 语义被旧消费端忽略。
             if (earlyDurableTid) {
                 res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", taskId: earlyDurableTid, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) })}\n\n`);
             }
+            // Abort the underlying run (and stop the heartbeat) when the client disconnects — otherwise a dropped
+            // relay keeps burning billable tokens to completion (council). Mirrors the closed-flag pattern of the
+            // poll-based SSE endpoints, and additionally cancels the generator via spec.signal.
             const ac = new AbortController();
+            // probe-stoppedby: a client DISCONNECT on the sync stream lane is a USER stop too —
+            // Ctrl+C on the shell drops the SSE and this abort kills the run, but the mark was only wired on the
+            // cancel-verb/resume legs, so background children reaped by THIS abort read "parent"/"system" instead
+            // of "user". Same registration discipline as runs.ts (FIRST on the signal, before core's teardown
+            // listeners). Owner = sessionId (the sync leg's core-canonical taskId — resolveSpec sets no spec.taskId,
+            // same key as the resume leg); skipSessionScoped inside the helper keeps CC Backgrounded children unmarked.
             if (prepared.spec.sessionId)
                 markChildrenStoppedByUserOnAbort(ac.signal, prepared.spec.sessionId, prepared.auth?.principal);
             let closed = false;
-            let detachLogged = false;
+            let detachLogged = false; // [854]①b:detach 断连 info 只打一条(req/res 两个 close listener 都可能进来)
             const onDisconnect = () => {
+                // [854]①b:detach opt-in 的断连分支 —— 不置 closed(for-await 继续消费到 done,终态走既有
+                // setTerminal 路径落 durable 账本)、不 abort(run 不杀)。断连后的 res.write 落在已 destroy 的
+                // socket 上被 Node 丢弃;防御:挂一个 res 'error' swallow(destroy 后的 write 在部分 Node 版本
+                // 经 nextTick 发 ERR_STREAM_DESTROYED,无 listener 会变 uncaught)—— 只在 detach 已断连后挂,
+                // 正常车道的 res 错误面不被吞。task_notification 的 deliverable 谓词含 res.destroyed,断连后
+                // 自动改走 durable inbox(既有行为,正合 detach 语义)。
                 if (detachOnDisconnect) {
+                    // 正常完成后的 req 'close' 不是断连(默认车道靠 abort-after-done 无害才容得下无 guard 的
+                    // req listener;detach 车道要防它打出误导的 detached info)。
                     if (res.writableEnded)
                         return;
                     if (!detachLogged) {
@@ -94,22 +142,58 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                 ac.abort();
             };
             req.on("close", onDisconnect);
+            // 🔴 req 'close' does NOT fire on a client disconnect once the request body has been fully consumed
+            // (prepareSpec read it before we get here; verified against node 24) — only res 'close' does. With only
+            // the req listener the disconnect-abort above never fired on this route, i.e. the dropped-relay token
+            // burn it exists to stop went right on burning. writableEnded guards the normal-completion close
+            // (end() already called → that close is not a disconnect).
             res.on("close", () => {
                 if (!res.writableEnded)
                     onDisconnect();
             });
+            // Heartbeat so a long no-token gap (e.g. a debate phase) doesn't trip a mesh/ingress idle timeout on
+            // the relay (center). SSE comment lines are ignored by EventSource but keep the socket alive.
             const hb = setInterval(() => {
+                // [854]①b: `!res.destroyed` — detach 断连后 run 可能再跑很久,别每 15s 往已死 socket 写心跳
+                // (destroyed = client 已断,写了也只是被丢弃/触发 error;默认车道断连即 abort,窗口极短,不受影响)。
                 if (!res.writableEnded && !res.destroyed)
-                    res.write(`event: heartbeat\ndata: {}\n\n`);
+                    res.write(`event: heartbeat\ndata: {}\n\n`); // real frame (not an SSE comment) — a per-frame-parsing BFF drops comments, so downstream saw a zero-frame window; EventSource clients without a heartbeat listener ignore it (zero break)
             }, 15_000);
+            // Wrap the whole stream in idemCache.run so the IN-FLIGHT promise is stored BEFORE work begins — a retry
+            // that arrives WHILE this stream is still running (relay timeout → re-send same key) is then caught by the
+            // peek above and replays this result instead of starting a second billable stream (council). `ranLive`
+            // tells the caller that actually produced the stream (wrote events live) apart from a concurrent caller the
+            // cache deduplicated — the latter got no live events, so it must be handed the terminal result.
             let ranLive = false;
             let resp;
+            // ── B3 ── 原文此处是 `idemCache.run` 的第二个实参、一个 **703 行匿名 async**。提为具名闭包:
+            // plain-stream 腿。捕获的自由变量(`ranLive`/`prepared`/`principal`/`res`/`ac`/`closed`/`hb`/
+            // `earlyDurableTid`/`usageKey`/`reqState`…)与原匿名回调完全同一批,故行为逐字。
             const runStreamSubmitLeg = async () => {
                 ranLive = true;
                 let finalResult;
+                // [868]③: true once the post-stream settle block below recorded the run row's park/terminal state.
+                // A throw OUT of the stream (abort mid-iteration, or any plain Error before `done`) skips that whole
+                // block — the finally's backstop then settles the leaked `running` row (the durable twin of the
+                // fleet-row leak C fixed below; the fleet half got its settleFleet("failed") backstop, the run row
+                // was left to reapStale's stale-timeout with a misleading "run stalled" verdict).
                 let runRowSettled = false;
+                // Durable F4/ask on the stream path. Two things the sync/async paths do that the stream path
+                // used to skip (audit functional gap; both caught live on the gate#3 P3 cross-replica drill):
+                //  1. putCtx BEFORE the run → a suspend here (e.g. an AskUserQuestion gate, TC-5.4) is resumable
+                //     on any replica; without it the operator's resume fails "resume context missing".
+                //  2. createRun a task_active claim at SUBMIT (+ heartbeat) → reapCtx's task_active guard then
+                //     protects the ctx for the WHOLE first leg. The ctx's updated_at is stamped at submit and
+                //     never refreshed, so a multi-minute first leg (a 5-min gradle build outlived the 120s
+                //     REAP_RUN_STALE_SEC) ages the ctx past the cutoff and reapCtx deletes it MID-RUN — before
+                //     the suspend's pending checkpoint can protect it. setSuspended KEEPS the claim (session
+                //     stays locked submit→resume); a clean completion releases it via setTerminal.
                 let durableTaskId;
                 let durableHeartbeat;
+                // R8 (CC parity, interactive rewind on disconnect): the user-message entryId is captured INSIDE
+                // streamBody, but the rewind anchor must be writable from BOTH the done branch AND the disconnect branch
+                // (Ctrl+C before done) — so hoist it + a once-guarded put to this scope. Without this, a turn cancelled
+                // before `done` left NO anchor → the shell, even holding the early taskId, 404'd on rewind.
                 let userMsgEntryId;
                 let anchorPut = false;
                 const putRewindAnchor = () => {
@@ -120,20 +204,47 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                         .put(prepared.spec.sessionId, durableTaskId, userMsgEntryId, principal ?? null)
                         .catch(() => deps.metrics?.inc("resume_anchor_capture_failed"));
                 };
+                // R8 (CC parity): the run-row claim + `durableTaskId` (the REWIND anchor key + the unique
+                // result.taskId re-stamp) is gated on `runStore` ALONE; the durable-suspend resume ctx (`putCtx`) on
+                // `checkpointStore`. They were bundled under ONE checkpointStore gate, over-coupling REWIND to
+                // DURABLE_APPROVAL — but E18 resume-at needs NO checkpoint (main.ts:815). Now matches the /v1/runs bg path:
+                // rewind works with just runStore (DB_BACKEND=tidb/pg), no approval. Claim-first preserved (session locked
+                // submit→resume; a concurrent submit → 409, never a silent 2nd leg, and a rejected submit never clobbers the ctx).
                 if (deps.runStore && prepared.spec.sessionId) {
-                    const tid = earlyDurableTid ?? uuidv7();
+                    const tid = earlyDurableTid ?? uuidv7(); // reuse the id already emitted as the X-Task-Id header (defensive mint if absent)
                     const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
                     if (created.ok)
-                        deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective);
+                        deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective); // fire-and-forget; in-titler dedupe
                     if (!created.ok) {
                         const conflict = { error: "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", errorCode: "conflict.session_active_run", activeTaskId: created.activeTaskId };
+                        // Headers are already SSE — encode the rejection as the stream's terminal event; the 409 in
+                        // the returned resp is for a deduplicated concurrent caller (and is never idem-cached).
                         res.write(`data: ${JSON.stringify({ type: "done", result: { status: "failed", errorMessage: conflict.error, activeTaskId: conflict.activeTaskId } })}\n\n`);
                         return { status: 409, body: conflict };
                     }
                     durableTaskId = tid;
                 }
+                // [900]①/[906]③ detach 车道逐事件落账:sync 腿历史上只 createRun+setTerminal(events 账本恒空,
+                // detach 后壳只能轮询终局)。opt-in 车道把 for-await 的每个事件喂给与 bg 腿(runs.ts)共享的
+                // LedgerSink(src/trace/ledger-sink.ts —— 单一 switch,落账 type/data 形状与 GET /v1/runs/:id/events
+                // 的 bg 产出完全一致),detach 后壳换道 events tail 全帧续收。非 detach 车道恒 undefined = 零改动
+                // (不落账,byte-compat)。reasoning gate 与 bg 腿同一配置源(config.traceThinking / TRACE_THINKING)。
+                // 本腿账面差异(如实;[1840]§五车后已缩两项):suggestions 不落(本腿不调 stream.suggestions)、
+                // elicitation/question/approval 帧走 live emitAsk 面不落账、stream-open inbox drain 与 observer 臂
+                // 的 task_notification 走 wire/durable-inbox 既有链(post-detach 自动 park 进 inbox,下一腿 drain
+                // 补投)——不在本账本。已对齐:model_usage(E8 三件,下方 register/turn_end delta/终局 attach)、
+                // file_link(live+durable 双写,emit 回调处)。
                 let ledgerSink;
+                // [900]①: a terminal/park event already landed in the ledger — the failure backstops below must
+                // never write `failed` over it (bg 腿 `reached` 同款纪律).
                 let ledgerTerminal = false;
+                // model_usage 双腿对齐([1840]§五,W9 同根):detach 账本腿补上 bg 腿的 E8 三件(register /
+                // turn_end delta 落账 / 终局 SUM 进 stats.modelUsage)。归因键=**sessionId**,不是 durableTaskId:
+                // core 的 taskId mint = `spec.taskId ?? sessionId`(dist 亲读 runtask.js:773),本腿 resolveSpec
+                // 不设 spec.taskId ⇒ tracer 的 brain.call e.taskId = sessionId。账本键仍是 durableTaskId(两域
+                // 分家——attach 时 getEvents 按账本键包一层)。非 detach 车道照旧不登记(下方 E8 INTENTIONAL
+                // 排除注释仍准确——那腿无账本消费者);2107 行的「账面差异」清单相应少了 model_usage 一项。
+                // (usageKey 声明在外层——leak-fence clear 在外层 finally,须覆盖 throw 路径。)
                 if (detachOnDisconnect && durableTaskId && deps.runStore) {
                     const rs = deps.runStore;
                     const tid = durableTaskId;
@@ -143,16 +254,20 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                         deps.modelUsage?.register(usageKey);
                 }
                 if (deps.checkpointStore && prepared.spec.sessionId) {
+                    // putCtx AFTER the claim (resumable). If this throws, the claim row self-heals: heartbeat hasn't
+                    // started, so reapStale flips it failed + releases task_active after runStaleSec.
                     await deps.checkpointStore.putCtx(prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
                 }
                 if (durableTaskId && deps.runStore) {
                     const rs = deps.runStore;
                     const tid = durableTaskId;
-                    const owner = principal ?? null;
+                    const owner = principal ?? null; // run created with this owner — pass it as the single-DB null-safe heartbeat guard
                     const abortFromVerb = () => {
-                        cancelledViaVerb.add(tid);
+                        cancelledViaVerb.add(tid); // H2: label the settle (errorCode "cancelled"), see the set's decl
                         ac.abort();
                     };
+                    // [1.207 codex H1] heartbeat ALSO polls the durable cancel flag (bg-leg parity, runs.ts) — a
+                    // cancel landing on ANOTHER replica only sets the flag, and this leg previously had no consumer.
                     durableHeartbeat = setInterval(() => {
                         void rs.heartbeat(tid, owner).catch(() => undefined);
                         if (!ac.signal.aborted) {
@@ -161,14 +276,36 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                         }
                     }, HEARTBEAT_MS);
                     durableHeartbeat.unref?.();
+                    // [888]① interactive live-run cancel: register this leg's abort controller under the SAME
+                    // in-flight map the bg/resume legs use — POST /v1/runs/:id/cancel's fast path (`inflightRuns
+                    // .get(taskId)?.abort()`) previously only ever hit bg legs, so cancelling an interactive run
+                    // flipped the durable flag that NOTHING on this leg consumed (release deferred to reapStale).
+                    // Abort rides the leg's existing disconnect-kill chain (spec.signal), which settles the row.
                     inflightRuns.set(tid, ac);
+                    // [1.207 codex H1] registration-window catch-up: a cancel that landed between createRun and this
+                    // point (the awaited putCtx window) flipped the flag while the fast path found no entry — check
+                    // once so it is honored now, not at the first heartbeat.
                     void Promise.resolve(rs.isCancelRequested?.(tid, owner)).then((c) => { if (c && !ac.signal.aborted)
                         abortFromVerb(); }).catch(() => undefined);
                 }
+                // MF-Fleet: publish this run's row transitions to the fleet bus (a tracked/durable run becomes a
+                // fleet row; turn_end accrues tokens; core `task_progress` adds subagent child rows; terminal removes
+                // it). No-op for an ephemeral sync run (no durableTaskId) or when no fleetBus is wired.
+                // [1.211 codex L] fleet 装配纳入清理保护:heartbeat/inflightRuns 注册在上面已发生,而外层
+                // try/finally 从更后面才开始——fleetRunPublisher/onStart 若在这窗内 throw,计时器与 cancel 句柄
+                // 无人清理(SSE 头已发,请求以 500 帧终止但资源漏)。let+窄 try/catch 清理后 rethrow 补上这段。
                 let fleetPub;
                 try {
                     fleetPub = durableTaskId
-                        ? fleetRunPublisher(deps.fleetBus, { runId: durableTaskId, scope: gatedPrincipal(req, deps.config) ?? "default", rootTaskId: prepared.spec.sessionId, ...fleetRunLabels(prepared.spec.objective) })
+                        // core 1.154 nested-subagent tree: rootTaskId = the run's CANONICAL core taskId (`spec.taskId ?? sessionId`).
+                        // The sync leg does NOT set spec.taskId, so canonical == sessionId — a forwarded subagent whose parentTaskId
+                        // equals it nests under the run; deeper subagents nest under their parent subagent's row.
+                        // 🔒 Scope the fleet row with the SAME identity GET /v1/fleet/stream FILTERS by — `gatedPrincipal`
+                        // (crypto-verified on a direct door), NOT the cost-attribution `principal` (= the spoofable header).
+                        // On a direct door the two diverge: a spoofed header would tag the row under a victim's scope (cross-
+                        // tenant leak) or under "default" while the verified owner's stream filters it OUT (the row vanishes
+                        // from its real owner's view). Tenant-isolation parity with the stream filter (TOC review #6).
+                        ? fleetRunPublisher(deps.fleetBus, { runId: durableTaskId, scope: gatedPrincipal(req, deps.config) ?? "default", rootTaskId: prepared.spec.sessionId, ...fleetRunLabels(prepared.spec.objective) }) // BC-1: name = short objective preview (description = live-activity, set by the publisher onEvent tool_start)
                         : undefined;
                 }
                 catch (e) {
@@ -176,41 +313,72 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                         clearInterval(durableHeartbeat);
                     if (durableTaskId && inflightRuns.get(durableTaskId) === ac) {
                         inflightRuns.delete(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
+                        cancelledViaVerb.delete(durableTaskId); // [1.211 codex L] 标记集同窗清理
                     }
                     throw e;
                 }
+                // C (TOC adversarial review): settle the fleet row EXACTLY once. A plain Error thrown mid-stream
+                // (not done/CheckpointError/cancel) escapes the loop before any onTerminal fires → the row leaks as a
+                // stale "running" forever. Route every onTerminal through this guard so the finally below can settle a
+                // row no terminal branch reached, without ever 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 再挡一层)
                 };
+                // 1.207: THIS leg's live TaskStream (assigned inside streamBody) — held here so the outer finally can
+                // identity-guard its deregistration (only delete the handle WE registered; see the finally).
                 let liveStreamRef;
+                // design/122 ③: this leg's subagent-handle unregister thunks — run at leg end (finally), not on settle.
                 const subagentHandleEvictions = [];
+                // false once this leg settles — a bg subagent/bash completion after that has no live
+                // harness (idle) → the observer parks it in the durable inbox (see fwdInternals below).
                 let syncLegLive = true;
+                // option A: taskNotificationStreamKey (域:task_id:status[#seq], core [784]④a + codex F2 域二分)
+                // keys this leg already delivered (turn-open inbox drain, stream branch OR observer) — each arm
+                // skips keys another arm already carried, so a notification isn't double-written to the SSE (the
+                // turn-TAIL reap notification, which never reaches the stream, is the one the observer catches;
+                // core's pend-drain replay of a double-parked idle arrival is the one the drain-registration
+                // catches — core [784]④b). codex F1: NotifiedKeys (Map keyed on write outcome) for three-leg
+                // parity — this leg's writes are all synchronous res.write (no async failure window), so every
+                // claim registers resolved(true) and the has/skip semantics are unchanged here.
                 const syncNotifiedKeys = new NotifiedKeys();
                 try {
-                    fleetPub?.onStart();
+                    fleetPub?.onStart(); // [1.211 codex L] 同窗保护:subscriber throw 不再漏计时器/句柄
                 }
                 catch (e) {
                     if (durableHeartbeat)
                         clearInterval(durableHeartbeat);
                     if (durableTaskId && inflightRuns.get(durableTaskId) === ac) {
                         inflightRuns.delete(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
+                        cancelledViaVerb.delete(durableTaskId); // [1.211 codex L] 标记集同窗清理
                     }
-                    settleFleet("failed");
+                    settleFleet("failed"); // [1.211 codex M2] publishTask 先写行再 emit——subscriber throw 时行已在,不清即永久 running 幽灵行
                     throw e;
                 }
+                // R8 rewind handle is now the X-Task-Id RESPONSE HEADER (set with earlyDurableTid above), not an
+                // out-of-contract `run_started` data frame — the shell reads it from the response headers even on an early
+                // disconnect, and the SDK's CLOSED AgentEvent stream stays unpolluted (workflow re-review #2 caught the drift).
                 try {
                     const streamBody = async () => {
                         await withPrincipal(principal, async () => {
+                            // core 1.154 nested-subagent live tree: opt into the forward sink — a subagent's task_progress
+                            // lives in its ISOLATED child stream (never on THIS top stream; core's only emitter is
+                            // parentToolCallId-gated), so this sink is the ONLY path a tick reaches the top-run consumers.
+                            // 1.78 (review HIGH): fan it out to the LIVE SSE too (shared whitelist+redact builder, carrying
+                            // the E2 identity the shell binds concurrent ticks by) — previously it fed ONLY the fleet bus,
+                            // so the conversation lane never saw a real tick and the in-loop task_progress branch below is
+                            // forward-compat only (dead against core ≤1.208). core swallow-guards a throwing sink.
                             const fwdInternals = {
                                 onForwardEvent: (e) => {
                                     fleetPub?.onForwardEvent(e);
+                                    // [900]① detach 车道:子代理 forward 事件(tool_start/end + task_progress)也落账 —— bg 腿
+                                    // 同姿势(共享 sink 的 fire-and-forget 门,child deltas 有意不逐块落,见 LedgerSink.onForwardEvent)。
                                     ledgerSink?.onForwardEvent(e);
+                                    // S2 live tail(core 1.370 bgAgentId;bg 腿 twin 在 runs.ts):句柄分发在 res 存活判之前
+                                    // ——主流断了 tail 订阅者照收(tail 是独立连接)。
                                     {
                                         const bg = e.bgAgentId;
                                         if (bg !== undefined && defaultSubagentTailBus.hasSubscribers(bg)) {
@@ -226,36 +394,73 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                         res.write(`data: ${JSON.stringify({ type: "task_progress", ...taskProgressEventData(e) })}\n\n`);
                                     }
                                     else if (t === "tool_start") {
+                                        // C1 (core 1.219, spec.forwardSubagentEvents): a delegated child's live CONTENT events now
+                                        // ride the forward sink (each stamped parentToolCallId — the shell nests them under the
+                                        // delegation card). Echo through the SAME shared whitelist+redact builders as the top
+                                        // stream (§E1 — forwarded events are UNTRUSTED RAW; redaction is ours at the wire).
                                         const tsv = e;
                                         res.write(`data: ${JSON.stringify({ type: "tool_start", ...toolStartEventData(tsv) })}\n\n`);
                                     }
                                     else if (t === "tool_end") {
                                         const te = e;
-                                        res.write(`data: ${JSON.stringify({ type: "tool_end", ...toolEndEventData(te) })}\n\n`);
+                                        res.write(`data: ${JSON.stringify({ type: "tool_end", ...toolEndEventData(te) })}\n\n`); // label 现由 builder 自带,外拼冗余已清
                                     }
                                     else if (t === "text_delta") {
+                                        // Child text is plain model output (same trust class as the top stream's text_delta, which
+                                        // rides verbatim); parentToolCallId attributes it. Whitelist the three fields explicitly.
                                         const td = e;
                                         res.write(`data: ${JSON.stringify({ type: "text_delta", delta: td.delta, ...(td.eventId ? { eventId: td.eventId } : {}), ...(td.parentToolCallId ? { parentToolCallId: td.parentToolCallId } : {}) })}\n\n`);
                                     }
                                     else if (t === "reasoning_delta") {
+                                        // §E1 parity with the top stream's live CoT: redactSecrets before echo.
                                         const rd = e;
                                         res.write(`data: ${JSON.stringify({ type: "reasoning_delta", delta: redactSecrets(rd.delta), ...(rd.eventId ? { eventId: rd.eventId } : {}), ...(rd.parentToolCallId ? { parentToolCallId: rd.parentToolCallId } : {}) })}\n\n`);
                                     }
                                 },
+                                // background-completion observer — flip the child's fleet
+                                // row (task_progress never emits a terminal tick) + park an idle-arrival in the durable
+                                // inbox (workflow-type skipped: own durable chain). Rationale in runs.ts (bg-leg twin).
+                                // core 1.283: `seq` = the per-stop-cycle counter (stop→wake→stop mints 1,2,…) — it MUST
+                                // ride into the dedup key below (core [784]④a) and into the parked inbox entry.
+                                // 白名单排查(2026-07-24,「彻查 as {} 连环坑」):手写窄类型换 core 真实类型,理由同 runs.ts twin。
                                 onTaskNotification: (n) => {
                                     if (n.task_type === "workflow")
                                         return;
+                                    // S2 复审 #3:中途终态信号——task_settled 帧让订阅者不再 heartbeat 永挂(路由收帧即收流)。
                                     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;
+                                    // 🔴 对抗评审 2026-07-11(HIGH,「下一 turn 0 帧」最强根因):the teardown WINDOW — after the
+                                    // client disconnects (the user killed the turn → ac.abort → core reaps the bg child → THIS
+                                    // notification fires) but BEFORE the outer finally flips `syncLegLive=false` (several awaits sit
+                                    // between the for-await break and the finally). In that window the old predicate neither parked
+                                    // (legLive still true) nor wrote (socket dead) — the notification vanished with no inbox copy and
+                                    // no frame. Fold the dead-socket state into the park predicate: the leg is only DELIVERABLE when
+                                    // it is live AND the socket can still be written. 🔴 `res.destroyed` is the CLIENT-disconnect
+                                    // signal (`writableEnded` only flips when WE call res.end()) — the real-HTTP retest caught the
+                                    // writableEnded-only predicate still writing into the dead socket.
                                     const deliverable = syncLegLive && !res.writableEnded && !res.destroyed;
                                     const parked = !deliverable && Boolean(deps.workflowCompletionInbox && prepared.spec.sessionId);
+                                    // diagnosability (rationale in runs.ts twin).
                                     deps.logger?.info?.("task_notification_observed", { route: "sync-stream", taskId: n.task_id, taskType: n.task_type, status: n.status, hadFleetRow: hadRow, legLive: syncLegLive, parkedDurable: parked });
                                     if (parked) {
+                                        // 对抗评审 2026-07-11(MED):the fire-and-forget swallow hid EVERY enqueue failure (SQL blip,
+                                        // fence race) while the diag line above had already printed parkedDurable:true — a false park✓
+                                        // fingerprint. Log the failure; behavior (never fault the callback) unchanged.
                                         void deps.workflowCompletionInbox.enqueue(taskNotificationInboxEntry(prepared.spec.sessionId, askOwner, n, Date.now(), durableTaskId)).catch((err) => deps.logger?.warn?.("park_enqueue_failed", { route: "sync-stream", taskId: n.task_id, err: err instanceof Error ? err.message : String(err) }));
                                     }
                                     else if (deliverable) {
+                                        // option A (turn-TAIL killed receipt must be IMMEDIATE): a teardown-time reap
+                                        // notification fires while the SSE is still open but past the stream's delivery window —
+                                        // write the display frame directly, skipping keys the stream already carried (mid-turn
+                                        // dedup; the shell's dedup stays the outer belt). core [784]④a: the key folds `seq` in
+                                        // (shared taskNotificationStreamKey) — the old seq-less `${task_id}:${status}` shape
+                                        // REVERSE-swallowed a second stop-cycle's same-status frame on this arm (stop→wake→stop:
+                                        // the seq=2 completed frame collided with cycle 1's key and the user never saw it).
+                                        // codex F1: res.write is a synchronous enqueue (no async failure window — a dead socket
+                                        // is already folded into `deliverable` above), so the claim registers resolved(true).
                                         const key = taskNotificationStreamKey(n);
                                         if (syncNotifiedKeys.get(key) === undefined) {
                                             syncNotifiedKeys.set(key, Promise.resolve(true));
@@ -263,6 +468,10 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                         }
                                     }
                                 },
+                                // C2 (core 1.219) + design/122 (core 1.225 ③): register each sync delegation's steer handle
+                                // under this run's durable taskId (the X-Task-Id the shell holds). NOT evicted on settle —
+                                // resume is only legal after settle; evicted at leg end via the collected identity-guarded
+                                // thunks (outer finally), so a settled child stays steer-409/resume-able while the run lives.
                                 ...(deps.subagentSteerRegistry && durableTaskId
                                     ? {
                                         onSubagentSpawn: (handle) => {
@@ -271,6 +480,15 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                     }
                                     : {}),
                             };
+                            // R8 (CC parity, interactive rewind): the sync `tasks.stream` path (the REPL's lane) must ALSO
+                            // leave a per-prompt rewind anchor, else an interactive-turn rewind 404s (the bg + resume legs capture
+                            // it, this one didn't). Buffer the committed USER-message entryId on the HOISTED `userMsgEntryId` (so
+                            // the disconnect branch can anchor too); the done branch anchors here, the disconnect branch below.
+                            // core 1.207: hold the LIVE TaskStream handle + register it (keyed by durableTaskId = the
+                            // X-Task-Id the shell already holds) so the replica-local verbs — POST /v1/runs/:id/detach
+                            // (mid-flight ctrl+b) and, as a natural consequence, steer/compact — now reach a mid-turn
+                            // INTERACTIVE run too (previously only the bg + resume legs registered). Deregistered in the
+                            // outer finally (with the fleet settle), so an early throw can't leak a stale handle.
                             const liveStream = deps.runner.runTaskStream({ ...prepared.spec, signal: ac.signal }, undefined, fwdInternals);
                             liveStreamRef = liveStream;
                             if (durableTaskId)
@@ -281,19 +499,45 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                 if (ev.type === "message_committed" && ev.role === "user")
                                     userMsgEntryId = ev.entryId;
                                 if (ev.type === "done") {
+                                    // Never stream the durable-resume capability token to the client: a
+                                    // durable suspend's done event carries it. Strip it from BOTH the live write and the cached
+                                    // body (handed to a concurrent deduplicated caller below). No-op for a normal result.
                                     finalResult = stripCheckpointToken(ev.result);
+                                    // R8 (CC parity, interactive rewind): on the sync leg core sets result.taskId = sessionId
+                                    // (spec.taskId is left unset so a forwarded subagent nests under the run — server.ts above), which
+                                    // is NOT unique per prompt → it can't be a per-turn rewind handle (every turn would collide). Re-
+                                    // stamp the WIRE result.taskId to the unique durable run id (uuidv7, == the bg path's result.taskId
+                                    // → consistent across paths) so the shell gets a unique per-prompt handle. Internal canonical
+                                    // (fleet/subagent nesting) keeps sessionId — only the external done-frame value changes. Durable-run
+                                    // only (ephemeral has no anchor store ⇒ no rewind anyway), so the fallback keeps sessionId.
                                     if (durableTaskId && finalResult)
                                         finalResult = { ...finalResult, taskId: durableTaskId };
+                                    // [1.207 codex H2] cancel-verb abort label: core's external-signal abort yields
+                                    // failed WITHOUT an errorCode — project `cancelled` onto the wire+persisted form so
+                                    // /cancel's outcome is uniform (first-writer-wins would pin the unlabeled form). Only
+                                    // an abort-shaped FAILED result is labeled — a completion that raced the abort stands.
                                     if (durableTaskId && cancelledViaVerb.has(durableTaskId) && finalResult?.status === "failed" && !finalResult.errorCode) {
                                         finalResult = { ...finalResult, errorCode: "cancelled" };
                                     }
                                     finalizeTaskResult(ev.result, principal, prepared.spec.objective, prepared.spec.sessionId);
+                                    // Anchor this interactive prompt (taskId → user-message entryId) keyed by the SAME unique id the
+                                    // shell now holds (done.result.taskId == durableTaskId). entryId came straight from
+                                    // `message_committed{role:"user"}` (no getLeafId). Best-effort + once-guarded — a capture failure
+                                    // only makes THIS turn non-rewindable, never faults the run; the disconnect branch shares the guard.
                                     putRewindAnchor();
-                                    settleFleet(finalResult?.status ?? "completed", fleetRunResiduals(finalResult));
+                                    settleFleet(finalResult?.status ?? "completed", fleetRunResiduals(finalResult)); // [1839]①/(a):终态残局键
+                                    // [900]① detach 车道:done 也落账(flush 攒批 + suspended/needs_review/done 投影,bg 词汇;
+                                    // finalResult 已 stripCheckpointToken + taskId 重印 + cancel 标注 —— 账本形 == wire 形)。
+                                    // 放在 res.write 之前:壳收到 wire done 后立刻换道 events tail 也必见终局帧。既有
+                                    // finalize/settleFleet/res.write/setTerminal 顺序不动(落账是旁路)。
                                     if (ledgerSink && finalResult) {
+                                        // E8 双腿对齐:终局 flush 最后一拍 delta + SUM 全账本 model_usage 进 stats.modelUsage
+                                        // (bg 腿 withModelUsage 同形)。⚠️ 键两域分家:drain 键=usageKey(sessionId,core 归因),
+                                        // 账本读键=durableTaskId——attachModelUsage 的 taskId 双用途在此不成立,getEvents 包一层。
                                         if (usageKey && deps.modelUsage && deps.runStore && durableTaskId) {
                                             const rs2 = deps.runStore;
                                             const tid2 = durableTaskId;
+                                            // attach 失败(SUM 读瞬断)不许炸掉 onDone——终局帧比 modelUsage 汇总重要,回落原 result。
                                             const fr = finalResult;
                                             finalResult = await attachModelUsage(fr, { append: ledgerSink.append, getEvents: (_id, after) => rs2.getEvents(tid2, after), modelUsage: deps.modelUsage, taskId: usageKey }).catch(() => fr);
                                         }
@@ -303,54 +547,116 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                     res.write(`data: ${JSON.stringify({ ...ev, result: finalResult })}\n\n`);
                                     continue;
                                 }
+                                // [900]① detach 车道逐事件落账(await 保序 —— 与 bg 腿同代价姿势;message_committed/未知型
+                                // sink 内部 no-op)。非 detach 车道 ledgerSink 恒 undefined = 零改动。
                                 if (ledgerSink) {
                                     await ledgerSink.onEvent(ev);
+                                    // E8 双腿对齐:turn 边界 drain per-model delta 落账(bg 腿 flushModelUsage 同位同形)。
                                     if (ev.type === "turn_end" && usageKey)
                                         await appendModelUsageDelta(ledgerSink.append, deps.modelUsage, usageKey);
                                 }
-                                fleetPub?.onEvent(ev);
+                                fleetPub?.onEvent(ev); // MF-Fleet: turn_end → tokens; task_progress → subagent child row
+                                // S4 P0-a: count brain-liveness phases on the sync leg too. The bg/resume legs count at
+                                // their append sites.
                                 if (ev.type === "status")
                                     deps.metrics?.inc("brain_retry_total", { phase: String(ev.phase) });
+                                // E1 (shell-host contract): tool_end.output AND (core 1.203) tool_end.structured are
+                                // UNTRUSTED RAW from core (file/shell/API bodies; a structured card carries `originalFile`) —
+                                // redact at the live wire boundary before echo (core only SIZE-bounds; redaction is ours, same
+                                // contract as the durable path). 🔒 EXPLICIT WHITELIST, not `{...ev}` (the 1.72 task_progress
+                                // lesson, re-proven by `structured`: a spread forwards a future core field RAW — 1.203 landing
+                                // meant `structured` rode this leg unredacted until this build). Known-safe fields verbatim:
+                                // ids/name/label/isError/truncated + E2 identity. NB the old guard also skipped redaction when
+                                // `output` was undefined (→ raw catch-all) — the whitelist path now covers every tool_end.
                                 if (ev.type === "status") {
+                                    // TaskEvent 三腿审查(steering_injected 跟进批):`status`(BrainStatus.detail,UNTRUSTED —
+                                    // 可能回显 provider 的 rate-limit/retry 报文)此前落裸 catch-all 未脱敏,与 durable 两腿
+                                    // (ledger-sink.onEvent + resume switch)共用的 brainStatusEventData 脱敏不一致——同类
+                                    // 「留在 catch-all」教训(1.72 task_progress),现挪显式分支,三腿同门同形。
                                     res.write(`data: ${JSON.stringify({ type: "status", ...brainStatusEventData(ev) })}\n\n`);
                                 }
                                 else if (ev.type === "tool_end") {
                                     const te = ev;
-                                    res.write(`data: ${JSON.stringify({ type: "tool_end", ...toolEndEventData(te) })}\n\n`);
+                                    res.write(`data: ${JSON.stringify({ type: "tool_end", ...toolEndEventData(te) })}\n\n`); // label 现由 builder 自带,外拼冗余已清
                                 }
                                 else if (ev.type === "tool_start") {
+                                    // 🔒 E1 parity (TOC adversarial review): redact tool_start.args on the LIVE wire too — the model's
+                                    // tool-call inputs can echo a secret it read (e.g. a value from a redacted tool_end fed into the
+                                    // next call). Whitelist for the same reason as tool_end (shared durable builder = one shape).
                                     const tsv = ev;
                                     res.write(`data: ${JSON.stringify({ type: "tool_start", ...toolStartEventData(tsv) })}\n\n`);
                                 }
                                 else if (ev.type === "task_notification") {
+                                    // core 1.202 (design/115 P2): a background task (workflow) finished while THIS harness was live —
+                                    // core already injected the <task-notification> XML into the model in-process; this is the display
+                                    // projection for the shell. Whitelist + redact via the shared builder (summary/result are UNTRUSTED
+                                    // free text). The shell dedups against the inbox-drain `workflow_complete` lane by run id.
+                                    // core [784]④b(跨层双泊车): a notification that arrived while the previous leg was idle is
+                                    // parked TWICE — core pends it in-Runner (pendingSessionNotifications) AND our sync observer
+                                    // parks it in the durable inbox. On this turn-open, our inbox drain (below the streamBody def)
+                                    // already wrote the frame and REGISTERED its key; core's pend-drain replays the same payload as
+                                    // a stream `task_notification` event (runtask.js queue.push) — skip it here instead of writing
+                                    // the wire twice. Same check also folds the mid-turn observer-then-stream echo. A frame whose
+                                    // key is NOT yet on this stream writes exactly as before (the first copy is never eaten).
+                                    // codex F1/F2: same await-the-claim shape as the bg/resume twins (on THIS leg every claim
+                                    // is resolved(true) — sync writes — so the await is immediate); task_type rides the key.
                                     const tnv = ev.notification;
                                     const tnvKey = tnv?.task_id ? taskNotificationStreamKey({ task_type: tnv.task_type, task_id: tnv.task_id, status: String(tnv.status), seq: tnv.seq }) : undefined;
                                     const tnvPrior = tnvKey !== undefined ? syncNotifiedKeys.get(tnvKey) : undefined;
                                     if (tnvPrior === undefined || !(await tnvPrior)) {
                                         if (tnvKey !== undefined)
-                                            syncNotifiedKeys.set(tnvKey, Promise.resolve(true));
+                                            syncNotifiedKeys.set(tnvKey, Promise.resolve(true)); // stream delivered this key
                                         res.write(`data: ${JSON.stringify({ type: "task_notification", ...taskNotificationEventData(ev) })}\n\n`);
                                     }
                                 }
                                 else if (ev.type === "reasoning_delta" && typeof ev.delta === "string") {
+                                    // 🔒 E1 parity (TOC adversarial review): redact the CoT on the LIVE wire too. The agent's
+                                    // reasoning can echo a secret it read (core [R57]: CoT may carry reasoned-about secrets). The
+                                    // DURABLE path redacts it (runs.ts → redactSecrets, gated by persistThinking/TRACE_THINKING);
+                                    // the live mirror MUST match. Keep STREAMING the (redacted) thinking so live CoT still renders.
+                                    // 🔒 EXPLICIT WHITELIST, not `{...ev}` (TaskEvent 三腿审查跟进批, 1.72 task_progress lesson
+                                    // re-proven here: a spread forwards an unknown/future field RAW; this arm was the one
+                                    // sibling branch that still spread — the FORWARDED twin below [t === "reasoning_delta"]
+                                    // already used the narrow form, this now matches it byte-for-byte).
                                     res.write(`data: ${JSON.stringify({ type: "reasoning_delta", delta: redactSecrets(ev.delta), ...(ev.eventId ? { eventId: ev.eventId } : {}), ...(ev.parentToolCallId ? { parentToolCallId: ev.parentToolCallId } : {}) })}\n\n`);
                                 }
                                 else if (ev.type === "task_progress") {
+                                    // 🔒 E1 live-wire parity: explicit whitelist via the SHARED builder (UNTRUSTED
+                                    // `name` redacted; 1.78: E2 identity rides — the shell binds concurrent subagent ticks by
+                                    // eventId/parentToolCallId) — parity with the durable runs.ts + resume legs.
                                     res.write(`data: ${JSON.stringify({ type: "task_progress", ...taskProgressEventData(ev) })}\n\n`);
                                 }
                                 else if (ev.type === "compacted") {
+                                    // core 1.219 (attachWorkingFiles default ON): `compacted` now carries `attachedFiles` — route it
+                                    // through the SHARED whitelist builder (paths redactSecrets'd) instead of the raw catch-all, so
+                                    // the live wire matches the durable legs' shape exactly (one builder, no drift).
                                     res.write(`data: ${JSON.stringify({ type: "compacted", ...compactedEventData(ev) })}\n\n`);
                                 }
                                 else if (ev.type === "diagnostics") {
+                                    // core 1.220 (design/121): the shell's render source for CC's diagnostics row.
+                                    // Shared whitelist builder (§E1: language-server output UNTRUSTED RAW → redactSecrets).
                                     res.write(`data: ${JSON.stringify({ type: "diagnostics", ...diagnosticsEventData(ev) })}\n\n`);
                                 }
                                 else if (ev.type === "steering_injected") {
+                                    // [1550]/[1552]: core's mid-run system-reminder injection — shared whitelist builder
+                                    // (§E1: preview is UNTRUSTED free text → redactSecrets). Previously fell through to the
+                                    // raw catch-all below (unredacted `{...ev}`) — moved to an explicit builder for the same
+                                    // reason every other content type left the catch-all (the 1.72 task_progress lesson).
                                     res.write(`data: ${JSON.stringify({ type: "steering_injected", ...steeringInjectedEventData(ev) })}\n\n`);
                                 }
                                 else if (ev.type === "workspace_changed") {
+                                    // [1559]二 core 裁定:bash cd/EnterWorktree 移动任务逻辑 cwd 后一帧,给 shell UI 的路径
+                                    // 提示行。cwd 与已展示的工具 args 同信任级 → 共享白名单构造器(redactSecrets + bound)。
                                     res.write(`data: ${JSON.stringify({ type: "workspace_changed", ...workspaceChangedEventData(ev) })}\n\n`);
                                 }
                                 else if (ev.type === "text_delta" || ev.type === "turn_end" || ev.type === "message_committed" || ev.type === "context_usage") {
+                                    // 裸 catch-all 白名单化收官(probe-wire-1 表征钉的根治半场):最后四个已知臂离开
+                                    // `JSON.stringify(ev)`。**零字节变化**白名单——已知键(含 E2 四 identity 键:live 现状
+                                    // 带全四键,消费端可能已依赖,与 durable builder 的「刻意排除」是两腿两策)逐一挑,
+                                    // 只挡 core 未来新键的裸穿透(structured 在 1.203 就真穿透过本腿)。text_delta 的 delta
+                                    // 不做内容变换:逐 token 片段上 redactSecrets 对跨 chunk 的秘密无效还破流式——durable
+                                    // 腿攒批后 redact 是那半的正解,两腿口径注在 ledger-sink.flush。catch-all(下方 else)
+                                    // 从此只剩**真未知臂**:L1 臂集门(core-keyset-guard ⑤)在 core 加臂时 tsc 红逼显式处置。
                                     const e = ev;
                                     const ident = {
                                         ...(e.eventId !== undefined ? { eventId: e.eventId } : {}),
@@ -373,35 +679,78 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                             }
                         });
                     };
+                    // E23 + §4④: wrap the synchronous stream in the per-run elicitation AND AskUserQuestion contexts (nested
+                    // — each uses its own ALS). emit = a named SSE frame on THIS open connection; taskId keys each throttle
+                    // (the durable run id, else a synthetic internal id); owner gates the respond (the VERIFIED principal —
+                    // NOT the cost-attribution `principal`, which is the spoofable header and null on a direct door → would
+                    // park owner=null and let any tenant answer); ac.signal cancels a parked ask on client disconnect. Each
+                    // wrap is a no-op when its coordinator is off; the two share the identical id/owner/emit/signal.
                     const askTaskId = durableTaskId ?? uuidv7();
                     const askOwner = gatedPrincipal(req, deps.config) ?? null;
                     const emitAsk = (frame) => {
                         if (!res.writableEnded)
                             res.write(`event: ${frame.type}\ndata: ${JSON.stringify(frame)}\n\n`);
                     };
+                    // P1 ①②: this new turn is a stream-open for the session — push any async-workflow completions that
+                    // finished since (frames ride the SAME connection, before the run's own events; the shell dedups by
+                    // runId). `askOwner` = the VERIFIED principal → only this caller's own completions are emitted.
+                    // 🔒 THROW on a dead/ended stream instead of emitAsk's silent no-op (1.80 review: a disconnect
+                    // between request-send and this drain made the two-phase ack a FALSE success — the entry was
+                    // removed with no frame ever written; throwing keeps it pending for the next leg). Only THIS
+                    // drain wrapper throws — the shared emitAsk (question/elicit frames) keeps its no-op semantics.
+                    // 🔴 drain 案: write these as ANONYMOUS `data:` frames, NOT emitAsk's NAMED
+                    // `event: <type>` form — the run's own live-leg task_notification frames on this SAME connection
+                    // are anonymous (L1392/L1474), so a shell parsing the default message channel silently never saw
+                    // a drained frame (the Monitor "park✓ drain✗" fingerprint). question/elicit stay on emitAsk
+                    // (their own established named-event contract).
                     await emitPendingWorkflowCompletions(deps.workflowCompletionInbox, prepared.spec.sessionId, askOwner, (frame) => {
                         if (closed || res.writableEnded || res.destroyed)
                             throw new Error("stream ended before the completion frame was written");
+                        // core [784]④b: register the drained frame's key on THIS stream — the same idle-arrival was
+                        // ALSO parked core-side (pendingSessionNotifications), and its pend-drain replay lands on this
+                        // very stream as a task_notification event; the loop's key check folds that second wire copy.
+                        // codex F1: resolved(true) — the res.write below is synchronous (the dead-stream guard above
+                        // already threw). codex F2: task_type (restored from the entry extras) rides into the key —
+                        // an external notify's caller-chosen task_id must not pre-claim an internal task's key.
                         const f = frame;
                         if (f.type === "task_notification" && f.task_id)
                             syncNotifiedKeys.set(taskNotificationStreamKey({ task_type: f.task_type, task_id: f.task_id, status: String(f.status), seq: f.seq }), Promise.resolve(true));
                         res.write(`data: ${JSON.stringify(frame)}\n\n`);
-                    }, { route: "sync-stream-open", connection: "live-sse", log: (m, x) => deps.logger?.info?.(m, x) });
+                    }, 
+                    // emit-target diagnostics — this drain rides the caller's OWN live SSE response.
+                    { route: "sync-stream-open", connection: "live-sse", log: (m, x) => deps.logger?.info?.(m, x) });
                     const withElicit = deps.elicitation
                         ? () => deps.elicitation.runWithContext({ taskId: askTaskId, owner: askOwner, emit: emitAsk, abortSignal: ac.signal }, streamBody)
                         : streamBody;
                     const withQuestion = () => deps.question
                         ? deps.question.runWithContext({ taskId: askTaskId, owner: askOwner, emit: emitAsk, abortSignal: ac.signal }, withElicit)
                         : withElicit();
+                    // [816]/[820]②: the live tool-approval context — SAME id/owner/emit/signal as question/elicit
+                    // (nested ALS, each its own store). sessionId keys the "allow all edits this session" state.
+                    // [1535] 正名:本 sync 腿仍是唯一 runWithContext 包裹,但不再是子代唯一到达路——下方
+                    // spec.onAsk 的 bound 闭包经 core 继承链给了 bg/嵌套子代直达宿主流的路;真正无宿主流的
+                    // 残余腿(durable-submit/headless resume)才落 "unavailable" → durable park / core deny。
+                    // 🔒 approval 帧不用共享 emitAsk 的静默 no-op 语义:res 已结束时 no-op = 卡「假投递成功」,
+                    // coordinator 等满 TTL 落 deny —— G1 "unavailable"→park 腿在真 wiring 里就不可达(cross-review
+                    // 抓获)。这里 THROW,coordinator 的 emit-catch 按「无活人可达」返 "unavailable"(durable 部署
+                    // park;非 durable 由 core fail-closed deny,行为不劣于旧 no-op)。仅 approval 帧收紧;question/
+                    // elicit 的共享 emitAsk 保持 no-op(它们各有 TTL/abort 语义,另议)。
                     const emitApproval = (frame) => {
                         if (res.writableEnded || res.destroyed)
                             throw new Error("live stream ended — approval card undeliverable");
                         emitAsk(frame);
                     };
+                    // [1535] server 半场([1539] 定谳断点①的修):同一 ctx 双装——ALS 包裹(宿主自身 ask 的
+                    // 既有路)+ **spec.onAsk = boundAsk(ctx)**(core 1.294 继承链 parentConstraints 冻结
+                    // `spec.onAsk ?? deps.onAsk` 逐 ancestor 传给每个委派子代:bg 子代 lane 无 ALS ctx 时不再
+                    // 「unavailable/零帧 fail-closed deny」,权限卡带 sourceTaskId 浮到宿主本流)。suspendAsk
+                    // 退位条件的「onAsk 在场」真值不变(deps.onAsk 恒 wire),durable 部署行为零漂移。
                     const approvalCtx = deps.toolApproval
                         ? { taskId: askTaskId, owner: askOwner, emit: emitApproval, abortSignal: ac.signal, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) }
                         : undefined;
                     if (approvalCtx && deps.toolApproval) {
+                        // [1546] HIGH-1:闭包只携身份——emit 经 broker 取「当前」活跃流(宿主重连的新 SSE 在
+                        // runWithContext 注册时覆盖指针),internalsSnapshot 冻结的闭包不再携死 response/死 signal。
                         prepared.spec.onAsk = deps.toolApproval.boundAsk({
                             owner: askOwner,
                             taskId: askTaskId,
@@ -409,6 +758,10 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                         });
                     }
                     const withApproval = () => approvalCtx && deps.toolApproval ? deps.toolApproval.runWithContext(approvalCtx, withQuestion) : withQuestion();
+                    // SendUserFile:sync 腿 file_link 走 live out-of-band 帧面(emitAsk)。detach 车道([1840]§五
+                    // file_link 修):**同落账**——断连后 live 面写在已死 socket 上被丢,壳换道 events tail 必须
+                    // 能拿到文件卡(bg 腿本就 durable append,双腿对齐);live+durable 双写与 text/tool 帧的换道
+                    // 语义同栏(壳按换道协议处理重放)。非 detach 车道 ledgerSink 恒 undefined = live-only 字节不变。
                     await (deps.sendUserFile
                         ? deps.sendUserFile.runWithContext({
                             taskId: askTaskId,
@@ -416,33 +769,50 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                 void (await emitAsk(f));
                                 if (ledgerSink) {
                                     const { type, ...rest } = f;
-                                    await ledgerSink.append(type, rest).catch(() => undefined);
+                                    await ledgerSink.append(type, rest).catch(() => undefined); // 账本瞬断不 fault 工具面(live 帧已出)
                                 }
                             },
                         }, withApproval)
                         : withApproval());
+                    // Drive the parked run row to its terminal/suspended state (releases or keeps task_active).
                     if (durableTaskId && deps.runStore) {
+                        // R8 decouple defense-in-depth (review LOW): only KEEP the lock (setSuspended/needs_review) when
+                        // checkpointStore exists — without it there's no resume ctx, so a suspend (unreachable per durableEnabled,
+                        // but fail-safe matters) FALLS THROUGH to setTerminal which RELEASES the claim. Mirrors the sync path.
                         if (finalResult?.status === "suspended" && deps.checkpointStore)
                             await deps.runStore.setSuspended(durableTaskId);
                         else if (finalResult?.status === "needs_review" && deps.checkpointStore)
-                            await deps.runStore.setNeedsReview(durableTaskId);
+                            await deps.runStore.setNeedsReview(durableTaskId); // D-B: park a review pause, keep the lock (resumable via /plan_review)
                         else if (finalResult)
                             await deps.runStore.setTerminal(durableTaskId, finalResult.status, finalResult, finalResult.errorMessage ?? null);
                         else {
+                            // No done event observed — the client disconnected (closed → break) and ac.abort() killed the
+                            // run. Race guard: the task may have SUSPENDED right before the abort (checkpoint already
+                            // persisted, its done event unread) — a pending checkpoint outlives the abort, so park the row
+                            // suspended (session stays locked for the operator's /decide). Otherwise record an honest
+                            // failure: never "completed" for a run whose terminal state was never seen.
+                            // R8: anchor the rewind handle even on disconnect — if the user-message entryId was committed
+                            // before the Ctrl+C, the shell (holding the early run_started taskId) can still rewind to this turn.
                             putRewindAnchor();
                             const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId);
                             if (pending) {
+                                // [1.211 codex M1] detach 账本补 park 终局帧(done 未读到但 checkpoint 已在——账本没有
+                                // suspended 帧则 events tail 无终局,壳等空;gate 内容未读到 done 无从知,落 gate:null)。
                                 if (ledgerSink && !ledgerTerminal) {
                                     ledgerTerminal = true;
                                     await ledgerSink.flush().catch(() => undefined);
                                     await ledgerSink.appendParked("suspended", {}).catch(() => undefined);
                                 }
                                 await deps.runStore.setSuspended(durableTaskId);
-                                settleFleet("suspended");
+                                settleFleet("suspended"); // parked → stays in fleet as "waiting"
                             }
                             else {
+                                // codex L1 对齐:同一类用户中止(disconnect abort)不再因 iterator 正常 return / throw 而给
+                                // 两种终局形——与 throw 路兜底、resume-abort settle 同为 errorCode "cancelled" 的取消终局。
                                 const dcErr = "stream client disconnected before completion (run aborted)";
                                 const dc = { taskId: durableTaskId, sessionId: prepared.spec.sessionId ?? "", status: "failed", errorCode: "cancelled", errorMessage: dcErr, stats: { turns: 0, tokens: 0 } };
+                                // [900]① detach 车道:账本也要有终局帧(bg 腿 cancelled 终局同形;detach 下本分支仅在
+                                // generator 无 done 早收/cancel-verb 干净收尾时可达)。best-effort:落账失败不改行既有 settle。
                                 if (ledgerSink && !ledgerTerminal) {
                                     ledgerTerminal = true;
                                     await ledgerSink.flush().catch(() => undefined);
@@ -452,46 +822,66 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                 settleFleet("failed");
                             }
                         }
-                        runRowSettled = true;
+                        runRowSettled = true; // [868]③: every branch above recorded the row — the finally backstop stands down
                     }
                 }
                 finally {
-                    syncLegLive = false;
+                    syncLegLive = false; // notifications from here on take the durable-inbox path
                     if (durableHeartbeat)
                         clearInterval(durableHeartbeat);
+                    // 1.207: drop the live verb handle — IDENTITY-GUARDED (review LOW): a suspend→fast-resume can
+                    // re-register the SAME taskId from the resume leg before this finally runs; an unconditional
+                    // delete would clobber the fresh handle (verbs would 409 "another replica" until re-registration).
                     if (durableTaskId && steerableRuns.get(durableTaskId) === liveStreamRef)
                         steerableRuns.delete(durableTaskId);
+                    // [888]① same identity guard for the cancel handle (a fast-resume registers its own controller).
                     if (durableTaskId && inflightRuns.get(durableTaskId) === ac) {
                         inflightRuns.delete(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
+                        cancelledViaVerb.delete(durableTaskId); // H2 label lifecycle rides the registration
                     }
                     for (const evict of subagentHandleEvictions)
-                        evict();
+                        evict(); // design/122 ③: leg-end handle eviction (identity-guarded)
+                    // [868]③: the DURABLE twin of leak C — a throw out of the stream (abort mid-iteration / plain
+                    // Error) also skipped the run-row settle block, leaving a `running` zombie that only reapStale
+                    // would flip (after runStaleSec, as a misleading "run stalled (instance lost?)"). Settle it here:
+                    // re-read the row (a concurrent path may have settled it — then this is a no-op), honour a
+                    // suspend that raced the abort (pending checkpoint ⇒ park, the disconnect branch's exact guard),
+                    // else fail it — errorCode "cancelled" when the leg was aborted (user kill / disconnect), bare
+                    // failed for a genuine mid-stream error. Best-effort: the backstop must never mask the real throw.
+                    // 🔴 runs BEFORE the leak-C fleet backstop below (codex M3): the run-row verdict here (park vs
+                    // fail) must drive the fleet verdict — the old order settled the fleet row "failed" first and a
+                    // subsequently PARKED run row contradicted it ("waiting" run under a failed fleet row).
                     if (!runRowSettled && durableTaskId && deps.runStore) {
                         try {
                             const row = await deps.runStore.getRun(durableTaskId);
                             if (row?.status === "running") {
                                 const pending = prepared.spec.sessionId ? await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId) : undefined;
                                 if (pending) {
+                                    // [1.211 codex M1] detach 账本补 park 终局帧(finally 兜底路同款,gate 未知落 null)。
                                     if (ledgerSink && !ledgerTerminal) {
                                         ledgerTerminal = true;
                                         await ledgerSink.flush().catch(() => undefined);
                                         await ledgerSink.appendParked("suspended", {}).catch(() => undefined);
                                     }
                                     await deps.runStore.setSuspended(durableTaskId);
-                                    settleFleet("suspended");
+                                    settleFleet("suspended"); // parked → the fleet row stays honest ("waiting", disconnect-branch parity)
                                 }
                                 else if (finalResult) {
+                                    // [1.211 codex H1] done 已观测(账本/fleet 可能已按它落)但行仍 running = 首次 setTerminal
+                                    // 抖动——兜底必须重试「原终局」,绝不写 failed(否则账本 done+fleet completed+行 failed
+                                    // 三面矛盾;bg 腿 `reached` 重试同款纪律)。账本侧若 onDone 也没落成,这里补一发。
                                     if (ledgerSink && !ledgerTerminal) {
                                         ledgerTerminal = true;
                                         await ledgerSink.onDone(finalResult).catch(() => undefined);
                                     }
                                     await deps.runStore.setTerminal(durableTaskId, finalResult.status, finalResult, finalResult.errorMessage ?? null);
-                                    settleFleet(finalResult.status, fleetRunResiduals(finalResult));
+                                    settleFleet(finalResult.status, fleetRunResiduals(finalResult)); // once-guard 下通常 no-op;[1839]①/(a) 残局键同带
                                 }
                                 else if (ac.signal.aborted) {
                                     const err = "stream aborted before completion (run cancelled)";
                                     const c = { taskId: durableTaskId, sessionId: prepared.spec.sessionId ?? "", status: "failed", errorCode: "cancelled", errorMessage: err, stats: { turns: 0, tokens: 0 } };
+                                    // [900]① detach 车道:throw 路兜底同样补账本终局帧(bg 腿 catch 路 append("failed") 同形;
+                                    // ledgerTerminal 防对已落 done/park 的账本覆写 failed —— bg 腿 `reached` 同款纪律)。
                                     if (ledgerSink && !ledgerTerminal) {
                                         ledgerTerminal = true;
                                         await ledgerSink.flush().catch(() => undefined);
@@ -511,17 +901,28 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                             }
                         }
                         catch {
+                            /* best-effort — reapStale remains the last-resort net; the original throw stays the story */
                         }
                     }
+                    // C: a plain Error thrown mid-stream skipped every onTerminal branch above — settle the leaked
+                    // "running" row to "failed" before the throw propagates (no-op when any branch — incl. the [868]③
+                    // park above — already settled; settleFleet is once-guarded).
                     settleFleet("failed");
                 }
                 return { status: 200, body: finalResult };
             };
+            // B3 复审(codex HIGH):无 runStore 的部署 durableTaskId 恒缺 → 这条活流从不进 steerableRuns,
+            // inflight() 全程读 0,SIGHUP 空闲窗(以及 SIGTERM drain)会把它当空闲斩掉。整腿显式计数,
+            // 与 steerableRuns 的短暂双计无害(两者同在终局递减,>0 语义只看非零)。
             counters.uncountedBillableInflight++;
             try {
-                resp = await idemCache.run(idemKey, runStreamSubmitLeg, (r) => r.body?.status === "completed");
+                resp = await idemCache.run(idemKey, runStreamSubmitLeg, 
+                // Cache only a clean completion; a failed/aborted stream is evicted so a retry re-runs.
+                (r) => r.body?.status === "completed");
             }
             catch (e) {
+                // Log unconditionally (don't silently drop a runner error that races with the client close — council);
+                // re-throw only while the client is still connected so the outer handler can surface it.
                 deps.logger?.error("stream_error", { closed, err: e instanceof Error ? e.message : String(e) });
                 if (!closed)
                     throw e;
@@ -529,40 +930,67 @@ async function handleTasksBody(req, res, url, ctx, miss) {
             finally {
                 counters.uncountedBillableInflight--;
                 clearInterval(hb);
+                // E8 leak fence(双腿对齐的对偶):detach 腿注册过的归因键在 leg 收尾必 clear——终局 attach 已
+                // drain 过时这是幂等 no-op;errored/aborted leg 则丢掉未 drain 的累积(bg 腿 finally 同款)。
                 if (usageKey)
                     deps.modelUsage?.clear(usageKey);
             }
+            // A concurrent caller the cache deduplicated (ranLive=false) received no live events — hand it the terminal.
             if (!ranLive && resp && !res.writableEnded) {
                 res.write(`data: ${JSON.stringify({ type: "done", result: resp.body, replay: true })}\n\n`);
             }
             res.end();
         }
         else {
+            // Idempotency-Key dedup (center blocker: exactly-once billing) — concurrent + retried same-key submits
+            // share one run; the whole run+record is wrapped so metrics/cost are counted exactly once on a replay.
+            // ── B3 ── 同上:原文此处是同步腿的 **128 行匿名 async**,提为具名闭包。
             const runSyncSubmitLeg = async () => {
+                // Durable F4/ask on the sync path — same two things as the stream path (audit functional gap):
+                //  1. createRun a task_active claim at SUBMIT (+ heartbeat) so reapCtx's task_active guard protects
+                //     the ctx for the WHOLE first leg (its updated_at is stamped at submit and never refreshed; a
+                //     multi-minute leg would otherwise age it past REAP_RUN_STALE_SEC and get it reaped MID-RUN).
+                //     setSuspended on suspend keeps the claim (session locked submit→resume); setTerminal releases it.
+                //  2. putCtx AFTER the claim → a suspend here is resumable on any replica. Claim-first is load-bearing
+                //     (parity with /v1/runs): a lost claim is a 409, never a silent second leg on a locked session —
+                //     and a rejected submit must not clobber the active run's resume ctx (putCtx is sessionId-keyed).
                 let durableTaskId;
                 let durableHeartbeat;
+                // R8 (CC parity): the run-row claim + `durableTaskId` (the REWIND anchor key + the unique result.taskId
+                // re-stamp) is gated on `runStore` ALONE; the durable-suspend resume ctx (`putCtx`) on `checkpointStore`. These
+                // were bundled under ONE checkpointStore gate, which over-coupled REWIND to DURABLE_APPROVAL — but E18 resume-at
+                // needs NO checkpoint (main.ts:815). Now matches the already-decoupled /v1/runs bg path: rewind works with just
+                // runStore (DB_BACKEND=tidb/pg), no approval. Claim-first preserved (a lost claim → 409, never a silent 2nd leg).
                 if (deps.runStore && prepared.spec.sessionId) {
                     const tid = uuidv7();
                     const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
                     if (!created.ok)
                         return { status: 409, body: { error: "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)", errorCode: "conflict.session_active_run", activeTaskId: created.activeTaskId } };
-                    deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective);
+                    deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective); // fire-and-forget session auto-title
                     durableTaskId = tid;
                 }
                 if (deps.checkpointStore && prepared.spec.sessionId) {
+                    // putCtx AFTER the claim (resumable). If this throws, the claim row self-heals: no heartbeat yet → reapStale flips it failed + releases.
                     await deps.checkpointStore.putCtx(prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
                 }
+                // [888]① interactive live-run cancel, non-stream twin: this leg previously ran with NO abort seam at
+                // all (bare runTask, no spec.signal) — a cancel flipped the durable flag nothing consumed. Wire a
+                // controller through spec.signal (same seam as the stream leg's disconnect-kill) + register it in the
+                // in-flight map so the cancel fast path lands. Children reaped by this abort are a USER stop (parity
+                // with the stream leg's disconnect marker).
                 const syncCancelCtrl = new AbortController();
                 if (prepared.spec.sessionId)
                     markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, prepared.spec.sessionId, prepared.auth?.principal);
                 if (durableTaskId && deps.runStore) {
                     const rs = deps.runStore;
                     const tid = durableTaskId;
-                    const owner = principal ?? null;
+                    const owner = principal ?? null; // run created with this owner — pass it as the single-DB null-safe heartbeat guard
                     const abortFromVerb = () => {
-                        cancelledViaVerb.add(tid);
+                        cancelledViaVerb.add(tid); // H2: label the settle (errorCode "cancelled")
                         syncCancelCtrl.abort();
                     };
+                    // [1.207 codex H1] heartbeat ALSO polls the durable cancel flag (bg-leg parity) — cross-replica
+                    // cancel only sets the flag; this leg previously had no consumer.
                     durableHeartbeat = setInterval(() => {
                         void rs.heartbeat(tid, owner).catch(() => undefined);
                         if (!syncCancelCtrl.signal.aborted) {
@@ -572,6 +1000,7 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                     }, HEARTBEAT_MS);
                     durableHeartbeat.unref?.();
                     inflightRuns.set(tid, syncCancelCtrl);
+                    // [1.207 codex H1] registration-window catch-up (flag flipped during the awaited putCtx window).
                     void Promise.resolve(rs.isCancelRequested?.(tid, owner)).then((c) => { if (c && !syncCancelCtrl.signal.aborted)
                         abortFromVerb(); }).catch(() => undefined);
                 }
@@ -579,10 +1008,21 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                     inflightRuns.set(durableTaskId, syncCancelCtrl);
                 }
                 const specWithSignal = { ...prepared.spec, signal: syncCancelCtrl.signal };
+                // Developer mode (1.44): verify = adversarial verify→fix gate. Cascade (1.45): cheap→strong ladder,
+                // escalate on a failed gate (default = didn't complete). Both opt-in, mutually exclusive, multi-attempt.
                 let result;
-                let cancelVerbLabel = false;
-                counters.uncountedBillableInflight++;
+                let cancelVerbLabel = false; // [1.207 codex H2] set in the finally below while the label entry is alive
+                // E8 (shell-host contract): the SYNCHRONOUS /v1/tasks path is INTENTIONALLY excluded from the per-task `modelUsage`
+                // echo — it does NOT register() with the ModelUsageTracker, so the register-gate makes its brain.call usage a
+                // no-op (NOT a leak; the register-gate prevents the prior unbounded growth). modelUsage is the
+                // async durable /v1/runs feature (cap `modelUsage` is gated on the run store + tracker); a sync caller gets
+                // its result synchronously and reads aggregate cost from stats. (Wiring sync = register + a withModelUsage
+                // attach pass; deferred as low-value for the synchronous path.)
+                counters.uncountedBillableInflight++; // B-1: the sync await is real model work — drain must see it
                 try {
+                    // ── B3 ── 原文此处是一处三层三元,把三条模型驱动腿挤在五行里。三腿具名化后判别顺序
+                    // (verify → cascade → plain)、短路语义、传参**逐字不变**;`runWithVerification` 仍是整对象
+                    // 直传(快审 F1:cost 顶不在重建中丢失),`runCascade` 仍从操作员梯子 + 本任务预算现算配置。
                     const verifyLeg = (v) => runWithVerification(deps.runner, specWithSignal, v);
                     const cascadeLeg = () => runCascade(deps.runner, specWithSignal, cascadeConfig(deps.config.cascadeLadder, prepared.spec.maxCostUsd));
                     const plainLeg = () => deps.runner.runTask(specWithSignal);
@@ -593,36 +1033,59 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                     if (durableHeartbeat)
                         clearInterval(durableHeartbeat);
                     if (durableTaskId && inflightRuns.get(durableTaskId) === syncCancelCtrl) {
-                        inflightRuns.delete(durableTaskId);
-                        cancelVerbLabel = cancelledViaVerb.has(durableTaskId);
+                        inflightRuns.delete(durableTaskId); // [888]① identity-guarded
+                        cancelVerbLabel = cancelledViaVerb.has(durableTaskId); // H2: capture before dropping (projection below)
                         cancelledViaVerb.delete(durableTaskId);
                     }
                 }
+                // [1.207 codex H2] cancel-verb abort label (non-stream twin of the SSE done-frame projection):
+                // core's external-signal abort yields failed WITHOUT an errorCode — label it so /cancel's outcome is
+                // uniform across legs. Only an abort-shaped FAILED result; a completion that raced the abort stands.
                 if (cancelVerbLabel && result.status === "failed" && !result.errorCode) {
                     result = { ...result, errorCode: "cancelled" };
                 }
+                // E18: a resume-at caller error (a stale/non-message anchor target) comes back as a failed result carrying a
+                // resume_at.* code — a caller mistake that BILLED NOTHING. Handle it BEFORE the suspend/terminal/finalize
+                // logic below: release the submit-time claim (unlock the session) but do NOT finalizeTaskResult (it must not
+                // count as a billed failure / plan-cache miss), and return a 4xx (caller fault) instead of a 200-with-failed
+                // body. NOT idem-cached (the predicate below caches only success-range responses) — a fixed anchor can retry.
                 const resumeAtStatus = resumeAtHttpStatus(result);
                 if (resumeAtStatus) {
                     if (durableTaskId && deps.runStore)
                         await deps.runStore.setTerminal(durableTaskId, "failed", stripCheckpointToken(result), result.errorMessage ?? null);
                     return { status: resumeAtStatus, body: { errorCode: result.errorCode, error: result.errorMessage ?? "resume-at failed" } };
                 }
+                // Durable suspend on the sync path: PARK it as an async run + return a pollable taskId, NEVER the
+                // capability token. The submitter switches to GET /v1/runs/:id. Cost is recorded
+                // by the RESUMED run (mirrors runInBackground, which also parks-without-record on suspend) — not here,
+                // so the pre-suspend tokens aren't double-counted on resume.
                 if (result.status === "suspended" && deps.checkpointStore && deps.runStore && prepared.spec.sessionId) {
+                    // The submit-time row — guaranteed when runStore is present (a lost claim was 409'd before running).
                     if (durableTaskId)
                         await deps.runStore.setSuspended(durableTaskId);
                     return { status: 200, body: { taskId: durableTaskId, sessionId: prepared.spec.sessionId, status: "suspended" } };
                 }
+                // design/80 D-B: a review pause (plan_review / dry_run_review) on the sync path — PARK it like a suspend
+                // (keep task_active) + return a pollable taskId so the /v1/assistant/tasks/:id/plan_review resume can
+                // claim it. NEVER the capability token (parity with the suspended branch above).
                 if (result.status === "needs_review" && deps.checkpointStore && deps.runStore && prepared.spec.sessionId) {
                     if (durableTaskId)
                         await deps.runStore.setNeedsReview(durableTaskId);
                     return { status: 200, body: { taskId: durableTaskId, sessionId: prepared.spec.sessionId, status: "needs_review" } };
                 }
+                // Not suspended → release the submit-time claim so the session unlocks + the ctx becomes reapable.
                 if (durableTaskId && deps.runStore)
                     await deps.runStore.setTerminal(durableTaskId, result.status, stripCheckpointToken(result), result.errorMessage ?? null);
+                // A completed OR failed result both BILLED → cache it so a retry replays the outcome (no double-bill);
+                // a thrown error / transient conflict is evicted by the cache so a genuine retry re-runs. (The async
+                // /v1/runs caches only its 202 receipt — a different object, queried separately — hence the asymmetry.)
                 finalizeTaskResult(result, principal, prepared.spec.objective, prepared.spec.sessionId);
+                // A verify/cascade NESTED suspend is mapped by core to status:"failed" while still carrying the
+                // capability token (the genuine top-level suspend is parked above and never reaches here). Strip it so
+                // the resume credential never goes in the response body OR the idempotency cache.
                 return { status: 200, body: stripCheckpointToken(result) };
             };
-            const resp = await idemCache.run(idemKey, runSyncSubmitLeg, (r) => r.status < 400);
+            const resp = await idemCache.run(idemKey, runSyncSubmitLeg, (r) => r.status < 400); // cache only success-range outcomes (a completed/failed BILLED result, replay to avoid double-bill); never a session-active 409 or a resume-at 4xx (billed nothing — a retry must re-check)
             sendJson(res, resp.status, resp.body);
         }
         return;