@sema-agent/sdk 6.8.0 → 6.9.0

package/openapi.yaml

@@ -56,8 +56,17 @@ openapi: 3.1.0
 #   live    — implemented & verified server-side; in the contract-test assertion set.
 #   draft   — verb exists but the response shape is not fully pinned; co-design pending (do not over-assert).
 #   planned — NOT yet implemented server-side; documented for SDK/producer alignment; EXCLUDED from
-#             contract-test assertions until it ships.
-#   gated   — implemented but off by a server deploy flag (e.g. leader); not on the default product path.
+#             contract-test assertions until it ships. ⚠️ It is a claim about the SERVER, and it EXPIRES:
+#             once the face ships, move it to `live`/`gated` the same day. Two gates now police that —
+#             `spec-path-drift-gate` (planned ∩ paths the SDK actually calls must be empty) and
+#             `test/live/route-existence.test.ts` (a planned path must have NO handler in the pinned
+#             server artifact). Both exist because `POST /v1/tasks/{taskId}/asks/{askId}/decision` kept
+#             this label for two server releases after it went live.
+#   gated   — implemented but off by a server deploy flag (e.g. leader, STREAM_APPROVAL_ENABLED); answers
+#             501 where the flag/deps are unmet. Says nothing about the flag's DEFAULT — that can differ
+#             per server version, so read the matching `capabilities` bit, never this label.
+#   retired — the face was DELETED server-side; the entry is a tombstone kept so consumers generated from
+#             an older spec can find out where it went. No deployment serves it.
 # ─────────────────────────────────────────────────────────────────────────────
 
 info:
@@ -907,7 +916,7 @@ paths:
       responses:
         '200':
           # 🔴 census 批2 第三段(2026-07-30)spec 谎修正:这条 200 此前只有一句 description、**零 content
-          # 声明**(机器视角=「无 body」),而 server 真发 JSON(`routes/runs.ts:1155`,与 output 面同一个
+          # 声明**(机器视角=「无 body」),而 server 真发 JSON(`routes/runs.ts`,与 output 面同一个
           # sendJson,含 g14 的条件 `cursorSemantics`)。补接同一个 schema。
           description: 'Stopped — same projection shape as the output verb.'
           content:
@@ -1077,8 +1086,8 @@ paths:
               schema:
                 type: object
                 # 封闭(census 批2 第二段):三个 200 铸造点都是单键字面量 —— `{deleted:false}` 两处
-                # (未知会话 / 外租户,`routes/sessions.ts:491,495`)+ purgeSession 的 `{deleted}` 返回
-                # (`http/server.ts:255` 的签名就是这一个键;它的另一臂 `{active}` 走 409)。
+                # (未知会话 / 外租户,`routes/sessions.ts`)+ purgeSession 的 `{deleted}` 返回
+                # (`http/server.ts` 的签名就是这一个键;它的另一臂 `{active}` 走 409)。
                 additionalProperties: false
                 required: [deleted]
                 properties:
@@ -1115,7 +1124,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 封闭:铸造点 `routes/sessions.ts:469` 是单键字面量 `{ sessionId: newId }`。
+                # 封闭:铸造点 `routes/sessions.ts` 是单键字面量 `{ sessionId: newId }`。
                 additionalProperties: false
                 required: [sessionId]
                 properties:
@@ -1157,7 +1166,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 封闭:铸造点 `routes/sessions.ts:212` 是两键字面量;版本号本身走 ETag 响应头,不进体。
+                # 封闭:铸造点 `routes/sessions.ts` 是两键字面量;版本号本身走 ETag 响应头,不进体。
                 additionalProperties: false
                 required: [sessionId, leafId]
                 properties:
@@ -1295,7 +1304,7 @@ paths:
           description: Delivered onto the live stream.
           content:
             application/json:
-              # 封闭(census 批2 第三段,2026-07-30):live 臂铸造点 `routes/notify-wake.ts:98` 是两键字面量。
+              # 封闭(census 批2 第三段,2026-07-30):live 臂铸造点 `routes/notify-wake.ts` 是两键字面量。
               # 4.3.0:形提成具名 `SessionNotifyResult` 的 live 臂(SDK 同批给了判别联合返回型)。
               schema:
                 type: object
@@ -1308,7 +1317,7 @@ paths:
           description: No live stream — parked in the session inbox, drained on the next stream open.
           content:
             application/json:
-              # 封闭 + note 补 required:parked 臂铸造点 `routes/notify-wake.ts:116` 是三键字面量,note 无条件。
+              # 封闭 + note 补 required:parked 臂铸造点 `routes/notify-wake.ts` 是三键字面量,note 无条件。
               schema:
                 type: object
                 additionalProperties: false
@@ -1352,7 +1361,7 @@ paths:
       responses:
         '200':
           # 🔴 census 批2 第三段(2026-07-30)spec 谎修正:此前这里写的是 **202** + required [taskId,…]。
-          # 亲读真码:wake 的成功腿是 `driveResumeIntoRunLog` 的返回(`server.ts:2289` 与取消臂 `:2240`),
+          # 亲读真码:wake 的成功腿是 `driveResumeIntoRunLog` 的返回(`server.ts`,成功腿与取消臂两处铸造点),
           # **恒为 200**(wake 是同步驱动到终局/再挂起,不是 accepted 回执),且 `taskId` 有条件
           # (无活跃行即省略——ApprovalDecisionResult 同一铸造点的同一注)。旧 202+required taskId 双谎。
           description: Woken — the resumed leg ran to its next settle (terminal, re-suspended, or needs_review).
@@ -1405,8 +1414,7 @@ paths:
           description: The snapshot listing.
           content:
             application/json:
-              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:624-629`(信封)与
-              # `:620`(行)。条件键=信封 `latest`(零快照即省略)、行 `bytes`(blobSizes 面缺席=诚实省略)。
+              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts`(信封与行两处)。条件键=信封 `latest`(零快照即省略)、行 `bytes`(blobSizes 面缺席=诚实省略)。
               # 4.3.0:形提成具名 `WorkspaceSnapshotPage`(SDK 同批把返回位的内联字面量也提成了 exported type,
               # 让 spec-resource-schema-gate 罩得住 —— CAPS-OPS-8)。
               schema: { $ref: '#/components/schemas/WorkspaceSnapshotPage' }
@@ -1450,8 +1458,7 @@ paths:
           description: One page of the tree.
           content:
             application/json:
-              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:651-657`(信封)与
-              # `:654`(行)。条件键=信封 `nextOffset`(尾页省略)、行 `size`(blobSizes 面缺席省略)。
+              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts`(信封与行两处)。条件键=信封 `nextOffset`(尾页省略)、行 `size`(blobSizes 面缺席省略)。
               # 4.3.0:形提成具名 `WorkspaceTreePage`(理由同 list 腿 —— CAPS-OPS-8)。
               schema: { $ref: '#/components/schemas/WorkspaceTreePage' }
         '400': { $ref: '#/components/responses/BadRequest' }
@@ -1571,7 +1578,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 封闭:铸造点 `routes/sessions.ts:540` 是单键字面量。BC-3 保证 `rules` 恒非 null
+                # 封闭:铸造点 `routes/sessions.ts` 是单键字面量。BC-3 保证 `rules` 恒非 null
                 # (无策略的已属会话回 `{rev:0}` 空记录,绝不回 `{rules:null}`)。
                 additionalProperties: false
                 required: [rules]
@@ -1612,7 +1619,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 封闭:铸造点 `routes/sessions.ts:558` 是单键字面量 `{ rules: stored }`。
+                # 封闭:铸造点 `routes/sessions.ts` 是单键字面量 `{ rules: stored }`。
                 additionalProperties: false
                 required: [rules]
                 properties:
@@ -1656,8 +1663,11 @@ paths:
 
   # ── 2c session-sync (P1d) — the cloud as a SYNC PEER ──────────────────────────────────────────────────────────
   # The local shell's local backend ⇄ this cloud service. PULL a session's whole state out, or PUSH the local
-  # peer's in. Gate the whole surface off `capabilities.sessionSync` (= durable backend + entry export + a
-  # file-snapshot store). Owner-gated like fork/delete (§9): a PULL 404s a non-owner; a PUSH is own-or-FRESH.
+  # peer's in. Gate the whole surface off `capabilities.sessionSync` — a FOUR-way conjunction (durable backend
+  # AND entry export AND import STAGING AND a file-snapshot store). The staging conjunct is not decorative: a
+  # three-conjunct predicate was disproven in the field ([2024]) when a warm-cache wrapper store forwarded the
+  # other three and dropped the staging family, so caps said true while PUSH Phase A 501'd forever.
+  # Owner-gated like fork/delete (§9): a PULL 404s a non-owner; a PUSH is own-or-FRESH.
   /v1/sessions/{sessionId}/sync/manifest:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -1675,7 +1685,7 @@ paths:
         `/sync/entries`) + per-snapshot relPath→blobHash + policy + anchors + leaf. The local peer feeds `entryIds`
         to the §7 classifier to decide fast-forward/fork BEFORE pulling the entry stream + only the blob hashes it
         lacks. Owner-scoped (non-owner → 404, no oracle); 400 on an id that is not uuid-SHAPED — 🔴 the sync family's
-        gate is `isUuidShape` (ANY uuid version), NOT `isUuidV7`: server `routes/session-sync.ts:135-138` deliberately
+        gate is `isUuidShape` (ANY uuid version), NOT `isUuidV7`: server `routes/session-sync.ts` deliberately
         keeps a v4-keyed legacy shell session pushable (it was creatable via the lenient submit face), while
         crafted-id classes stay shut out. `fork`/`delete`/`policy` DO use `isUuidV7` — only this family is lenient;
         501 without a durable session store.
@@ -1686,7 +1696,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 封闭(census 批2 第三段,2026-07-30):铸造点 `routes/session-sync.ts:165` 是单键字面量。
+                # 封闭(census 批2 第三段,2026-07-30):铸造点 `routes/session-sync.ts` 是单键字面量。
                 additionalProperties: false
                 required: [manifest]
                 properties:
@@ -1889,7 +1899,7 @@ paths:
                   description: >
                     🔴 OPTIONAL content digest of the SOURCE's whole entry log (core `sessionLogDigest`, scheme
                     `sema-log-v3`; this leg's core floor is ^1.416.0). Server producer/consumer:
-                    `routes/session-sync.ts:295,310,357-366`. This is THE key that makes `ImportStaged.payloadVerified:true`
+                    `routes/session-sync.ts`. This is THE key that makes `ImportStaged.payloadVerified:true`
                     reachable — until 4.3.0 the response schema promised a `payloadVerified`/`entry-ids+digest` pair
                     that the request side had no way to trigger. Rationale: `identical` is classified from entry-id
                     SETS only, and an entry id is a uuidv7 (NOT content-addressed), so "same ids, different payloads"
@@ -2086,7 +2096,7 @@ paths:
             Owner-gate / unknown session (no existence oracle), OR — [2400] CB-2, declared 2026-08-02 — the core
             code `checkpoint.not_found`: the pending checkpoint this decide addressed is gone. It is the ONE
             member of the mirrored `checkpoint.*` family the server sends as a 404 rather than a 409
-            (`src/http/server.ts:2199`: `e.code === "checkpoint.not_found" ? 404 : 409`), so the SDK maps it to
+            (`src/http/server.ts`: `e.code === "checkpoint.not_found" ? 404 : 409`), so the SDK maps it to
             NotFoundError while the rest of the family maps to ConflictError. Client action: refetch the inbox —
             do not retry this decide.
           content:
@@ -2101,14 +2111,14 @@ paths:
             ConflictError vs ApprovalBindingMismatchError. binding_mismatch = SAFETY signal: refetch + re-present
             to the human, NEVER auto-retry.
             FOURTH member ([2400] CB-2, declared 2026-08-02): `gate_not_tool_approval` — the suspension this
-            sessionId is parked on is NOT a tool-approval gate (`src/http/server.ts:1581` rejects pre-CAS when the
+            sessionId is parked on is NOT a tool-approval gate (`src/http/server.ts` rejects pre-CAS when the
             gate kind is neither `human` nor `irreversible_ask`: nothing is consumed, no model leg burns). It is
             the THIRD member of the wrong-door guard family alongside `gate_not_resumable` (§4b) and
             `gate_not_plan_review` (§4c) → SDK `GateNotToolApprovalError`. Client action: route by the row's
             `gateKind` — `plan_review` → `POST /v1/assistant/tasks/{taskId}/plan_review`, `resource_limit` →
             `POST /v1/assistant/tasks/{taskId}/resume`. Retrying the same body never succeeds.
             FIFTH group ([2400] CB-2): the core `checkpoint.*` family the server mirrors verbatim
-            (`src/http/server.ts:2199-2206`) — `checkpoint.gate_mismatch` / `checkpoint.reopen_failed` /
+            (`src/http/server.ts`) — `checkpoint.gate_mismatch` / `checkpoint.reopen_failed` /
             `checkpoint.reopen_revote` / `checkpoint.already_exists` / `checkpoint.resume_aborted` /
             `checkpoint.unsupported_version` all arrive as 409 and fall on the SDK's `checkpoint.` PREFIX family
             (→ ConflictError, `.errorCode` carried verbatim; an OPEN set, so a future core code degrades with
@@ -2246,7 +2256,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 封闭:铸造点 `routes/approvals-assistant.ts:146` 的 200 臂是单键字面量
+                # 封闭:铸造点 `routes/approvals-assistant.ts` 的 200 臂是单键字面量
                 # `{ revoked: true }`(404 臂是另一个字面量,走 NotFound 信封)。
                 additionalProperties: false
                 required: [revoked]
@@ -2475,7 +2485,7 @@ paths:
             application/json:
               schema:
                 type: object
-                # 🔴 封闭 + 两处 spec 谎修正(census 批2 第三段,2026-07-30),铸造点 `routes/trace-usage.ts:61`:
+                # 🔴 封闭 + 两处 spec 谎修正(census 批2 第三段,2026-07-30),铸造点 `routes/trace-usage.ts`:
                 #   ① 顶层信封 server 真发 `{sinceSec, rows}` —— `sinceSec`(生效的窗口秒数,默认 86400)
                 #      此前整键不在 spec 里;
                 #   ② 行 `source` 三个 store 实现(sql/pg/local 的 sourceSummary)签名都是 `string | null`
@@ -2495,7 +2505,7 @@ paths:
                         status: { type: string }
                         count: { type: integer }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { $ref: '#/components/responses/NotImplemented' }   # 无 durable run store(capability.run_store_required)——`routes/trace-usage.ts:56`,此前漏登记
+        '501': { $ref: '#/components/responses/NotImplemented' }   # 无 durable run store(capability.run_store_required)——`routes/trace-usage.ts`,此前漏登记
 
   /v1/tasks/{taskId}/artifacts:
     parameters:
@@ -2536,7 +2546,7 @@ paths:
           # 🔴 修正(2026-07-25):此处原先 $ref 到 `AgentEvent`,是真错 —— 而且本文件自己就矛盾:专门为这条路写的
           #   `TraceStreamEvent` schema 的描述里明写「A DISTINCT vocabulary from AgentEvent」,却没有任何地方引用它
           #   (它是本文件里的一个孤儿 schema)。按 server 真码两侧取证后确定 TraceStreamEvent 才是对的:
-          #   `streamTaskTrace` 每帧走 `mapTraceEvent`(`trace/project.ts:530`),发的是 SSE **event 名**
+          #   `streamTaskTrace` 每帧走 `mapTraceEvent`(`trace/project.ts`),发的是 SSE **event 名**
           #   `block-thinking-delta` / `block-content-delta` / `tool-call` / `tool-result` / `turn` /
           #   `prompt-assembled` / `done` / `error`,帧里**没有** `type` 字段;SDK 的 `trace.stream()` 注释逐字同款。
           #   照旧声明生成的客户端会去 switch 一个不存在的 `type` ⇒ 这条流路对它完全不可用。
@@ -2680,7 +2690,7 @@ paths:
               schema:
                 type: object
                 # 🔴 封闭 + `defaultModel` 补登记(census 批2 第三段,2026-07-30):铸造点
-                # `routes/capabilities.ts:322` 三键字面量。`defaultModel`([865]③ id/name 撕裂消解,server
+                # `routes/capabilities.ts` 三键字面量。`defaultModel`([865]③ id/name 撕裂消解,server
                 # 已发多版)SDK `models.list()` 的返回类型早就带,**spec 是唯一没登记的一侧** —— 生成式
                 # 消费方对它全瞎。`name` 条件(目录无命中即省略),`id` 恒在。
                 additionalProperties: false
@@ -2817,7 +2827,7 @@ paths:
     post:
       tags: [questions]
       operationId: askDecision
-      x-status: planned          # design/172 §3.2 (#151 车4) — UNRELEASED; ships with server 7.3.0, gated OFF by STREAM_APPROVAL_ENABLED. SDK toolApprovals.decideAsk() 消费。
+      x-status: gated            # design/172 §3.2 (#151 车4) — SHIPPED in server 7.3.0 (7.3.0/7.4.0 both on npm); off-by-flag (STREAM_APPROVAL_ENABLED, default OFF ≤7.4.0 / ON ≥7.5.0) ⇒ 501 feature.approval_ask_disabled when the five-way gate is unmet. SDK toolApprovals.decideAsk() 消费。
       summary: Settle an IN-STREAM approval card (design/172 streaming approval protocol).
       description: >
         The in-stream sibling of POST /v1/tool-approvals/{id}/respond: the approver is live on the SSE stream, so
@@ -3123,7 +3133,7 @@ paths:
         POST-MERGE FULL row — replace by `row.id`, NOT a sparse patch) + `event: task_remove`/`event:
         workflow_remove` `{id, ts}` departures.
         🔴 Keep-alive is a REAL NAMED FRAME — `event: heartbeat` + `data: {}` every 15 s
-        (`src/http/routes/fleet.ts:223`), NOT an SSE `: hb` comment (the旁注 says why: a per-frame-parsing BFF
+        (`src/http/routes/fleet.ts`), NOT an SSE `: hb` comment (the旁注 says why: a per-frame-parsing BFF
         drops comments, so downstream saw a zero-frame window). Do NOT implement the reader as "skip lines
         starting with `:`" — swallow the heartbeat BY NAME. (Corrected 2026-08-02; the `: hb` shape belongs to
         `GET /v1/sessions/{sessionId}/events` alone, and beats at a tunable ~25 s.)
@@ -3279,7 +3289,7 @@ paths:
       summary: 'Newest PUBLISHED entry for a profile → { image }.'
       responses:
         # 🔴 census 批2 四段:this arm was a bare open `{}` (no `image` key even declared) — the handler's real
-        # body is `{ image: entry }` (images.ts:478-484), entry = the SAME ImageIndexEntry as the list route.
+        # body is `{ image: entry }` (images.ts), entry = the SAME ImageIndexEntry as the list route.
         '200': { description: '{ image: entry }.', content: { application/json: { schema: { type: object, required: [image], additionalProperties: false, properties: { image: { $ref: '#/components/schemas/ImageIndexEntry' } } } } } }
         '404': { $ref: '#/components/responses/NotFound' }
 
@@ -3293,7 +3303,7 @@ paths:
       x-status: live
       summary: 'Entry by immutable digest → { image }.'
       responses:
-        # 🔴 census 批2 四段:same open-`{}` gap as imagesByProfile — real body `{ image: entry }` (images.ts:466-472).
+        # 🔴 census 批2 四段:same open-`{}` gap as imagesByProfile — real body `{ image: entry }` (images.ts).
         '200': { description: '{ image: entry }.', content: { application/json: { schema: { type: object, required: [image], additionalProperties: false, properties: { image: { $ref: '#/components/schemas/ImageIndexEntry' } } } } } }
         '404': { $ref: '#/components/responses/NotFound' }
 
@@ -3568,7 +3578,7 @@ paths:
               schema:
                 type: object
                 # 🔴 census 批2 五段:CLOSED — exact literal `{ scope, exportedAt, entries }`
-                # (memory-policy.ts:58), no fourth key.
+                # (memory-policy.ts), no fourth key.
                 required: [scope, exportedAt, entries]
                 additionalProperties: false
                 properties:
@@ -3649,7 +3659,7 @@ paths:
               schema:
                 type: object
                 # 🔴 census 批2 五段:path↔schema 脱钩修(same class as the earlier BakeClaim/usage-triplet
-                # finds) — `OutcomeRow` already existed named+correct (observability.ts:51's exact
+                # finds) — `OutcomeRow` already existed named+correct (observability.ts's exact
                 # `{ outcomes: rows }`) but this path never `$ref`'d it, declaring a bare open `{}` instead.
                 required: [outcomes]
                 additionalProperties: false
@@ -3819,7 +3829,7 @@ paths:
           description: 'Injected. Body `{ runId, label, status: "running", delivery: "applied", marker }`.'
           # 🔴 census 批2 五段:spec-谎修——this 200 declared a bare `description` with NO `content`/`schema`
           # at all (classify() reads it as "no-json", invisible to both the open- and closed-op ledgers)
-          # while the server genuinely sends a JSON body (workflows.ts:279). The named schema
+          # while the server genuinely sends a JSON body (workflows.ts). The named schema
           # `WorkflowAgentSteerReceipt` already existed (path↔schema decoupling, same class as the earlier
           # BakeClaim/usage-triplet finds) — wiring it up here, not inventing a new one.
           content:
@@ -3863,7 +3873,7 @@ paths:
           content:
             application/json:
               # 🔴 census 批2 五段:CLOSED against the real emitter — `sendJson(res, 200, { model,
-              # ...deps.metrics.summarize() })` (server.ts:794) is a fixed key set (server observability/
+              # ...deps.metrics.summarize() })` (server.ts) is a fixed key set (server observability/
               # metrics.ts `MetricsSummary`), not an ops free-for-all. Left `x-status: draft` / `x-sdk: none`
               # untouched (still deliberately outside the SDK's wrapped surface) — closing the SHAPE and
               # keeping it un-wrapped are independent axes.
@@ -4054,8 +4064,8 @@ components:
         `Capabilities.scenarios` instead. `source`/`builtin` = builtin vs center-config overlay; `toolset` names
         the tool bundle while `tools` are the resolved tool names; `promptSummary` is a human-readable prompt
         DIGEST (never the full prompt); `enabled` = a center scenario can be declared-but-disabled.
-      # 封闭(census 批2 第三段,2026-07-30):路由 `routes/capabilities.ts:38` 原样发 `deps.scenarioDetails[name]`,
-      # 其类型 `ScenarioDetail`(capabilities/scenarios.ts:353)恰是这 8 个必填键;builtin 工厂 `mk`(:379)与
+      # 封闭(census 批2 第三段,2026-07-30):路由 `routes/capabilities.ts` 原样发 `deps.scenarioDetails[name]`,
+      # 其类型 `ScenarioDetail`(capabilities/scenarios.ts)恰是这 8 个必填键;builtin 工厂 `mk` 与
       # center overlay 都按该接口铸,无第 9 键来源。
       required: [name, source, builtin, summary, toolset, tools, promptSummary, enabled]
       additionalProperties: false
@@ -4200,7 +4210,7 @@ components:
           type: string
           description: >-
             [2400] TR-16 (declared 2026-08-02) — CALLER-MINTED uuidv7 task id: the DURABLE second tier of
-            idempotency on POST /v1/runs (`src/http/routes/runs.ts:196-217`). The `Idempotency-Key` header's
+            idempotency on POST /v1/runs (`src/http/routes/runs.ts`). The `Idempotency-Key` header's
             cache is in-memory and PER-POD, so a dispatch gateway that re-routes a retry to ANOTHER instance
             after a network error would start a SECOND run; THIS replay reads the durable run store, so it
             survives the re-route and a restart — it is the prerequisite for gateway failover. A hit replays the
@@ -4390,7 +4400,7 @@ components:
           description: Quality-gate cascade (cheap→strong). Mutually exclusive with `verify`. Not on the stream.
         suggestNextPrompts:
           description: >
-            E12 (shell-host; service spec-fields.ts:9 / runs.ts:392, SHIPPED) — opt-in post-completion "what to ask
+            E12 (shell-host; service spec-fields.ts / runs.ts, SHIPPED) — opt-in post-completion "what to ask
             next" suggestions. After a COMPLETED run, core runs an LLM pass and the service appends a `suggestions`
             event to the durable run-events tail. `true` = core defaults; the object form tunes count / generating
             role. 🔴 Mutually exclusive with `verify`/`cascade` (those return a result, not a streamed run → 400).
@@ -4421,8 +4431,12 @@ components:
             callability; the advertised schema stays the empty object); `swap` advertises the REAL schema on the
             next request. A provider whose decoding is CONSTRAINED by the advertised schema loops UNBOUNDED under
             `static` (every round emits `{}` and the next round still advertises an empty schema), which is why
-            this is a per-task knob. OMIT to inherit the engine chain (`spec ?? env ?? static`) — sending an
-            explicit value takes that decision away from the deployment env lane. Unknown value => 400 fail-loud.
+            this is a per-task knob. OMIT to inherit the engine chain,
+            `spec ?? env(SEMA_TOOL_MATERIALIZE_STRATEGY) ?? "swap"` — sending an explicit value takes that
+            decision away from the deployment env lane. 🔴 The chain-tail default is **`swap`** (this text used
+            to say `static`): it defaulted to `static` for exactly one core release window and core 5.15.0
+            (BREAKING) put it back to `swap`; the server floor is core >= 5.16.0, so every supported deployment
+            resolves an omitted value to `swap`. Unknown value => 400 fail-loud.
         clientContext:
           type: object
           description: Non-authoritative client hints (never trusted for authz).
@@ -4465,7 +4479,7 @@ components:
           type: boolean
           description: >
             🔴 PER-TASK opt-in for forwarding subagent CONTENT onto the parent's event stream (server
-            `src/http/wire-types.ts:157`, consumed at `boot/resolve-spec.ts:557` — read STRICTLY as `=== true`).
+            `src/http/wire-types.ts`, consumed at `boot/resolve-spec.ts` — read STRICTLY as `=== true`).
             ⚠️ The capability bit of the same name says "this body key is ACCEPTED", NOT "forwarding is on":
             it is hard-coded true, while forwarding itself is OFF unless this key is sent. Without it the parent
             stream carries progress-only frames and a subagent-transcript view stays empty forever.
@@ -4476,11 +4490,11 @@ components:
             - type: object
               additionalProperties: false
               properties:
-                ttlMs: { type: integer, description: 'Retention window; server CLAMPS to ≤ 24 h (task-workflow.ts:77-83).' }
+                ttlMs: { type: integer, description: 'Retention window; server CLAMPS to ≤ 24 h (task-workflow.ts).' }
                 max: { type: integer, description: 'Retained session count; server CLAMPS to ≤ 64.' }
           description: >
             🔴 PER-TASK opt-in to RETAIN finished subagent sessions so they can be resumed (server
-            `src/http/wire-types.ts:169`, normalized at `boot/resolve-spec.ts:564`). This is the OTHER HALF of
+            `src/http/wire-types.ts`, normalized at `boot/resolve-spec.ts`). This is the OTHER HALF of
             `POST /v1/runs/{runId}/subagents/{handle}/resume`: the capability bit `subagentResume` can be true and
             the route mounted, and the call still 409s `resume.retain_off` — retention is per-run and OFF by default.
             An over-large ask is CLAMPED, not rejected. (Declared 2026-08-02; the error code and the capability bit
@@ -4572,7 +4586,7 @@ components:
       # 🔴 **刻意不封闭**(census 轴一裁定,2026-07-30)。此前是「没写」= JSON Schema 默认开放,分不清
       # 「决定了要开」还是「忘了」;现在显式写成 true,让这条决定可读、可复审。理由:server 对引擎
       # `TaskResult` 是**整体透传**(runs.ts `withModelUsage` 只做 `{...result, stats:{...}}` 的加法),
-      # 而 SDK 的 `TaskResult`/`TaskStats` 两侧都带 `[key: string]: unknown` 开集(types.ts:119)——把
+      # 而 SDK 的 `TaskResult`/`TaskStats` 两侧都带 `[key: string]: unknown` 开集(types.ts)——把
       # 这里改成 false 会让 spec 与本仓自己的类型面互相打脸,并且把「引擎加字段」判成 wire 违约(它不是)。
       # 收紧这一面的正解不是 additionalProperties,是把引擎真发的键**逐个登记**(字段级 drift 门的活)。
       additionalProperties: true
@@ -4684,7 +4698,7 @@ components:
 
     RunReceipt:
       type: object
-      # 封闭(census 轴一,2026-07-30):producer 铸造点 routes/runs.ts:180 与 idem 重放臂各自逐字写死
+      # 封闭(census 轴一,2026-07-30):producer 铸造点 routes/runs.ts 与 idem 重放臂各自逐字写死
       # `{taskId, sessionId, status}` —— 三键全在场、无第四键 ⇒ required 已完整,additionalProperties 收紧到
       # false 后「server 多发一个 spec 没登记的键」当场红(此前 ①档只校已声明键的类型,多键完全不可见)。
       additionalProperties: false
@@ -4701,7 +4715,7 @@ components:
         Run state (`GET /v1/runs/:id`) — live shape per the pinned wire contract Drift 2: `result` is the NESTED TaskResult
         object (output text in result.result, stats in result.stats; NO top-level stats), and the error text
         field is `error` (not errorMessage; errorCode is floated up from result.errorCode).
-      # 封闭(census 轴一,2026-07-30):铸造点 routes/runs.ts:337-351 是一个逐键写死的字面量,恰好 10 键
+      # 封闭(census 轴一,2026-07-30):铸造点 routes/runs.ts 是一个逐键写死的字面量,恰好 10 键
       # (taskId/sessionId/status/result/supervisorCost/suggestions/errorCode/error/jobId/source),与本
       # properties 一一对上;只有前三键无条件在场(其余走 `?? undefined` ⇒ JSON 丢键)⇒ required 维持 3 键。
       additionalProperties: false
@@ -4765,7 +4779,7 @@ components:
       description: >
         Synchronous ack for `POST /v1/runs/:id/cancel`. `status` is "cancelling" (accepted) or a terminal status
         (idempotent no-op). NOTE: "cancelling" is NOT a RunStatus enum member — it only appears here.
-      # 封闭(census 轴一,2026-07-30):cancel 面的 7 个 sendJson 铸造点(routes/runs.ts:417/436/480/483/
+      # 封闭(census 轴一,2026-07-30):cancel 面的 7 个 sendJson 铸造点(routes/runs.ts
       # 495/505/512)键集的并集恰好 = {taskId, status, note?, errorCode?};taskId/status 无条件在场。
       additionalProperties: false
       required: [taskId, status]
@@ -4866,7 +4880,7 @@ components:
         securityContext: { type: object, additionalProperties: true, description: 'k8s-shaped, genuinely arbitrary — Record<string,unknown> server-side.' }
 
     ImageSelectResult:
-      # 新增(2026-07-25 回填批)。🔴 census 批2 四段:closed against the real handler (images.ts:407-415) — ALL
+      # 新增(2026-07-25 回填批)。🔴 census 批2 四段:closed against the real handler (images.ts) — ALL
       # seven keys are unconditionally assigned every 200 (required tightened from none); `manifestSha` can be
       # null (ImageIndexEntry.manifestSha is `string | null`, this was typed non-nullable — a spec lie); and
       # `podContract`/`capabilities` now share the SAME closed schemas as ImageIndexEntry (no more drift/no
@@ -4943,7 +4957,7 @@ components:
       description: >
         Turn trace envelope (`GET /v1/tasks/:id/turns`). Key is `turns` (resource-named). `retainedFrom` marks
         the lowest retained seq. Turn ITEM shape is draft (co-design with artifacts, Q7).
-      # 封闭 + required 补全(census 轴一,2026-07-30):铸造点 routes/trace-usage.ts:233
+      # 封闭 + required 补全(census 轴一,2026-07-30):铸造点 routes/trace-usage.ts
       # `{ turns, ...(nextCursor?{nextCursor}:{}) , retainedFrom }` —— `retainedFrom` 是**无条件**键
       # (`RunStore.retainedFrom(): Promise<number>`,四个实现都返回数字),此前只 required 了 `turns`,
       # 于是「server 少发 retainedFrom」这种断页判据丢失对本门不可见。
@@ -4959,7 +4973,7 @@ components:
     TaskList:
       type: object
       description: Paginated run summaries (`GET /v1/tasks`). Envelope key is `tasks` (resource-named, NOT `items`).
-      # 封闭(census 轴一,2026-07-30):信封铸造点 routes/trace-usage.ts:201 只有 tasks + 条件 nextCursor。
+      # 封闭(census 轴一,2026-07-30):信封铸造点 routes/trace-usage.ts 只有 tasks + 条件 nextCursor。
       # 行本身(`TaskSummary`)保持开集 —— 它的 TS 侧有索引签名(引擎透传),那份「开」是真的。
       additionalProperties: false
       required: [tasks]
@@ -5020,7 +5034,7 @@ components:
 
     ArtifactList:
       type: object
-      # 封闭(census 轴一,2026-07-30):铸造点 routes/trace-usage.ts:214 只有 artifacts 一键(无分页)。
+      # 封闭(census 轴一,2026-07-30):铸造点 routes/trace-usage.ts 只有 artifacts 一键(无分页)。
       # 行本身(`Artifact`)保持开集(TS 侧索引签名)。
       additionalProperties: false
       required: [artifacts]
@@ -5032,7 +5046,7 @@ components:
     LeaderReceipt:
       type: object
       description: >
-        202 receipt of POST /v1/leader (server leader/endpoint.ts:130 — exact literal
+        202 receipt of POST /v1/leader (server leader/endpoint.ts — exact literal
         `{ leaderRunId, status: "running" }`; the POST ack is always the "running" value, the other
         `status` enum members only ever appear on the GET twin below).
       # 🔴 census 批2 五段:CLOSED — the POST handler's literal never carries a third key.
@@ -5045,12 +5059,12 @@ components:
     LeaderRecord:
       type: object
       description: >
-        200 body of GET /v1/leader/{leaderRunId} (server leader/endpoint.ts:142-150 — exact literal
+        200 body of GET /v1/leader/{leaderRunId} (server leader/endpoint.ts — exact literal
         `{ id, status, ...(result?{result}:{}), ...(error?{error}:{}) }`).
       # 🔴 census 批2 五段:两处修——① CLOSED(result/error 是 OMIT-when-absent 的可选键,不是额外键);
       # ② `status` 的第四值 `needs_human`(LEADER-REPAIRLOOP-INTEGRATION §5/§10.6 的第三终态,
       # `statusForLeaderResult` 在 candidate_only/needs_human_oracle/conflict 三个 repairTerminal 上产出)
-      # 此前 SPEC LIES BY OMISSION——TS 侧 `LeaderRecord.status` 早就带这个第四值(types.ts:1607,亲验
+      # 此前 SPEC LIES BY OMISSION——TS 侧 `LeaderRecord.status` 早就带这个第四值(types.ts,亲验
       # 已在场),只有 spec 的 enum 一直缺它,是个只有场景真触发才会现形的假红洞(一个真实合法帧被判违约)。
       required: [id, status]
       additionalProperties: false
@@ -5113,7 +5127,7 @@ components:
       type: object
       description: >
         The legacy D-lane approval row of GET /v1/approvals/{approvalId} (server `ApprovalRow`,
-        plugins/approval-store-sql.ts:43 — the row is `sendJson`'d verbatim, approvals-assistant.ts:668).
+        plugins/approval-store-sql.ts — the row is `sendJson`'d verbatim, approvals-assistant.ts).
         Present only on deployments running the legacy `approvalStore` leg (no `checkpointStore` wired);
         the durable F4 lane has no by-id GET (only list + decide).
       # 🔴 census 批2 五段:CLOSED — byte-identical to the server row type, no extra keys.
@@ -5167,7 +5181,7 @@ components:
             legacy verbs in 1.0.0; the live face is `client.memory.exportScope` / `.sync`
             (`GET /v1/memory/export`, `POST /v1/memory/sync/{scope}`), which this flag does NOT gate.
             Kept on the wire so an older shell that still reads it honestly hides the dead affordances.
-        workflows: { type: boolean, description: "S8 self-orchestration workflow routes are mounted." }
+        workflows: { type: boolean, description: "ENGINE-CAN: this worker's engine can orchestrate S8 self-orchestration workflows (server: `workflowsCapable ?? Boolean(workflowRunStore)`). The MOUNTING of the durable /v1/workflows read routes is the separate `workflowsList` bit below; the two coincide in today's wiring but are declared as orthogonal axes." }
         workflowsList: { type: boolean, description: "`GET /v1/workflows` list face (separate from the per-run reads)." }
         resumeAt: { type: boolean, description: "E18 resume-at-message anchors are resolvable." }
         rewindFiles: { type: boolean, description: "E19 working-tree snapshot/restore is wired." }
@@ -5178,7 +5192,7 @@ components:
         sessionSearch: { type: boolean, description: "Server-side session search." }
         sessionFork: { type: boolean, description: "Session fork verb." }
         sessionDelete: { type: boolean, description: "Session delete verb." }
-        sessionInit: { type: boolean, description: "Session pre-initialization verb." }
+        sessionInit: { type: boolean, description: "`GET /v1/sessions/{sessionId}/init` startup bundle (E11 shell-host contract) is available. Pure config assembly (model + mode), always served — the server hard-codes true. NOTE: this advertises an ENDPOINT, not a `session_init` stream frame; no such frame exists on any leg." }
         sessionPolicy: { type: boolean, description: "E6 per-session operator-tightened tool rules are durable." }
         usage: { type: boolean, description: "QUOTA face wired (server costQuota dep — cost/token budget enforcement + per-principal accounting). NOT an analytics-availability probe ([1871] B15): per-turn analytics (turn_end.usage, model_usage frames) are engine-side and unconditional, and GET /v1/usage always answers 200 (with `enabled: false` when the quota face is off). Gate quota UI on this key; never gate analytics on it." }
         fleet:
@@ -5219,7 +5233,7 @@ components:
         sessionEvents:
           type: boolean
           description: >
-            🔴 契约调和车1 H② (2026-08-02): server HAS been emitting this key (`src/http/routes/capabilities.ts:70`)
+            🔴 契约调和车1 H② (2026-08-02): server HAS been emitting this key (the `sessionEvents` bit in `src/http/routes/capabilities.ts`)
             while both this spec and the SDK type were missing it. Gates `GET /v1/sessions/{sessionId}/events`
             (the session-level SSE head subscription). Predicate is a THREE-way AND: a durable session-watch seam
             plus a session store exposing BOTH `getLeafId` and `ownerOf` — the route's 501 uses the same
@@ -5253,8 +5267,8 @@ components:
         streamApproval:
           type: boolean
           description: >
-            design/172 IN-STREAM approval protocol is on this worker (server >=7.3.0,
-            `src/http/routes/capabilities.ts:233` — `resolveStreamApprovalGate(...).active`). TRUE ⇒ the live
+            design/172 IN-STREAM approval protocol is on this worker (server >=7.3.0, the `streamApproval` bit in
+            `src/http/routes/capabilities.ts` — `resolveStreamApprovalGate(...).active`). TRUE ⇒ the live
             stream may carry `approval_request` / `approval_revoke` frames and `POST
             /v1/tasks/{taskId}/asks/{askId}/decision` settles them. FALSE/absent ⇒ that endpoint answers **501
             `feature.approval_ask_disabled`** on every call and the two frames never appear — the SAME predicate
@@ -5264,15 +5278,22 @@ components:
             `backend.kind != "local"` (the ask ledger must be DURABLE — an in-memory ledger loses accepted
             decisions on restart) AND the park facility is present (checkpoint store + DURABLE_APPROVAL, the
             degradation target when a window expires; without it the outcome would be a fail-closed deny, worse
-            than today's live card). `STREAM_APPROVAL_ENABLED` is **default OFF**, so on virtually every
-            deployment today this bit is `false` and the legacy `tool_approval` live-card leg is the only
-            approval face. Orthogonal to `toolApproval` (the live-card leg) and to `approvals` (the durable
-            checkpoint leg) — all three can differ.
+            than today's live card). The deployment default for `STREAM_APPROVAL_ENABLED` reads in TWO
+            SEGMENTS: on server **<= 7.4.0 it is default OFF**, so on virtually every deployment of those
+            versions this bit is `false` and the legacy `tool_approval` live-card leg is the only approval face;
+            on server **>= 7.5.0 it is default ON** (published to npm 2026-08-07, disclosed as BREAKING in the
+            server CHANGELOG together with the ask window default 60s -> 300s), so a deployment meeting the
+            other four conjuncts serves the frames and the decision endpoint out of the box. BOTH segments are
+            live deployment realities — the first is not a historical footnote, it still describes every running
+            7.3.x/7.4.x install, and a consumer that reads only one of them is wrong about half the fleet.
+            `STREAM_APPROVAL_ENABLED=false` is the clean revert key. Do NOT infer from the version number or
+            from this prose — READ THIS BIT; it is the conjunction's actual value. Orthogonal to `toolApproval`
+            (the live-card leg) and to `approvals` (the durable checkpoint leg) — all three can differ.
         promptSuggestions: { type: boolean, description: "Follow-up prompt suggestions are generated." }
         modelUsage:
           type: boolean
           description: >
-            Per-model usage echo is available (server `src/http/routes/capabilities.ts:197`
+            Per-model usage echo is available (server: the `modelUsage` bit in `src/http/routes/capabilities.ts`,
             `Boolean(runStore && modelUsage)` — BOTH the durable run store and the tracker that feeds it;
             absent either, a consumer only gets aggregate cost).
             🔴 CORRECTED (契约调和车1 H③, 2026-08-02): this bit does NOT gate a read route — the route this
@@ -5288,21 +5309,25 @@ components:
         s3PublicEndpoint:
           type: ["string", "null"]
           description: >
-            Public base URL for artifact/snapshot links, when the deployment exposes one. `null` = not configured
-            (links are then worker-relative). One of only two NON-boolean capability values the server emits.
+            SendUserFile's S3 public-link base (`config.sendUserFile.publicEndpoint`), when the deployment
+            configures one. `null` = not configured. 🔴 CORRECTED: it has NOTHING to do with artifact/snapshot
+            links, and there is no "links are then worker-relative" fallback — an unconfigured endpoint makes
+            SendUserFile fail loudly and the sibling `sendUserFile` bit report false. A NON-boolean capability
+            value (there are several — see `taskSettings`, `fleet`, `workspace`, `version`, `scenarios`).
         taskSettings:
           type: object
           description: >
             Which `settings.json` sub-faces this worker honours (CC-parity v1). OPEN object — unknown keys may
-            appear. The other non-boolean capability value.
+            appear. One of the NON-boolean capability values (not "the other one": `fleet`, `workspace`,
+            `s3PublicEndpoint`, `version` and `scenarios` are non-boolean too — read each key's own shape).
           additionalProperties: true
           properties:
             permissions: { type: boolean }
             permissionMode: { type: boolean }
             model: { type: boolean }
             outputStyle: { type: boolean }
-            env: { type: boolean }
-            hooks: { type: boolean }
+            env: { type: boolean, description: 'TRUE on the single-user host lane (server emits `cwdHonored(config)`). It is NOT hard-coded false any more — the old always-false value predated the per-task shellEnv seam and hid a live capability.' }
+            hooks: { type: boolean, description: 'Single-user deployments only (`requirePrincipal !== true`).' }
         memoryWrite:
           type: boolean
           description: >
@@ -5388,7 +5413,7 @@ components:
       description: >
         core `MemoryEntry` (@sema-agent/core memory-engine/types.d.ts) — one memory-engine (DB twins)
         note. Used verbatim by both GET /v1/memory/export's `entries` and POST /v1/memory/sync/{scope}'s
-        `serverEntries` (server never re-shapes it — memory-policy.ts:57 / memory-sync.ts:79 pass the core
+        `serverEntries` (server never re-shapes it — memory-policy.ts / memory-sync.ts pass the core
         array straight to `sendJson`).
       required: [id, slug, frontmatter, body, rev, scope]
       additionalProperties: false
@@ -5403,8 +5428,8 @@ components:
     MemorySyncResponse:
       type: object
       description: >
-        200 body of POST /v1/memory/sync/{scope} — core `MemorySyncResponse` (server memory-sync.ts:74-86),
-        `sendJson`'d verbatim (memory-policy.ts:107). `pullTruncated` is OMIT-when-absent (present+`true`
+        200 body of POST /v1/memory/sync/{scope} — core `MemorySyncResponse` (server memory-sync.ts),
+        `sendJson`'d verbatim (memory-policy.ts). `pullTruncated` is OMIT-when-absent (present+`true`
         only when `serverEntries` was cut by `?pull.limit`).
       required: [applied, conflicts, serverEntries, serverDeletes, cursor]
       additionalProperties: false
@@ -5457,7 +5482,7 @@ components:
     MetricsSummaryOps:
       type: object
       description: >
-        200 body of GET /metrics/summary — `{ model, ...MetricsSummary }` (server.ts:794; server
+        200 body of GET /metrics/summary — `{ model, ...MetricsSummary }` (server.ts; server
         observability/metrics.ts `MetricsSummary` interface + `summarize()`, all keys unconditional).
         Ops/observability face (`x-sdk: none` on the path) — closed here for census fidelity, but this
         does NOT change its SDK-wrapping status.
@@ -5508,7 +5533,7 @@ components:
         A non-secret `@model` catalog entry (GET /v1/models; service src/http/routes/capabilities.ts). `name` = the `@handle` the
         user types in the objective body to pick this model per-task. 🔴 NON-SECRET — name/capabilities only, never
         baseUrl/apiKey/headers (the service strips them).
-      # 🔴 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):铸造点 `routes/capabilities.ts:295-313`
+      # 🔴 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):铸造点 `routes/capabilities.ts`
       # 是逐键字面量投影(白名单,不是透传——「open set」旧注不成立,新键要先过这道 spec)。core Model 类型
       # 里 id/provider/reasoning 都是必填、`vision` 由 `input` 恒算 ⇒ 五键无条件;contextWindow/maxOutputTokens
       # 0/缺省即省略,supportedEffortLevels 仅 reasoning 模型。
@@ -5548,7 +5573,7 @@ components:
 
     ElicitRespondAck:
       type: object
-      description: The 200 ack from a successful elicitation respond (service elicitation.ts:267).
+      description: The 200 ack from a successful elicitation respond (service elicitation.ts).
       # 封闭(census 批2 第三段,2026-07-30):铸造点是三键字面量,三键全部无条件。
       additionalProperties: false
       required: [elicitationId, delivery, action]
@@ -5560,7 +5585,7 @@ components:
     QuestionAnswer:
       type: object
       description: >
-        The shell's answer to a live `question` frame (= core QuestionAnswer, ask-question.ts:69). The service validates
+        The shell's answer to a live `question` frame (= core QuestionAnswer, ask-question.ts). The service validates
         only this OUTER shape (`answers[]` of `{header, selected:string[], note?}`); core owns the semantic fence
         (`selected ⊆ the offered options`, `note` wrapped in an untrusted-DATA fence).
       required: [answers]
@@ -5582,7 +5607,7 @@ components:
 
     QuestionRespondAck:
       type: object
-      description: The 200 ack from a successful question respond (service question.ts:226).
+      description: The 200 ack from a successful question respond (service question.ts).
       # 封闭(census 批2 第三段,2026-07-30):铸造点是两键字面量。
       additionalProperties: false
       required: [questionId, delivery]
@@ -5597,7 +5622,7 @@ components:
         the REQUEST principal. When no quota window is configured → enabled=false + ONLY windowSec/maxTask*
         (the amount/limit fields are ABSENT) — render must tolerate the gap.
       # 🔴 封闭 + required 补铸造点(census 批2 第二段,2026-07-30)。两条腿都是逐字字面量
-      # (`routes/observability.ts:68` 无配额臂 4 键 / `:72` 有配额臂 11 键),11 个属性就是并集。
+      # (`routes/observability.ts` —— 无配额臂 4 键 / 有配额臂 11 键),11 个属性就是并集。
       # required 从 `[enabled]` 抬到四键:`windowSec`/`maxTaskCostUsd`/`maxTaskTokens` 在**两条腿上都**
       # 无条件发送(config 直读),只列 `enabled` 是把恒在键写成了可缺 —— 消费方因此得写永远为真的判空。
       required: [enabled, windowSec, maxTaskCostUsd, maxTaskTokens]
@@ -5623,7 +5648,7 @@ components:
         admission + approval enforcement is 100% server-side). Top level CLOSED; the two pass-through
         collections (`commandPolicy` rows, `approvalRequire` entries) stay permissive — they are operator config
         echoed verbatim, not a service-minted shape.
-      # 🔴 封闭 + required(census 批2 第二段,2026-07-30):铸造点 `routes/memory-policy.ts:131` 是一个
+      # 🔴 封闭 + required(census 批2 第二段,2026-07-30):铸造点 `routes/memory-policy.ts` 是一个
       # 四键字面量,四个键**全部无条件**发送(`autonomy` 走 `?? null`,`commandPolicy` 走 `?? []`)——
       # 此前 required 是空的,于是「一个丢了三个键的响应」也能干干净净通过。
       required: [autonomy, commandPolicy, approvalRequire, limits]
@@ -5647,7 +5672,7 @@ components:
           type: object
           description: >
             Effective ceilings (single-task + principal-level + quota window). CLOSED (the literal at
-            `routes/memory-policy.ts:135` has exactly these four keys); the two `maxPrincipal*`/`costQuota*`
+            `routes/memory-policy.ts` has exactly these four keys); the two `maxPrincipal*`/`costQuota*`
             entries stay OUT of `required` — they are optional config and are omitted when unset.
           additionalProperties: false
           required: [maxTaskCostUsd, maxTaskTokens]
@@ -5670,7 +5695,7 @@ components:
         GET /v1/workflows list row = core summarizeWorkflowRun projection (owner-scoped; scope = the creating
         principal). All times are epoch MS.
         🔴 census 批2 四段(2026-07-30):CLOSED against core's real `summarizeWorkflowRun` (sema-core
-        src/core/workflow-run-store.ts:79-97) — `originatingSessionId`/`agentFailures` were emitted on the
+        src/core/workflow-run-store.ts) — `originatingSessionId`/`agentFailures` were emitted on the
         wire (both conditional-spread, present only when defined) but absent from this schema (two-side same-gap).
       required: [id, scope, status, phaseCount, agentCount, tokens, startedAt, createdAt]
       additionalProperties: false
@@ -5700,7 +5725,7 @@ components:
         🔴 `arg` is a SHORT primary-arg SUMMARY (command→name, path→basename, url→origin+path), secret-scrubbed
         and truncated (~80 code points) by core. It exists for the monitor's `Read(path)` / `Bash(grep …)`
         display — it is NOT the full args. RENDER it; NEVER re-feed it to a model.
-        🔴 census 批2 四段:CLOSED against core's real `ToolActivity` (sema-core src/core/types.ts:2332-2348) —
+        🔴 census 批2 四段:CLOSED against core's real `ToolActivity` (sema-core src/core/types.ts) —
         `at` (the [843]④a epoch-ms stamp, carried verbatim by both the start and end beat) was on the wire
         but absent from this schema.
       required: [phase, toolCallId, toolName]
@@ -5716,7 +5741,7 @@ components:
     WorkflowAgentRow:
       # 新增(2026-07-25 回填批)—— 取代 `WorkflowRun.agents` 的 `items: {}`(零形状)。
       # 🔴 census 批2 四段:CLOSED against the REAL wire projection — server's `summarizeWorkflowDetail`
-      # (src/http/routes/workflows.ts:358-394), not core's raw `WorkflowAgentRun`. The two differ: the server
+      # (src/http/routes/workflows.ts), not core's raw `WorkflowAgentRun`. The two differ: the server
       # ADDS `displayStatus`/`callKey`/`groupId`/`lastActivityAt`/`durationMs`/`queuedAt`/`startedAt`/`endedAt`/
       # `replayed` (all present on the wire but previously undeclared — same-side gap, no server change needed)
       # and DROPS core's `errorCode`/`errorMessage`/`attempts`/`lastAttemptReason`/`sessionId` (never projected
@@ -5753,7 +5778,7 @@ components:
 
     WorkflowPhaseProgress:
       # 新(census 批2 四段):此前 `WorkflowRun.phases` 是 `items: {}`(零形状)。真形 = server
-      # `summarizeWorkflowDetail`'s phases.map projection (workflows.ts:335-346) — a DERIVED progress view,
+      # `summarizeWorkflowDetail`'s phases.map projection (workflows.ts) — a DERIVED progress view,
       # not core's raw `WorkflowPhase` (drops `detail`/`model`/(phase-level) `agentFailures`; adds `done`/`total`).
       type: object
       description: One phase's progress in a workflow's detail (server-derived — done/total of the agents grouped under it).
@@ -5770,7 +5795,7 @@ components:
 
     WorkflowGroupNode:
       # 新(census 批2 四段):`WorkflowRun.groups` was undeclared entirely. Real shape = server's rebuilt nested
-      # tree (workflows.ts:399-441, GroupNode) — recursive, acyclic (a dangling/cyclic parentGroupId is grafted
+      # tree (workflows.ts, GroupNode) — recursive, acyclic (a dangling/cyclic parentGroupId is grafted
       # onto the root by the server, so this shape never actually cycles on the wire).
       type: object
       description: One node of the workflow's nested `ctx.workflow` group tree (rebuilt server-side from `parentGroupId`).
@@ -5788,7 +5813,7 @@ components:
 
     WorkflowRunStats:
       # 新(census 批2 四段):此前 inline `stats` 只钉了 `tokens`/`nested.tokens` 两键;真形 = core
-      # `WorkflowRunStats`(sema-core src/orchestration/workflow-types.ts:105-110)——own/nested 各自还有
+      # `WorkflowRunStats`(sema-core src/orchestration/workflow-types.ts)——own/nested 各自还有
       # `turns`/`costMicroUsd`,nested 另有 `tasks`。四键(own turns/costMicroUsd + nested 两键)此前两侧同缺。
       type: object
       description: 'Cumulative workflow usage. `own` (top-level) and `nested` (delegated sub-agents) are kept SEPARATE (R-5) — total spend = tokens + nested.tokens.'
@@ -5810,7 +5835,7 @@ components:
 
     WorkflowRun:
       # 🔴 census 批2 四段:CLOSED against the REAL wire projection — server's `summarizeWorkflowDetail`
-      # (src/http/routes/workflows.ts:317-475), which is a DERIVED view over core's `WorkflowRun`, not the raw
+      # (src/http/routes/workflows.ts), which is a DERIVED view over core's `WorkflowRun`, not the raw
       # record. This schema previously mirrored (a stale subset of) the core type; the actual wire adds
       # `durationMs`/`unphased`/`groups` and drops core's `sourceTaskId`/`originatingSessionId`/`effectiveArgs`/
       # `resultFull`/`completionId`/`resume`/`journalSkips` (never projected by this route — genuinely absent
@@ -5933,7 +5958,7 @@ components:
     SessionNotifyResult:
       # 4.3.0(SM-9):把 notify 的两态提成**具名** schema —— 此前只有 path 内联的两个匿名 200/202 形,
       # SDK 侧的返回型则是裸 `Record<string, unknown>`,`delivery` 这条承重语义(已送达 vs 排队)在类型面
-      # 整个丢失。铸造点 `routes/notify-wake.ts:98`(live)/ `:116`(parked),两臂都是字面量。
+      # 整个丢失。铸造点 `routes/notify-wake.ts`(live / parked 两臂),都是字面量。
       description: >
         POST /v1/sessions/{sessionId}/notify 的判别联合。分支 `delivery`:`live` = 会话有活流、通知已送达
         (HTTP 200);`parked` = 无活流,排队到下次开流才 drain(HTTP 202)。消费方不得把两者都渲染成"已通知"。
@@ -5984,7 +6009,7 @@ components:
         nextOffset: { type: integer, description: 'Pagination cursor; present only when the page is exactly `limit` rows.' }
     WorkflowJournalEntry:
       # 新(census 批2 四段):GET /v1/workflows/:id/journal row, the non-truncated arm (server `projectResult`,
-      # workflows.ts:127-134) — one agent()-call's cached TaskResult, bounded + redacted.
+      # workflows.ts) — one agent()-call's cached TaskResult, bounded + redacted.
       type: object
       description: One journal entry — a completed agent() call's projected TaskResult (bounded + redacted).
       required: [callKey, ordinal, status]
@@ -5999,7 +6024,7 @@ components:
         turns: { type: integer, description: 'present only when the result carried stats.' }
 
     WorkflowJournalEntryTruncated:
-      # 新(census 批2 四段):the truncated arm (workflows.ts:141-142/159-162) — an honest stub for a row whose
+      # 新(census 批2 四段):the truncated arm (workflows.ts) — an honest stub for a row whose
       # stored TaskResult exceeded the per-row 64KiB gate (SQL stores) or byte length (file/in-memory
       # fallback): the server never pulls the oversized payload into process memory.
       type: object
@@ -6016,17 +6041,17 @@ components:
       type: object
       description: >
         One frame of GET /v1/workflows/:id/stream (streamWorkflowRun). FIRST frame is `event:meta` with
-        `data: {type:"meta", version, runId}` (`src/http/routes/workflows.ts:487` — the `type` is double-emitted
+        `data: {type:"meta", version, runId}` (`src/http/routes/workflows.ts` — the `type` is double-emitted
         on purpose: a proxy that forwards only `data:` lines would otherwise leave a `data.type`-dispatching
         consumer unable to recognise the opener). Subsequent frames carry a core WorkflowEvent verbatim (its
         `type` is the SSE event name). NOT resumable (replica-local, in-process; no id/Last-Event-ID).
         `data` is permissive (core-internal, evolves).
         🔴 There IS exactly one TERMINAL frame and it means FAILURE: `event: error` with
         `data: {type:"error", errorCode:"workflow.stream_error", message:"workflow stream error"}`
-        (`routes/workflows.ts:517`). Branch on `errorCode` — NEVER anchor on `message`; the errorCode was added
+        (`routes/workflows.ts`). Branch on `errorCode` — NEVER anchor on `message`; the errorCode was added
         precisely because consumers were otherwise forced to anchor prose or to conflate "the stream broke" with
         "the stream ended normally", i.e. to report a FAILED workflow as finished. (Declared 2026-08-02.)
-        Keep-alive is a REAL NAMED FRAME `event: heartbeat` / `data: {}` @15 s (`:496`), not an SSE comment.
+        Keep-alive is a REAL NAMED FRAME `event: heartbeat` / `data: {}` @15 s (`routes/workflows.ts`), not an SSE comment.
         NOTE: on the wire this is SSE framing (event name + JSON data), not a JSON body — schema describes one
         decoded frame.
       required: [event, data]
@@ -6039,7 +6064,7 @@ components:
     FleetTaskStatus:
       type: string
       description: >
-        The fleet vocabulary the shell renders (service FleetTaskStatus, fleet-bus.ts:27-36). The service maps its
+        The fleet vocabulary the shell renders (service FleetTaskStatus, fleet-bus.ts). The service maps its
         run/workflow status onto this NEUTRAL set: `awaiting approval` = a needs-review/plan-approval park,
         `waiting` = a durable suspend. CLOSED on the wire; render OPEN (branch known, fall back generically).
       enum: [queued, running, waiting, stopping, 'awaiting approval', idle, completed, failed, killed]
@@ -6047,7 +6072,7 @@ components:
       type: object
       description: 'Upload receipt (POST /v1/attachments 201). `name` is the SANITIZED basename the server will materialize under `attachments/`.'
       # 🔴 census 批2 五段(2026-07-30):CLOSED against the real emitter — `sendJson(res, 201, { id, name,
-      # mime, sha256, sizeBytes })` (server attachments.ts:90) is an EXACT 5-key object literal, never a
+      # mime, sha256, sizeBytes })` (server attachments.ts) is an EXACT 5-key object literal, never a
       # superset.
       required: [id, name, mime, sha256, sizeBytes]
       additionalProperties: false
@@ -6060,7 +6085,7 @@ components:
     FleetTaskRow:
       type: object
       description: >
-        One active task row (service FleetTaskRow fleet-bus.ts:40-54) — MINUS the wire-STRIPPED `scope` (a
+        One active task row (service FleetTaskRow fleet-bus.ts) — MINUS the wire-STRIPPED `scope` (a
         tenant-isolation field the service removes AFTER the owner-gate; never rendered, never on this wire). A
         `task` frame carries the POST-MERGE FULL row → replace by `id`, NOT a sparse patch. A subagent child row
         sets `parentId` (E2 parentToolCallId) + an id of `"<runId> <taskId>"`.
@@ -6125,14 +6150,14 @@ components:
     FleetWorkflowRow:
       type: object
       description: >
-        One workflow row (service FleetWorkflowRow fleet-bus.ts:57-69) — MINUS the wire-stripped `scope`. `status`
+        One workflow row (service FleetWorkflowRow fleet-bus.ts) — MINUS the wire-stripped `scope`. `status`
         is the NEUTRAL workflow run status (running|completed|failed), open on read.
       required: [id, name, status]
       additionalProperties: true
       properties:
         # 🔴 FW-6(2026-08-02):这里此前有一个 `sourceLane` —— **幻影键,已删**。`sourceLane` 只在
-        # `FleetTaskRow`(`src/fleet/fleet-bus.ts:146`)上,`FleetWorkflowRow`(`:150-170`)全文没有它,
-        # `publishWorkflow`(`:338-342`)也从不写它;SDK 侧同样没有(SDK 是对的那一边)。
+        # `FleetTaskRow`(`src/fleet/fleet-bus.ts`)上,`FleetWorkflowRow` 全文没有它,
+        # 同文件的 `publishWorkflow` 也从不写它;SDK 侧同样没有(SDK 是对的那一边)。
         # 按它 codegen 的第三方会得到一个永远 undefined 的 `workflowRow.sourceLane`,并照 FleetTaskRow 那条
         # 「run-leg composite rows only」的描述写出一个**永不触发**的 workflow 行去重分支。
         id: { type: string }
@@ -6141,7 +6166,7 @@ components:
         status: { type: string, description: 'Neutral workflow run status (running|completed|failed; open).' }
         doneCount: { type: integer }
         # 🔴 FW-6(2026-08-02):补上一个 server 真发、SDK 真声明、只有 spec 漏了的键。
-        # `src/fleet/fleet-bus.ts:167` 声明,`src/orchestration/workflow-notify-journal.ts:511` 真发。
+        # `src/fleet/fleet-bus.ts` 声明,`src/orchestration/workflow-notify-journal.ts` 真发。
         startedCount: { type: integer, description: 'Agents actually STARTED (vs `totalCount` = planned, queued included). CC 2.1.220 的 `⚠ Large workflow` 规模告警用它当分母 —— 漏了它那条告警根本渲染不出来。' }
         totalCount: { type: integer }
         failedCount: { type: integer }
@@ -6179,7 +6204,7 @@ components:
           hook_notice: '#/components/schemas/FleetFrame_hook_notice'
     FleetFrame_meta:
       type: object
-      # 🔴 FW-10(2026-08-02):此前只声明三键,而铸造点 `src/http/routes/fleet.ts:79` **无条件**发五键 ——
+      # 🔴 FW-10(2026-08-02):此前只声明三键,而铸造点 `src/http/routes/fleet.ts` **无条件**发五键 ——
       # `sessionScoped` / `bgNotifyFailClosed` 不在任何条件分支里。这两个键正是「server 契约方复审 F1
       # (行为错·最高)」的当事键:它们曾被一次白名单重构静默剥掉,导致 cli 的让位臂全程死代码。
       # SDK 侧已上锁(`test/fleet.test.ts` 有专门的透传回归钉),spec 侧一直空白 —— 按 spec 生成的客户端
@@ -6334,8 +6359,8 @@ components:
             type:
               type: string
               description: >
-                契约调和车1 G(2026-08-02;server [2373]C-12, `src/trace/project.ts:763` + the meta frame at
-                `routes/trace-usage.ts:258`): the frame's own event name, DOUBLE-EMITTED inside `data`. Always
+                契约调和车1 G(2026-08-02;server [2373]C-12, `src/trace/project.ts` + the meta frame at
+                `routes/trace-usage.ts`): the frame's own event name, DOUBLE-EMITTED inside `data`. Always
                 present on server >= 5.0.0; OPTIONAL here because the SDK's supported floor is server 3.0.0
                 (where only the `error` frame carried it). Equal to the SSE `event:` line verbatim — its reason
                 to exist is the proxy/relay case that strips the `event:` line and forwards only the data JSON,
@@ -6344,7 +6369,7 @@ components:
     PendingList:
       type: object
       description: Envelope for pending HITL checkpoints (key `pending`, NOT a bare array — the pinned wire contract).
-      # 封闭(census 轴一,2026-07-30):三个铸造点(routes/approvals-assistant.ts:89/620/624)都只发
+      # 封闭(census 轴一,2026-07-30):三个铸造点(routes/approvals-assistant.ts)都只发
       # `{ pending }`。行本身(`PendingCheckpoint`)保持开集(TS 侧索引签名)。
       additionalProperties: false
       required: [pending]
@@ -6357,7 +6382,7 @@ components:
       type: object
       description: Envelope for a session's approval exemptions (; key `exemptions`, NOT a bare array).
       required: [exemptions]
-      # 封闭:铸造点 `routes/approvals-assistant.ts:138` 是单键字面量。
+      # 封闭:铸造点 `routes/approvals-assistant.ts` 是单键字面量。
       additionalProperties: false
       properties:
         exemptions:
@@ -6373,7 +6398,7 @@ components:
          · the RESUMED-TASK shape (`http/server.ts` driveResumeIntoRunLog return) — `{taskId?, sessionId, status,
            errorCode?, errorMessage?, retriable?}`, plus `rememberApplied` when the request carried
            `remember:"session"` AND the worker has an exemption store;
-         · the PARKED-BACKGROUND-AGENT shape (`parked-decide.ts:272`, server >=1.267) — `{taskId, status:"resuming",
+         · the PARKED-BACKGROUND-AGENT shape (`parked-decide.ts`, server >=1.267) — `{taskId, status:"resuming",
            decision}`, an ACCEPTED (not completed) receipt; the revive drives asynchronously.
         `status` is the only key BOTH shapes guarantee: `taskId` rides `getActiveTaskId` on the resumed leg (omitted
         when there is no active row) and `sessionId` is absent from the parked shape.
@@ -6415,7 +6440,7 @@ components:
         MEMORY only — deny/neverAuto always outrank it; it never loosens the session-policy layer.
       required: [toolName, grantedBy, createdAt]
       # 封闭:三个 store 实现(sql/pg/local)的 `list()` 都逐字铸这三键
-      # (`plugins/approval-exemption-store.ts:67`),行不是原样透传的 DB 行。
+      # (`plugins/approval-exemption-store.ts`),行不是原样透传的 DB 行。
       additionalProperties: false
       properties:
         toolName: { type: string, description: Canonical tool name the exemption covers. }
@@ -6430,7 +6455,7 @@ components:
         The `GET /v1/approvals` operator queue row (true shape). NEVER includes a capability token.
         ⚠️ `createdAt`/`deadline` are EPOCH MILLISECONDS (numbers), not ISO strings.
         🔴 真矛盾撞获+纠正(2026-07-25,core [1640] 审计撞获 + server 复核确认 src/http/routes/approvals-assistant.ts→
-        listPending() 真实实现 `src/plugins/tidb-checkpoint-store.ts:54-79`):这份 schema 此前声称
+        listPending() 真实实现 `src/plugins/tidb-checkpoint-store.ts`):这份 schema 此前声称
         "MIRRORS core CheckpointSummary,顶层 gateKind/severity,NEVER a riskDescriptor object"——
         与真实实现完全相反。真实的 `PendingCheckpoint`(service 自定义类型,不是 core 的
         `CheckpointSummary`)**没有 token 字段**(store 层注释:"deliberately NO token")、**没有
@@ -6559,7 +6584,7 @@ components:
       type: object
       description: 'ASSISTANT-WIRE-CONTRACT §2 — `GET /v1/assistant/inbox` envelope. Already severity-sorted by core.'
       required: [inbox]
-      # 封闭:铸造点 `routes/approvals-assistant.ts:210` 是单键字面量(行本身 InboxRow 已封闭)。
+      # 封闭:铸造点 `routes/approvals-assistant.ts` 是单键字面量(行本身 InboxRow 已封闭)。
       additionalProperties: false
       properties:
         inbox:
@@ -6663,7 +6688,7 @@ components:
         ASSISTANT-WIRE-CONTRACT §3 — `GET /v1/assistant/tasks` envelope. Triage-ordered by core (needs-attention
         first, then severity DESC, then spend DESC). Empty `{tasks:[]}` when no TiDB run store.
       required: [tasks]
-      # 封闭:两个铸造点(`routes/approvals-assistant.ts:224` 的无 run-store 空臂 + `:273`)都是单键字面量。
+      # 封闭:两个铸造点(`routes/approvals-assistant.ts` 的无 run-store 空臂 + 正常臂)都是单键字面量。
       additionalProperties: false
       properties:
         tasks:
@@ -6754,12 +6779,12 @@ components:
     SessionSummary:
       type: object
       description: >
-        E16 (shell-host sessionPicker; service SessionSummary tidb-run-store.ts:42) — a `GET /v1/sessions` list row
+        E16 (shell-host sessionPicker; service SessionSummary tidb-run-store.ts) — a `GET /v1/sessions` list row
         aggregating a session's run ledger (last activity + most-recent objective preview + status). owner-scoped.
         All timestamps ISO. `objectivePreview` is service-redacted + truncated (genuinely `null` when no run).
       required: [sessionId, owner, lastActivityAt, firstActivityAt, runCount, objectivePreview, lastStatus]
-      # 🔴 封闭(census 批2 第二段,2026-07-30)。铸造点=`security.ts:22 SessionListItem`,9 键逐字对上;
-      # 路由 `routes/sessions-list.ts:148` 把 store 行**原样**放进 `sessions[]`(零投影),所以「多键」
+      # 🔴 封闭(census 批2 第二段,2026-07-30)。铸造点=`security.ts SessionListItem`,9 键逐字对上;
+      # 路由 `routes/sessions-list.ts` 把 store 行**原样**放进 `sessions[]`(零投影),所以「多键」
       # 只能来自 store 实现自己加字段 —— 那正是要抓的漂。`lastRunId`/`title` 刻意**不进 required**:
       # 两者由 store 侧 SQL 投影(legacy `task_run` 聚合腿的 lister 不一定发),required 会把一条
       # 合法的退化面响应判红。
@@ -6833,7 +6858,7 @@ components:
       type: object
       description: Keyset page envelope for `GET /v1/sessions`. `nextCursor` absent = last page.
       required: [sessions]
-      # 封闭:铸造点 `routes/sessions-list.ts:148` 是逐字两键字面量(`nextCursor` 条件在场)。
+      # 封闭:铸造点 `routes/sessions-list.ts` 是逐字两键字面量(`nextCursor` 条件在场)。
       additionalProperties: false
       properties:
         sessions:
@@ -6844,7 +6869,7 @@ components:
     SessionPermissionRules:
       type: object
       description: >
-        E6 (shell-host permissionMode; core SessionPermissionRules session-policy-store.ts:23) — operator-tightened
+        E6 (shell-host permissionMode; core SessionPermissionRules session-policy-store.ts) — operator-tightened
         per-session tool-permission rules (core reads them at prepare-time, SUBTRACT-only). 5 optional `string[]`
         fields. tighten-only invariant is core-enforced (a loosen needs an operator).
       properties:
@@ -6868,7 +6893,7 @@ components:
       # SessionPermissionRules + 内联的 `rev`)声明的键不在它作用域内 ⇒ 只写 `false` 会把合法的
       # `toolAllow`/`rev` 判成违约。镜像的一致性由 spec.test.ts 的通用「封闭 allOf 臂必须镜像被引
       # schema 全部键」门看守(以后往 SessionPermissionRules 加键,忘了同步镜像就当场红)。
-      # 为什么值得封闭:PUT 腿 `routes/sessions.ts:551` 只挑这 5 个已知字段落店,GET 腿回的是 store
+      # 为什么值得封闭:PUT 腿 `routes/sessions.ts` 只挑这 5 个已知字段落店,GET 腿回的是 store
       # 原样 —— 「store 多回一个键」正是本门要抓的那类漂(消费方按 spec 生成的类型会漏掉它)。
       additionalProperties: false
       properties:
@@ -6882,10 +6907,10 @@ components:
     McpServerStatus:
       type: object
       description: >
-        E9 (shell-host mcpStatus; core McpServerStatus core/mcp.ts:76) — one MCP server's status at materialization
+        E9 (shell-host mcpStatus; core McpServerStatus core/mcp.ts) — one MCP server's status at materialization
         time. `status` is connected | failed (core never emits disabled). `error` (failed only) is service-redacted
         + length-bounded.
-      # 封闭三层(census 批2 第三段,2026-07-30):行铸造点 `routes/sessions.ts:157-165` 逐键条件展开这 5 键;
+      # 封闭三层(census 批2 第三段,2026-07-30):行铸造点 `routes/sessions.ts` 逐键条件展开这 5 键;
       # `serverInfo` 不是透传——core 自己投影成两键字面量(core dist mcp.js:986 `{name, version}`)。
       required: [name, status]
       additionalProperties: false
@@ -6907,8 +6932,7 @@ components:
       description: >
         `GET /v1/sessions/:id/mcp` envelope. `asOf` = THIS materialization moment (ISO). `degraded:true` (servers
         empty) ⇒ materialize timed out/failed (NOT "no MCP"). No MCP configured ⇒ `servers:[]` without `degraded`.
-      # 封闭(census 批2 第三段,2026-07-30):三个铸造臂(`routes/sessions.ts:134` 空面板 / `:152` 超时
-      # degraded / `:155-166` 正常)键集并集恰是这 3 键;degraded 只在超时臂铸。
+      # 封闭(census 批2 第三段,2026-07-30):三个铸造臂(`routes/sessions.ts` 的空面板 / 超时 degraded / 正常)键集并集恰是这 3 键;degraded 只在超时臂铸。
       required: [asOf, servers]
       additionalProperties: false
       properties:
@@ -6937,8 +6961,8 @@ components:
       description: >
         One E19 file snapshot keyed by a `SessionTreeEntry.id`. `manifest` = `[relPath, blobHash]` tuples; the blob
         BYTES are NOT inlined (they ride the content-addressed blob routes).
-      # 封闭(census 批2 第三段,2026-07-30):server 侧类型+铸造点(`session-sync.ts:206` PULL 出 /
-      # `routes/session-sync.ts:53` PUSH 校验形)都恰是这两键。
+      # 封闭(census 批2 第三段,2026-07-30):server 侧类型+铸造点(`session-sync.ts` PULL 出 /
+      # `routes/session-sync.ts` PUSH 校验形)都恰是这两键。
       additionalProperties: false
       required: [key, manifest]
       properties:
@@ -6955,7 +6979,7 @@ components:
     SyncAnchor:
       type: object
       description: One E18 resume-at anchor. `owner` is RE-KEYED to the importing principal on a PUSH (§9).
-      # 封闭(census 批2 第三段,2026-07-30):server 侧行类型 `session-sync.ts:52` 恰是这三键(owner 可 null 不可缺)。
+      # 封闭(census 批2 第三段,2026-07-30):server 侧行类型 `session-sync.ts` 恰是这三键(owner 可 null 不可缺)。
       additionalProperties: false
       required: [eventId, entryId, owner]
       properties:
@@ -6966,7 +6990,7 @@ components:
     SessionRulesRecord:
       type: object
       description: A (principal, rules) policy record — one row across ALL principals (E6 `listBySession`). Replayed verbatim on import (the cloud applies the tighten-only gate).
-      # 封闭(census 批2 第三段,2026-07-30):core `SessionRulesRecord`(session-policy-store.d.ts:19)恰是
+      # 封闭(census 批2 第三段,2026-07-30):core `SessionRulesRecord`(session-policy-store.d.ts)恰是
       # 这两键;`principal: undefined`(会话默认规则)在 JSON 里=整键省略。
       additionalProperties: false
       required: [rules]
@@ -6979,7 +7003,7 @@ components:
       description: >
         2c session-sync `GET …/sync/manifest` payload (wrapped server-side as `{ manifest }`). The THIN cross-backend
         snapshot: entry IDS (oldest-first, NOT payloads) + per-snapshot relPath→blobHash + policy + anchors + leaf.
-      # 封闭(census 批2 第三段,2026-07-30):铸造点 `session-sync.ts:226`(exportSessionManifest 尾部
+      # 封闭(census 批2 第三段,2026-07-30):铸造点 `session-sync.ts`(exportSessionManifest 尾部
       # 字面量)恰是这 7 键,全部无条件(leafId 缺席位=null 不省略)。
       additionalProperties: false
       required: [sessionId, entryIds, entryCount, leafId, snapshots, policy, anchors]
@@ -7011,7 +7035,7 @@ components:
         §7 — how a SOURCE log relates to a DESTINATION log, decided over the entry-ID SETS. A discriminated union on
         `relation`. `fresh`/`identical` carry nothing else; `fast_forward` the appended tail; `stale` the dst entries
         the src lacks; `fork` the common ancestor + each side's exclusive ids.
-      # 五臂全封闭(census 批2 第三段,2026-07-30):铸造点=分类器 `session-sync-kernel.ts:126-160`,
+      # 五臂全封闭(census 批2 第三段,2026-07-30):铸造点=分类器 `session-sync-kernel.ts`,
       # 五个 return 全是字面量,臂形与 core 导出的 `SyncRelation` 判别联合逐键一致。
       oneOf:
         - type: object
@@ -7056,8 +7080,8 @@ components:
       description: >
         `POST …/sync/import` Phase-A result. `identical` → no `stagingId` (skip Phase B); `fresh`/`fast_forward` →
         `{ stagingId, relation }`. `relation` is the BARE classifier tag (not the full object).
-      # 封闭(census 批2 第三段,2026-07-30):两个铸造臂——identical 臂 `routes/session-sync.ts:385-389`
-      # (relation+basis+payloadVerified,无 stagingId)/ staged 臂 `:472`(stagingId+relation)。
+      # 封闭(census 批2 第三段,2026-07-30):两个铸造臂——identical 臂 `routes/session-sync.ts`
+      # (relation+basis+payloadVerified,无 stagingId)/ 同文件的 staged 臂(stagingId+relation)。
       additionalProperties: false
       required: [relation]
       properties:
@@ -7068,7 +7092,7 @@ components:
           type: string
           # 🔴 census 批2 第三段(2026-07-30)spec 谎修正:`entry-ids+digest` 不是"将来值"——1.277.0 落
           # digest 半场的**同一车**里铸造点就是 `basis: payloadVerified ? "entry-ids+digest" : "entry-ids"`
-          # (routes/session-sync.ts:387),旧注却把它写成 x-open-enum 的假想例。补进闭集;x-open-enum 保留
+          # (routes/session-sync.ts),旧注却把它写成 x-open-enum 的假想例。补进闭集;x-open-enum 保留
           # (真正的将来值仍按未知值降级)。
           enum: [entry-ids, entry-ids+digest]
           x-open-enum: true
@@ -7090,7 +7114,7 @@ components:
     ImportCommitted:
       type: object
       description: '`POST …/sync/import/:stagingId/entries` (Phase B) commit result — the AUTHORITATIVE in-txn re-classify tag.'
-      # 封闭(census 批2 第三段,2026-07-30):铸造点 `routes/session-sync.ts:608`(`{ relation: committed.relation }`)单键字面量。
+      # 封闭(census 批2 第三段,2026-07-30):铸造点 `routes/session-sync.ts`(`{ relation: committed.relation }`)单键字面量。
       additionalProperties: false
       required: [relation]
       properties:
@@ -7129,10 +7153,13 @@ components:
             `quota_exhausted` (429 — the E4 fleet quota-LEASE budget, distinct from the cost quota).
             NOTE: budget (`budget.precall`/`budget.exceeded`) and `cancelled` are RESULT-level codes on
             TaskResult/RunRecord, NOT HTTP errors (pinned wire contract).
-            🔴 STABLE PREFIX FAMILIES (wire-contract Appendix A, criterion 3) — nine prefixes are a stable
+            🔴 STABLE PREFIX FAMILIES (wire-contract Appendix A, criterion 3) — ELEVEN prefixes are a stable
             COARSE branch surface, so falling back on the prefix (unknown code → look at its prefix → only then
-            at the status) is always safe: `auth.` `request.` `not_found.` `conflict.` `limit.` `capability.`
-            `feature.` `internal.` `state.`. The SDK maps each family to a typed class, so a code this SDK has
+            at the status) is always safe: `auth.` `request.` `not_found.` `conflict.` `gone.` `parking.`
+            `limit.` `capability.` `feature.` `internal.` `state.`. (`gone.` = 410, "the channel closed, switch
+            channels"; `parking.` = 425, "intermediate state — you retry to learn the landing, not to re-submit".
+            Both families, and both status codes, first reached the wire with server 7.3.0's in-stream approval
+            decision endpoint.) The SDK maps each family to a typed class, so a code this SDK has
             never seen still degrades INFORMATIVELY (e.g. a future `capability.xyz_required` already lands on
             CapabilityUnavailableError). Family examples not named elsewhere in this document:
             `request.payload_too_large` (413 — a field or the whole body is over the server cap; shorten and
@@ -7148,11 +7175,18 @@ components:
           description: On a 409 — the task currently holding the session lock (see the Conflict response note).
 
     # ── Streaming event taxonomy (the UX 命脉). Each SSE `data:` line is one JSON-serialized AgentEvent. ──
-    # TWO vocabularies (the pinned wire contract Drift 3):
+    # TWO vocabularies (the pinned wire contract Drift 3). ⚠️ The two lines below are the SHAPE-DEFINING
+    # contrast (per-token deltas vs turn-aggregated), NOT an enumeration of either leg's arm set — the union
+    # under `AgentEvent` below is the authoritative list, and each `Event_*` schema states its own legs.
     #   live  (POST /v1/tasks/stream):  text_delta / reasoning_delta (delta = string fragment, core-native)
-    #                                   + tool_start/tool_end/turn_end/compacted/done
+    #                                   + the lifecycle/tool/observation arms + the out-of-band NAMED frames
+    #                                     (question / elicitation / tool_approval / approval_request), which
+    #                                     interleave on the same connection but are NOT AgentEvent arms
     #   durable (GET /v1/runs/:id/events): text / reasoning (turn-AGGREGATED, no deltas)
-    #                                   + tool_start/tool_end/turn_end/compacted/suspended/done/failed
+    #                                   + the same lifecycle/tool arms + the durable-only appends
+    #                                     (prompt_assembled / config_assembled / model_usage / suggestions /
+    #                                      needs_review / task_notification / diagnostics / workflow_complete)
+    #                                   + suspended/failed
     AgentEvent:
       oneOf:
         - $ref: '#/components/schemas/Event_meta'
@@ -7198,6 +7232,16 @@ components:
         # [2854] core 5.14.0 TaskEvent 16->18 (server 7.3.0 pickup): both new arms, projected.
         - $ref: '#/components/schemas/Event_human_input'
         - $ref: '#/components/schemas/Event_wiring_manifest'
+        # 🔴 #185a (2026-08-08): the three APPROVAL arms of the DURABLE leg. They were replayed by
+        #   GET /v1/runs/:id/events all along (the server appends them and the read boundary re-emits
+        #   `{type, ...data}`) but neither this union nor the SDK's declared them, so a generated client
+        #   had no arm to switch on and dropped approval cards. Each arm is `allOf: [<the frame schema>, the
+        #   narrowed discriminant]` — the key set stays owned by ToolApprovalFrame / ApprovalRequestFrame,
+        #   so a frame gaining a key (7.5.0's governanceForced) needs no edit here.
+        #   `approval_revoke` is deliberately ABSENT: it is live-only and never appended.
+        - $ref: '#/components/schemas/Event_tool_approval'
+        - $ref: '#/components/schemas/Event_tool_approval_complete'
+        - $ref: '#/components/schemas/Event_approval_request'
       discriminator:
         propertyName: type
         mapping:
@@ -7236,15 +7280,18 @@ components:
           workflow_complete: '#/components/schemas/Event_workflow_complete'
           human_input: '#/components/schemas/Event_human_input'
           wiring_manifest: '#/components/schemas/Event_wiring_manifest'
+          tool_approval: '#/components/schemas/Event_tool_approval'
+          tool_approval_complete: '#/components/schemas/Event_tool_approval_complete'
+          approval_request: '#/components/schemas/Event_approval_request'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
-    # `text` re-stamps the turn's first text_delta eventId, runs.ts:250); parentToolCallId = sub-agent attribution.
+    # `text` re-stamps the turn's first text_delta eventId, runs.ts); parentToolCallId = sub-agent attribution.
     EventIdentity:
       type: object
       # 🔴 census 轴一(2026-07-30)亲读铸造点补的两键:LIVE 腿的白名单化 catch-all
-      # (server `routes/tasks.ts:640-648`,text_delta / turn_end / message_committed / context_usage 四臂)
-      # 传的是**四个** identity 键,而 durable 腿的 `identityFields`(trace/project.ts:101)只传前两个
+      # (server `routes/tasks.ts`,text_delta / turn_end / message_committed / context_usage 四臂)
+      # 传的是**四个** identity 键,而 durable 腿的 `identityFields`(trace/project.ts)只传前两个
       # ——「两腿两策」是那段代码自己写下的口径。此前 spec 只声明两键 ⇒ 在封闭这些臂时会把真键判成违约。
       # 声明面取两腿并集(逐臂再收窄不值当),缺席即缺席。
       properties:
@@ -7260,7 +7307,7 @@ components:
         condition: durable-ledger leg only (no ledger => neither header nor frame). sessionId rides along
         (needed to bind subsequent turns when the server minted a fresh session). Always precedes any content
         frame. NOT an engine event — server-minted, no EventIdentity.
-      # 封闭:铸造点 routes/tasks.ts:122 是逐字写死的三键字面量(sessionId 条件在场)。
+      # 封闭:铸造点 routes/tasks.ts 是逐字写死的三键字面量(sessionId 条件在场)。
       additionalProperties: false
       required: [type, taskId]
       properties:
@@ -7275,7 +7322,7 @@ components:
       # `additionalProperties` 只认**同一个 subschema** 的 `properties`,`allOf` 分支($ref EventIdentity)
       # 声明的键不在它的作用域内 —— 只写 `additionalProperties: false` 会把合法的 eventId 判成违约
       # (draft-07 的 ajv 也不支持能跨 allOf 结算的 `unevaluatedProperties`,写了会被静默忽略 = 假绿)。
-      # 镜像取两腿并集(超集,宁可漏抓不可假红);`$ref` 保留(spec.test.ts:92 的 §E2 门要它)。
+      # 镜像取两腿并集(超集,宁可漏抓不可假红);`$ref` 保留(spec.test.ts 的 §E2 门要它)。
       # 镜像与 EventIdentity 的一致性由 spec.test.ts 的「封闭臂必须镜像全部 identity 键」门看守。
       additionalProperties: false
       required: [type, text]
@@ -7334,7 +7381,7 @@ components:
         type: { const: tool_start }
         toolCallId: { type: string }
         toolName: { type: string }
-        # 🔴 census 轴一(2026-07-30)回填:server 白名单 builder `toolStartEventData`(trace/project.ts:112)
+        # 🔴 census 轴一(2026-07-30)回填:server 白名单 builder `toolStartEventData`(trace/project.ts)
         # 真发 `label`(core 展示名,与 tool_end 同待遇),spec 此前漏声明 —— 封闭前必须先补,否则真帧变假红。
         label: { type: string, description: 'core 展示名(缺席 ⇒ 用 toolName 渲染)。' }
         args: {}
@@ -7356,7 +7403,7 @@ components:
         type: { const: tool_end }
         toolCallId: { type: string }
         toolName: { type: string }
-        # 🔴 census 轴一(2026-07-30)回填:`toolEndEventData`(trace/project.ts:125)真发 `label` 与
+        # 🔴 census 轴一(2026-07-30)回填:`toolEndEventData`(trace/project.ts)真发 `label` 与
         # `structured`,spec 此前两者都漏 —— SDK 的 events.ts 早已声明,漂移只在 spec 这一侧。
         label: { type: string, description: 'core 展示名(同 tool_start.label)。' }
         structured: {}   # core 1.203 CC 卡片明细;与 output 同一 UNTRUSTED RAW 待遇(已 redactDeep),形状开放
@@ -7370,7 +7417,7 @@ components:
         bgAgentId: { type: string }
     Event_turn_end:
       type: object
-      # 🔴 census 轴一(2026-07-30):`turn_end` 走 LIVE 腿的白名单 catch-all(routes/tasks.ts:646),该分支
+      # 🔴 census 轴一(2026-07-30):`turn_end` 走 LIVE 腿的白名单 catch-all(routes/tasks.ts),该分支
       # 对四个 identity 键做条件 spread —— 即「core 若真在 turn_end 上盖了 identity,它会上 wire」。
       # 处置:**不** allOf EventIdentity(契约面继续不承诺生命周期臂带 identity,spec.test.ts §E2 那条钉
       # 保持有效),但把四键作为本地可选属性声明出来,好让下面的封闭对那条真实代码路径不产生假红。
@@ -7399,7 +7446,7 @@ components:
             cacheReadTokens: { type: integer }
             cacheWriteTokens: { type: integer }
             costMicroUsd: { type: integer }
-        # 🔴 census 轴一(2026-07-30)回填:`turnEndEventData`(trace/project.ts:449)是 2026-07-25 才补的
+        # 🔴 census 轴一(2026-07-30)回填:`turnEndEventData`(trace/project.ts)是 2026-07-25 才补的
         # builder,它带上来的这两键 spec 从未声明过 —— 而它们恰恰是**诚实缺席**语义的载体:
         # `usageMissing` 缺了,「没有 usage」会被读成「用量是 0」而不是「未知」。
         usageMissing: { const: true, description: '本轮用量不可信/缺失的诚实标记。缺席 ⇒ usage 可信。' }
@@ -7411,14 +7458,14 @@ components:
     Event_compacted:
       type: object
       # 🔴 **刻意不封闭**(SDK events.ts 的 compacted 臂带 `[k: string]: unknown`),但 census 轴一
-      # (2026-07-30)把 `compactedEventData`(trace/project.ts:340-407)真发的键**全部登记**了一遍 ——
+      # (2026-07-30)把 `compactedEventData`(trace/project.ts)真发的键**全部登记**了一遍 ——
       # 此前 spec 只有 tokensBefore 一键,连 fixture 天天在喂的 `trigger` 都不在声明面上。
       additionalProperties: true
       required: [type]
       properties:
         type: { const: compacted }
         tokensBefore: { type: integer }
-        trigger: { type: string, description: 'auto(逼近窗口上限)| manual(/compact)。缺席按 auto 渲染。' }
+        trigger: { type: string, description: '开集(engine-shaped,别当闭合枚举):`auto`(逼近窗口上限)/ `manual`(`POST /v1/runs/:id/compact`,发在该 run 自己的流上)/ `forced`(core ≥5.16.0 的 prompt-too-long 恢复腿)。缺席按 auto 渲染;未知值也按 auto 渲染,别崩。' }
         preserved_segment:
           type: object
           required: [firstKeptEntryId]
@@ -7453,7 +7500,7 @@ components:
     Event_suggestions:
       type: object
       description: >
-        E12 (shell-host; service runs.ts:392 + src/http/routes/runs.ts, opt-in via `TaskRequest.suggestNextPrompts`) —
+        E12 (shell-host; service runs.ts + src/http/routes/runs.ts, opt-in via `TaskRequest.suggestNextPrompts`) —
         post-completion "what to ask next" prompt suggestions. Appended to the DURABLE run-events tail AFTER a
         `done` with `status:"completed"` (core's fire-and-forget LLM pass). 🔴 UNTRUSTED model text, service-
         redacted, UI-ONLY — render as clickable next-prompt chips; NEVER re-feed to a model. Empty/absent ⇒ none.
@@ -7499,7 +7546,7 @@ components:
         CLIENT wire」已是 doc-rot,SDK events.ts 早已改口):server **确实**在三条腿上转发本臂
         (`taskProgressEventData`,bg runs.ts append / resume append / 同步 live SSE),此外才是 fleet 子行。
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
-      # 🔴 census 轴一(2026-07-30)三处纠正,依据=亲读 `taskProgressEventData`(trace/project.ts:146-166):
+      # 🔴 census 轴一(2026-07-30)三处纠正,依据=亲读 `taskProgressEventData`(trace/project.ts):
       #  ① required 过严 —— builder 里 `usage`/`status` 都是**条件 spread**,只有 `taskId` 无条件在场;
       #     spec 却把它们列进 required ⇒ 一个没带 usage 的真 tick 会被判违约(方向反了的假红)。
       #  ② `status` 写成 `const: running` 太窄 —— core [1414]#3 的 settle 终态 tick("completed"/"failed")
@@ -7741,8 +7788,8 @@ components:
     Event_suspended:
       type: object
       description: HITL — the run paused on an F4 gate or AskUserQuestion. Resolve via approvals.decide, then resume.
-      # 封闭(census 轴一,2026-07-30)。两个铸造点都是写死的字面量:server.ts:2147 `{gate}`、
-      # server.ts:2161 `{gate:null, reopened}` —— 后者的 `reopened` 此前 spec 完全没有,是本次亲读补上的。
+      # 封闭(census 轴一,2026-07-30)。两个铸造点都是写死的字面量:server.ts `{gate}`、
+      # server.ts `{gate:null, reopened}` —— 后者的 `reopened` 此前 spec 完全没有,是本次亲读补上的。
       additionalProperties: false
       required: [type]
       properties:
@@ -7755,7 +7802,7 @@ components:
         reopened:
           type: ['string', 'null']
           description: >
-            server.ts:2161 —— 一条 resume 腿把 run 重新挂回 suspended 时,带上「为什么重开」的 errorCode
+            server.ts —— 一条 resume 腿把 run 重新挂回 suspended 时,带上「为什么重开」的 errorCode
             (无则显式 null)。只出现在这条重开臂上;普通挂起帧不带此键。
     ModelUsageDelta:
       # 新增(2026-07-25 回填批)。SDK 的 facade 审计把这个形状命名了一次(此前是在两个使用点各写一遍的匿名内联形:
@@ -7897,7 +7944,7 @@ components:
       description: >
         Per-model usage delta (live-verified on canary). `usage` is keyed BY MODEL NAME — same source as
         `done.result.stats.modelUsage` (lets a multi-model / role-routed run attribute spend per model).
-      # 封闭:铸造点 trace/project.ts:27 `append("model_usage", { usage: delta })` 只有这一键
+      # 封闭:铸造点 trace/project.ts `append("model_usage", { usage: delta })` 只有这一键
       #(map 的**值**仍是开集 ModelUsageDelta —— 那层的「开」是真的,不动)。
       additionalProperties: false
       required: [type, usage]
@@ -7997,9 +8044,16 @@ components:
     ToolApprovalFrame:
       type: object
       description: >
-        LIVE tool-approval frame (SSE, `type` IS the event name). NOT an AgentEvent arm — it interleaves on the
-        run's stream when TOOL_APPROVAL_ENABLED. The shell renders `tool_approval` as the three-choice card and
-        dismisses it on `tool_approval_complete`. Respond via POST /v1/tool-approvals/{approvalId}/respond.
+        Tool-approval frame (SSE, `type` IS the event name). On the LIVE stream it interleaves out-of-band when
+        TOOL_APPROVAL_ENABLED and is NOT an AgentEvent arm there (the live leg dispatches by SSE `event:` name).
+        On the BACKGROUND/durable leg the server appends it to the events tail so it also replays through
+        GET /v1/runs/:id/events — and there it IS a declared arm as of #185a, via `Event_tool_approval` /
+        `Event_tool_approval_complete` (each = THIS schema plus the narrowed discriminant, so the keys live
+        here only). Before #185a the durable response was typed solely as `AgentEvent` with no such arm: the
+        payload carried `type` (the read boundary emits `{type, ...data}`) so runtime discrimination worked,
+        but a generated client had nothing to switch on and dropped approval cards. That gap is closed.
+        The shell renders `tool_approval` as the three-choice card and dismisses it on `tool_approval_complete`.
+        Respond via POST /v1/tool-approvals/{approvalId}/respond.
       required: [type, approvalId]
       additionalProperties: true
       properties:
@@ -8021,6 +8075,25 @@ components:
         args:
           description: '"tool_approval" only: the call''s args, secret-redacted. UNTRUSTED for display. Absent (with argsOmitted) when over the byte cap or unserializable.'
         argsOmitted: { type: boolean, enum: [true] }
+        governanceForced:
+          type: boolean
+          enum: [true]
+          description: >
+            "tool_approval" only, ADDITIVE, two-stage presence: ABSENT on server <= 7.4.0; from server >= 7.5.0
+            ([2942]/[2943]) present with value `true` when this ask's gate comes from the OPERATOR GOVERNANCE
+            layer (the deployment-side AUTONOMY / commandPolicy / MANUAL_MODE_SHELL_GATE / SENSITIVE_WRITE_PATTERNS
+            knobs) rather than from a model default gate or the request's own client permission posture.
+            The only authority on presence is an observed frame, never a version string.
+
+            Use it to render a "forced by governance" badge: such a gate CANNOT be removed by a client posture,
+            so the shell must present it as non-bypassable instead of pointing the user at `permissionMode`.
+
+            🔴 ABSENT != false (same discipline as the risk axes): the key is present ONLY when true. Absence
+            means "no evidence of a governance origin" — it covers both genuinely non-governance asks (e.g. a tool
+            listed in the deployment's APPROVAL_REQUIRE) AND shapes the server cannot discriminate (e.g. when the
+            governance shell gate sits at the "classify" tier, a shell ask may come from the classifier or from
+            another gate; the server leaves the key absent rather than guessing). Never render absence as
+            "this gate can be bypassed by a posture".
         fromSubagent:
           type: boolean
           enum: [true]
@@ -8029,20 +8102,36 @@ components:
           type: string
           description: 'Child''s core session id (same id domain as task_progress.taskId) — row-join value + fallback discriminator against a server predating fromSubagent.'
         sourceAgentName: { type: string, description: 'Display name of the child agent, redacted. UNTRUSTED.' }
+        delegation:
+          type: object
+          description: >
+            core >= 5.9.0 W1 ([2535]), "tool_approval" only, ADDITIVE: the ask's DELEGATION provenance chain
+            (the innermost grandchild frame wins). Present on the same door as `fromSubagent`. Read-only display
+            enrichment; `agentName` is UNTRUSTED for display like `sourceAgentName`.
+          additionalProperties: true
+          required: [parentToolCallId, depth]
+          properties:
+            parentToolCallId: { type: string }
+            depth: { type: integer }
+            agentName: { type: string }
         outcome:
           type: string
           enum: [allowed, denied, expired]
-          description: '"tool_approval_complete" only. `expired` = TTL/abort/disconnect — a fail-closed DENY the shell should render as such, not as "still pending".'
+          description: '"tool_approval_complete" only. Cosmetic dismiss reason. `expired` = TTL/abort/disconnect; what the ENGINE received for it DEPENDS on the deployment: where the design/172 ask ledger is on (server >= 7.3.0 under STREAM_APPROVAL_ENABLED) the server''s expireAsk CAS re-adjudicates the outcome to "unavailable" and the run PARKS; without that ledger the historical fail-closed DENY stands. Never derive the run''s fate from this frame.'
 
-    # ── design/172 流内审批协议(#151;UNRELEASED,候 server 7.3.0 + STREAM_APPROVAL_ENABLED,默认 OFF)──
+    # ── design/172 流内审批协议(#151)—— 已随 server 7.3.0 上线;开关 STREAM_APPROVAL_ENABLED 的默认值
+    #    分两段:server ≤7.4.0 默认 OFF,≥7.5.0 默认 ON(BREAKING,见 server CHANGELOG)。──
     # 与上面的 ToolApprovalFrame 是**并行加帧,不替换**:开关打开时同一只 ask 出两帧(先 tool_approval,
     # 后 approval_request),两帧同带 `approvalId` ⇒ 消费端按它去重、优先渲染新帧。
     ApprovalRequestFrame:
       type: object
       description: >
-        IN-STREAM approval card (SSE, `type` IS the event name; design/172 §3.1). NOT an AgentEvent arm — it
-        interleaves on the live token stream like tool_approval/question/elicitation. Settle it via
-        POST /v1/tasks/{taskId}/asks/{askId}/decision.
+        IN-STREAM approval card (SSE, `type` IS the event name; design/172 §3.1). TWO LEGS: on the LIVE token
+        stream it is an out-of-band named frame (NOT an AgentEvent arm) interleaved like
+        tool_approval/question/elicitation; on the DURABLE leg the server appends it, so the same frame replays
+        through GET /v1/runs/:id/events — and there it IS registered, as the `Event_approval_request` arm
+        (#185a; that arm allOf-refs THIS schema, so the keys are never restated).
+        Settle it via POST /v1/tasks/{taskId}/asks/{askId}/decision.
 
         WINDOW: `expiresAtMs` is cast ONCE and never recomputed; `expiresInMs` = max(0, expiresAtMs - serverNowMs)
         and is therefore MONOTONICALLY DECREASING across replays — a reconnect NEVER renews the window.
@@ -8115,6 +8204,15 @@ components:
         argsOmitted: { type: boolean, enum: [true], description: 'Present (true) only when args exceeded the byte cap. Never false.' }
         toolCallId: { type: string, description: 'The engine''s tool-call id (the `call_…` on the assistant message''s tool_use block) — same domain as ToolApprovalFrame.toolCallId.' }
         risk: { $ref: '#/components/schemas/ApprovalRiskAxes' }
+        governanceForced:
+          type: boolean
+          enum: [true]
+          description: >
+            ADDITIVE, two-stage presence (ABSENT on server <= 7.4.0; present with `true` from server >= 7.5.0):
+            this ask's gate comes from the OPERATOR GOVERNANCE layer and cannot be removed by a client permission
+            posture. Semantics, the ABSENT != false clause and the discrimination boundary are stated verbatim on
+            ToolApprovalFrame.governanceForced. It sits at the card's top level rather than inside `risk` because
+            `risk` describes the ENGINE's judgement of the call, while this key says WHO imposed the gate.
         fromSubagent: { type: boolean, enum: [true], description: 'Present ⇔ the ask comes from a DELEGATED child — the explicit discriminator (a worker cannot forge it).' }
         sourceTaskId: { type: string, description: 'The child''s core session id — row-join value + fallback discriminator.' }
         sourceAgentName: { type: string, description: 'The child agent''s display name, redacted. UNTRUSTED.' }
@@ -8344,8 +8442,14 @@ components:
     QuestionFrame:
       type: object
       description: >
-        LIVE AskUserQuestion frame (SSE, `type` IS the event name). NOT an AgentEvent arm. Respond via
-        POST /v1/questions/{questionId}/respond; unanswered asks fall back to the headless default.
+        AskUserQuestion frame (SSE, `type` IS the event name). TWO LEGS: on the LIVE stream it is an out-of-band
+        named frame (NOT an AgentEvent arm); on the DURABLE leg the server persists it, so the same frame replays
+        through GET /v1/runs/:id/events — and there it IS registered, as the closed `Event_question` /
+        `Event_question_complete` arms (keep the key sets mirrored; a gate enforces it).
+        Respond via POST /v1/questions/{questionId}/respond. 🔴 An UNANSWERED ask does NOT "fall back to the headless
+        default" (server 7.4.0 / #166): the deployment reports `unavailable` ("nobody was reachable") and CORE
+        picks the landing — a DURABLE leg PARKS a checkpoint for an operator to answer later, a non-durable leg
+        continues on the `declined_unavailable` synthetic-continuation card. The run never hangs either way.
       required: [type, questionId]
       additionalProperties: true
       properties:
@@ -8354,11 +8458,14 @@ components:
         questions:
           type: array
           items: { $ref: '#/components/schemas/AskQuestion' }
-          description: '"question" only: the model''s structured questions, secret-redacted. UNTRUSTED — never re-feed to a model. Absent on an over-cap payload (the ask then headless-defaults and the shell never renders it).'
+          description: '"question" only: the model''s structured questions, secret-redacted. UNTRUSTED — never re-feed to a model. Absent on an over-cap payload — and then NO frame is emitted at all: the ask reports `unavailable` (see this schema''s description).'
         outcome:
           type: string
           enum: [answered, unanswered]
-          description: '"question_complete" only: `answered` = a human responded; `unanswered` = ttl/abort/throttle released it (the model got the headless default). Cosmetic dismiss reason.'
+          description: '"question_complete" only: `answered` = a human responded; `unanswered` = ttl/abort/throttle released it and core was told NOBODY WAS REACHABLE (`unavailable`) — on a durable deployment that PARKS rather than handing the model a default. Cosmetic dismiss reason only; never derive the run''s fate from it.'
+        serverNowMs:
+          type: integer
+          description: 'server >= 7.3.0, ADDITIVE: the server-signed emit timestamp. A server-minted side-frame has no core-stream eventId to carry, so this is its own time coordinate. Absent on older servers.'
 
     AskQuestion:
       type: object
@@ -8385,8 +8492,11 @@ components:
     ElicitationFrame:
       type: object
       description: >
-        LIVE MCP elicitation frame (SSE, `type` IS the event name). NOT an AgentEvent arm. Respond via
-        POST /v1/elicitations/{elicitationId}/respond.
+        MCP elicitation frame (SSE, `type` IS the event name). TWO LEGS: on the LIVE stream it is an
+        out-of-band named frame (NOT an AgentEvent arm); on the DURABLE leg the server persists it, so the same
+        frame replays through GET /v1/runs/:id/events — and there it IS registered, as the closed
+        `Event_elicitation` / `Event_elicitation_complete` arms (keep the key sets mirrored; a gate enforces it).
+        Respond via POST /v1/elicitations/{elicitationId}/respond.
       required: [type, elicitationId, mcpServerName]
       additionalProperties: true
       properties:
@@ -8403,6 +8513,9 @@ components:
           type: string
           enum: [accept, decline, cancel]
           description: '"elicitation_complete" only: how it resolved (dialog dismiss reason).'
+        serverNowMs:
+          type: integer
+          description: 'server >= 7.3.0, ADDITIVE: the server-signed emit timestamp. A server-minted side-frame carries no core-stream `eventId`, so this is its own time coordinate. Absent on older servers.'
 
     Event_steering_injected:
       type: object
@@ -8427,7 +8540,7 @@ components:
         2026-08-02) — do NOT assume the full TaskResult:
          · `TaskResult` — the normal terminal (output string at `.result`, stats at `.stats`), service Drift 4;
          · `ActiveRunConflictDoneResult` — the SSE lane's REJECTION terminal: when the session already has an
-           active run, the submit's 409 is encoded as this done frame (`src/http/routes/tasks.ts:234`), and it
+           active run, the submit's 409 is encoded as this done frame (`src/http/routes/tasks.ts`), and it
            carries NO `taskId` / `sessionId` / `stats`.
         Narrow on the presence of `stats` (required on TaskResult, absent from the conflict shape), or on
         `errorCode === "conflict.session_active_run"`. `status` does NOT discriminate — both shapes carry it.
@@ -8442,17 +8555,17 @@ components:
         replay:
           type: boolean
           description: >
-            契约调和车1 F(2026-08-02;server `src/http/routes/tasks.ts:71` 与 `:919` 两处铸造点)— `true`
+            契约调和车1 F(2026-08-02;server `src/http/routes/tasks.ts` 的两处铸造点)— `true`
             marks the IDEMPOTENT-REPLAY leg: this terminal was NOT produced by a live run of your submit. Either
-            the `Idempotency-Key` hit the in-flight/settled cache (:71), or your call was deduplicated into a
-            concurrent identical submit and received no live events at all (:919). The `result` is the original
+            the `Idempotency-Key` hit the in-flight/settled cache, or your call was deduplicated into a
+            concurrent identical submit and received no live events at all. The `result` is the original
             run's terminal, verbatim. ABSENT on every live leg (never `false`) — a UI can use it to say "replayed"
             instead of implying the work just ran twice.
 
     ActiveRunConflictDoneResult:
       type: object
       description: >
-        The SSE lane's REJECTION `done.result` (server `src/http/active-run-conflict.ts:64` `toDoneFrameResult`,
+        The SSE lane's REJECTION `done.result` (server `src/http/active-run-conflict.ts` `toDoneFrameResult`,
         server >= 3.21). Same material as the 409 `conflict.session_active_run` body, minus the token-free
         addressing rule's exceptions: a checkpoint token NEVER appears on the wire. It is NOT a TaskResult —
         there is no run to report on, so `taskId`/`sessionId`/`stats` are structurally absent.
@@ -8499,11 +8612,11 @@ components:
 
     # ══════════════════════════════════════════════════════════════════════════════════════════════
     # 🔴 census 轴一(2026-07-30)补的**四个未登记臂**。它们不是「将来会有」——**今天就在 wire 上**:
-    #   · `context_usage`     LIVE(routes/tasks.ts:653)+ DURABLE(trace/ledger-sink.ts:144 / server.ts:2115)
-    #   · `config_assembled`  DURABLE(trace/project.ts:43)
-    #   · `needs_review`      DURABLE(http/server.ts:2148)
-    #   · `message_committed` LIVE(routes/tasks.ts:650)
-    # durable 腿的读边界(routes/runs.ts:99 `formatEvent`)对**每一条**落库事件原样下发 `{type, ...data}`
+    #   · `context_usage`     LIVE(routes/tasks.ts)+ DURABLE(trace/ledger-sink.ts / server.ts)
+    #   · `config_assembled`  DURABLE(trace/project.ts)
+    #   · `needs_review`      DURABLE(http/server.ts)
+    #   · `message_committed` LIVE(routes/tasks.ts)
+    # durable 腿的读边界(routes/runs.ts `formatEvent`)对**每一条**落库事件原样下发 `{type, ...data}`
     # (唯一归一是 brain_status→status),所以「本仓 append 了什么」= 「wire 上会出现什么」。而本文件的
     # `AgentEvent` 是闭集 oneOf ⇒ 一个真实的 context_usage 帧对着 spec 校验**当场零臂命中**。
     # ⚠️ 元教训:`spec-union-arm-gate` 比的是 spec ↔ SDK 两侧的臂集,这四个臂**两侧同缺**,所以那道门
@@ -8512,7 +8625,7 @@ components:
     Event_context_usage:
       type: object
       description: >
-        core 1.414 first-class arm, whitelisted by `contextUsageEventData` (server trace/project.ts:431).
+        core 1.414 first-class arm, whitelisted by `contextUsageEventData` (server trace/project.ts).
         🔴 Two engine-stated conventions, pass them through, never re-derive: (a) `usedTokens > compactAtTokens`
         IS the predicate the engine itself feeds `shouldCompact`; (b) `windowTokens` is the AUTOCOMPACT window,
         NOT the model's context size (rendering it as "model context" gives the user a wrong denominator).
@@ -8526,7 +8639,7 @@ components:
         usedTokens: { type: integer }
         windowTokens: { type: integer, description: 'autocompact 窗,不是模型上下文大小。' }
         compactAtTokens: { type: integer }
-        # LIVE 腿(routes/tasks.ts:653)在这条臂上挂 identity;durable 腿不挂。同 turn_end 的处置:
+        # LIVE 腿(routes/tasks.ts)在这条臂上挂 identity;durable 腿不挂。同 turn_end 的处置:
         # 本地可选声明,不 allOf(不把 identity 承诺进契约面)。
         eventId: { type: string }
         parentToolCallId: { type: string }
@@ -8536,7 +8649,7 @@ components:
       type: object
       description: >
         Compaction result frame ([2373]A-2, server 5.0.0 three-leg parity batch: live SSE + durable bg append +
-        durable resume append all share one builder, `compactionOutcomeEventData`, server trace/project.ts:375 —
+        durable resume append all share one builder, `compactionOutcomeEventData`, server trace/project.ts —
         replays no longer drop it). `outcome`/`trigger` are engine-shaped passthrough strings coerced via
         String(); `reason` is optional, secret-redacted. Identity: TWO keys only (`eventId`,
         `parentToolCallId`) — this arm is NOT on the live-leg four-key whitelist that `context_usage` sits on
@@ -8555,7 +8668,7 @@ components:
     Event_config_assembled:
       type: object
       description: >
-        DURABLE only ([1301]③, server trace/project.ts:43) — the per-turn companion record of `prompt_assembled`:
+        DURABLE only ([1301]③, server trace/project.ts) — the per-turn companion record of `prompt_assembled`:
         which config catalog version produced this turn's effective fields, and why anything was overridden.
         Bounded frame: the builder DROPS the whole record over 32 KiB rather than shipping a truncated half-shape.
         `fields` / `overrideReasons` are engine/registry-shaped passthrough — treat as opaque display data.
@@ -8570,7 +8683,7 @@ components:
     Event_needs_review:
       type: object
       description: >
-        DURABLE only (design/80 D-B, server http/server.ts:2148) — a RESUMED plan_review leg got re-gated into
+        DURABLE only (design/80 D-B, server http/server.ts) — a RESUMED plan_review leg got re-gated into
         another review pause. Same payload shape as `suspended`: the gate verbatim, or an explicit `null`.
         NOTE `needs_review` is BOTH a `RunStatus` terminal and a `CheckpointGate.kind`; this arm is the third
         use of the name — the stream frame announcing that pause.
@@ -8586,7 +8699,7 @@ components:
     Event_message_committed:
       type: object
       description: >
-        LIVE only (server routes/tasks.ts:650, whitelisted in the same catch-all as text_delta/turn_end/
+        LIVE only (server routes/tasks.ts, whitelisted in the same catch-all as text_delta/turn_end/
         context_usage) — a session-history entry was committed. `entryId` is the durable entry handle the
         R8 rewind anchor is keyed on ("rewind to the prompt" targets a `role:"user"` entry).
       additionalProperties: false
@@ -8609,8 +8722,8 @@ components:
     Event_error:
       type: object
       description: >
-        STREAM-CONTROL frame, NOT a run failure (server src/http/sse-log.ts:86; the trace leg emits the same
-        shape at routes/trace-usage.ts:294). The server writes it as a NAMED frame (`event: error`) whose payload
+        STREAM-CONTROL frame, NOT a run failure (server src/http/sse-log.ts; the trace leg emits the same
+        shape at routes/trace-usage.ts). The server writes it as a NAMED frame (`event: error`) whose payload
         echoes `type`, so both an `event:`-dispatching client and a payload-dispatching one see it.
         🔴 Its arrival means the RUN IS STILL ALIVE — the 15-minute stream cap fired. The correct handling is to
         RECONNECT with `Last-Event-ID` and keep reading (the durable leg stamps `id:` on every frame); rendering
@@ -8626,12 +8739,15 @@ components:
     Event_question:
       type: object
       description: >
-        AskUserQuestion OPEN frame (server src/question.ts:38 `QuestionFrame`). The live leg dispatches it by SSE
-        event name (routes/tasks.ts:677, the same out-of-band channel as `elicitation`/`tool_approval`); the
-        DURABLE leg persists it via `append(type, rest)` (src/runs.ts:498), so the same frame also replays on
+        AskUserQuestion OPEN frame (server src/question.ts `QuestionFrame`). The live leg dispatches it by SSE
+        event name (routes/tasks.ts, the same out-of-band channel as `elicitation`/`tool_approval`); the
+        DURABLE leg persists it via `append(type, rest)` (src/runs.ts), so the same frame also replays on
         GET /v1/runs/:id/events — that half is what this schema registers.
         🔴 UNTRUSTED-for-display: `questions` is secret-redacted, render only, NEVER re-feed to a model.
-        `questions` absent ⇒ the payload exceeded the 16 KiB cap and was dropped (the ask headless-defaults).
+        `questions` absent ⇒ the payload exceeded the 16 KiB cap and was dropped — and then NO frame is emitted
+        at all: the ask reports `unavailable` (server 7.4.0 / #166), which on a DURABLE deployment PARKS a
+        checkpoint for an operator and on a non-durable one continues via the `declined_unavailable`
+        synthetic-continuation card. It does NOT "headless-default".
       additionalProperties: false
       required: [type, questionId]
       properties:
@@ -8640,22 +8756,38 @@ components:
         questions:
           type: array
           items: { $ref: '#/components/schemas/AskQuestion' }
+        serverNowMs:
+          type: integer
+          description: >
+            server >= 7.3.0, ADDITIVE: the server-signed emit timestamp. A server-minted side-frame carries no
+            core-stream `eventId`, so this is its own time coordinate. 🔴 It MUST be declared here: this schema
+            is `additionalProperties: false`, so omitting a key the server really sends makes a strict validator
+            reject a legitimate frame. Absent on servers < 7.3.0.
     Event_question_complete:
       type: object
       description: >
         AskUserQuestion CLOSE frame (dialog-dismiss signal). `answered` = a human responded; `unanswered` =
-        ttl / abort / throttle released it and the model got the headless default. Cosmetic — it does not change
-        the run's status.
+        ttl / abort / throttle released it and core was told NOBODY WAS REACHABLE (`unavailable`) — on a durable
+        deployment that PARKS rather than handing the model a default (server 7.4.0 / #166; the old "the model
+        got the headless default" reading is wrong). Cosmetic dismiss reason — it does not itself change the
+        run's status, and the run's fate must never be derived from it.
       additionalProperties: false
       required: [type, questionId]
       properties:
         type: { const: question_complete }
         questionId: { type: string }
         outcome: { type: string, enum: [answered, unanswered] }
+        serverNowMs:
+          type: integer
+          description: >
+            server >= 7.3.0, ADDITIVE: the server-signed emit timestamp. A server-minted side-frame carries no
+            core-stream `eventId`, so this is its own time coordinate. 🔴 It MUST be declared here: this schema
+            is `additionalProperties: false`, so omitting a key the server really sends makes a strict validator
+            reject a legitimate frame. Absent on servers < 7.3.0.
     Event_elicitation:
       type: object
       description: >
-        Inbound-MCP elicitation OPEN frame (server src/elicitation.ts:42 `ElicitationFrame`). Same two legs as
+        Inbound-MCP elicitation OPEN frame (server src/elicitation.ts `ElicitationFrame`). Same two legs as
         `question`: live dispatches by event name, the durable leg persists + replays it.
         🔴 UNTRUSTED: `message` is fenced + secret-redacted; `requestedSchema` is an OPAQUE passthrough (never
         interpreted/validated) and must still be fenced on display. v1 is always `mode: "form"` (url-mode is
@@ -8669,6 +8801,13 @@ components:
         message: { type: string }
         requestedSchema: {}
         mode: { type: string, enum: [form] }
+        serverNowMs:
+          type: integer
+          description: >
+            server >= 7.3.0, ADDITIVE: the server-signed emit timestamp. A server-minted side-frame carries no
+            core-stream `eventId`, so this is its own time coordinate. 🔴 It MUST be declared here: this schema
+            is `additionalProperties: false`, so omitting a key the server really sends makes a strict validator
+            reject a legitimate frame. Absent on servers < 7.3.0.
     Event_elicitation_complete:
       type: object
       description: 'Inbound-MCP elicitation CLOSE frame; `action` is how it settled (the dialog-dismiss reason).'
@@ -8679,11 +8818,18 @@ components:
         elicitationId: { type: string }
         mcpServerName: { type: string }
         action: { type: string, enum: [accept, decline, cancel] }
+        serverNowMs:
+          type: integer
+          description: >
+            server >= 7.3.0, ADDITIVE: the server-signed emit timestamp. A server-minted side-frame carries no
+            core-stream `eventId`, so this is its own time coordinate. 🔴 It MUST be declared here: this schema
+            is `additionalProperties: false`, so omitting a key the server really sends makes a strict validator
+            reject a legitimate frame. Absent on servers < 7.3.0.
     Event_workflow_complete:
       type: object
       description: >
         Out-of-band delivery of an async workflow's completion (server
-        src/orchestration/workflow-completion-inbox.ts:522). Delivery is STREAM-OPEN driven: the session's inbox
+        src/orchestration/workflow-completion-inbox.ts). Delivery is STREAM-OPEN driven: the session's inbox
         is drained on its NEXT leg — the sync leg writes a live frame, the bg/resume legs `append` it as a durable
         event the tailing client replays.
         🔴 AT-LEAST-ONCE (two-phase: the entry is acked only after a successful emit, and two legs racing the same
@@ -8697,6 +8843,67 @@ components:
         status: { type: string }
         summary: { type: string }
 
+    # ── 🔴 #185a (2026-08-08): the DURABLE leg's three APPROVAL arms ────────────────────────────────
+    #   Shape rule for all three: `allOf: [<frame schema>, {the narrowed discriminant}]`. The keys are NOT
+    #   restated here — ToolApprovalFrame / ApprovalRequestFrame stay their single owner, so an additive
+    #   frame key (7.5.0's `governanceForced`) lands on the arm for free. The arms stay OPEN
+    #   (the frame schemas are `additionalProperties: true`), which is also why they need no local mirror
+    #   of the allOf branch keys (that duty only binds closed schemas).
+    #   Presence is CONDITIONAL and differs per family — an arm being declared says the payload's SHAPE,
+    #   never that the frame will arrive: `tool_approval*` needs TOOL_APPROVAL_ENABLED, `approval_request`
+    #   needs the design/172 protocol (server >= 7.3.0; default OFF <= 7.4.0 / ON >= 7.5.0, and the only
+    #   authority is the measured `capabilities.streamApproval` bit, never a version string).
+    Event_tool_approval:
+      description: >
+        DURABLE-leg replay of the legacy tool-approval OPEN frame. Same payload as ToolApprovalFrame with the
+        discriminant narrowed to `tool_approval`. Settle it via POST /v1/tool-approvals/{approvalId}/respond.
+        Anchor the card on `toolCallId` (NOT `approvalId`); render `governanceForced` as a non-bypassable
+        "forced by governance" badge. UNTRUSTED for display: `message`/`args` are redacted but model-authored.
+      allOf:
+        - $ref: '#/components/schemas/ToolApprovalFrame'
+        - type: object
+          required: [type]
+          properties:
+            type: { type: string, enum: [tool_approval] }
+    Event_tool_approval_complete:
+      description: >
+        DURABLE-leg replay of the legacy tool-approval CLOSE frame (ToolApprovalFrame with the discriminant
+        narrowed to `tool_approval_complete`). `outcome` is a COSMETIC dismiss reason: for `expired`, a
+        deployment carrying the design/172 ask ledger re-adjudicates to "unavailable" and the run PARKS, while
+        one without it keeps the historical fail-closed DENY. NEVER derive the run's fate from this frame.
+      allOf:
+        - $ref: '#/components/schemas/ToolApprovalFrame'
+        - type: object
+          required: [type]
+          properties:
+            type: { type: string, enum: [tool_approval_complete] }
+    Event_approval_request:
+      description: >
+        The design/172 in-stream approval card as an AgentEvent arm. PARALLEL to `tool_approval`, not a
+        replacement: with the protocol on, one ask emits BOTH frames (legacy first) carrying the SAME
+        `approvalId` — dedupe on it and prefer this arm. The decision key is `askId`; settle via
+        POST /v1/tasks/{taskId}/asks/{askId}/decision.
+
+        🔴 THIS ARM IS THE OPEN ENVELOPE, NOT `ApprovalRequestFrame`, AND THAT IS DELIBERATE. The v1 frame
+        schema pins `schemaVersion: 1` and `kind: permission`, but a stream carries whatever the server sends:
+        binding the arm to v1 would (a) make a generated client REJECT a legitimate future-version frame at the
+        `oneOf`, and (b) tell a TypeScript/codegen consumer that `card` and its risk axes are guaranteed present
+        on a frame that never validated as v1 — the exact bypass of the "unknown shapes get a GENERIC card,
+        NEVER auto-deny" rule stated on ApprovalRequestFrame and ApprovalFrameEnvelope.
+        ⇒ Read this arm as the envelope, THEN check `schemaVersion == 1 && kind == "permission"` (SDK:
+        `isApprovalRequestFrameV1`) before touching `card`/`askId`/the window keys — the validated v1 payload is
+        described by `ApprovalRequestFrame`. If it does not validate, render the generic card.
+
+        🔴 A frame replayed from the durable events tail is for TIMELINE RENDERING ONLY, never a card-set
+        baseline: its `expiresInMs` is frozen at mint time, and the full reconciliation baseline is the
+        open-stream preamble.
+      allOf:
+        - $ref: '#/components/schemas/ApprovalFrameEnvelope'
+        - type: object
+          required: [type]
+          properties:
+            type: { type: string, enum: [approval_request] }
+
     # ── resources/*.ts schema backfill, batch 2 (2026-07-28) — the 28-item WIRE_PENDING ratchet zeroed.
     #    Each schema below is cross-checked against the server source (file:line cited in its description
     #    or in the SDK resource JSDoc it mirrors). Wire objects are OPEN sets (additionalProperties: true).
@@ -8727,7 +8934,7 @@ components:
       description: >
         The 200 body of POST /v1/approvals/{sessionId}/decide when the pending checkpoint belongs to a
         PARKED background agent (server 1.267, ASSISTANT-WIRE-CONTRACT §4a parked variant; server
-        parked-decide.ts:272 — exact literal shape). ACCEPTANCE semantics: the revive drives
+        parked-decide.ts — exact literal shape). ACCEPTANCE semantics: the revive drives
         ASYNCHRONOUSLY — 200 means accepted, not completed; a failed drive honestly re-parks the row and
         the pending re-appears on the list. Task-level suspends keep the legacy resumed shape —
         discriminate by `status === "resuming"`.
@@ -8827,19 +9034,19 @@ components:
         detail: { type: string, description: 'Redacted supplement (e.g. why skipped). Additive / tolerate-absent.' }
 
     BakeStatus:
-      # 新(census 批2 四段)——server `BakeStatus`(plugins/store-contracts.ts:83), the COARSE lifecycle
+      # 新(census 批2 四段)——server `BakeStatus`(plugins/store-contracts.ts), the COARSE lifecycle
       # bakeView/claimResponse/bakesCreate all key on.
       type: string
       enum: [queued, running, done, failed]
 
     BakeState:
-      # 新(census 批2 四段)——server `BakeState`(store-contracts.ts:85-93), build.sh's finer 8-value state;
+      # 新(census 批2 四段)——server `BakeState`(store-contracts.ts), build.sh's finer 8-value state;
       # null before the runner's first `state` line lands.
       type: [string, 'null']
       enum: [PENDING, BUILDING, PUSHING, VERIFYING, REGISTERING, COMPLETE, FAILED, CANCELLED, null]
 
     BakeErrorCode:
-      # 新(census 批2 四段)——server `BakeErrorCode`(store-contracts.ts:96), the closed structured terminal
+      # 新(census 批2 四段)——server `BakeErrorCode`(store-contracts.ts), the closed structured terminal
       # code set (§P2.14 #2); null = success or an uncategorized failure.
       type: [string, 'null']
       enum: [band-conflict, duplicate, disk, timeout, cancelled, null]
@@ -8875,7 +9082,7 @@ components:
 
     BakeRecordView:
       # 新(census 批2 四段)——GET /v1/images/bakes/{bakeId}'s `{ bake }` envelope. Exact key set = server
-      # `bakeView()` (images.ts:527-551): the durable BakeRecord MINUS the runner-internal secret/lease fields
+      # `bakeView()` (images.ts): the durable BakeRecord MINUS the runner-internal secret/lease fields
       # (ingestSecret/runnerId/leaseUntil/cancelRequested/argv — an ops surface, not the claim credential).
       type: object
       description: The operator poll view of one bake (server bakeView projection over the durable BakeRecord).
@@ -8908,7 +9115,7 @@ components:
 
     BakeSubmitAck:
       # 新(census 批2 四段)——POST /v1/images/bakes 202 body. All three code paths (attach-to-in-flight,
-      # atomic-admission-created, dryRun) produce this SAME shape (images.ts:193/206/213/217).
+      # atomic-admission-created, dryRun) produce this SAME shape (images.ts).
       type: object
       description: Acknowledgement of a submitted/attached-to bake.
       required: [bakeId, eventsUrl, status, state]
@@ -8920,7 +9127,7 @@ components:
         state: { $ref: '#/components/schemas/BakeState' }
 
     BakeCancelAck:
-      # 新(census 批2 四段)——POST /v1/images/bakes/{bakeId}/cancel 202 body (images.ts:239-241). `note` is
+      # 新(census 批2 四段)——POST /v1/images/bakes/{bakeId}/cancel 202 body (images.ts). `note` is
       # ALWAYS present (a ternary VALUE, not a conditional key) — the spec previously implied it was optional.
       type: object
       description: Cooperative-cancel acknowledgement (a durable flag; the runner kills the build at its next heartbeat).
@@ -8933,7 +9140,7 @@ components:
 
     BakeIngestAck:
       # 新(census 批2 四段)——POST /v1/images/bakes/{bakeId}/ingest 200 body. 🔴 FOUR distinct shapes share
-      # this one status code (images.ts:302-334): a heartbeat ack carries no `seq`; a non-terminal frame ack
+      # this one status code (images.ts): a heartbeat ack carries no `seq`; a non-terminal frame ack
       # carries `seq` but no `terminal`; a terminal `done` carries `terminal`+`indexId` (success) OR
       # `terminal`+`needsFlip` (the bounded-retry-exhausted non-throw path, still 200 — the runner re-POSTs the
       # idempotent done to re-drive the flip). `cancelRequested`+`leaseValid` ride on every non-heartbeat shape
@@ -9102,7 +9309,7 @@ components:
         nextBefore?}`; server src/http/routes/sessions-list.ts — exact projection). A principal caller is PINNED to its
         own scope (?scope= ignored); a fleet credential may pass ?scope= (default = the single-user
         sentinel "_"). Page with `before` = a previous page's `nextBefore` (uuidv7; malformed → 400).
-      # 🔴 census 批2 五段:CLOSED — exact projection (sessions-list.ts:94-105); taskId/sessionId are the
+      # 🔴 census 批2 五段:CLOSED — exact projection (sessions-list.ts); taskId/sessionId are the
       # only OMIT-when-absent keys, no others.
       required: [id, filename, size, ttlSec, track, bucket, key, createdAt]
       additionalProperties: false
@@ -9123,7 +9330,7 @@ components:
       enum: [now, next, later]
       description: >-
         [2400] TR-4 — per-message queue priority on POST /v1/runs/{taskId}/steer. ACCEPTED + ENUM-VALIDATED
-        FAIL-LOUD (`routes/runs.ts:603`; anything else is 400 `request.field_invalid`) and echoed back on the
+        FAIL-LOUD (`routes/runs.ts`; anything else is 400 `request.field_invalid`) and echoed back on the
         receipt, but ADVISORY today: core's steer is a single-slot last-writer-wins with no per-message priority
         or addressable drop, so a faithful priority queue (and DELETE /v1/runs/{taskId}/queue/{messageId}) waits
         on a core seam.
@@ -9133,16 +9340,16 @@ components:
       description: >
         [2400] TR-4 — the POST /v1/runs/{taskId}/steer receipt, DISCRIMINATED on `delivery` (three server mint
         points meaning three different things; branch on this, NOT on the status code):
-        `applied` (200, `routes/runs.ts:648`) — injected into the run LIVE on this replica, drains at the next
+        `applied` (200, `routes/runs.ts`) — injected into the run LIVE on this replica, drains at the next
         turn boundary (`status:"running"`);
-        `queued` (202, `:641`) — the run is durably SUSPENDED, so the steer was PARKED on its pending checkpoint
+        `queued` (202) — the run is durably SUSPENDED, so the steer was PARKED on its pending checkpoint
         and is injected on resume (`status:"suspended"`);
-        `parked_for_wake` (202, `:734`) — the run already ENDED; the server minted a `task_done` checkpoint and
+        `parked_for_wake` (202) — the run already ENDED; the server minted a `task_done` checkpoint and
         parked the message on it, delivered ONLY by POST /v1/sessions/{sessionId}/wake — nothing happens until
         the session is woken.
         `messageId` is server-minted and stable across all three (dedup / correlation handle).
       required: [taskId, status, delivery, messageId]
-      # 封闭:三个铸造点是逐字面量拼出来的对象(routes/runs.ts:641/648/734),不是引擎透传形。
+      # 封闭:三个铸造点是逐字面量拼出来的对象(routes/runs.ts),不是引擎透传形。
       additionalProperties: false
       properties:
         taskId: { type: string }
@@ -9176,8 +9383,7 @@ components:
         TaskOutput-tool text (the child's final assistant body once terminal) — UNTRUSTED model output,
         same posture as a run `result`. `output` = the engine registry's UnifiedTaskOutput projection
         passed through VERBATIM.
-      # 封闭(census 批2 第三段,2026-07-30):两个铸造点(`routes/runs.ts:934` 窄面 4 键 / `:1155` generic
-      # 面 4 键 + 条件 `...g14`)顶层键集就是这 5 个。`output` 子对象**保持开**——它是 registry 投影的
+      # 封闭(census 批2 第三段,2026-07-30):两个铸造点(`routes/runs.ts` 的窄面 4 键 / generic 面 4 键 + 条件 `...g14`)顶层键集就是这 5 个。`output` 子对象**保持开**——它是 registry 投影的
       # verbatim 透传(deps 签名 `details: unknown`),不是 server 铸的形。
       required: [taskId, target, content, output]
       additionalProperties: false
@@ -9216,7 +9422,7 @@ components:
         exact literal: `status:"running"`, `delivery:"accepted"`). ACCEPTANCE, not an outcome: compaction
         runs at the next turn boundary and a `compacted{trigger:"manual"}` event rides the run stream ONLY
         if anything was summarized (mooted/failed → no event).
-      # 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):唯一铸造点 `routes/runs.ts:793` 是
+      # 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):唯一铸造点 `routes/runs.ts` 是
       # 四键字面量,四键**全部无条件**——此前 required 只列 taskId,把恒在键写成了可缺。
       required: [taskId, status, delivery, note]
       additionalProperties: false
@@ -9233,7 +9439,7 @@ components:
         `toolCallId` echoed, `delivery:"requested"`). Fire-and-forget: acceptance only — the
         authoritative outcome is the tool call's own `tool_end.structured {detached:true, task_id}`;
         a non-detachable env makes the request a fail-safe no-op.
-      # 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):唯一铸造点 `routes/runs.ts:848` 是
+      # 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):唯一铸造点 `routes/runs.ts` 是
       # 四键字面量,四键全部无条件(toolCallId=请求回显,body 校验过必在)。
       required: [taskId, toolCallId, delivery, note]
       additionalProperties: false
@@ -9321,10 +9527,10 @@ components:
     ToolApprovalRespondAck:
       type: object
       description: >
-        The 200 ack of POST /v1/tool-approvals/{approvalId}/respond (server tool-approval.ts:521 — exact
+        The 200 ack of POST /v1/tool-approvals/{approvalId}/respond (server tool-approval.ts — exact
         shape, `decision` echoed). Owner-gated with a 404 and NO existence oracle: non-owner and
         unknown/settled/expired/wrong-replica ids are indistinguishable.
-      # 封闭(census 批2 第三段,2026-07-30):铸造点 `tool-approval.ts:521` 三恒在键 + 两条件键
+      # 封闭(census 批2 第三段,2026-07-30):铸造点 `tool-approval.ts` 三恒在键 + 两条件键
       # (rememberApplied/updatedInputForwarded 的条件展开就在同一行字面量里),键集恰是这 5 个。
       required: [approvalId, delivery, decision]
       additionalProperties: false
@@ -9348,25 +9554,25 @@ components:
     UsageMetric:
       type: string
       enum: [tasks, tokensIn, tokensOut, costUsd]
-      description: 'The ?metric= axis of GET /v1/usage/series (server usage-analytics.ts:67). Default costUsd.'
+      description: 'The ?metric= axis of GET /v1/usage/series (server usage-analytics.ts). Default costUsd.'
 
     UsageGranularity:
       type: string
       enum: [hour, day]
-      description: 'The ?granularity= axis of GET /v1/usage/series (UTC buckets; server usage-analytics.ts:68). Default day.'
+      description: 'The ?granularity= axis of GET /v1/usage/series (UTC buckets; server usage-analytics.ts). Default day.'
 
     UsageDimension:
       type: string
       enum: [principal, model]
       description: >
-        The ?dimension= axis of GET /v1/usage/breakdown (server usage-analytics.ts:85). Default principal.
+        The ?dimension= axis of GET /v1/usage/breakdown (server usage-analytics.ts). Default principal.
         A JWT principal querying dimension=principal only ever sees its own bucket (owner is enforced
         upstream — the semantics hold naturally, no leak surface).
 
     UsageTotals:
       type: object
       description: >
-        Window totals (server usage-analytics.ts:31 UsageTotals). tokensIn = Σ(inputTokens +
+        Window totals (server usage-analytics.ts UsageTotals). tokensIn = Σ(inputTokens +
         cacheReadTokens + cacheWriteTokens) — the billing view (cache hits count); tokensOut = Σ
         outputTokens; costUsd = Σ costMicroUsd / 1e6 (authoritative micro-USD ledger, not an estimate).
       required: [tasks, tokensIn, tokensOut, costUsd, estimated]
@@ -9401,9 +9607,9 @@ components:
       allOf:
         - $ref: '#/components/schemas/UsageWindowBase'
         - $ref: '#/components/schemas/UsageTotals'
-      # 🔴 封闭 + 本地镜像(census 批2 第二段,2026-07-30)。铸造点 `routes/trace-usage.ts:141` 逐字是
+      # 🔴 封闭 + 本地镜像(census 批2 第二段,2026-07-30)。铸造点 `routes/trace-usage.ts` 逐字是
       # `{ ...base, ...usageSummary(scan.rows) }`,两半都是本仓自己的字面量:`base` = from/to/truncated?
-      # (`:139`),`usageSummary` = `finish(UsageTotals)` 的五键(`usage-analytics.ts:98`)。
+      # (`usage-analytics.ts`),`usageSummary` = `finish(UsageTotals)` 的五键(`usage-analytics.ts`)。
       # 镜像的理由与 Event_reasoning 处那条长注逐字同一条(`additionalProperties` 不结算 allOf 分支);
       # 一致性由 spec.test.ts 的通用「封闭 allOf 臂必须镜像被引 schema 全部键」门看守。
       additionalProperties: false
@@ -9433,13 +9639,13 @@ components:
               type: array
               items:
                 type: object
-                # 封闭:桶行铸造点 `usage-analytics.ts:118` 是两键字面量 `{ t, v }`。
+                # 封闭:桶行铸造点 `usage-analytics.ts` 是两键字面量 `{ t, v }`。
                 additionalProperties: false
                 required: [t, v]
                 properties:
                   t: { type: string, description: 'ISO-8601 bucket start (UTC).' }
                   v: { type: number }
-      # 封闭 + 本地镜像:铸造点 `routes/trace-usage.ts:149` = `{ ...base, metric, granularity, series }`。见 UsageSummary 处的注。
+      # 封闭 + 本地镜像:铸造点 `routes/trace-usage.ts` = `{ ...base, metric, granularity, series }`。见 UsageSummary 处的注。
       additionalProperties: false
       properties:
         from: { type: string }
@@ -9471,7 +9677,7 @@ components:
                     properties:
                       key: { type: string, description: 'The bucket key (a principal or a model id).' }
                   - $ref: '#/components/schemas/UsageTotals'
-                # 封闭 + 本地镜像:桶行铸造点 `usage-analytics.ts:126` 是 `{ key, ...UsageTotals }`。
+                # 封闭 + 本地镜像:桶行铸造点 `usage-analytics.ts` 是 `{ key, ...UsageTotals }`。
                 additionalProperties: false
                 properties:
                   key: { type: string }
@@ -9480,7 +9686,7 @@ components:
                   tokensOut: { type: number }
                   costUsd: { type: number }
                   estimated: { type: boolean }
-      # 封闭 + 本地镜像:铸造点 `routes/trace-usage.ts:157` = `{ ...base, dimension, breakdown }`。见 UsageSummary 处的注。
+      # 封闭 + 本地镜像:铸造点 `routes/trace-usage.ts` = `{ ...base, dimension, breakdown }`。见 UsageSummary 处的注。
       additionalProperties: false
       properties:
         from: { type: string }
@@ -9496,7 +9702,7 @@ components:
         exact literal: `status:"running"`, `delivery:"applied"`, `marker` = the engine-minted delivery
         marker; NO `note`, unlike the run-subagent verb).
       # 🔴 census 批2 五段:CLOSED — all 5 keys are unconditional in the literal
-      # `{ runId: wfRunId, label, status: "running", delivery: "applied", marker }` (workflows.ts:279);
+      # `{ runId: wfRunId, label, status: "running", delivery: "applied", marker }` (workflows.ts);
       # this schema previously existed but no path `$ref`'d it (see the path fix above).
       required: [runId, label, status, delivery, marker]
       additionalProperties: false
@@ -9513,7 +9719,7 @@ components:
       # type)对方法返回位的内联形都是盲的 —— 于是它漏了这里一直标为 required 的 `sessionId`,CI 全绿。
       type: object
       description: >
-        GET /v1/sessions/{sessionId}/workspace 的 200 信封(server src/http/routes/sessions.ts:624-629)。
+        GET /v1/sessions/{sessionId}/workspace 的 200 信封(server src/http/routes/sessions.ts)。
         ⚠️ `total` = **本页行数**(`snapshots.length`),不是快照总数,且这条腿没有任何分页游标 —— 与同族
         `WorkspaceTreePage.total`(真·全量)**同名反义**。`latest` 与展示行同源(防 ghost key)。
       additionalProperties: false
@@ -9530,7 +9736,7 @@ components:
       # 4.3.0(CAPS-OPS-8):同上,tree 腿的 200 信封。
       type: object
       description: >
-        GET /v1/sessions/{sessionId}/workspace/{key}/tree 的 200 信封(server src/http/routes/sessions.ts:651-657)。
+        GET /v1/sessions/{sessionId}/workspace/{key}/tree 的 200 信封(server src/http/routes/sessions.ts)。
         `total` 在这条腿上是**全量**(`all.length`)—— 与 `WorkspaceSnapshotPage.total` 语义相反。
         `key` 回的是解析后的真实键(请求可传 `latest` 别名)。
       additionalProperties: false