@sema-agent/server 1.322.0 → 2.0.0

package/dist/http/routes/runs.js

@@ -11,26 +11,48 @@ import { streamSseLog } from "../sse-log.js";
 import { normalizeRunEventType } from "../../trace/project.js";
 import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+// server.ts 侧的 routeLabel / isBillableSubmitPath 仍要用下面这些正则,故本模块导出(方向恒为 server.ts → routes/*)。
 export const RUN_ID_RE = /^\/v1\/runs\/([^/]+)(\/events)?$/;
 export const RUN_CANCEL_RE = /^\/v1\/runs\/([^/]+)\/cancel$/;
 export const RUN_STEER_RE = /^\/v1\/runs\/([^/]+)\/steer$/;
 export const RUN_DETACH_RE = /^\/v1\/runs\/([^/]+)\/detach$/;
 export const RUN_COMPACT_RE = /^\/v1\/runs\/([^/]+)\/compact$/;
+// E23 (shell-host contract): the shell answers an inbound MCP elicitation here. Live-only + same-replica (the pending promise
+// is in-memory) — a respond on the wrong replica / after answer/expiry → 404, like a steer on a non-live run.
+/** PAIR-REVIEW F-10:runs 面 404 文案统一富形——a\* 形 id(background-agent registry 句柄,`a`+hex 短形)
+ *  是「结构性不在 run 店」的常客([1347]⑤ 记档裁量:不改路由,只给引导)。识别句法形即补引导;
+ *  非 a\* 形保通用富文案(cancel 腿 [888]① 同款)。 */
+/** B7(design/158):文案逐字不动,只把「体」换成「文案」——两个调用点改走 `sendError(…, "not_found.run", …)`,
+ *  机器码由发送点携带(errorCode 恒在),这样错误码门不必为「体来自 helper」的站点开豁免。 */
 function runNotFoundMessage(id) {
+    // [1434]:前缀=域判别子既成契约——wa\*(workflow agent 观测行,1.356)与 a\* 同族放宽。
     const aStar = /^(?:a|wa)[0-9a-f]{4,}$/i.test(id);
     return aStar
         ? `run not found — "${id}" looks like an agent handle (a*/wa* domain), which is never in the run store; use the TaskOutput tool (or the workflow journal / subagents surface) to read it, and the run's durable taskId (X-Task-Id) for this endpoint`
         : "run not found — the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)";
 }
 export const ELICIT_RESPOND_RE = /^\/v1\/elicitations\/([^/]+)\/respond$/;
+// §4④: the shell answers the agent's AskUserQuestion here. Same live-only + same-replica shape as elicit.
 export const QUESTION_RESPOND_RE = /^\/v1\/questions\/([^/]+)\/respond$/;
 export const TOOL_APPROVAL_RESPOND_RE = /^\/v1\/tool-approvals\/([^/]+)\/respond$/;
+// C2 (core 1.219): steer a still-running Task SUB-AGENT of a run. `:target` = the child's
+// parentToolCallId (spawn-time identity, unique) or its agentName (display name; 409 when ambiguous).
 export const RUN_SUBAGENT_STEER_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/steer$/;
+// design/122 (core 1.225): REVIVE a SETTLED sub-agent with a new prompt (CC dfe parity).
 export const RUN_SUBAGENT_RESUME_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/resume$/;
+// [1488]③(b): GET a BACKGROUND child's final report / current status (a… agent handle → core TaskRegistry,
+// the TaskOutput-tool face over HTTP; background_agent ONLY — wa… workflow-agent rows are observation
+// identities read via the workflow journal). Complements steer/resume (which cover SYNC children only).
 export const RUN_SUBAGENT_OUTPUT_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/output$/;
 export const RUN_SUBAGENT_STREAM_RE = /^\/v1\/runs\/([^/]+)\/subagents\/([^/]+)\/stream$/;
+// [1499] CC TaskOutput/TaskStop 人侧对位 — the GENERIC task-handle verbs (b* bash stdout — cursor
+// consumption depends on the handle's shape, see the handler; m* monitor batches, a* agent final report;
+// `workflow` refused — journal face owns it). SESSION-enforced from birth (new face, zero consumers):
+// a session-bound run requires the matching ?session=.
 export const RUN_TASK_OUTPUT_RE = /^\/v1\/runs\/([^/]+)\/tasks\/([^/]+)\/output$/;
 export const RUN_TASK_STOP_RE = /^\/v1\/runs\/([^/]+)\/tasks\/([^/]+)\/stop$/;
+/** The task_run SSE — a thin wrapper over `streamSseLog` that PRESERVES the existing wire shape exactly
+ *  (`data: {type, ...data}`, `event: failed` stale frame). Behavior-identical to the pre-refactor reader. */
 async function streamRunEvents(req, res, runStore, taskId, staleMs) {
     await streamSseLog(req, res, {
         statusOf: async (id) => {
@@ -39,6 +61,9 @@ async function streamRunEvents(req, res, runStore, taskId, staleMs) {
         },
         getEvents: (id, after) => runStore.getEvents(id, after),
         retainedFrom: (id) => runStore.retainedFrom(id),
+        // design/158 B2:唯一的读边界归一 —— 存量 `brain_status` 行按公开联合的名字(`status`)下发。
+        // `event:` 与 `data.type` 用**同一个**归一后的名字(此前也是同一个原始名),否则按 event 名分派的
+        // 消费端与按 data.type 分派的消费端会看到两套名字。除这一个键外全部原样透传(见 normalizeRunEventType)。
         formatEvent: (ev) => {
             const type = normalizeRunEventType(ev.type);
             return { id: ev.seq, event: type, data: { type, ...(ev.data ?? {}) } };
@@ -51,23 +76,34 @@ export async function handleRuns(req, res, url, ctx) {
     await handleRunsBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 子代理 / 任务句柄 / HITL 应答段——`handle()` 里它在 SVC-5 workflow steer **之后**,故是独立的域入口。 */
 export async function handleRunVerbs(req, res, url, ctx) {
     const miss = { fell: false };
     await handleRunVerbsBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleRunsBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints } = ctx.registry;
     const { readJson, rateLimited, quotaExceeded, leaseDenied, runOwnerOk, runSessionAcceptOk } = ctx.helpers;
     const { prepareSpec } = ctx.legs;
     const source = ctx.req.source;
+    // Async run: create + return ids immediately, execute in the background.
     if (req.method === "POST" && url === "/v1/runs") {
         if (!deps.runStore) {
             sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store (SESSION_BACKEND=tidb)");
             return;
         }
+        // Idempotency-Key dedup (center blocker): a retried create returns the SAME taskId instead of starting a
+        // second background run (= second bill). Concurrent same-key requests share the one in-flight create. The
+        // replay is checked BEFORE the rate/quota gates so a retry doesn't get a fresh 429 (council).
         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) {
@@ -75,12 +111,22 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendJson(res, resp.status, resp.body);
             return;
         }
+        // 🔴 复审 C1:NO lease gate here — it must not sit ABOVE the durable-taskId idempotency replay
+        // below, or a retry of an already-created run (dispatch-gateway failover) would get 429 instead of its
+        // existing 202 receipt, breaking the exactly-once contract. The lease admits a genuinely-NEW run only
+        // (applied just before createRun). Rate/quota stay here (cheap pre-reject; a rate-limited replay is a
+        // transient the caller retries, unlike a persistent lease exhaustion).
         if (rateLimited(req, res) || quotaExceeded(req, res))
             return;
         const prepared = await prepareSpec(req, res);
         if (!prepared)
             return;
         const runStore = deps.runStore;
+        // dispatch-gateway failover prerequisite: OPTIONAL caller-minted `body.taskId` idempotency. Unlike the
+        // Idempotency-Key header (in-memory, per-instance), this replay reads the DURABLE run store, so a gateway that
+        // re-routes a submit to ANOTHER instance after a network error cannot start a second run. uuidv7-validated
+        // (same alphabet the server mints — a caller can't inject an arbitrary PK shape); owner-gated replay mirrors
+        // the GET /v1/runs/:id gate (a foreign taskId reads as 404-shaped conflict, not another tenant's run ids).
         const rawClientTaskId = prepared.body.taskId;
         if (rawClientTaskId !== undefined && (typeof rawClientTaskId !== "string" || !isUuidV7(rawClientTaskId))) {
             sendError(res, 400, "request.id_invalid", "body.taskId must be a uuidv7 string (caller-minted idempotency key)");
@@ -92,13 +138,15 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             if (existing) {
                 const verified = verifiedPrincipal(req, deps.config);
                 if (existing.owner !== null && existing.owner !== verified) {
-                    sendError(res, 409, "conflict.run_exists", "taskId already exists");
+                    sendError(res, 409, "conflict.run_exists", "taskId already exists"); // foreign owner: conflict, no replay (no cross-tenant oracle)
                     return;
                 }
                 sendJson(res, 202, { taskId: existing.taskId, sessionId: existing.sessionId, status: existing.status });
                 return;
             }
         }
+        // 🔴 复审 C1:lease gate for a genuinely-NEW submission (past the idempotency replay above). Keyed on the
+        // VERIFIED submitter = the principal billed for this run's spend (correct principal for the sync door).
         if (await leaseDenied(req, res))
             return;
         const resp = await idemCache.run(idemKey, async () => {
@@ -106,16 +154,23 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             const taskId = clientTaskId ?? uuidv7();
             const created = await runStore.createRun(taskId, sessionId, prepared.auth?.principal ?? null, deps.instanceId ?? "default", runMeta(prepared, source));
             if (created.ok)
-                deps.sessionTitler?.maybeTitle(sessionId, prepared.spec.objective);
+                deps.sessionTitler?.maybeTitle(sessionId, prepared.spec.objective); // fire-and-forget session auto-title
             if (!created.ok) {
+                // race twin: two concurrent same-taskId submits (gateway retry racing the original) — the loser's
+                // session claim collides with ITS OWN taskId → idempotent 202 replay, not a 409 (the run exists, once).
                 if (clientTaskId && created.activeTaskId === clientTaskId) {
                     return { status: 202, body: { taskId: clientTaskId, sessionId, status: "running" } };
                 }
                 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 } };
             }
+            // Durable F4: persist the resume rebuild inputs (sessionId-keyed) so an operator can resume from any
+            // replica even after this worker is gone — core's checkpoint blob can't carry service scenario context.
             if (deps.checkpointStore) {
                 await deps.checkpointStore.putCtx(sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
             }
+            // E18 resume-at: capture each completed turn's (message eventId → leaf entryId) anchor so the shell can later
+            // rewind to that message. Closes over THIS run's sessionId/owner + the session store's getLeafId + the anchor
+            // store. undefined ⇒ no anchor store / no getLeafId (the env-only deploy) → resume-at simply isn't captured.
             const anchorOwner = prepared.auth?.principal ?? null;
             const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
             const captureTurnAnchor = deps.resumeAnchorStore && getLeafId
@@ -125,18 +180,42 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                         await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner);
                 }
                 : undefined;
+            // R8 (CC-parity rewind): the USER-message anchor — keyed by THIS run's taskId (the handle the shell holds
+            // from the 202 response), value = the user-message `entryId` straight from `message_committed{role:"user"}`
+            // (always a valid resumeAt target). No `getLeafId` (the entryId is on the event), so it works even on a
+            // store that lacks getLeafId. This is the "rewind to the prompt" target = the code-restore parity path.
             const captureUserMessageAnchor = deps.resumeAnchorStore
                 ? async (entryId) => { await deps.resumeAnchorStore.put(sessionId, taskId, entryId, anchorOwner); }
                 : undefined;
+            // MF-Fleet: a background (202) run is a durable run → it gets a live fleet row exactly like the sync leg.
+            // runInBackground fires onStart/onEvent/onTerminal across ALL its legs (verify/cascade/plain-stream). No-op
+            // when no fleetBus is wired (the publisher is a null-object).
             const fleetPub = fleetRunPublisher(deps.fleetBus, {
                 runId: taskId,
+                // 🔒 Scope the fleet row with the SAME identity GET /v1/fleet/stream FILTERS by — `gatedPrincipal`
+                // (crypto-verified on a direct door), NOT `prepared.auth.principal` (= the spoofable header). On a direct
+                // door the two diverge: a spoofed header tags 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). TOC review #6.
                 scope: gatedPrincipal(req, deps.config) ?? "default",
+                // core 1.154 nested-subagent tree: rootTaskId = the run's CANONICAL core taskId (`spec.taskId ?? sessionId`).
+                // The background leg sets `spec.taskId = taskId` (runs.ts), so canonical == taskId == runId — a forwarded
+                // subagent whose `parentTaskId` equals this nests under the run; deeper ones nest under their parent subagent.
                 rootTaskId: taskId,
-                ...fleetRunLabels(prepared.spec.objective),
+                ...fleetRunLabels(prepared.spec.objective), // BC-1: name = short objective preview (description = live-activity, set by the publisher onEvent tool_start)
             });
-            void runInBackground(deps.runner, { ...prepared.spec, sessionId }, runStore, taskId, deps.metrics, prepared.auth?.principal, prepared.verify, prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, prepared.spec.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, gatedPrincipal(req, deps.config) ?? null, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests);
+            void runInBackground(deps.runner, { ...prepared.spec, sessionId }, runStore, taskId, deps.metrics, prepared.auth?.principal, prepared.verify, prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, prepared.spec.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, // E23: per-run elicitation context (onElicit routes inbound MCP elicitations to this run's stream)
+            gatedPrincipal(req, deps.config) ?? null, // E23: the VERIFIED principal that may answer (same source the respond gate uses — never the spoofable header)
+            captureTurnAnchor, // E18: per-turn (message eventId → leaf entryId) anchor capture
+            fleetPub, // MF-Fleet: the run-scoped fleet-row publisher (onStart/onEvent/onTerminal across all legs)
+            captureUserMessageAnchor, // R8: per-prompt (taskId → user-message entryId) anchor — CC "rewind to the prompt"
+            deps.question, // §4④: per-run AskUserQuestion context (onQuestion routes the agent's asks to this run's stream)
+            deps.workflowCompletionInbox, // P1 ①② follow-on: drain pending workflow completions into this leg's durable log at start
+            deps.subagentSteerRegistry, // C2 (core 1.219): register sync-delegation steer handles under this run's taskId
+            (m, x) => deps.logger?.info?.(m, x), // emit-target diagnostics for the bg leg's inbox drain
+            deps.sendUserFile, // SendUserFile 切片2:file_link 帧走本腿 durable append
+            deps.promptManifests);
             return { status: 202, body: { taskId, sessionId, status: "running" } };
-        }, (r) => r.status === 202);
+        }, (r) => r.status === 202); // don't cache a transient 409 (session-active, billed nothing) — let a retry re-run (council)
         sendJson(res, resp.status, resp.body);
         return;
     }
@@ -147,11 +226,18 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             return;
         }
         const taskId = runMatch[1];
+        // Enforce the principal requirement BEFORE the lookup so the 401/404 ordering matches the approvals
+        // endpoint (no 404-vs-401 existence oracle for an unauthenticated caller under requirePrincipal).
+        // 🔴 F-fix: gatedPrincipal (VERIFIED), not the spoofable header. On a direct door the legit owner authenticates
+        // by the JWT (no x-agent-principal header), so a `principalFrom` presence check would 401 a VALID caller — and a
+        // spoofed header must not satisfy this gate either. Mirrors runOwnerOk's verified check below. (BFF/gated: same.)
         if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
         }
         const run = await deps.runStore.getRun(taskId);
+        // NB: `runOwnerOk` is short-circuited away when `!run`, so the unknown-run case MUST send its own
+        // response — otherwise the request never completes (hung socket, invisible to access log/metrics).
         if (!run) {
             sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
             return;
@@ -159,15 +245,25 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         if (!runOwnerOk(req, res, run.owner))
             return;
         if (!runSessionAcceptOk(req, res, run, runMatch[2] ? "run.events" : "run.poll"))
-            return;
+            return; // [1499] accept-phase
         if (runMatch[2]) {
             await streamRunEvents(req, res, deps.runStore, taskId, deps.config.runStaleSec * 1000);
         }
         else {
             const stale = run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > deps.config.runStaleSec * 1000;
+            // design/80 b (item 3): the supervisor cost surface = core's LLM costBreakdown + the service's infra axes.
+            // Only when infra pricing is configured (else the client reads stats.costBreakdown directly) AND the run is
+            // terminal with stats — reads the event log ONCE for the tool-call count + uses the run's wall-clock span as
+            // the sandbox-walltime proxy. Skipped for running/no-rate runs (no per-poll events read in the common case).
             const infraRates = deps.config.infraCostRates;
             const needCost = Boolean(run.result?.stats && !stale && infraRates && hasInfraPricing(infraRates));
+            // E12: surface post-completion prompt suggestions on the poll (the `await suggestions()` retrieval). They land
+            // as a `suggestions` event AFTER `done` (post-terminal, fire-and-forget) — so NO live events tail (which closes
+            // at the terminal status) can carry them; a poller reads them HERE once the pass settles. Only on a COMPLETED
+            // run (the sole status with suggestions), so a running poll never pays the events read.
             const needSuggestions = !stale && run.status === "completed";
+            // Read the event log ONCE if either consumer needs it (skipped for running / no-rate to avoid a per-poll read).
+            // getEvents is a RunStore staple, but guard its presence so a degraded/partial store just omits these extras.
             const events = (needCost || needSuggestions) && deps.runStore.getEvents ? await deps.runStore.getEvents(taskId, 0).catch(() => []) : undefined;
             let supervisorCost;
             if (needCost && events && run.result?.stats) {
@@ -178,8 +274,13 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             }
             let suggestions;
             if (needSuggestions && events) {
-                const sug = [...events].reverse().find((e) => e.type === "suggestions");
+                const sug = [...events].reverse().find((e) => e.type === "suggestions"); // last wins (a re-run could re-emit)
                 const arr = sug?.data?.suggestions;
+                // 🔴 **事件在场 ⇒ 已结算**,空数组必须原样透出(2026-07-26)。此前这里要求 `arr.length`,
+                // 于是「跑完了、确实一条都没有」与「还没跑完」都变成 `undefined` ⇒ **轮询方无从判断该不该停**。
+                // 与发射侧那半(`runs.ts` 此前 `if (suggestions.length)` 才 append)是同一个态被两处叠加抹平。
+                // ⚠️ 这属于本仓刚修过的**同一类**:消费方拿终态当停止条件,而数据在终态之后才到
+                // (`setTerminal` 在 suggestions 落之前)。判据统一成:事件在 = 已结算;事件不在 = 仍在跑。
                 if (Array.isArray(arr))
                     suggestions = arr.map((s) => String(s));
             }
@@ -189,7 +290,11 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 status: stale ? "failed" : run.status,
                 result: run.result ?? undefined,
                 supervisorCost,
-                suggestions,
+                suggestions, // E12: present once the post-completion pass settled (undefined while pending / if none / off)
+                // Surface the structured failure code at the top level so async-run clients (OA / team skill) can
+                // branch (auth → stop, budget.*/limit.* → quota, network·server → retry/failover) without parsing
+                // the whole result. It already lives inside the persisted result JSON — no run_store schema change.
+                // A `_stale` infra timeout is not a core error, so it carries no errorCode.
                 errorCode: stale ? undefined : (run.result?.errorCode ?? undefined),
                 error: stale ? "run stalled (instance lost?)" : run.error ?? undefined,
                 jobId: run.jobId ?? undefined,
@@ -198,12 +303,19 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         return;
     }
+    // POST /v1/runs/:id/cancel — stop a durable async run. Durable cross-replica flag (the owning instance's
+    // heartbeat tick honors it) + a same-replica AbortController fast path. Terminal = "failed"+errorCode
+    // "cancelled". Idempotent on a terminal run. [868] a SUSPENDED run is cancelled here too: settle the
+    // pending checkpoint (CAS expire) then terminalize the row — see cancelSuspended below.
     const cancelMatch = req.method === "POST" ? RUN_CANCEL_RE.exec(url) : null;
     if (cancelMatch) {
         if (!deps.runStore) {
             sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
             return;
         }
+        // Principal check BEFORE the lookup (parity with GET /v1/runs/:id): no 404-vs-401 existence oracle.
+        // 🔴 F-fix: gatedPrincipal (VERIFIED), not the spoofable header (parity with runOwnerOk below + the GET gate) —
+        // else a direct-door owner authenticating by JWT (no x-agent-principal header) is wrongly 401'd.
         if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
@@ -211,13 +323,27 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         const taskId = cancelMatch[1];
         const run = await deps.runStore.getRun(taskId);
         if (!run) {
+            // [888]① 文案:这个 face 覆盖本部署 run store 里的全部 run(bg/durable + interactive sync 腿都建行、
+            // 都注册快路)——404 只剩「id 属于别的进程/别的 store」一类(如另起的 server 进程配 in-memory store)。
             sendError(res, 404, "not_found.run", "run not found — the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)");
             return;
         }
         if (!runOwnerOk(req, res, run.owner))
-            return;
+            return; // owner mismatch → 404 (no existence oracle for non-owners)
         if (!runSessionAcceptOk(req, res, run, "run.cancel"))
-            return;
+            return; // [1499] accept-phase
+        // [868] P0: cancel of a SUSPENDED run — the user's recovery handle for a locked session. Previously a flat
+        // 409 "deny the pending approval instead", which dead-ended when the deny itself failed or was swallowed
+        // (the incident: an AskUserQuestion durable park whose shell deny was lost kept the task_active claim with
+        // ZERO release paths on the file/memory lane — every later submit on the session 409'd forever). New
+        // semantics: settle the pending checkpoint FIRST via the CheckpointStore CAS `expire` (the reaper's
+        // "≈ deny" terminal — deliberately NOT resolve/resumeCheckpoint, which would drive a model continuation:
+        // cancel means the run DIES; a deny-RESUME feeds the refusal back to the model and burns tokens against
+        // the user's intent, and denying an AskUserQuestion is incoherent anyway — the reapExpired kind-split
+        // already encodes that), THEN terminalize the run row (setTerminal releases task_active = unlocks the
+        // session). Order is load-bearing: checkpoint-first means a late approve loses the CAS and is rejected
+        // honestly by /decide; terminal-first would open the window where an approve wins the CAS on a dead row
+        // and driveResume ghosts against markResuming (safe, but a lie in two ledgers).
         const rs = deps.runStore;
         const cancelSuspended = async () => {
             const cs = deps.checkpointStore;
@@ -226,20 +352,34 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 const token = await cs.findPendingTokenBySession(run.sessionId);
                 if (token) {
                     const cp = await cs.get(token);
+                    // CAS pending→expired; `false` = a concurrent decide (or the reaper) settled the gate first.
+                    // Winning it means NO model leg can run off this gate: an approve that already won markResuming
+                    // (row=running) has its resumeStream reject on the now-expired checkpoint BEFORE any model call and
+                    // settles the row failed itself — our unconditional setTerminal below double-writes the same
+                    // terminal (harmless; claim releases once). 双腿并跑 is impossible on this path (codex H1 review).
                     const won = cp ? await cs.expire(token, cp.scope) : false;
                     if (!won) {
+                        // CAS lost — answer by the run's ACTUAL state, never pretend the cancel landed.
                         const now = await rs.getRun(taskId);
                         const st = now?.status;
                         if (st === "suspended" || st === "needs_review" || st === "running") {
+                            // 文案中性覆盖两因(复验镜头:输家可能是 decide 也可能是 reaper 的 expire——后者无人 resuming)
                             sendError(res, 409, "conflict.approval_settled", "pending approval was settled concurrently (decided or expired) — re-check the run and retry cancel if it is still active", { taskId, status: st });
                         }
                         else {
-                            sendJson(res, 202, { taskId, status: st ?? "failed", note: "run already terminal — cancel is a no-op" });
+                            sendJson(res, 202, { taskId, status: st ?? "failed", note: "run already terminal — cancel is a no-op" }); // idempotent
                         }
                         return;
                     }
                 }
                 else {
+                    // NO pending token. Two very different worlds share this face (codex H1):
+                    //  (a) the lockup fingerprint — deny lost / checkpoint expired-or-reaped, row parked forever;
+                    //  (b) a concurrent approve ALREADY resolved the checkpoint and its resume leg is running — an
+                    //      unconditional setTerminal here would kill/orphan that leg AND release the claim (双腿并跑).
+                    // Disambiguate with the SAME CAS the resume path uses: markResuming flips ONLY a suspended row.
+                    // Winning it = no resume leg exists nor can start (approve's own markResuming will now lose) — the
+                    // row is OURS to terminalize. Losing it = answer by the run's actual state, never pretend.
                     const claimed = await rs.markResuming(taskId);
                     if (!claimed) {
                         const now = await rs.getRun(taskId);
@@ -248,7 +388,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                             sendError(res, 409, "conflict.approval_settled", "pending approval was settled concurrently (decided or expired) — re-check the run and retry cancel if it is still active", { taskId, status: st });
                         }
                         else {
-                            sendJson(res, 202, { taskId, status: st ?? "failed", note: "run already terminal — cancel is a no-op" });
+                            sendJson(res, 202, { taskId, status: st ?? "failed", note: "run already terminal — cancel is a no-op" }); // idempotent
                         }
                         return;
                     }
@@ -256,15 +396,23 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 }
             }
             else {
+                // Minimal deployments without a checkpoint store: the run row is the only ledger — release it, say so.
                 note = "cancelled while suspended (no checkpoint store on this deployment — run row terminalized only)";
             }
+            // Run-row terminal AFTER the checkpoint settle. Two ledgers, no silent tear: if this write fails after
+            // the checkpoint already expired, report exactly how far the cancel got — a retry takes the
+            // no-pending-token path above and completes the release (idempotent recovery). The row's error text
+            // = the SAME per-path truth as the response note (a stale-park release must not claim it settled a gate).
             const err = note;
             try {
                 const result = { taskId, sessionId: run.sessionId, status: "failed", errorCode: "cancelled", errorMessage: err, stats: { turns: 0, tokens: 0 } };
+                // [888] 低危残账修:撕裂窗自愈——checkpoint 已 settle 后 setTerminal 一次瞬时失败(store 抖动)曾直接
+                // 500,把释放推给 reapStale 的整个 stale 窗(no-token 路的重试读到 running 只会挂 requestCancel 旗,
+                // 无人消费)。这里就地有界重试(2 次退避)把瞬时抖动吞掉;仍然失败才 500 交 reapStale 兜底。
                 let lastErr;
                 for (let attempt = 0;; attempt++) {
                     try {
-                        await rs.setTerminal(taskId, "failed", result, err);
+                        await rs.setTerminal(taskId, "failed", result, err); // TaskStatus has no 'cancelled' member — failed + errorCode 'cancelled' is the codebase-wide cancel terminal (same shape as the resume-abort settle)
                         lastErr = undefined;
                         break;
                     }
@@ -279,9 +427,14 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                     throw lastErr;
             }
             catch (e) {
+                // 文案与 note 同源(复验镜头:no-token/无 cs 路没有 settle 任何 gate,固定文案会失真);另注:
+                // no-token 路的重试会读到 running 走 requestCancel 旗,实际释放由 reapStale 兜底(有界延迟)。
                 sendError(res, 500, "internal.cancel_not_terminalized", `cancel progressed (${note}) but could not terminalize the run row (retried) — retry cancel; a stuck row is reaped after the stale window (${e instanceof Error ? e.message : String(e)})`, { taskId });
                 return;
             }
+            // [1.207 codex M2] setTerminal 是 void 且 first-writer-wins 后 CAS 写打空不抛——退避窗内 reaper/
+            // 并发腿可能先终态化(如 approval.expired),我方写打空却仍答 "cancelled" 就是响应与账本不一致。
+            // 写后复读,照实际行应答(锁一样释放了;谁先写赢谁的 errorCode)。
             const finalRow = await rs.getRun(taskId).catch(() => undefined);
             if (finalRow && finalRow.errorCode !== "cancelled" && (finalRow.status === "failed" || finalRow.status === "completed" || finalRow.status === "blocked" || finalRow.status === "timeout")) {
                 sendJson(res, 202, { taskId, status: finalRow.status, errorCode: finalRow.errorCode ?? null, note: `session unlocked; the run was terminalized concurrently (${finalRow.errorCode ?? finalRow.status}) before this cancel's write — reporting the actual ledger state` });
@@ -290,17 +443,22 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendJson(res, 202, { taskId, status: "failed", errorCode: "cancelled", note });
         };
         if (run.status === "running") {
-            const flagged = await deps.runStore.requestCancel(taskId, run.owner);
+            // Durable flag FIRST (only flips a still-running row), abort after: if the run suspended/terminal'd
+            // between the getRun above and here, the flag write affects 0 rows — re-read and answer by the run's
+            // ACTUAL state instead of lying "cancelling" about a run nothing will cancel.
+            const flagged = await deps.runStore.requestCancel(taskId, run.owner); // owner guard: single-DB defense-in-depth (HTTP gate already passed runOwnerOk)
             if (!flagged) {
                 const now = await deps.runStore.getRun(taskId);
                 if (now?.status === "suspended") {
-                    await cancelSuspended();
+                    await cancelSuspended(); // [868] lost race INTO suspended — same recovery handle as the direct branch
                 }
                 else {
                     sendJson(res, 202, { taskId, status: now?.status ?? "failed", note: "run already terminal — cancel is a no-op" });
                 }
                 return;
             }
+            // fast path: cancel landed on the running instance → abort now. Label FIRST ([1.207 codex H2]) so the
+            // interactive legs' settle projection sees the verb origin (bg legs already write "cancelled" themselves).
             if (inflightRuns.has(taskId)) {
                 cancelledViaVerb.add(taskId);
                 inflightRuns.get(taskId).abort();
@@ -308,27 +466,53 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendJson(res, 202, { taskId, status: "cancelling" });
         }
         else if (run.status === "suspended" || run.status === "needs_review") {
+            // [868] settle the pending gate + terminalize + unlock (was a flat 409 dead-end). needs_review rides the
+            // SAME handle (codex M1): a plan-review park holds the claim identically and the old else branch lied
+            // "already terminal" about it (claim never released).
             await cancelSuspended();
         }
         else {
-            sendJson(res, 202, { taskId, status: run.status, note: "run already terminal — cancel is a no-op" });
+            sendJson(res, 202, { taskId, status: run.status, note: "run already terminal — cancel is a no-op" }); // idempotent
         }
         return;
     }
+    // POST /v1/runs/:id/steer — inject a mid-task steering message (CC-parity "运行中插话", design/47 + design/80
+    // D-A). Delivery is picked by the run's CURRENT state, surfaced via the status code (matching the spec):
+    //   • in-flight on THIS replica (a live core TaskStream in `steerableRuns`) → `stream.steer()` queues the
+    //     message into the harness, drained at the next turn boundary → 200 (applied).
+    //   • durably SUSPENDED (any replica) → `setPendingSteer` parks it on the pending checkpoint, injected by core
+    //     on the resume continuation → 202 (queued).
+    //   • running on ANOTHER replica (not live here, status "running") → 409 steering.not_running. Cross-replica
+    //     live-steer (a durable steer-signal + heartbeat poll, mirroring cancel_requested/preempt_requested) is a
+    //     fast-follow — single-replica-per-worker deployment today, so the live + parked paths cover the headline
+    //     use case; this branch is the honest seam, never a silent drop.
+    //   • terminal (done/failed/cancelled/needs_review) → 409 steering.not_running.
+    // Content carrying a `</system-reminder>` break-out or control chars → 422 steering.invalid_content, validated
+    // ONCE up front with core's `validatePendingSteer` (the same validator setPendingSteer runs) so the 422 is
+    // consistent across both delivery paths — deliberately STRICTER than core's live path (which would sanitize an
+    // untrusted break-out at injection rather than reject it), trading that edge case for a uniform wire contract.
     const steerMatch = req.method === "POST" ? RUN_STEER_RE.exec(url) : null;
     if (steerMatch) {
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-            return;
+            return; // mutating + hits TiDB / runs the model
         if (!deps.runStore) {
             sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
             return;
         }
+        // Per-tenant identity MUST come from gatedPrincipal (direct-door secure single point), NOT principalFrom:
+        // `trusted` carries OPERATOR authority (a trusted steer may ride a <system-reminder>), so deriving it from a
+        // spoofable header on a direct-door worker would be a privilege escalation (HANDOFF 铁律 + core §3 inv #1).
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
         }
         const taskId = steerMatch[1];
+        // Parse + validate the REQUEST before the run lookup: a bad body is the caller's error regardless of run
+        // state, and validating once here (not per delivery path) keeps 400/422 identical whether the run is live or
+        // suspended. `text` required non-empty; `mode` (CC `--steering-mode`) is accepted + enum-checked but a v1
+        // no-op — core's public TaskStream.steer takes only { trusted } today (harness steeringMode is build-time),
+        // so per-call mode is forward-draft pending core wiring (raised to core).
         let body;
         try {
             body = (await readJson(req));
@@ -345,16 +529,23 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.field_invalid", "mode must be 'all' or 'one-at-a-time' when present");
             return;
         }
+        // E15 (shell-host contract): per-message queue priority. Accepted + enum-validated FAIL-LOUD, but ADVISORY
+        // today — core's steer is single-slot last-writer-wins with no per-message priority / addressable drop, so the
+        // faithful priority queue + DELETE /v1/runs/:id/queue/:messageId wait on a core seam (raised to core).
         if (body.priority !== undefined && body.priority !== "now" && body.priority !== "next" && body.priority !== "later") {
             sendError(res, 400, "request.field_invalid", "priority must be 'now', 'next', or 'later' when present");
             return;
         }
         const text = body.text;
         const priority = body.priority;
+        // Mint a server-side messageId so the shell can reference this steer (its drop handle once the core queue seam
+        // lands). Honest + stable now even while `priority` is a no-op forward-draft.
         const messageId = uuidv7();
+        // trusted = explicit operator (NOT bare isOperator — its empty-list "true-for-all" would let any caller send a
+        // system-authority steer). A normal owner's steer reaches the model as a plain user message (trusted:false).
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         try {
-            validatePendingSteer({ text, trusted });
+            validatePendingSteer({ text, trusted }); // throws CheckpointError(steering.invalid_content) on break-out / control chars
         }
         catch (e) {
             if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
@@ -368,12 +559,19 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
             return;
         }
+        // Owner-gate (parity with preempt): an EXPLICIT operator may steer any tenant's run (supervisor intervention);
+        // a normal caller only its own. 404 (not 403) for a non-owner — no existence oracle.
         if (!trusted && run.owner !== null && run.owner !== principal) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
         if (!runSessionAcceptOk(req, res, run, "run.steer"))
-            return;
+            return; // [1499] accept-phase
+        // Durable-park helper: land the steer on this session's PENDING checkpoint. The checkpoint table — not the run
+        // row — is the AUTHORITY: core writes the pending checkpoint during a suspend (before the service flips the run
+        // row to "suspended"), and CASes on `status='pending'`, so this lands iff the run is genuinely parked. Read the
+        // checkpoint's ACTUAL scope ("_" for a no-principal run) then its token; a missing scope/token/CAS-loss means
+        // the checkpoint resolved/expired/never-existed → "no-checkpoint". "no-store" = no checkpoint store wired.
         const tryPark = async () => {
             const cs = deps.checkpointStore;
             if (!cs)
@@ -388,6 +586,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         };
         const sendParked = () => sendJson(res, 202, { taskId, status: "suspended", delivery: "queued", messageId, ...(priority ? { priority } : {}), note: "steer parked on the checkpoint — injected when the run resumes" });
         const sendNotRunning = (error) => sendError(res, 409, "steering.not_running", error);
+        // (a) Same-replica live path: the run is streaming here → inject now (drained at the next turn boundary).
         const live = steerableRuns.get(taskId);
         if (live) {
             try {
@@ -402,7 +601,10 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                     return;
                 }
                 if (code !== "steering.not_running")
-                    throw e;
+                    throw e; // unexpected → outer handler 500
+                // Raced: the stream finished between the map lookup and steer(). It may have durably SUSPENDED in the SAME
+                // tick (core already wrote the pending checkpoint) — fall through to the durable park rather than a spurious
+                // 409 (the live→suspended transition window). Only a genuinely-terminal run → not_running.
                 if (await tryPark() === "parked") {
                     sendParked();
                     return;
@@ -411,6 +613,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 return;
             }
         }
+        // (b) Durably suspended → park the steer on the pending checkpoint (drained on resume).
         if (run.status === "suspended") {
             const outcome = await tryPark();
             if (outcome === "no-store") {
@@ -424,16 +627,27 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendNotRunning("run is no longer suspended (resolved or expired)");
             return;
         }
+        // (c) running-elsewhere (cross-replica, fast-follow seam) → not_running.
         if (run.status === "running") {
             sendNotRunning("run is active on another replica — cross-replica live-steer is not yet supported");
             return;
         }
+        // (d) design/144 wake 半场(core 1.283):TERMINAL run + steer = 不再一律 409——铸一个部署侧
+        // task_done 纯 park checkpoint(PendingAction {kind:"task_done"},deployment-minted per [770]①c),
+        // 把消息 park 上去,等 POST /v1/sessions/:id/wake({gate:"wake"})把它作为续跑首轮输入消费。
+        // 先 tryPark:session 若已有 pending checkpoint(needs_review park / 先前铸的 wake park)直接park上去,
+        // 绝不双铸(一 session 一 pending 不变式)。铸造前置=checkpoint store + session leaf(leafId 锚续跑);
+        // 缺任一 = 原 409 契约(env-only/无树面诚实拒绝)。
         if (deps.checkpointStore && deps.sessionStorage?.getLeafId) {
+            // 复审 MED(陈旧 run 守卫):目标 run 终态但同 session 另有 ACTIVE run(claim 在)时,消息该去
+            // 活 run(live steer / suspended park),给这条旧终态 run 铸 park 只会造出基于活 leaf 的陈旧
+            // checkpoint + wake 撞 markResuming 409。诚实拒绝并指路。
             const activeTaskId = await deps.runStore.getActiveTaskId?.(run.sessionId).catch(() => undefined);
             if (activeTaskId !== undefined && activeTaskId !== null && activeTaskId !== taskId) {
                 sendNotRunning(`run is ${run.status} and its session has an ACTIVE run (${activeTaskId}) — steer that run instead`);
                 return;
             }
+            // per-session 串行(复审 HIGH:并发双终态 steer 的 tryPark→put 窗口双铸两个 pending park)。
             const prior = wakeParkMints.get(run.sessionId) ?? Promise.resolve();
             const mintResult = { parked: false };
             const job = prior.then(async () => {
@@ -441,11 +655,11 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 if (await tryPark() === "parked") {
                     mintResult.parked = true;
                     return;
-                }
+                } // 锁内重查:前一位刚铸完 → 直接 park 上去
                 const leafId = await Promise.resolve(deps.sessionStorage.getLeafId(run.sessionId)).catch(() => undefined);
                 if (leafId === undefined || leafId === null)
                     return;
-                const cpScope = run.owner ?? "_";
+                const cpScope = run.owner ?? "_"; // 匿名提交哨兵,与 main.ts putCtx 的 principal ?? "_" 同域
                 const wakeToken = mintCheckpointToken();
                 await cs.put(wakeToken, {
                     token: wakeToken,
@@ -459,6 +673,8 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                     createdAt: Date.now(),
                     sourceTaskId: taskId,
                 });
+                // 跨副本纵深:put 后复核赢家——若另一副本抢先铸了别的 pending,expire 我方孤儿并把消息
+                // park 到赢家上(收敛到单 park;店无序时收敛到店的稳定扫描序,残窗如实记 fast-follow)。
                 const winner = await cs.findPendingTokenBySession(run.sessionId).catch(() => null);
                 if (winner !== null && winner !== wakeToken) {
                     await cs.expire(wakeToken, cpScope).catch(() => undefined);
@@ -475,6 +691,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                 await job;
             }
             finally {
+                // 链尾自清:没有更晚的排队者(Map 仍指向本包装)才删,防长期泄漏;有排队者则由其链尾清。
                 if (wakeParkMints.get(run.sessionId) === wrapped)
                     wakeParkMints.delete(run.sessionId);
             }
@@ -486,15 +703,20 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         sendNotRunning(`run is ${run.status} — not accepting steers`);
         return;
     }
+    // K-1c (shell-host §K): POST /v1/runs/:id/compact — MANUAL compaction (un-greys the shell's `/compact`). core
+    // 1.156 added `TaskStream.compact()`: it forces a compaction at the next SAFE turn boundary (never mid-turn) and
+    // emits `compacted{trigger:"manual"}` on the run's OWN stream (the result rides that stream, like steer). So this
+    // verb only applies to a run LIVE on THIS replica (`steerableRuns`); a suspended/terminal/other-replica run has no
+    // live stream + there is NO durable "pending compact" in core (unlike steer's setPendingSteer) → 409.
     const compactMatch = req.method === "POST" ? RUN_COMPACT_RE.exec(url) : null;
     if (compactMatch) {
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-            return;
+            return; // mutating + runs the model (compaction summarizes)
         if (!deps.runStore) {
             sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
             return;
         }
-        const principal = gatedPrincipal(req, deps.config);
+        const principal = gatedPrincipal(req, deps.config); // direct-door-secure identity, never the spoofable header
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
@@ -505,15 +727,22 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
+        // Owner-gate (parity with steer/preempt): an explicit operator may compact any tenant's run; a normal caller
+        // only its own. 404 (not 403) for a non-owner — no existence oracle.
         const operator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         if (!operator && run.owner !== null && run.owner !== principal) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
         if (!runSessionAcceptOk(req, res, run, "run.compact"))
-            return;
+            return; // [1499] accept-phase
+        // core 1.293:compact(opts) 收 { instructions?, signal? }。instructions=壳 /compact 的定向摘要指令,
+        // 此处 additive 透传(空 body/无字段=现状);signal(取消腿)不在本 verb——取消需要独立动词+
+        // per-pending AbortController 台账,等壳侧 UX 契约定形再开(先到先记:[853] 知会件)。
+        // 校验在 live 查找之前(steer 同纪律):400 形状不依赖运行态,live/非 live 一致。
         let compactBody;
         try {
+            // HttpError(413 request body too large)原样透传,不降级成语义错误的 400(交叉评审 L5)
             const parsed = await readJson(req);
             if (parsed === null || typeof parsed !== "object") {
                 sendError(res, 400, "request.invalid_json", "body must be a JSON object when present");
@@ -529,6 +758,9 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.invalid_json", "invalid JSON body");
             return;
         }
+        // 上限=core COMPACTION_INSTRUCTIONS_MAX_CHARS(2048 码点,auto-compaction.js:9;超长 core 会静默
+        // 截断)——HTTP 面按同口径拒收,fail-loud 而非 202 后半截指令悄悄丢(交叉评审 M1)。码点计数与
+        // core 同形([...s] 展开),防代理对 emoji 类双单元字符的错杀/漏杀。
         if (compactBody.instructions !== undefined && (typeof compactBody.instructions !== "string" || compactBody.instructions.length === 0 || [...compactBody.instructions].length > 2_048)) {
             sendError(res, 400, "request.field_invalid", "instructions must be a non-empty string of at most 2048 characters (code points) when present — the engine caps compaction instructions there");
             return;
@@ -539,10 +771,28 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendError(res, 409, "compact.not_running", run.status === "running" ? "run is active on another replica — manual compact is replica-local" : `run is ${run.status} — not accepting compaction`);
             return;
         }
-        void live.compact(compactInstructions !== undefined ? { instructions: compactInstructions } : undefined).then((outcome) => {
+        // FIRE-AND-FORGET 202 (review): `compact()` resolves only once PROCESSED at the next SAFE turn boundary — which
+        // can be a whole in-flight turn away — so awaiting it would hold the HTTP connection (gateway-timeout risk + poor
+        // UX). Ack "accepted" immediately; the compaction runs at the boundary and a `compacted{trigger:"manual"}` event
+        // rides the run's OWN stream (which the client already consumes — this matches the shell's `compacting%` spinner
+        // waiting on that event). A NO-OP compaction (nothing to summarize) emits NO event (so the shell must time out its
+        // spinner, not block forever). Swallow the benign race where the stream finished between the lookup and the call
+        // (steering.not_running) + any compact error — best-effort; failure surfaces as the absence of the event, the user
+        // can retry. (core guarantees compact() never hangs — it resolves by task end at the latest.)
+        void live.compact(compactInstructions !== undefined ? { instructions: compactInstructions } : undefined).then(
+        // core 1.257 (MF-18 BREAKING): compact() now RESOLVES WITH a CompactOutcome instead of void
+        // — "processed" alone was silent when the attempt failed or was mooted (the 202-then-silence fingerprint).
+        // Consume the outcome: "compacted" is the only one that emits a `compacted{trigger:"manual"}` event on the
+        // stream; the other five (failed/mooted/noop/blocked/disabled) each have a `compaction.*` trace counterpart
+        // and produce NO event, so the shell's spinner must fall through. Log the discriminated outcome so a
+        // "202 → no event" incident reads its reason straight from the log (not a service-wire-vs-core guess).
+        (outcome) => {
             const level = outcome === "failed" ? "warn" : "info";
             deps.logger?.[level]?.("manual_compact_outcome", { taskId, outcome, note: outcome === "compacted" ? "a compacted{trigger:'manual'} event rode the run stream" : `no event (see compaction.${outcome === "mooted" ? "mooted" : outcome} trace / task terminal events)` });
         }, (e) => {
+            // The not_running rejection was fully silent — correct for the benign settle race it was
+            // designed for, but a SYSTEMATIC not_running (e.g. a verb/handle mismatch on one lane) then has zero
+            // observability. Keep it non-warn (it IS usually benign) but leave a fingerprint.
             if (e.code !== "steering.not_running") {
                 deps.logger?.warn?.("manual_compact_failed", { taskId, err: e instanceof Error ? e.message : String(e) });
             }
@@ -553,15 +803,25 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         sendJson(res, 202, { taskId, status: "running", delivery: "accepted", note: "compaction will run at the next turn boundary; a compacted{trigger:'manual'} event rides the run stream if anything is summarized" });
         return;
     }
+    // core 1.207 (design/116 detach, CC mid-flight ctrl+b): POST /v1/runs/:id/detach {toolCallId} —
+    // move a RUNNING tool call to the background via `TaskStream.detach(toolCallId)`. Route (a) of the sync-leg
+    // detach verb design ((b)'s durable-leg fallback
+    // is blocked on TOC-local having no runStore). Core semantics: fire-and-forget + race-safe (a request landing
+    // before the tool reads its signal still detaches; after it finished = no-op; unknown toolCallId = no-op) —
+    // the detached Bash settles early with "moved to background; task_id=b*" + a `{type:"bash", detached:true}`
+    // structured card, and the G2b completion notification/spool take over. Only a detach-capable env honors it
+    // (`backgroundCapabilities.supportsDetach`; TOB envs ignore = fail-safe). Like compact, this verb is LIVE-only
+    // (replica-local `steerableRuns` handle — the sync leg now registers too): a suspended run has no running tool
+    // and there is no durable "pending detach" → 409.
     const detachMatch = req.method === "POST" ? RUN_DETACH_RE.exec(url) : null;
     if (detachMatch) {
         if (rateLimited(req, res))
-            return;
+            return; // mutating, but runs no model (no quota gate — parity with cancel, not steer)
         if (!deps.runStore) {
             sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
             return;
         }
-        const principal = gatedPrincipal(req, deps.config);
+        const principal = gatedPrincipal(req, deps.config); // direct-door-secure identity, never the spoofable header
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
@@ -576,6 +836,10 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             return;
         }
         if (typeof body.toolCallId !== "string" || body.toolCallId.length === 0 || body.toolCallId.length > 256) {
+            // 🔒 The length cap is load-bearing (review MEDIUM): core's ToolDetachHub.request() is create-then-abort —
+            // an UNKNOWN id still allocates + retains a Map entry (keyed by the raw string) for the run's lifetime
+            // (gc only fires from a real tool's completion), so unbounded ids = per-run memory growth on a shared
+            // replica. Real core toolCallIds are short; 256 is generous.
             sendError(res, 400, "request.body_shape", "body must be { toolCallId: string (non-empty, ≤256 chars) }");
             return;
         }
@@ -584,27 +848,50 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
+        // Owner-gate (parity with steer/compact): an explicit operator may detach on any tenant's run; a normal
+        // caller only its own. 404 (not 403) for a non-owner — no existence oracle.
         const operator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         if (!operator && run.owner !== null && run.owner !== principal) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
         if (!runSessionAcceptOk(req, res, run, "run.detach"))
-            return;
+            return; // [1499] accept-phase
         const live = steerableRuns.get(taskId);
         if (!live) {
             sendError(res, 409, "detach.not_running", run.status === "running" ? "run is active on another replica — detach is replica-local" : `run is ${run.status} — no running tool call to detach`);
             return;
         }
+        // Fire-and-forget by CONTRACT (`detach(toolCallId): void`) — race-safety is core's; the outcome surfaces on
+        // the run's OWN stream (the early-settled tool_end with the `detached:true` structured card, then the b* task
+        // notification), which the client already consumes. 202 = "requested", honest about no confirmation here.
         live.detach(body.toolCallId);
         sendJson(res, 202, { taskId, toolCallId: body.toolCallId, delivery: "requested", note: "if the tool call is running in a detach-capable env it settles early with 'moved to background; task_id=b*'; otherwise the request is a no-op (fail-safe)" });
         return;
     }
     miss.fell = true;
 }
+/** 同上纪律(子代理 / 任务句柄 / HITL 应答段)。 */
 async function handleRunVerbsBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode, runSessionAcceptOk } = ctx.helpers;
+    // C2 (core 1.219) + design/122 (core 1.225): the Task-SUB-AGENT verbs of a run —
+    //   POST /v1/runs/:runId/subagents/:target/steer  — inject fenced guidance into a STILL-RUNNING child;
+    //   POST /v1/runs/:runId/subagents/:target/resume — REVIVE a SETTLED child with a new prompt (CC dfe parity;
+    //     always async: the revived child runs in the background on its retained session, completion announced
+    //     via the deployment notify sink — requires the parent run to have set `retainSubagentSessions`).
+    // Shared plumbing (one trust gate): addressed by the PARENT run's taskId + the child's parentToolCallId (or
+    // agentName when unambiguous); replica-local handle registry (the legs' `onSubagentSpawn` sink; design/122 ③
+    // handles now live until LEG END, not child settle — resume is only legal after settle); owner-gated via the
+    // parent run row; content through `redactSteerIn`. 🔐 `handle.childSessionId` is a continuation capability
+    // — never in any response. Sync delegations only (core r1-M3: bg children have no handle).
+    // [1488]③(b): GET /v1/runs/:runId/subagents/:handle/output — the BACKGROUND child read face. The shell's
+    // fleet viewer gets bg_notification summaries only; the child's FINAL assistant body lives in the core
+    // TaskRegistry (what the TaskOutput tool reads). Auth = the runs-face read pattern (verified principal →
+    // owner-gate via the parent run row → honest 404, no existence oracle); access into the registry is the
+    // REGISTRATION tuple derived from the run row (owner=runId | sessionScoped via sessionId, scope=run
+    // owner ?? "default") — NEVER caller-supplied. Replica-local (the registry is in-process, like steer);
+    // non-blocking read: a still-running child returns its current status honestly, no long-poll (v1).
     const subOutputMatch = req.method === "GET" ? RUN_SUBAGENT_OUTPUT_RE.exec(url) : null;
     if (subOutputMatch) {
         if (!deps.runStore || !deps.subagentTaskOutput) {
@@ -628,6 +915,22 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
+        // [1493] SESSION-scoped content read. principal answers "is this your data at all" (whose); session
+        // answers "which conversation" (which). This verb returns CONVERSATION CONTENT (a child's final body), so
+        // the principal owner-gate above is necessary but NOT sufficient: under a SHARED principal (single-user
+        // multi-shell — the default local posture, and any tenant that shares an identity) it passes for every
+        // co-principal shell, so a SIBLING session could read another conversation's child (clay's dual-shell
+        // repro). The run belongs to a conversation (run.sessionId); a non-operator caller must PROVE it owns that
+        // conversation by asserting the matching `?session=`. Threat model is ACCIDENTAL cross-read within one
+        // user's own shells (no adversary — the shell honestly reports its own session), so an honest
+        // caller-asserted session is correct AND sufficient here (no unguessable capability needed). fable5 R1
+        // (deliberate boundary, do not "harden" this into a capability): yes, a co-principal caller COULD forge the
+        // target's session — but co-principal means the SAME authz identity, i.e. the same user reading their own
+        // data through another window; session is a content-ROUTING axis inside one principal, not an authz wall.
+        // Deployments with genuinely different humans MUST give them distinct principals (requirePrincipal) — the
+        // principal owner-gate above is the security boundary, and it runs first. An
+        // operator/trace caller bypasses (as it does the owner-gate). A run with no sessionId is not
+        // conversation-bound → principal gate only. Fail-CLOSED: a session-bound run with no/mismatched assertion → 404.
         const callerSession = new URL(req.url ?? "", "http://x").searchParams.get("session");
         if (!trusted && run.sessionId && callerSession !== run.sessionId) {
             sendError(res, 404, "not_found.run", "run not found");
@@ -635,13 +938,28 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         const out = await deps.subagentTaskOutput(target, { owner: runId, scope: run.owner ?? "default", ...(run.sessionId ? { sessionId: run.sessionId } : {}) });
         const details = out.details;
+        // codex R1 (type gate): pollTask is the GENERIC registry face — same-tuple b*/m*/w* handles (bash
+        // stdout, monitor batches, workflow projections) would ride this verb otherwise, a broader egress
+        // than the documented agent-final-output contract. Only `background_agent` passes; everything else
+        // gets the SAME indistinguishable 404 (unknown / not-yours / wrong-kind — no oracle). wa* workflow-
+        // agent rows are OBSERVATION identities (never in the registry) — their read face is the workflow
+        // journal (GET /v1/workflows/:id/journal), and they land in the not_found arm here by construction.
         if (details?.error === "not_found" || details?.type !== "background_agent") {
             sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
             return;
         }
+        // Pass the registry's honest projection through: status/retrieval_status/partial flags verbatim,
+        // `content` = the TaskOutput-tool text (the child's final assistant body once terminal). UNTRUSTED
+        // model output, same posture as the runs face's `result`.
         sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details });
         return;
     }
+    // S2([1520]{core} 提货,core 1.370 `bgAgentId`):GET /v1/runs/:id/subagents/:handle/stream —— per-agent
+    // **live tail**(SSE)。「replay+tail」的 tail 半场:replay/终报=上面的 output 面(durable 臂 1.250),
+    // 本面=从连接时刻起的 content 帧(text/reasoning delta、tool_start/end、task_progress——投影与 sync 主流
+    // forward 分支同 builder 同纪律,subagent-tail-bus.ts 顶注)。帧只在宿主 run 所在副本产生 ⇒ live 帧
+    // replica-local(meta 如实声明;他实例 running 的行=只 heartbeat,不虚构)。门=output 面逐字同形
+    // (principal→owner→session fail-closed;a* 形判;探测经同 seam,未知/非本 run/型错=同 404 无 oracle)。
     const subStreamMatch = req.method === "GET" ? RUN_SUBAGENT_STREAM_RE.exec(url) : null;
     if (subStreamMatch) {
         if (!deps.runStore || !deps.subagentTaskOutput) {
@@ -665,12 +983,19 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
+        // [1493] session 门(output 面同注,出生即强制——新面零消费者无软拍需要)。
         const callerSession = new URL(req.url ?? "", "http://x").searchParams.get("session");
         if (!trusted && run.sessionId && callerSession !== run.sessionId) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
+        // 🔴 cli[1524] HIGH-2:**subscribe 先行,probe 在后**——原序(probe await→meta→subscribe)在
+        // probe 与 subscribe 之间留竞态窗:窗内子代 settle → task_settled 发布时无订阅者被丢(总线无
+        // replay/sticky)→ 订阅者只收 heartbeat 永挂。先建订阅,窗内 settle 自然落进队列;probe 判 404
+        // 时 it.return() 清订阅(未写任何帧,404 照常)。
         const it = defaultSubagentTailBus.subscribe(target);
+        // 归属+型探测经 output 同 seam(含 1.250 durable 臂——跨实例行也探得到 status);not_found/型错=
+        // 同一不可区分 404(无 oracle)。探测是纯读(a* 形在 seam 内先过形判门;background_agent poll 无副作用)。
         const probe = await deps.subagentTaskOutput(target, { owner: runId, scope: run.owner ?? "default", ...(run.sessionId ? { sessionId: run.sessionId } : {}) });
         const probeDetails = probe.details;
         if (probeDetails?.error === "not_found" || probeDetails?.type !== "background_agent") {
@@ -679,22 +1004,30 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             return;
         }
         sseHeaders(res);
+        // meta 声明:live 帧 replica-local + replay 指引;status=探测快照(终态=不再有帧,发 meta 即收尾,
+        // cli 拿到「走 replay 面」的信号而不是空挂)。seq=stop-cycle 世代号(settle 铸;core 1.377 起
+        // **全域投影**——进程内 live 臂投当前复活周期号 [[1533] ask 兑现,[1548]①],durable 终态 serve
+        // 同键同义;老 core 只在 durable 臂在场,缺省容忍)。1=spawn 周期,≥2=复活周期(retained revive
+        // 或 tier-3 均 bump——codex 快审 #11 纠,勿窄读成仅 tier-3)。
         res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, runId, target, status: probeDetails.status ?? "running", ...(typeof probeDetails.seq === "number" ? { seq: probeDetails.seq } : {}), live: "replica-local", replayFace: "GET /v1/runs/:id/subagents/:handle/output" })}\n\n`);
+        // core 1.382([1561] 提货单③):"parked" 非活非终态(durably suspended pending approval)——跟
+        // running/pending 同归"还没完",tail 该继续等而不是收尾指去 replay 面(那是给真终态用的)。子代获批
+        // 恢复后会在**同一条**活流上继续产帧,提前收尾会让客户端误判"已经结束",错过恢复后的后续内容。
         if (probeDetails.status !== "running" && probeDetails.status !== "pending" && probeDetails.status !== "parked") {
             void it.return?.();
-            res.end();
+            res.end(); // 终态:tail 无帧可等——replay 面才是读处(meta 已指路)
             return;
         }
         let closed = false;
         const hb = setInterval(() => {
             if (!res.writableEnded)
-                res.write(`event: heartbeat\ndata: {}\n\n`);
+                res.write(`event: heartbeat\ndata: {}\n\n`); // workflow stream 同款真帧(BFF 丢注释帧案)
         }, 15_000);
         if (typeof hb.unref === "function")
             hb.unref();
         req.on("close", () => {
             closed = true;
-            void it.return?.();
+            void it.return?.(); // parked next() 不观察 closed 旗——显式 return 解除 park + 清订阅(subscribeWorkflow 同案)
         });
         try {
             for (;;) {
@@ -703,7 +1036,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                     break;
                 res.write(`event: forward\ndata: ${JSON.stringify(n.value)}\n\n`);
                 if (n.value.type === "task_settled")
-                    break;
+                    break; // 复审 #3:终态帧即完整故事结束——收流,余下在 replay 面
             }
         }
         finally {
@@ -714,6 +1047,16 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         return;
     }
+    // [1499] CC TaskOutput/TaskStop 人侧对位 — the GENERIC task-handle verbs. The narrow subagents/:h/output
+    // face above stays byte-stable (公告过的 background_agent ONLY contract); THIS family serves the full
+    // registry kind set the TaskOutput/TaskStop tools serve (background_bash stdout — NB whether a read
+    // consumes the output cursor depends on the handle's shape: a spooled handle re-reads in full, a
+    // cursor-only handle returns new bytes per read; the projection's own flags are authoritative; monitor
+    // batches; background_agent final report), with `workflow` refused at the seam (the journal face owns
+    // workflow reads; a poll here would fire onServedTerminal and suppress the completion push). Addressing
+    // is EXACT task_id only — the tools' agent-name / legacy-shellId resolution is deliberately not on the
+    // wire (fail-closed 404). Gates mirror subagentOutput: verified principal → owner via the run row →
+    // SESSION (enforced from birth — new face, zero consumers, no soft phase needed).
     const taskVerbMatch = req.method === "GET" ? RUN_TASK_OUTPUT_RE.exec(url) : req.method === "POST" ? RUN_TASK_STOP_RE.exec(url) : null;
     if (taskVerbMatch) {
         const stopVerb = req.method === "POST";
@@ -722,7 +1065,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             return;
         }
         if (stopVerb && rateLimited(req, res))
-            return;
+            return; // mutating, runs no model (parity with detach — rateLimited only, no quota/lease gate)
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
@@ -740,12 +1083,25 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
+        // SESSION-scoped content/action face ([1493] model): enforced fail-closed — same boundary rationale as
+        // subagentOutput (principal = whose data, session = which conversation; honest caller-asserted session is
+        // correct AND sufficient inside one principal; operators bypass; a session-unbound run is principal-only).
         const q = new URL(req.url ?? "", "http://x").searchParams;
         if (!trusted && run.sessionId && q.get("session") !== run.sessionId) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
         const access = { owner: runId, scope: run.owner ?? "default", ...(run.sessionId ? { sessionId: run.sessionId } : {}) };
+        // ?filter= is REFUSED on BOTH verbs, not ignored (fail-loud 400; the face shipped unreleased, zero
+        // consumers — and codex R2: a GET-only refusal would leave the stop verb silently accepting it). The
+        // tools' filter is a caller-supplied RegExp run line-by-line on the replica's shared event loop — over
+        // the wire that lets one request stall the whole replica for every tenant (pathological patterns on
+        // long output lines take unbounded time in a backtracking engine). Client-side filtering of the fetched
+        // output is the alternative, with an honest limit (codex R2): the wire serves the registry's CLIPPED
+        // projection (core filters BEFORE clipping; a client can only filter after) — matches inside a clipped
+        // middle are not recoverable over the wire, and a cursor-only bash leg consumes what it serves.
+        // Full-fidelity filtered reads stay an in-engine tool capability; if a linear-time engine lands in
+        // core, the wire filter can reopen deliberately.
         if (q.get("filter") !== null) {
             sendError(res, 400, "request.param_unsupported", "filter is not accepted on the wire — fetch the output and filter client-side (note: the wire serves the clipped projection)");
             return;
@@ -758,10 +1114,28 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.task_handle", `no background task "${target}" under this run (unknown handle, not this run's task, already reaped — handles live in the replica-local registry for the parent's lifetime — or a workflow handle: workflow rows read via GET /v1/workflows/:id/journal; stopping a workflow is not on this wire)`);
             return;
         }
+        // [1499] codex R3: a stop whose kill did NOT land must not read as success. Core keeps the handle
+        // honest (status stays "running", error = the env failure code) — surface that as a 409 so a
+        // status-driven client never mistakes a failed stop for a dead process. The projection rides along
+        // verbatim for diagnosis. NB the "user" attribution pre-mark stays pending on this arm (first-write-
+        // wins, no public per-handle clear) — if the task later dies of another cause it reads stoppedBy:
+        // "user"; the atomic fix is a `source` option on core's stopTask (asked on the board), same residue
+        // shape as core's own internal "parent" pre-mark.
+        // core 1.382([1561] 提货单③):parked 行的两个新 stop 结局——`parked_pending_approval`(stop 撞见
+        // 一个仍在 parked 的行,没有活跃可 kill 的进程)与 `park_resume_won`(stop 与"审批已落地→恢复"发生
+        // 竞态,恢复那侧赢了,行不再是 parked,但 status 不一定翻回 "running"——error 码本身才是权威判据,
+        // 不能靠 status 反推)。二者都不该读成 200 成功("kill 没落地"同一条纪律的延伸),各给各的
+        // errorCode(同 409 家族,additive,与既有 not_local/not_landed 同姿势)。
+        // [1596]/[1600] core 1.397 三分:仲裁器**抛错**(店不可达)此前被误吞成 park_resume_won 的假话——
+        // 「输给了并发 resume」与「根本问不到仲裁结果」是两种不同的行动建议(前者重查状态,后者原样重试
+        // stop),新码 `park_arbiter_unreachable` 让二者不再共用一个 errorCode。
         const parkArbiterUnreachable = details?.error === "park_arbiter_unreachable";
         const parkResumeWon = details?.error === "park_resume_won";
         const stillParked = details?.error === "parked_pending_approval" || details?.status === "parked";
         if (stopVerb && details?.error !== undefined && (details.status === "running" || stillParked || parkResumeWon || parkArbiterUnreachable)) {
+            // 1.250:durable 回落臂(core stopTask agentStore 分支)对他实例 running 行应答 error="not_local"
+            // (没有 kill 被尝试)——与「kill 尝试了没落地」(stop.not_landed)是不同的失败形,各给各的
+            // errorCode(同 409 家族,additive)。
             const notLocal = details.error === "not_local";
             sendError(res, 409, notLocal
                 ? "stop.not_local"
@@ -782,6 +1156,14 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                             : `stop did not land (${details.error}) — the process may still be running`, { taskId: runId, target, content: out.content, output: out.details });
             return;
         }
+        // Registry projection passed through verbatim (status/retrieval_status/cursor flags); `content` is
+        // UNTRUSTED tool/model output, same posture as subagentOutput.
+        // G14([1833]/[1840]§五):顶层铸 `cursorSemantics` —— 此前「这次读是否消费了游标」只能从 content
+        // 文本标记(`--- stdout (full, re-readable) ---` vs `--- new stdout ---`)反解,每个消费端都得抄
+        // 字符串判别。判据(core task-registry dist 亲读):游标消费形(非 spool 的 pollBackground 路径)
+        // 的内层 details.bytesDroppedBeforeCursor **恒在**(0 也发);spool bash / monitor / background_agent
+        // 全是重读安全的 full 形。⚠️ 这仍是对 core 内形的一处嗅探——集中在 server 这一处替所有端挑担;
+        // 已在黑板请 core 出一等 flag,到货换源、wire 键不变。error/not_ready 形不铸(没有输出体,别给假语义)。
         const g14 = (() => {
             const d = out.details;
             if (!d || d.error !== undefined || d.retrieval_status === "not_ready")
@@ -790,7 +1172,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                 return { cursorSemantics: d.details && "bytesDroppedBeforeCursor" in d.details ? "cursor" : "full" };
             if (d.type === "monitor" || d.type === "background_agent")
                 return { cursorSemantics: "full" };
-            return {};
+            return {}; // 未知 kind:不猜
         })();
         sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details, ...g14 });
         return;
@@ -799,11 +1181,13 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
     if (subVerbMatch) {
         const verb = url.endsWith("/resume") ? "resume" : "steer";
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-            return;
+            return; // mutating + drives a model agent
         if (!deps.runStore) {
             sendError(res, 501, "capability.run_store_required", "async runs require the TiDB run store");
             return;
         }
+        // Identity from gatedPrincipal (direct-door-secure single point), NEVER the spoofable header — `trusted`
+        // carries operator authority (parity with RUN steer / workflow-agent steer; HANDOFF 铁律 + core §3 inv #1).
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
@@ -827,19 +1211,28 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.body_shape", "body must be { content: string (non-empty) }");
             return;
         }
+        // 入参上限(见 `STEER_IN_MAX_REQUEST_CHARS` 旁注):脱敏门是**同步**的,烧的是事件循环 ⇒
+        // 一次超大 steer 卡住的是**整个副本**。**拒**而不是服务端先截 —— 先截会让引擎的
+        // `[+N chars]` 披露低报,而"诚实标记不得低报"是本仓另一条钉守着的性质。
         if (body.content.length > STEER_IN_MAX_REQUEST_CHARS) {
             sendError(res, 413, "steer.content_too_large", `content exceeds ${STEER_IN_MAX_REQUEST_CHARS} characters (got ${body.content.length}); note only the first ${STEER_IN_MAX_CHARS} are delivered anyway`);
             return;
         }
+        // trusted = explicit operator (NOT bare isOperator); a normal caller may drive only their OWN run's children.
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         const run = await deps.runStore.getRun(runId);
+        // Owner-gate via the parent run row (the child inherits the parent's tenancy — core threads the parent's
+        // principal to the child, design/62). 404 (not 403) for a non-owner — no existence oracle.
         if (!run || (!trusted && run.owner !== null && run.owner !== principal)) {
             sendError(res, 404, "not_found.run", "run not found");
             return;
         }
         if (!runSessionAcceptOk(req, res, run, `subagent.${verb}`))
-            return;
+            return; // [1499] accept-phase (child write verbs, same class)
         const send409 = (errorCode, error) => sendError(res, 409, errorCode, error);
+        // STEER-IN REDACTION GATE — same trust gate as the workflow-agent route (one owner: redactSteerIn): the
+        // human content is UNTRUSTED (host-leak/size/fence) BEFORE it reaches the child; core's handle.steer/
+        // resume fence AGAIN inside their trusted marker framing (defense in depth).
         const redacted = redactSteerIn(body.content, target);
         const resolution = deps.subagentSteerRegistry?.resolve(runId, target);
         if (resolution && resolution.count > 1) {
@@ -850,6 +1243,8 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         if (handle) {
             try {
                 if (verb === "resume") {
+                    // design/122: `handle.resume` is absent when the parent run did not retain child sessions — the
+                    // same condition core's own rejection names; report it with core's code so the shell renders one story.
                     if (!handle.resume) {
                         send409("resume.retain_off", "the parent run did not retain sub-agent sessions (set retainSubagentSessions on the run to enable revival)");
                         return;
@@ -859,11 +1254,14 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const marker = await handle.steer(redacted);
+                // Receipt wording aligned with CC ("Message queued for delivery…").
                 sendJson(res, 200, { taskId: runId, target, status: "running", delivery: "applied", marker, note: `Message queued for delivery to ${handle.agentName ?? target} at its next tool round.` });
                 return;
             }
             catch (e) {
                 const code = e.code;
+                // core's typed rejections → honest 409s with the core code verbatim (steer: not_running only;
+                // resume: still_running / retain_off / evicted / cap / session_not_found — design/122 D2 contract).
                 if (code === "steering.not_running") {
                     send409(code, "sub-agent just finished — no longer accepting steers");
                     return;
@@ -876,22 +1274,32 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                     send409(code, e instanceof Error ? e.message : "resume rejected");
                     return;
                 }
-                throw e;
+                throw e; // unexpected → outer handler 500
             }
         }
+        // No handle here. Either the parent run is elsewhere/terminal, the child was never registered (bg
+        // delegation — no handle by core's r1-M3 scope), or the owning leg already tore down. Honest 409.
         send409("steering.not_running", run.status === "running"
             ? "no sub-agent matches on this replica (it runs backgrounded, or the run is on another replica)"
             : `run is ${run.status} — its sub-agents are no longer addressable`);
         return;
     }
+    // E23 (shell-host contract): POST /v1/elicitations/:id/respond — the shell answers an inbound MCP elicitation. LIVE-ONLY +
+    // same-replica (the parked promise is in-memory, like a live steer): the coordinator owner-gates (404 — no
+    // existence oracle), validates the body (= core's McpElicitResponse), and resolves the promise so onElicit returns
+    // to core, which replies to the MCP server on the still-open connection. A respond on the wrong replica / after
+    // answer/TTL finds nothing → 404.
     const elicitMatch = req.method === "POST" ? ELICIT_RESPOND_RE.exec(url) : null;
     if (elicitMatch) {
         if (rateLimited(req, res))
-            return;
+            return; // mutating, but only resolves an in-flight promise (no new billable work → no quota gate)
         if (!deps.elicitation) {
             sendError(res, 501, "feature.elicitation_disabled", "inbound MCP elicitation is not enabled on this worker (MCP_ELICITATION_ENABLED)");
             return;
         }
+        // Identity from gatedPrincipal (direct-door-secure single point), NEVER the spoofable header — the answer is
+        // owner-gated against the run's owner (the END USER the elicitation was routed to). No operator bypass: an
+        // elicitation form is the user's to fill, not a supervisor's (unlike steer).
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
@@ -910,14 +1318,21 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         sendJson(res, status, respBody);
         return;
     }
+    // §4④: POST /v1/questions/:id/respond — the shell answers the agent's AskUserQuestion. LIVE-ONLY +
+    // same-replica (parked promise in-memory), the sibling of the elicit respond: owner-gated (404, no existence
+    // oracle), body validated (= core's QuestionAnswer), resolves the promise so onQuestion returns to core and the
+    // model continues with "The user answered: …". The security ANSWER-fence (selected ⊆ options, note untrusted-fenced)
+    // is core's AskUserQuestion tool, not here. A respond on the wrong replica / after answer/TTL finds nothing → 404.
     const questionMatch = req.method === "POST" ? QUESTION_RESPOND_RE.exec(url) : null;
     if (questionMatch) {
         if (rateLimited(req, res))
-            return;
+            return; // resolves an in-flight promise (no new billable work → no quota gate)
         if (!deps.question) {
             sendError(res, 501, "feature.ask_question_disabled", "AskUserQuestion live HITL is not enabled on this worker (ASK_QUESTION_ENABLED)");
             return;
         }
+        // Same owner-gate identity as elicit: the VERIFIED principal (gatedPrincipal), never the spoofable header. The
+        // question is the END USER's to answer (routed to their stream) — no operator bypass.
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
@@ -936,14 +1351,22 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         sendJson(res, status, respBody);
         return;
     }
+    // [816]/[820]②: POST /v1/tool-approvals/:id/respond — the shell answers a policy `ask` (the CC three-choice
+    // card: {decision: "allow" | "allow_session" | "deny"}). LIVE-ONLY + same-replica (parked promise in-memory),
+    // the sibling of the question respond: owner-gated (404, no existence oracle), body validated first (400 is
+    // existence-independent), resolves the promise so core's resolveAsk returns allow/deny and the tool call
+    // proceeds/denies. `allow_session` additionally arms the coordinator's per-session allow-all (fs-write family
+    // only — rationale in tool-approval.ts). A respond on the wrong replica / after settle/TTL finds nothing → 404.
     const approvalMatch = req.method === "POST" ? TOOL_APPROVAL_RESPOND_RE.exec(url) : null;
     if (approvalMatch) {
         if (rateLimited(req, res))
-            return;
+            return; // resolves an in-flight promise (no new billable work → no quota gate)
         if (!deps.toolApproval) {
             sendError(res, 501, "feature.tool_approval_disabled", "live tool-approval HITL is not enabled on this worker (TOOL_APPROVAL_ENABLED)");
             return;
         }
+        // Same owner-gate identity as question/elicit: the VERIFIED principal (gatedPrincipal), never the spoofable
+        // header. The approval is the END USER's to answer (routed to their stream) — no operator bypass.
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);