@sema-agent/server 1.322.0 → 2.0.0

package/dist/runs.js

@@ -6,6 +6,44 @@ import { createLedgerSink } from "./trace/ledger-sink.js";
 import { fleetRunResiduals } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
+/**
+ * stoppedBy (core 1.252): a service cancel is a USER stop — mark the run's still-running background
+ * children BEFORE core's teardown reaps them (bare abort = attribution falls back to "system"; core's own
+ * reap marks "parent", but first-marker-wins means our earlier "user" is the one that lands). Register this
+ * FIRST on the cancel signal so it runs ahead of any later-registered core listener (listener-order
+ * guarantee); one registration covers every abort route on that signal (same-replica fast path + the
+ * cross-replica flag poll). Advisory only — the cancel itself must never fail on attribution.
+ *
+ * Access = TASK-scoped children ONLY: owner = the parent taskId (on a RESUME leg: the sessionId — core's
+ * canonical taskId there), scope = `principal ?? "default"` (core registers children under
+ * `spec.principal ?? "default"`, so an anonymous run's children live in scope "default" and an access
+ * WITHOUT scope matched nothing). Session-scoped children are DELIBERATELY not marked: a cancelled parent
+ * does NOT take them down (CC Backgrounded semantics — core's teardown reaps with skipSessionScoped), so
+ * pre-marking them "user" would misattribute a stop that isn't happening.
+ *
+ * core 1.256: `markStopSourceForOwner` replaces the old `list()+markStopSource`
+ * per-row loop, closing BOTH documented holes — ① the EXPLICIT `sessionScoped` flag
+ * (`skipSessionScoped:true`) makes the resume leg safe (its owner key == sessionId COINCIDES with
+ * session-scoped children's; the old code couldn't tell them apart and took an honest degrade instead),
+ * ② a direct handle-map walk (no `list()` 500-row display cap under-marking >500-children runs). Covers
+ * core's full markable set (background_agent / background_bash / monitor); running-only +
+ * first-marker-wins guards live inside the seam.
+ */
+/** [1488]③(b) + codex R2: the bg agent-handle OUTPUT read, kind-gated BEFORE any poll. `pollTask` is the
+ *  generic registry face and polling is NOT side-effect-free for other kinds — a terminal workflow poll
+ *  fires `onServedTerminal` (acknowledges the completion as served → suppresses its notification) and a
+ *  bash poll advances the output cursor. `getAccessibleTask` is a pure lookup: resolve + access-check +
+ *  type-check FIRST; only a `background_agent` row is ever polled (non-blocking). Everything else returns
+ *  the registry's own not_found shape, indistinguishable from an unknown handle (the route 404s it).
+ *
+ *  1.250 durable arm (core 1.364, [1511] follow-up delivered): a FULL in-process miss (`!row`) falls
+ *  through to `pollTask(…, { agentStore })` — core's durable arm only fires for `a*`-shaped handles
+ *  (DURABLE_AGENT_HANDLE_RE) behind `canAccessAgentRecord`, and with NO in-process handle the live
+ *  workflow/bash branches are unreachable, so the kind-gate's reason (onServedTerminal / cursor advance)
+ *  cannot trigger. Terminal rows serve the durable snapshot cross-instance/post-restart; a foreign-writer
+ *  running row answers the honest "outcome unknown here"; anything else is core's own not_found (byte-same
+ *  route 404 as today). A row that IS in-process but of the wrong type stays a hard 404 — the process
+ *  knows the truth, falling back would sidestep the kind gate. */
 export async function backgroundAgentOutput(registry, handle, access, agentStore) {
     const row = registry.getAccessibleTask(handle, access);
     if (!row || row.type !== "background_agent") {
@@ -15,20 +53,54 @@ export async function backgroundAgentOutput(registry, handle, access, agentStore
     }
     return registry.pollTask(handle, access);
 }
+/** [1499] CC TaskOutput 人侧对位 — the GENERIC task-handle read face (b* bash stdout — NB whether a read
+ *  consumes the output cursor depends on the handle's shape: spooled handles re-read in full [GET-idempotent],
+ *  cursor-only handles return new bytes per read; the projection's flags are authoritative; m* monitor
+ *  batches; a* agent final report). No filter option: caller-supplied regexes are refused at the route (a
+ *  backtracking engine on the shared event loop must not run wire-supplied patterns; client-side filtering
+ *  sees only the clipped projection — full-fidelity filtered reads stay an in-engine tool capability).
+ *  Addressing is exact task_id only (the tools' name/legacy-id resolution stays off the wire). Kind-gate
+ *  FIRST on the pure getAccessibleTask (codex-R2 shape — pollTask is not side-effect-free): `workflow` is
+ *  refused — its HTTP read face is the workflow journal ([1491] contract), and a pollTask here would fire
+ *  onServedTerminal (ack the completion as served) and suppress the workflow completion push. Refusals
+ *  return the registry's own not_found shape, indistinguishable from an unknown handle (the route 404s it). */
 const TASK_HANDLE_KINDS = new Set(["background_bash", "monitor", "background_agent"]);
+/** 1.250 复审 F1(HIGH):durable 回落的**形判门**——`getAccessibleTask` 是精确键(不 trim、不查 legacy
+ *  别名),而 core `pollTask/stopTask` 是通用解析面(先 trim、`resolveInternal` 含 legacyToTaskId、
+ *  stopTask 还有 byName 臂)。裸 `!row` 回落会让垫充空白句柄(" "+wfId)/legacy shellId/agent 名字从
+ *  回落缝穿进 live 分支——kind 门要防的 onServedTerminal/游标消费/按名 stop 全部复活(复审实测复现)。
+ *  只有 **a\* 精确形**才回落:`DURABLE_AGENT_HANDLE_RE` = core 公共导出(core 1.369,[1518] ask 即答
+ *  ——两边判词同源,镜像私拷已删)。残余(documented):恰为 a\* 形的 agent **名字**
+ *  在无 durable 行时仍会进 core stopTask 的 byName 臂——同 access 元组内、名字域与句柄域同形的病态窄面,
+ *  接受。 */
 const DURABLE_AGENT_HANDLE_SHAPE = DURABLE_AGENT_HANDLE_RE;
 export async function taskHandleOutput(registry, handle, access, agentStore) {
     const row = registry.getAccessibleTask(handle, access);
     if (!row || !TASK_HANDLE_KINDS.has(row.type)) {
+        // 1.250 durable arm — full in-process miss + a* 精确形才回落(F1 形判门,DURABLE_AGENT_HANDLE_SHAPE
+        // 顶注;b*/m* 无 durable 面照旧 not_found;进程内命中但型错 = 真相已知,不回落)。
         if (!row && agentStore && DURABLE_AGENT_HANDLE_SHAPE.test(handle))
             return registry.pollTask(handle, access, { agentStore });
         return { content: "", details: { task_id: handle, retrieval_status: "not_ready", error: "not_found" } };
     }
     return registry.pollTask(handle, access);
 }
+/** [1499] CC TaskStop 人侧对位 — stop a background task handle (bash kill / monitor stop / agent abort).
+ *  Same kind gate as the read face (a workflow stops via its own cancel face, never this verb). stopTask is
+ *  idempotent on a terminal handle (the registry answers honestly); the stop is attributed "user" via the
+ *  registry's existing markStopSource machinery (an HTTP stop is the human's hand — parity with the shell's
+ *  TaskStop attribution). The pre-mark is first-write-wins and MUST come first (core's own stop path marks
+ *  "parent" internally — marking after would lose the attribution race on success, the common path); the
+ *  trade (codex R3) is that on a kill-that-didn't-land the pending "user" mark is not clearable through the
+ *  public registry face — the route surfaces that arm as 409 stop.not_landed, and the atomic fix (a `source`
+ *  option on stopTask) is a core ask. */
 export async function taskHandleStop(registry, handle, access, agentStore) {
     const row = registry.getAccessibleTask(handle, access);
     if (!row || !TASK_HANDLE_KINDS.has(row.type)) {
+        // 1.250 durable arm — core stopTask's agentStore branch answers honestly (terminal row: "already
+        // <status> — nothing to stop"; foreign-writer running row: not_local, no kill is attempted). NO
+        // markStopSource here: there is no in-process kill to attribute, and the durable answer never reads
+        // as a landed stop. F1 形判门同 output 面(stopTask 还有 byName 臂——非 a* 形一律不进通用解析面)。
         if (!row && agentStore && DURABLE_AGENT_HANDLE_SHAPE.test(handle))
             return registry.stopTask(handle, access, { agentStore });
         return { content: "", details: { task_id: handle, retrieval_status: "not_ready", error: "not_found" } };
@@ -42,9 +114,15 @@ export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
             defaultTaskRegistry.markStopSourceForOwner({ owner: taskId, scope: principal ?? "default" }, "user", { skipSessionScoped: true });
         }
         catch {
+            /* attribution is advisory — the cancel itself must never fail on it */
         }
     }, { once: true });
 }
+/**
+ * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
+ * `runTaskStream`), so detect it from the result. Prefer the structured `errorCode` (core ≥1.8); fall
+ * back to the conflict wording only for older results without one.
+ */
 export function isSessionConflictResult(result) {
     if (result.status !== "failed")
         return false;
@@ -52,6 +130,23 @@ export function isSessionConflictResult(result) {
         return result.errorCode === "conflict";
     return /stale write|concurrent write|conflict/i.test(result.errorMessage ?? "");
 }
+/**
+ * E18 resume-at CALLER error → an HTTP 4xx. A bad/stale resume-at target (the resolved entryId is gone or is not a
+ * settled message boundary) surfaces as a FAILED TaskResult carrying a `resume_at.*` errorCode (core swallows the
+ * prepare-throw into the result, exactly like a session conflict — runtask catch → status:"failed"+errorCode). The
+ * sync path otherwise 200s a failed result; map these to 4xx so a caller mistake reads as one. `not_found` (the
+ * entry is genuinely absent) → 404; everything else (not_a_message / conflicts_resume / no_session) → 422.
+ *
+ * design/114 Phase3: `requireExistingSession` on a genuinely-missing/purged session ALSO surfaces as a failed result
+ * (core prepare-task maps the store's `not_found` → `resume.session_not_found`); map it to 404 (the session is gone),
+ * the same "caller mistake reads as a 4xx, not a silent 200 fresh run" discipline.
+ *
+ * [833] rewind exclusive mode (core 1.292 resumeAtMode:"before"): its two edge rejections ride the same `resume_at.*`
+ * prefix (before_target_not_user / before_root_unsupported → 422 via the existing branch, errorCode passed through
+ * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
+ * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
+ * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
+ */
 export function resumeAtHttpStatus(result) {
     if (result.status !== "failed")
         return undefined;
@@ -63,31 +158,71 @@ export function resumeAtHttpStatus(result) {
         return undefined;
     return result.errorCode === "resume_at.not_found" ? 404 : 422;
 }
+/**
+ * E18 resume-at — per-turn anchor capture, shared by runInBackground AND the resume-leg driveResume so the (single,
+ * tricky) capture rule can't drift between the two stream-drain loops.
+ *
+ * A "turn" in core = ONE assistant message + its tool batch. resume-at is valid ONLY at a SETTLED rewindable boundary
+ * — core's prepare-task accepts "user messages or finished assistant-text turns" and REJECTS an assistant message that
+ * ends mid-tool-call (resume_at.not_a_message). So we capture an anchor ONLY for a turn that produced text AND ran NO
+ * tools: then the turn's leaf at turn_end IS that assistant-text message (the rewindable target). For a tool-using
+ * turn neither candidate works — at turn_end the leaf is the turn's LAST tool-result (core appends tool results before
+ * emitting turn_end; a tool-result is stored as a `message` so core would SILENTLY branch AFTER the tools ran), and
+ * the assistant message itself ends mid-tool-call so core would reject it. The shell still gets a per-message eventId
+ * handle on every text event (E2 identity); a rewind to a non-captured (tool-using) message simply 404s — honest,
+ * never a silent wrong-point branch. (The adversarial-review HIGH: capturing at turn_end unconditionally mis-anchored
+ * every tool-using turn — the common agentic shape — to the tool-result leaf.)
+ *
+ * Best-effort: a capture failure must NEVER fail the run (it only makes that one turn non-rewindable). `onCaptureFail`
+ * surfaces the degrade (a metric) so a SYSTEMATIC failure — e.g. an un-migrated DB missing `resume_anchor` — is
+ * observable instead of a silent feature outage.
+ */
 export class TurnAnchorCapture {
     capture;
     onCaptureFail;
     captureUser;
+    /** The turn's FIRST text_delta eventId = the message's stable resume handle (also stamped on the durable text event). */
     firstTextEventId;
     turnHadTool = false;
-    constructor(capture, onCaptureFail, captureUser) {
+    constructor(capture, onCaptureFail, 
+    /** R8 (CC-parity rewind): capture a USER-message anchor straight from the
+     *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
+     *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
+     *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
+     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
+     *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
+     *  side map / no `getLeafId` inference needed). The assistant-turn capture above stays as an additive bonus. */
+    captureUser) {
         this.capture = capture;
         this.onCaptureFail = onCaptureFail;
         this.captureUser = captureUser;
     }
+    /** A `message_committed` arrived — capture a USER-message rewind anchor (CC parity). Best-effort (a failure only
+     *  makes that one prompt non-rewindable). Only `role==="user"`; assistant/toolResult committed entries are handled
+     *  by the turn-text path (assistant) or deliberately not anchored (toolResult — `resumeAt` rejects them). */
     async onMessageCommitted(role, entryId) {
         if (role === "user" && entryId && this.captureUser) {
             await this.captureUser(entryId).catch(() => this.onCaptureFail?.());
         }
     }
+    /** A text_delta arrived — latch the first DEFINED eventId as the message handle (eventId is optional on the stream). */
     onText(eventId) {
         if (this.firstTextEventId === undefined) {
+            // First text of THIS turn. Any tool seen before now belonged to a PRIOR turn: on the resume leg, core streams
+            // the suspended turn's resolution tool_start/tool_end (the approved tool) with NO intervening turn_end before the
+            // continuation turn (runtask.js applyResumeDecision). Clearing turnHadTool here keeps a pure-text continuation
+            // turn anchorable. SAFE for normal turns: within a turn the assistant streams its text BEFORE its own tool calls,
+            // so a real same-turn tool always arrives AFTER this first text and re-sets the flag (guarded by `=== undefined`,
+            // so a later text part after a tool — [text, toolCall, text] — does NOT wrongly clear it).
             this.turnHadTool = false;
         }
         this.firstTextEventId ??= eventId;
     }
+    /** A tool ran this turn — mark it non-rewindable (its leaf will be a tool-result, not a settled assistant-text message). */
     onTool() {
         this.turnHadTool = true;
     }
+    /** turn_end — capture the anchor iff this was a settled assistant-TEXT turn, then reset for the next turn. */
     async onTurnEnd() {
         if (this.firstTextEventId && !this.turnHadTool && this.capture) {
             await this.capture(this.firstTextEventId).catch(() => this.onCaptureFail?.());
@@ -96,25 +231,109 @@ export class TurnAnchorCapture {
         this.turnHadTool = false;
     }
 }
+/**
+ * Strip the durable-resume capability token from a result before it is persisted to the replayable event
+ * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
+ * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended" while still
+ * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
+ * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
+ * non-secret and intentionally kept.
+ */
 export function stripCheckpointToken(result) {
+    // Narrow to a plain object (reject null / arrays) and an OWN `checkpointToken` key, so a non-plain or
+    // array input is returned unchanged rather than reshaped.
     if (result !== null && typeof result === "object" && !Array.isArray(result) && Object.hasOwn(result, "checkpointToken")) {
         const { checkpointToken: _drop, ...rest } = result;
         return rest;
     }
     return result;
 }
+/** Evict a stale warm-cache entry after a cross-instance write conflict (broken-affinity backstop). */
 export function evictIfConflict(runner, sessionId, result) {
     if (sessionId && isSessionConflictResult(result)) {
         runner.sessions.evict?.(sessionId);
     }
 }
-export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests) {
+/**
+ * Drive a task to completion in the background, persisting its events to the durable run log (S2).
+ *
+ * Text deltas are coalesced into one `text` event per turn (the durable stream is turn-grained for
+ * text); tool/lifecycle events are recorded individually. Per-token live streaming stays on the
+ * synchronous `/v1/tasks/stream` endpoint. Never throws — failures are recorded on the run.
+ *
+ * Cancellation (POST /v1/runs/:id/cancel): the run registers an AbortController in `inflight` (same-replica
+ * fast path — the cancel handler aborts it directly) and its heartbeat tick polls the durable
+ * `cancel_requested` flag (cross-replica, ≤HEARTBEAT_MS lag). Either way the run settles to
+ * status "failed" + errorCode "cancelled" (metric label "cancelled"); the entry is removed in `finally`.
+ *
+ * Preemption (POST /v1/assistant/tasks/:id/preempt, design/80 seam #2): a SECOND, INDEPENDENT controller
+ * (`preemptCtrl`, registered in `preemptable`) carries the scheduler's graceful "yield this task" — when raised,
+ * core durably SUSPENDS the task at the next clean turn boundary (gate resource_limit, reason "preempt") so it is
+ * RESUMABLE, the opposite of cancel's kill. It is wired ONLY on the plain-stream path: the verify/cascade
+ * branches finalize with `setTerminal` unconditionally (no `setSuspended`), so a preempt-suspend there would write
+ * a non-terminal "suspended" as terminal and release the session lock — and preempt's contract is graceful, not a
+ * failure. Cross-replica via the `preempt_requested` flag (same heartbeat tick). Eligibility (resourceSuspend +
+ * durable store + durable tool-results + remote env) is core's call: an ineligible task's preemptSignal no-ops.
+ *
+ * Steering (POST /v1/runs/:id/steer, design/47): the live core `TaskStream` is registered in `steerable` so the
+ * HTTP route can inject a mid-task message via `stream.steer()` (drained at the next turn boundary). Same-replica
+ * only — a suspended run is steered durably via the checkpoint's `setPendingSteer` instead, and only the
+ * plain-stream path holds a steerable stream (the verify/cascade branches return a result, not a stream).
+ */
+export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, // 快审 F1:number 参升整对象——cost 顶随传
+cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, 
+/** E23: the VERIFIED principal (gatedPrincipal) that may answer this run's elicitations — matches the respond
+ *  owner-gate's identity source (NOT the cost-attribution `principal`, which on a direct door is the spoofable
+ *  header → can be null while a JWT principal exists). Falls back to the run owner when not supplied. */
+elicitOwner, 
+/** E18 resume-at: capture the turn's (firstTextEventId → leaf entryId) anchor at each turn_end. Built by the caller
+ *  closing over {sessionId, owner, sessionStore.getLeafId, resumeAnchorStore}; undefined ⇒ no anchor store wired. */
+captureTurnAnchor, 
+/** MF-Fleet (shell-host contract): the run-scoped fleet-row publisher. `onStart` adds the live row; `onEvent` accrues
+ *  tokens (turn_end) + subagent child rows (task_progress); `onTerminal` flips/removes it. Fired for ALL legs
+ *  (verify/cascade/plain-stream) so a background run TRANSITIONS its `GET /v1/fleet/stream` row exactly like the
+ *  sync leg. No-op when no fleet bus is wired (the publisher is a null-object). */
+fleetPublisher, 
+/** R8 (CC-parity rewind): capture a USER-message anchor (keyed by this run's taskId) from `message_committed{role:"user"}`
+ *  — the CC "rewind to the prompt" target. undefined ⇒ no anchor store wired. */
+captureUserMessageAnchor, 
+/** §4④ : AskUserQuestion LIVE coordinator — establishes a per-run onQuestion ALS context (like `elicitation`)
+ *  so an AskUserQuestion tool call routes to this run's stream + owner-gated respond. undefined ⇒ headless default. */
+question, 
+/** P1 ①② follow-on (core): the async-workflow completion inbox, drained at the START of this background
+ *  leg (parity with the sync stream-open drain) into durable `workflow_complete` events a tailing client replays.
+ *  Owner gate = `elicitOwner ?? owner` (the same verified-principal-with-run-owner-fallback the elicit/question
+ *  contexts use). undefined ⇒ no push half wired (the WorkflowStatus poll floor stands alone). */
+workflowCompletionInbox, 
+/** C2 (core 1.219): the replica-local Task-subagent steer-handle registry. When present, this leg
+ *  opts into core's `onSubagentSpawn` sink — each SYNC delegation's steer handle registers under THIS run's
+ *  taskId (auto-evicted on child settle) so POST /v1/runs/:id/subagents/:target/steer can route into it. */
+subagentSteer, 
+/** ask①: emit-target diagnostic sink for the completion-inbox drain below (route/connection/
+ *  deliveryLagMs per delivered `workflow_complete`). runs.ts has no logger of its own — the caller closes over
+ *  deps.logger. undefined ⇒ silent (behavior unchanged). */
+completionDiagLog, 
+/** SendUserFile(切片2):per-run file_link 帧发射 ALS(question/elicitation 同款)。emit=durable append。 */
+sendUserFile, 
+/** [998]② the shared prompt-manifest accumulator (tracer records at prepare; this leg drains the pending
+ *  record into a durable `prompt_assembled` event — turns/stream read it). undefined ⇒ not wired. */
+promptManifests) {
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
-    fleetPublisher?.onStart();
+    fleetPublisher?.onStart(); // MF-Fleet: the row goes live (running) the moment the background run starts
+    // Cancel (POST /v1/runs/:id/cancel): the controller aborts the run two ways — (a) same-replica fast path,
+    // the cancel handler looks this up in `inflight` and aborts now; (b) cross-replica, the heartbeat tick below
+    // polls the durable `cancel_requested` flag and aborts. Either way an aborted run finalizes to
+    // "failed" + errorCode "cancelled" (we do NOT extend TaskStatus — errorCode distinguishes user-cancel).
     const cancelCtrl = new AbortController();
     inflight?.set(taskId, cancelCtrl);
+    // stoppedBy (core 1.252): a service cancel is a USER stop — see markChildrenStoppedByUserOnAbort.
     markChildrenStoppedByUserOnAbort(cancelCtrl.signal, taskId, principal);
+    // design/80 seam #2 (preemption): only the plain-stream path can durably suspend-and-resume on a preempt (the
+    // verify/cascade branches setTerminal unconditionally). Register the preempt controller — and poll the durable
+    // flag — ONLY for that path, so the endpoint that looks a task up in `preemptable` can honestly tell a
+    // verify/cascade task apart (not preemptible) from a stream task.
     const preemptEligible = verify === undefined && cascade === undefined;
     const preemptCtrl = new AbortController();
     if (preemptEligible)
@@ -128,69 +347,157 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             metrics?.inc("task_tokens_total", {}, result.stats.tokens);
         if (result?.stats.cacheHitRate !== undefined)
             metrics?.observe("task_cache_hit_rate", result.stats.cacheHitRate);
+        // Degenerate-output a/b instrument (1.59) — same as the sync path; no-op unless output.degenerate.
         if (result)
             instrumentDegenerate?.(result);
+        // Plan-cache recurrence probe (design/42): objective recurrence per scope. status "completed" feeds
+        // the history ring (mirrors the sync path); other terminal states still count toward the denominator.
         planCacheProbe?.record(principal, spec.objective, status === "completed");
     };
+    // Liveness heartbeat (independent of events): keeps a long-but-alive run — e.g. one blocked in a
+    // multi-minute subagent that streams no parent events — from being mistaken for a dead instance.
+    // The owning principal is this run's owner — thread it as the single-DB-fleet null-safe owner guard on every
+    // run-store mutation/poll below (the run row was created with owner = principal ?? null).
     const owner = principal ?? null;
     const heartbeat = setInterval(() => {
         void runStore.heartbeat(taskId, owner).catch(() => undefined);
+        // Cross-replica cancel: the cancel may have landed on another instance, which only set the durable flag.
+        // Poll it here so the OWNING instance aborts its in-flight run (bounded by HEARTBEAT_MS).
         if (!cancelCtrl.signal.aborted) {
             void runStore.isCancelRequested(taskId, owner).then((c) => { if (c)
                 cancelCtrl.abort(); }).catch(() => undefined);
         }
+        // Cross-replica preempt (design/80 seam #2): a preempt may have landed on another instance (durable flag
+        // only). Poll it so the OWNING instance raises its preemptSignal → core suspends at the next clean turn
+        // boundary (resumable). Only the stream path wires the signal, so only poll there.
         if (preemptEligible && !preemptCtrl.signal.aborted) {
             void runStore.isPreemptRequested(taskId, owner).then((p) => { if (p)
                 preemptCtrl.abort(); }).catch(() => undefined);
         }
     }, HEARTBEAT_MS);
     heartbeat.unref?.();
+    // E18 resume-at: per-turn anchor capture (the turn's first text_delta eventId = the stable per-message handle, which
+    // is also stamped on the durable `text` event so the shell sees ONE resume handle per message). The shared
+    // TurnAnchorCapture only anchors a SETTLED assistant-text turn (text + no tools) — see its doc; the metric surfaces
+    // a systematic capture failure (un-migrated DB) instead of a silent feature outage.
     const anchor = new TurnAnchorCapture(captureTurnAnchor, () => metrics?.inc("resume_anchor_capture_failed"), captureUserMessageAnchor);
+    // Once a terminal outcome's event is DURABLY appended, the run has reached that state — record it so a later
+    // failure (e.g. setTerminal throws after the `done` event is logged) re-attempts the SAME terminal write
+    // rather than clobbering a completed run with `failed` (which would log both `done` and `failed` and report a
+    // succeeded task as failed).
     let reached;
+    // 1.78 (review LOW): the plain-stream leg's live TaskStream — held so the finally can identity-guard the
+    // `steerable` deregistration (see the finally).
     let steerableStreamRef;
+    // false once this leg settles — a background subagent/bash completion arriving AFTER that has no live
+    // harness for core's in-process injection (the idle gap), so the observer below parks it durably instead.
     let legLive = true;
+    // option A: taskNotificationStreamKey (域:task_id:status[#seq], core [784]④a + codex F2 域二分) keys
+    // already carried by THIS leg (start-of-leg inbox drain, event-stream branch OR observer) — each arm skips
+    // keys another arm already delivered, so a notification isn't double-appended to the durable log (the
+    // turn-TAIL reap notification, which never reaches the stream, is exactly the one the observer catches;
+    // core's pend-drain replay of a double-parked idle arrival is exactly the one the drain-registration
+    // catches). The shell's dedup stays the outer belt. codex F1: value = the claiming write's outcome promise
+    // (the observer arm appends fire-and-forget; a failed claim must NOT eat the stream replay — see NotifiedKeys).
     const notifiedKeys = new NotifiedKeys();
+    // design/122 ③: THIS leg's subagent-handle unregister thunks (identity-guarded by the registry) — run at
+    // leg end (finally), NOT on child settle, so a settled child stays resumable while the parent run lives.
     const subagentHandleEvictions = [];
+    // design/80 D-B: PARK a `needs_review` result (a dry-run diff review OR a pre-action `plan_review` pause; core
+    // assemble-result slot 8.6) like a suspend — KEEP task_active + flip the row non-terminal so the resume
+    // (getActiveTaskId → markResuming) can claim it. Without this every finalize site setTerminal'd it (deleting the
+    // session lock), and the plan_review resume then got taskId=undefined → drove the model UNPROTECTED on an
+    // unlocked session with the row stuck `needs_review` (the adversarial-review HIGH finding). Mirrors the suspended
+    // branch (append only the non-secret gate, never the capability token).
     const parkNeedsReview = async (res) => {
         await sink.appendParked("needs_review", res);
-        await flushModelUsage();
+        await flushModelUsage(); // E8: persist pre-park usage before the review pause (resume leg accumulates fresh)
         reached = { kind: "needs_review" };
         await runStore.setNeedsReview(taskId);
         metrics?.addGauge("runs_active", -1);
         metrics?.inc("tasks_total", { status: "needs_review" });
     };
+    // [900]①/[906]③: the event→ledger projection (text/reasoning coalescing + redaction + seq + the type/data
+    // whitelist shapes) lives in the SHARED LedgerSink — the sync /v1/tasks/stream detach lane consumes the same
+    // single switch, so the two ledgers can't drift. This leg keeps its non-ledger side-legs (anchor/metrics/
+    // model-usage/park-terminal/fleet) in place and drives the sink; `append`/`flush` below stay the leg-local
+    // names for every out-of-band row (elicit/question frames, model_usage deltas, suggestions, failed) so they
+    // share the run's single seq counter. `notifiedKeys` is the same per-leg instance the observer/drain arms use.
     const sink = createLedgerSink({ appendEvent: (seq, type, data) => runStore.appendEvent(taskId, seq, type, data), persistThinking, notifiedKeys });
     const append = (type, data) => sink.append(type, data);
     const flush = () => sink.flush();
+    // E8 (shell-host contract): drain the per-task model-usage accumulator into an append-only `model_usage` DELTA event, so
+    // the durable log is the resume-safe source of `TaskStats.modelUsage`. Called at every turn boundary AND before a
+    // park (suspend/needs_review) — a run that suspends has its pre-suspend usage persisted before the resume leg
+    // continues accumulating; the append-only deltas SUM across all legs (no overwrite).
     const flushModelUsage = () => appendModelUsageDelta(append, modelUsage, taskId);
+    // At a TERMINAL done: flush the final delta + SUM all `model_usage` events into result.stats.modelUsage (shared
+    // with the resume leg's terminal so a suspended→resumed run's total is summed across both legs).
     const withModelUsage = (result) => attachModelUsage(result, { append, getEvents: (id, after) => runStore.getEvents(id, after), modelUsage, taskId });
-    modelUsage?.register(taskId);
+    modelUsage?.register(taskId); // E8 leak fence: only this top-level run's brain.calls are tracked (sub-tasks excluded)
+    // [998]②: same fence — sub-task manifests are never registered, never leak. The returned LEASE guards the
+    // finally's clear (B-3 window: a fast sibling resume re-registers this taskId before our finally runs —
+    // an unconditional clear would delete the NEW leg's registration/pending manifest).
     const manifestLease = promptManifests?.register(taskId) ?? 0;
+    // [998]②: no-op when nothing is pending (one Map.get) — fired per stream event so the manifest lands at the
+    // top of the log right after core's prepare records it, and before the terminal on the no-stream legs.
     const flushPromptManifest = () => appendPromptManifest(append, promptManifests, taskId);
+    // E23 (shell-host contract): an inbound MCP elicitation fired deep inside core's callTool surfaces via onElicit, which has
+    // no taskId — so establish a per-run elicitation context (ALS) carrying this run's emit (durable append → delivered
+    // on the events tail), owner (respond owner-gate) + cancel signal (a run abort cancels a parked elicitation). The
+    // elicitation append interleaves safely: onElicit is awaited SYNCHRONOUSLY inside callTool, so the loop is parked
+    // (not appending) while it runs. No-op when elicitation is off. `type` is the SSE event name; the rest is the data.
     const elicitEmit = (frame) => {
         const { type, ...rest } = frame;
         return append(type, rest);
     };
+    // §4④: same durable-append emit for AskUserQuestion frames (delivered on the events tail; the shell renders `question`
+    // + dismisses on `question_complete`). onQuestion is awaited SYNCHRONOUSLY inside core's callTool, so the loop parks
+    // (not appending) while it runs — the open frame's append is ordered ahead of the answer/terminal appends.
     const questionEmit = (frame) => {
         const { type, ...rest } = frame;
         return append(type, rest);
     };
     try {
+        // P1 ①② follow-on (core): drain this session's async-workflow completion inbox at the START of the
+        // background leg (before ANY branch — verify/cascade/plain-stream all get it; parity with the sync leg's
+        // stream-open drain) into durable `workflow_complete` events the tailing client (GET /v1/runs/:id/events)
+        // replays as <task-notification>s. Best-effort inside the helper (it never throws); inside the try so the
+        // heartbeat/gauge finally-cleanup would cover even a defensive miss. Owner gate mirrors the elicit/question owner.
         await emitPendingWorkflowCompletions(workflowCompletionInbox, spec.sessionId, elicitOwner ?? owner, (frame) => {
             const { type, ...rest } = frame;
+            // core [784]④b: register the drained frame's key on THIS leg — the same idle-arrival was ALSO parked
+            // core-side (pendingSessionNotifications); its pend-drain replay rides this run's stream as a
+            // task_notification event, and the loop's key check folds that second durable append (sync twin's note).
+            // 三路复审修2(MED,推翻旧 codex F1 注释的 resolved(true) 登记):emitPendingWorkflowCompletions
+            // 虽 await 这次 append,但它 CATCH 失败(留 row 不 ack)——键却已被 Promise.resolve(true) 认领;
+            // core 若把同一 pending 经 pend-drain 重放到本腿 stream 臂,stream 臂见「真成功」claim 抑制重写,
+            // 通知就延到下一次开腿(可能无限延)。登记真实 append 结果:失败 resolve false,stream 臂
+            // await 到 false 照写(咬合 NotifiedKeys 的 F1 语义);row 未 ack 的下腿重投仍是兜底。
+            // codex F2: task_type rides into the key(drained frames restore it from the entry extras)——
+            // external 帧独立键域,不与内部任务帧互吞.
             const f = frame;
             const write = append(type, rest);
             if (f.type === "task_notification" && f.task_id)
                 notifiedKeys.set(taskNotificationStreamKey({ task_type: f.task_type, task_id: f.task_id, status: String(f.status), seq: f.seq }), write.then(() => true, () => false));
             return write;
-        }, completionDiagLog ? { route: "bg-run-start", connection: "durable-append", log: completionDiagLog } : undefined);
+        }, 
+        // ask①: emit-target diagnostics — this drain appends to THIS background run's durable event log.
+        completionDiagLog ? { route: "bg-run-start", connection: "durable-append", log: completionDiagLog } : undefined);
+        // Thread the owning principal so the cost tracer attributes this run's spend (incl. council/team
+        // sub-tasks) to the principal's cumulative quota — mirrors the synchronous path.
         const runBody = async () => {
             if (verify !== undefined) {
+                // Developer-mode verification gate (1.44): multi-round (impl → adversarial verify → fix loop), not
+                // a stream — await the result and persist it terminal. The durable event log gets just the `done`
+                // (the verifier subtask runs on its own session). `result.verification` carries the verdict.
                 const result = await runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify);
                 await flush();
                 evictIfConflict(runner, spec.sessionId, result);
-                await flushPromptManifest();
-                const safe = await withModelUsage(stripCheckpointToken(result));
+                // A nested suspend under the verify gate is mapped by core to status:"failed" carrying the capability
+                // token — strip it before it touches the replayable log / run row (search [18] Q1b).
+                await flushPromptManifest(); // [998]②: the verify leg has no stream — persist the manifest before the terminal
+                const safe = await withModelUsage(stripCheckpointToken(result)); // E8: attach stats.modelUsage at terminal
                 await append("done", { result: safe });
                 reached = { kind: "done", result: safe };
                 await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
@@ -198,21 +505,39 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 return;
             }
             if (cascade !== undefined) {
+                // Cascade (1.45): cheap→strong ladder; multi-attempt cold re-runs, not a stream. Persist terminal.
                 const result = await runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade);
                 await flush();
                 evictIfConflict(runner, spec.sessionId, result);
-                await flushPromptManifest();
-                const safe = await withModelUsage(stripCheckpointToken(result));
+                await flushPromptManifest(); // [998]②: same no-stream posture as the verify leg above
+                const safe = await withModelUsage(stripCheckpointToken(result)); // see the verify branch; E8 modelUsage at terminal
                 await append("done", { result: safe });
                 reached = { kind: "done", result: safe };
                 await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
                 recordDone(safe, safe.status);
                 return;
             }
+            // design/47 (mid-task steering): hold the live stream handle so POST /v1/runs/:id/steer can inject a steer via
+            // stream.steer() (drained at the next turn boundary). Only this plain-stream path is steerable — the verify/
+            // cascade branches above return a result, not a stream (parity with the preemptable registration). Deregistered
+            // in `finally`. Registering it AFTER the verify/cascade early-returns means those legs never enter the map.
+            // core 1.154 nested-subagent live tree: opt into the forward sink — a subagent's task_progress lives in the
+            // child run's ISOLATED stream (core's only emitter is parentToolCallId-gated and pushes onto the CHILD queue;
+            // the top stream NEVER carries it), so this sink is the ONLY path a tick reaches the top-run consumers. 1.78
+            // (review HIGH): fan it out to the DURABLE event log too (via the shared whitelist+redact builder, fire-and-
+            // forget — `++seq` is a sync increment so sink-vs-loop appends get unique seqs), not just the fleet bus —
+            // previously no fleet bus wired ⇒ ticks dropped entirely, and the stream-switch task_progress case below is
+            // forward-compat only (dead against core ≤1.208). core swallow-guards a throwing sink.
             const fwdInternals = {
                 onForwardEvent: (e) => {
                     fleetPublisher?.onForwardEvent(e);
+                    // C1 (core 1.219): a delegated child's tool lifecycle + task_progress ticks persist through the SHARED
+                    // sink (same whitelist+redact builders as the top stream — §E1, forwarded events are UNTRUSTED RAW;
+                    // fire-and-forget with sync seq allocation). Rationale + the deliberate per-chunk-delta omission live
+                    // on LedgerSink.onForwardEvent.
                     sink.onForwardEvent(e);
+                    // S2 live tail(core 1.370 bgAgentId,[1520]{core}):bg 子代帧按句柄分发给 per-agent 订阅者
+                    // (sync 腿 twin 在 http/server.ts)。hasSubscribers 快门=没人听不投影;投影一次 N 订阅者共享。
                     const bg = e.bgAgentId;
                     if (bg !== undefined && defaultSubagentTailBus.hasSubscribers(bg)) {
                         const f = projectTailFrame(e);
@@ -220,25 +545,60 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                             defaultSubagentTailBus.publish(bg, f);
                     }
                 },
+                // (durable half is the deployment's job): observe EVERY background
+                // completion notification. (1) flip the child's fleet row (task_progress never emits a terminal tick —
+                // without this a settled bg agent showed "running" until parent settle); (2) when the LEG already ended
+                // (idle — core's steer/followUp had nowhere to go), park it in the durable inbox; the next stream-open
+                // drain emits it as the same `task_notification` frame family. Workflow-type notifications are SKIPPED —
+                // they have their own durable chain (notify gate + inbox + serve fences); double-enqueueing would re-open
+                // the double-push. While the leg is LIVE, core injects in-process + the stream carries the display frame —
+                // no durable copy (a boundary-race notification that misses both is covered by the TaskOutput poll floor).
+                // core 1.283 `seq` (per-stop-cycle counter) rides into the dedup key + parked entry — core [784]④a.
+                // 白名单排查(clay 令,2026-07-24,「彻查 as {} 连环坑」):此前手写窄类型(仅 10/19 键),3 处
+                // (此处+http/server.ts 两处)复制粘贴、随 core payload 增field 逐渐过时——n 本身按引用直转
+                // taskNotificationEventData({notification:n}),运行时不丢字段(该函数自己的白名单是完整的),
+                // 但窄类型会让未来在这些回调体内新增读字段的人被 TS 误导「这个字段到不了这里」。改用 core
+                // 真实导出类型,杜绝副本漂移。
                 onTaskNotification: (n) => {
                     if (n.task_type === "workflow")
                         return;
+                    // S2 复审 #3(sync 腿同注):中途终态信号。
                     if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
                         defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
                     }
+                    // id-domain alias (core): fleet child rows key by the TICK's taskId = the child's sessionId
+                    // (uuid domain); the notification's task_id is the a* domain — payload.sessionId IS the tick-domain
+                    // alias, so flip by it (fallback task_id for pre-1.238 payloads / bash lane).
                     const hadRow = fleetPublisher?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false;
                     const parked = !legLive && Boolean(workflowCompletionInbox && spec.sessionId);
+                    // diagnosability: one line per observed bg completion. hadFleetRow=false = the terminal frame was
+                    // FLIP-THROUGH synthesized (the row was gone — parent settle removed it, or a bg BASH never ticked).
                     completionDiagLog?.("task_notification_observed", { route: "bg-run-start", taskId: n.task_id, taskType: n.task_type, status: n.status, hadFleetRow: hadRow, legLive, parkedDurable: parked });
                     if (parked) {
+                        // 对抗评审 2026-07-11(MED):log the enqueue failure — the diag line above already printed
+                        // parkedDurable:true, so a swallow made that a false park✓ fingerprint. Never faults the callback.
                         void workflowCompletionInbox.enqueue(taskNotificationInboxEntry(spec.sessionId, elicitOwner ?? owner, n, Date.now(), taskId)).catch((err) => completionDiagLog?.("park_enqueue_failed", { route: "bg-run-start", taskId: n.task_id, err: err instanceof Error ? err.message : String(err) }));
                     }
                     else if (legLive) {
+                        // option A (the turn-TAIL killed receipt must be IMMEDIATE): a teardown-time reap
+                        // notification fires while the leg is still live but past the stream's delivery window — core's
+                        // in-process steer is swallowed and the event never reaches the log. Append the display frame HERE,
+                        // skipping keys the stream already delivered (mid-turn dedup); the tailing client renders the receipt
+                        // this turn, not one turn late. core [784]④a: seq-folded shared key — the seq-less
+                        // `${task_id}:${status}` shape reverse-swallowed a second stop-cycle's same-status frame here.
+                        // codex F1 (HIGH): this append is fire-and-forget — claim the key with its REAL outcome, not
+                        // unconditionally. A failed append (SQL blip) resolves the claim false, and the stream arm's
+                        // await-then-write below re-delivers the same key instead of being swallowed by a dead claim.
                         const key = taskNotificationStreamKey(n);
                         if (notifiedKeys.get(key) === undefined) {
                             notifiedKeys.set(key, append("task_notification", taskNotificationEventData({ notification: n })).then(() => true, () => false));
                         }
                     }
                 },
+                // C2 (core 1.219) + design/122 (core 1.225 ③): register each SYNC child's steer handle under THIS
+                // run's taskId. NOT evicted on settle — `resume` is only legal AFTER the child settled (a settle-evict
+                // would make revival structurally unreachable). Evicted at LEG END via the collected identity-guarded
+                // thunks (finally below); a resume re-emits a FRESH handle under the same id (registry newest-wins).
                 ...(subagentSteer
                     ? {
                         onSubagentSpawn: (handle) => {
@@ -248,30 +608,53 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     : {}),
             };
             const stream = runner.runTaskStream({ ...spec, taskId, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, undefined, fwdInternals);
-            steerableStreamRef = stream;
+            steerableStreamRef = stream; // held for the finally's identity-guarded delete (1.78 review LOW)
             steerable?.set(taskId, stream);
             for await (const ev of stream) {
+                // MF-Fleet: accrue this run's fleet-row tokens (turn_end usage). Fired before the switch so every event
+                // reaches it. No-op when no bus is wired. (Subagent task_progress arrives via the FORWARD sink above, not
+                // this top stream — the case below is forward-compat only; a stale comment here claimed otherwise.)
                 fleetPublisher?.onEvent(ev);
+                // [998]② release-review round 2: drain the pending prompt manifest at the TOP of every iteration —
+                // BEFORE the done/suspend branches below. A done-first stream (post-prepare failure/abort, or an
+                // immediate suspend) would otherwise skip the flush entirely: the manifest recorded at prepare would
+                // be cleared by the finally (or, worse, survive a lease-guarded no-op clear into a fast sibling
+                // resume's queue and land AFTER the suspension event). Here it always precedes its own terminal.
                 await flushPromptManifest();
+                // Non-ledger side-legs stay HERE (E18 anchor capture / S4 metrics) — the event→ledger projection itself
+                // is the shared sink below (single switch; the sync detach lane consumes the same one, so the persisted
+                // type/data vocabulary has ONE source). Ordering parity: anchor.onTool precedes the sink's tool_start
+                // flush (as before); the metric fires before the brain_status row lands (metric ≠ ledger, no row moves).
                 switch (ev.type) {
                     case "text_delta":
-                        anchor.onText(ev.eventId);
+                        anchor.onText(ev.eventId); // E18: latch the turn's first-text eventId = the message's resume handle
                         break;
                     case "tool_start":
-                        anchor.onTool();
+                        anchor.onTool(); // E18: a tool ran this turn → not a settled assistant-text boundary (don't anchor it)
                         break;
                     case "status":
+                        // S4 (SILENT-FALLBACK P0-a): count the brain-layer liveness observation (the sink persists the row —
+                        // previously: sync SSE only, async runs completely dark).
                         metrics?.inc("brain_retry_total", { phase: String(ev.phase) });
                         break;
                     case "message_committed":
+                        // R8 (CC-parity rewind): a persisted session entry was committed. Capture a USER-message rewind anchor
+                        // (keyed by taskId) straight from its `entryId` — the CC "rewind to the prompt" target. assistant entries
+                        // are anchored by the turn-text path; tool-results are deliberately not anchored (resumeAt rejects them).
+                        // NOT forwarded to the durable trace / shell stream (core口径: replay walks the persisted session tree —
+                        // the sink deliberately ignores this type).
                         await anchor.onMessageCommitted(ev.role, ev.entryId);
                         break;
                 }
                 if (ev.type === "done") {
                     await flush();
                     if (ev.result.status === "suspended") {
+                        // Durable F4 pause (design/45): PARK the run (non-terminal), NOT a `done`. Never persist the
+                        // capability `checkpointToken` to the replayable event log / run row (search [18] Q1b) — only the
+                        // non-secret gate (sink.appendParked). The submitter polling GET /v1/runs/:id sees status:"suspended";
+                        // an operator resumes via /v1/approvals (token looked up internally). The worker is freed (runs_active -1).
                         await sink.appendParked("suspended", ev.result);
-                        await flushModelUsage();
+                        await flushModelUsage(); // E8: persist pre-suspend usage before parking (resume leg accumulates fresh)
                         reached = { kind: "suspended" };
                         await runStore.setSuspended(taskId);
                         metrics?.addGauge("runs_active", -1);
@@ -279,12 +662,18 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                         continue;
                     }
                     if (ev.result.status === "needs_review") {
+                        // design/80 D-B: a review pause (plan_review / dry_run_review) — PARK it like a suspend (keep the lock)
+                        // so the /v1/assistant/tasks/:id/plan_review resume can claim the row. NEVER persist the token.
                         await parkNeedsReview(ev.result);
                         continue;
                     }
+                    // A session CAS conflict arrives here as a failed result (core swallows it) — evict the
+                    // now-stale warm-cache entry so the next turn re-wakes from TiDB instead of re-conflicting.
                     evictIfConflict(runner, spec.sessionId, ev.result);
+                    // Structural token fence (no-op today; this plain-stream path's only token-bearing result is the
+                    // suspended branch above, handled separately) — symmetric with the verify/cascade + resume paths.
                     {
-                        const safe = await withModelUsage(stripCheckpointToken(ev.result));
+                        const safe = await withModelUsage(stripCheckpointToken(ev.result)); // E8: attach stats.modelUsage at terminal
                         await sink.appendDone(safe);
                         reached = { kind: "done", result: safe };
                         await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
@@ -292,17 +681,37 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     }
                     continue;
                 }
+                // The shared event→ledger projection (text/reasoning coalescing, whitelist+redact builders, flush-before
+                // discipline, task_notification dedup against this leg's `notifiedKeys`) — see LedgerSink.onEvent.
+                // (The prompt-manifest drain runs at the loop TOP — ahead of done/suspend too, see above.)
                 await sink.onEvent(ev);
                 if (ev.type === "turn_end") {
-                    await flushModelUsage();
+                    await flushModelUsage(); // E8: persist this turn's per-model usage delta (resume-safe)
+                    // E18 resume-at: anchor (this turn's message eventId → its leaf SessionTreeEntry.id), but ONLY for a settled
+                    // assistant-TEXT turn (text + no tools) — for a tool-using turn the leaf here is the last tool-result, NOT
+                    // the message the eventId names (see TurnAnchorCapture). Best-effort + reset for the next turn.
                     await anchor.onTurnEnd();
                 }
             }
+            // E12 (shell-host contract): after a COMPLETED run, pull core's opt-in post-completion prompt suggestions (a fire-and-forget
+            // pass in core; suggestions() never rejects + resolves to [] when off / not completed / empty). UNTRUSTED model
+            // text for the shell UI ONLY → redact + persist as a `suggestions` event so the shell reads it off the events tail
+            // (like model_usage); NEVER re-fed to a model. Gated on a COMPLETED terminal — a suspended/parked/failed leg has
+            // none (core also returns [] for a non-completed task; the explicit status gate avoids the needless call + pins the
+            // completed-only contract rather than depending on core's guard).
             if (spec.suggestNextPrompts && reached?.kind === "done" && reached.result.status === "completed") {
                 const suggestions = await stream.suggestions().catch(() => []);
+                // 🔴 **空结果也要落事件**(2026-07-26):这个事件是「已结算」的唯一信号。此前 `if (suggestions.length)`
+                // 才 append ⇒ 「跑完了、确实一条都没有」在轮询面上与「还没跑完」完全同形(都是 `suggestions: undefined`)
+                // ⇒ 轮询方无从判断该不该停。而 `setTerminal`(上方)在本段**之前**执行,所以确实存在一个真实的
+                // pending 窗口 —— 这正是本仓刚在后台 shell `poll()` 上修过的**同一类**:消费方拿终态当停止条件,
+                // 而数据在终态之后才到。⇒ 事件在 = 已结算(哪怕是空);事件不在 = 仍在跑。
                 await append("suggestions", { suggestions: suggestions.map((s) => redactSecrets(s)) });
             }
         };
+        // E23 + §4④: nest the elicitation AND AskUserQuestion per-run contexts (each its own ALS) around the run body — a
+        // background run's inbound elicitation AND the agent's AskUserQuestion both route to this run's durable events tail
+        // + owner-gated respond. Same id/owner/signal; the nesting order is immaterial (disjoint ALS).
         await withPrincipal(principal, () => {
             const withElicit = elicitation
                 ? () => elicitation.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: elicitEmit, abortSignal: cancelCtrl.signal }, runBody)
@@ -310,10 +719,13 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             const withQuestion = () => question
                 ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: questionEmit, abortSignal: cancelCtrl.signal }, withElicit)
                 : withElicit();
+            // SendUserFile 帧与 question 帧同投递面(durable events tail,web 渲染文件卡);嵌套序无关(ALS 互不相交)。
             return sendUserFile
                 ? sendUserFile.runWithContext({ taskId, emit: (frame) => { const { type, ...rest } = frame; return append(type, rest); } }, withQuestion)
                 : withQuestion();
         });
+        // Cancelled mid-stream and the generator ended WITHOUT a terminal event (abort can end the stream cleanly
+        // rather than throwing) — finalize cancelled here so the run isn't left "running" for the reaper to catch.
         if (!reached && cancelCtrl.signal.aborted) {
             await flush();
             const c = cancelledResult();
@@ -326,29 +738,41 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         try {
-            await flush();
+            await flush(); // persist any buffered turn text before recording the failure (don't drop it)
             if (reached?.kind === "done") {
+                // The task already produced a terminal result (its `done` event is durably logged); only the run-row
+                // write failed. Re-attempt THAT write — never write `failed` over a completed run.
                 await runStore.setTerminal(taskId, reached.result.status, reached.result, reached.result.errorMessage ?? null);
             }
             else if (reached?.kind === "suspended") {
-                await runStore.setSuspended(taskId);
+                await runStore.setSuspended(taskId); // parked, not failed — re-attempt the suspend row write
             }
             else if (reached?.kind === "needs_review") {
-                await runStore.setNeedsReview(taskId);
+                await runStore.setNeedsReview(taskId); // D-B: parked on a review gate — re-attempt the review-park row write
             }
             else if (cancelCtrl.signal.aborted) {
+                // Cancelled: the abort threw out of the stream/verify/cascade. Record a cancelled terminal (queryable
+                // errorCode) instead of a generic failure, so the portal can show "cancelled by user" not an error.
                 const c = cancelledResult();
                 await append("failed", { errorMessage: c.errorMessage ?? "cancelled by user", errorCode: "cancelled" });
                 await runStore.setTerminal(taskId, "failed", c, c.errorMessage ?? null);
             }
             else {
+                // BL-12: redact the raw exception message before it lands in the durable event log / run row — a tool
+                // or transport error can carry a secret (a credentialed URL, a token) and the trace surface is served
+                // to TRACE_TOKEN holders. redactSecrets is best-effort + idempotent (the read side redacts again, BL-13).
                 const safeMsg = redactSecrets(message);
                 await append("failed", { errorMessage: safeMsg });
                 await runStore.setTerminal(taskId, "failed", null, safeMsg);
             }
         }
         catch {
+            /* best-effort: the stale reaper will catch a run we couldn't finalize */
         }
+        // recordDone runs exactly once: the success paths call it inline (and return/break before the throw); we
+        // reach here only if the terminal-row write threw AFTER the event was logged, or on a genuine failure.
+        // A cancelled terminal keeps its distinct metric label even on this retry path (council B2: the result's
+        // STATUS is "failed" — labeling by status would count a user cancel as a failure).
         if (reached?.kind === "done")
             recordDone(reached.result, reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status);
         else if (reached?.kind === "suspended") {
@@ -356,15 +780,22 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             metrics?.inc("tasks_total", { status: "suspended" });
         }
         else if (cancelCtrl.signal.aborted) {
-            recordDone(null, "cancelled");
+            recordDone(null, "cancelled"); // distinct metric label; the run row is "failed"+errorCode:"cancelled"
         }
         else {
             recordDone(null, "failed");
         }
     }
     finally {
-        legLive = false;
+        legLive = false; // notifications from here on take the durable-inbox path
+        // MF-Fleet: flip/remove the fleet row at the SINGLE finalization point — runs once for EVERY exit path
+        // (success / cancel / error / suspend / needs_review). A truly-terminal status leaves the fleet; a PARKED
+        // status (suspended→waiting / needs_review→awaiting approval) STAYS (the run is still active). A cancelled
+        // run carries status:"failed"+errorCode:"cancelled" — map it to "killed" so the row reads as a kill, not a
+        // failure. `reached` undefined ⇒ errored/aborted before any terminal event (catch recorded failed/cancelled).
         if (fleetPublisher) {
+            // [1839]①/(a) 案:真终态帧带残局键(usage=stats 映射 / cancel⇒stoppedBy:"user" / transcriptId=sessionId);
+            // parked(suspended/needs_review)不带(publisher 侧也再挡一层)。
             if (reached?.kind === "done")
                 fleetPublisher.onTerminal(reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status, fleetRunResiduals(reached.result));
             else if (reached?.kind === "suspended")
@@ -373,22 +804,32 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 fleetPublisher.onTerminal("needs_review");
             else
                 fleetPublisher.onTerminal(cancelCtrl.signal.aborted ? "cancelled" : "failed", {
+                    // errored/aborted before any terminal event — no TaskResult.stats to map; the transcript still exists.
                     ...(cancelCtrl.signal.aborted ? { stoppedBy: "user" } : {}),
                     ...(spec.sessionId ? { transcriptId: spec.sessionId } : {}),
                 });
         }
+        // 对抗复查 B-3(HIGH):identity-guard these two like `steerable` below — the run row flips suspended
+        // BEFORE this finally runs, so a fast resume can re-register the SAME taskId (a fresh cancelCtrl /
+        // preemptCtrl) in the window; an unconditional delete then evicted the NEW leg's entry, and drain
+        // under-counted the resuming leg (its cancel/preempt handles also went unreachable).
         if (inflight?.get(taskId) === cancelCtrl)
             inflight.delete(taskId);
         if (preemptable?.get(taskId) === preemptCtrl)
             preemptable.delete(taskId);
+        // Identity-guarded (1.78 review LOW, parity with the sync/resume legs): only delete the handle THIS leg
+        // registered and only if it is still ours — a fast sibling leg re-registering the same taskId must not lose
+        // its fresh handle to our teardown; never registered ⇒ nothing of ours to delete.
         if (steerableStreamRef !== undefined && steerable?.get(taskId) === steerableStreamRef)
             steerable.delete(taskId);
         for (const evict of subagentHandleEvictions)
-            evict();
-        modelUsage?.clear(taskId);
-        promptManifests?.clear(taskId, manifestLease);
+            evict(); // design/122 ③: leg-end handle eviction (identity-guarded — a fast sibling leg's fresh handles survive)
+        modelUsage?.clear(taskId); // E8: drop any un-drained accumulation (abandoned/errored leg) — no memory leak
+        promptManifests?.clear(taskId, manifestLease); // [998]②: lease-guarded — a stale leg never tears down the new leg's slot
         clearInterval(heartbeat);
     }
 }
+/** How often a running instance refreshes its run's updated_at (liveness, independent of events).
+ *  Must stay strictly below `runStaleSec` (asserted at startup) or the reaper would race live runs. */
 export const HEARTBEAT_MS = 30_000;
 //# sourceMappingURL=runs.js.map