@sema-agent/sdk 0.0.100 → 0.0.102

package/openapi.yaml

@@ -13,8 +13,29 @@ openapi: 3.1.0
 # 测试锚定,是目前唯一真正贴合 server 当前实现的文档**。本文件保留作 M0 时代的历史参照(早期
 # verb 清单/大致响应形状仍可读),但**任何具体字段名/是否顶层/是否为 optional 的判断,一律以
 # types.ts 为准,本文件不可信**——已实证撞获至少一处两者互斥的真矛盾(`PendingCheckpoint`,
-# 见下方该 schema 旁注)。回填 spec + 建反射式字段 diff 门是后续候办项,未完成前不要相信这里
-# 的字段级细节。
+# 见下方该 schema 旁注)。
+#
+# ── 状态更新(2026-07-25 回填批完成)────────────────────────────────────────────────────────
+# 上面那句「回填 spec + 建反射式字段 diff 门是后续候办项,未完成前不要相信这里的字段级细节」
+# **已经过时**。现状是:
+#   ✅ 反射式字段级 diff 门已建并**零容忍**:`packages/sdk/test/spec-field-drift-gate.test.ts`
+#      用 TS 编译器 API 解析 `types.ts`(跟 extends / 解 Omit / Pick)× 解析本文件(递归展开
+#      `allOf`/`$ref`)逐字段比对。存量两族基线**都已清零**:字段级 drift 0、整 schema 缺席 0。
+#      ⇒ types.ts 加了字段而这里不加,CI 就红。**字段级细节现在有机器看守了。**
+#   ✅ 本批同时补了 3 条此前整条缺失的路径(`/v1/images`、`/v1/images/select`、
+#      `/v1/capabilities/scenarios/{name}`)、`AgentEvent` 缺的 6 个臂、`/v1/sessions/{id}` 的
+#      5 个 query 参数,并修掉一处真错(`/v1/tasks/{id}/stream` 原先 $ref 到 `AgentEvent`,实际是
+#      `TraceStreamEvent` 词汇表 —— 本文件自己的两处声明互相矛盾)。
+#
+# 🔴 但**权威依然是 types.ts**,理由没变:本文件是手写的第二份声明,门只能保证"字段名集合一致",
+#    保不了语义/可空性/枚举值。已知门**看不见**的三类(判断时请回 types.ts 或 server 源码):
+#      ① 枚举值陈旧 —— 本批就抓到 `AssistantTask.status` 少了 `needs_review`(真的一等 triage 态)。
+#      ② 联合缺臂 —— `AgentEvent` 曾少 6 臂;门只按"命名 schema ↔ 同名 interface"配对,联合对它不可见。
+#      ③ 层差 —— 本文件描述 **wire**(如 gate 的数值字段是显式 `null`),types.ts 描述 **SDK 归一后**
+#         (null 已在资源层折成省略键)。两者都对,不要互相"修正"。见 `AssistantGate` 旁注。
+#    另仍有意留在覆盖外(**不是已覆盖**):`/v1/images` 前缀下的 register/:profile/digests 与整个
+#    bake 控制面(SDK 侧还用 `Record<string, unknown>`、没有具名类型 ⇒ 应先在 types.ts 具名);
+#    `SessionBundle` 目前是本文件里唯一的孤儿 schema(无人 $ref)。
 #
 # Consumed by @sema-agent/sdk (→ both doors: the CC/Codex MCP façade and the
 # portal BFF). Producer = the service.
@@ -124,6 +145,37 @@ paths:
               schema: { $ref: '#/components/schemas/Capabilities' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  # 补漏(2026-07-25):本路径此前完全不在本文件里,尽管 SDK 早有 `ScenarioDetail` 类型。形按 server 亲读取证。
+  /v1/capabilities/scenarios/{name}:
+    get:
+      tags: [metrics]
+      operationId: scenarioDetail
+      x-status: live
+      summary: One scenario's detail card.
+      description: >
+        The detail for a single scenario. The LIST of available names rides `capabilities().scenarios` — this
+        route only expands one. Auth = same as `/v1/capabilities` (config surface).
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema: { type: string }
+          description: 'the scenario name (as listed in `capabilities().scenarios`).'
+      responses:
+        '200':
+          description: The scenario detail card.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ScenarioDetail' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          # 🔴 这条曾是全站唯一的**对象形** error(`{error:{code}}`),SDK 的 toApiError 为它特判过一轮。
+          #    server 已统一为「字符串 error + 顶层 errorCode」的邻位形(同 cancel/decide),机器判据保留为 errorCode。
+          description: 'Unknown scenario — `{ error: "scenario not found", errorCode: "scenario_not_found" }`.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/memory:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -533,14 +585,71 @@ paths:
         CURRENT model context (older history already folded into a summary message) — can be LARGE, the portal
         should lazy-expand. Absent entirely on workers without the TiDB pool (capabilities.asyncRuns is the
         practical same-prereq signal).
+
+
+        🔴 The 5 query params below are ADDITIVE: a request with NONE of them returns the byte-identical legacy
+        payload. `?message=` SHORT-CIRCUITS to a different response schema (`SessionMessageEnvelope`) — see below.
+      # 补漏(2026-07-25):此前本操作**一个 query 参数都没声明**,所以整个分页/截断/单条展开面对生成式消费方
+      # 等于不存在。以下 5 个按 server 亲读取证(`http/server.ts:5692-5723`)。
+      parameters:
+        - name: message
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: >
+            The single-message EXPAND leg: returns `SessionMessageEnvelope` (ONE full message body) instead of a
+            `SessionRecord`, and IGNORES the other params. Index is stable within one `floorEntryId` generation —
+            a compaction changes `floorEntryId` and invalidates held indices. Out-of-range → 404 (body carries
+            `total`). This is the companion of a `blobCap`-truncated read: expand = refetch that ONE message.
+        - name: tail
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: 'return the LAST N messages (+ a `window` `{offset,total}`).'
+        - name: before
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: 'return the page ABOVE a prior window offset (pair with `limit`).'
+        - name: limit
+          in: query
+          required: false
+          schema: { type: integer, minimum: 0 }
+          description: 'page size for the `tail`/`before` window. Ignored unless one of those is present.'
+        - name: blobCap
+          in: query
+          required: false
+          schema: { type: integer, minimum: 1 }
+          description: >
+            Truncate oversized string bodies to a preview and mark that message `truncated: true`. Only values
+            > 0 take effect. Expand a truncated message via `?message=<index>` (full size).
       responses:
         '200':
-          description: Session record.
+          description: >
+            A `SessionRecord` — or a `SessionMessageEnvelope` when `?message=` was supplied.
+
+            ⚠️ Parameter parsing is LENIENT by construction: a non-numeric or NEGATIVE value is treated as
+            ABSENT, not as an error (so `?tail=-1` quietly returns the full record rather than a 400). A client
+            must not rely on a 400 to catch its own bad paging arithmetic.
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/SessionRecord' }
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/SessionRecord'
+                  - $ref: '#/components/schemas/SessionMessageEnvelope'
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { $ref: '#/components/responses/NotFound' }
+        '404':
+          description: >
+            Non-owner / unknown session (no existence oracle) — or, with `?message=`, an out-of-range index, whose
+            body additionally carries `total`.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                properties:
+                  error: { type: string }
+                  total: { type: integer, description: 'present on the out-of-range `?message=` 404 — the message count available.' }
     delete:
       tags: [sessions]
       operationId: sessionsDelete
@@ -1278,15 +1387,14 @@ paths:
         Owner-gated (NOT D-G); non-owner → 404. SDK → GateNotResumableError on the 409.
       responses:
         '200':
-          description: Resumed; `{status}` (e.g. "completed").
+          # 2026-07-25:此前只声明 `{status}`。真体(`http/server.ts:7688-7696`,与 plan_review 共用
+          # `driveResumeIntoRunLog`)带 taskId/sessionId + 失败态的 errorCode/errorMessage/retriable。
+          description: >
+            Resumed. 🔴 A 200 does NOT mean success — `status` can be `failed`, in which case `errorCode`/
+            `errorMessage` say why and `retriable:true` means the park is STILL PENDING (decide again).
           content:
             application/json:
-              schema:
-                type: object
-                required: [status]
-                additionalProperties: true
-                properties:
-                  status: { type: string }
+              schema: { $ref: '#/components/schemas/AssistantTaskStatus' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -1321,15 +1429,13 @@ paths:
             schema: { $ref: '#/components/schemas/PlanReviewRequest' }
       responses:
         '200':
-          description: Resolved; `{status}` (e.g. "completed").
+          # 2026-07-25:同 resume —— 两条共用 `driveResumeIntoRunLog`,响应体逐字相同。
+          description: >
+            Resolved. 🔴 A 200 does NOT mean success — see `status`/`errorCode`/`retriable` (same body as §4b
+            resume; the two share one handler).
           content:
             application/json:
-              schema:
-                type: object
-                required: [status]
-                additionalProperties: true
-                properties:
-                  status: { type: string }
+              schema: { $ref: '#/components/schemas/AssistantTaskStatus' }
         '400':
           description: >
             Bad/missing `decision`; `edit` without a non-empty `editedPlan`; `editedPlan` present on
@@ -1364,15 +1470,14 @@ paths:
         `202` no-op; an already-`suspended` task → 409; `RESOURCE_SUSPEND` off → 501. Owner-gated; non-owner → 404.
       responses:
         '202':
-          description: Preempting (or 202 no-op on a terminal task); `{status}`.
+          # 2026-07-25:此前只声明 `{status}`。真体是 `{taskId, status, note}`(`http/server.ts` 三个 202 出口)。
+          description: >
+            Preempting — or an honest 202 NO-OP. ⚠️ `status` is NOT always `"preempting"`: the two no-op exits
+            echo the run's own status instead (a non-preempt-eligible leg, or a task that already stopped
+            running), and `note` says which case it was. Read `note`, do not assume the preempt took effect.
           content:
             application/json:
-              schema:
-                type: object
-                required: [status]
-                additionalProperties: true
-                properties:
-                  status: { type: string }
+              schema: { $ref: '#/components/schemas/AssistantTaskStatus' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -1472,10 +1577,20 @@ paths:
         - $ref: '#/components/parameters/LastEventId'
       responses:
         '200':
-          description: SSE stream of AgentEvents (resumable; same durable source as runs.events).
+          # 🔴 修正(2026-07-25):此处原先 $ref 到 `AgentEvent`,是真错 —— 而且本文件自己就矛盾:专门为这条路写的
+          #   `TraceStreamEvent` schema 的描述里明写「A DISTINCT vocabulary from AgentEvent」,却没有任何地方引用它
+          #   (它是本文件里的一个孤儿 schema)。按 server 真码两侧取证后确定 TraceStreamEvent 才是对的:
+          #   `streamTaskTrace` 每帧走 `mapTraceEvent`(`trace/project.ts:530`),发的是 SSE **event 名**
+          #   `block-thinking-delta` / `block-content-delta` / `tool-call` / `tool-result` / `turn` /
+          #   `prompt-assembled` / `done` / `error`,帧里**没有** `type` 字段;SDK 的 `trace.stream()` 注释逐字同款。
+          #   照旧声明生成的客户端会去 switch 一个不存在的 `type` ⇒ 这条流路对它完全不可用。
+          #   (AgentEvent 词汇表在 `GET /v1/runs/:id/events`,那条声明是对的 —— 两条是不同的面,别再混。)
+          description: >
+            Resumable SSE of the workspace LIVE timeline — the BLOCK-grained trace vocabulary
+            (`TraceStreamEvent`), NOT the `AgentEvent` vocabulary of `/v1/runs/:id/events`.
           content:
             text/event-stream:
-              schema: { $ref: '#/components/schemas/AgentEvent' }
+              schema: { $ref: '#/components/schemas/TraceStreamEvent' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
 
@@ -1793,6 +1908,101 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
 
+  # ── sandbox 镜像目录(补漏 2026-07-25)──────────────────────────────────────────────────────────────
+  # ⚠️ 诚实记下本次的**范围**:只补了带 SDK 具名类型的这两条读面(`ImageIndexEntry`/`ImageSelectResult`)。
+  #    server 的 `/v1/images` 前缀下还有 register / :profile / digests/:digest 以及整个 bake 控制面
+  #    (`/v1/images/bakes*`,operator 与 runner 两种主体),SDK 侧目前用 `Record<string, unknown>` 表达、
+  #    没有具名类型 ⇒ 本批不进 spec(补它们等于在这里新发明一份契约,应当先在 types.ts 具名)。**不是已覆盖**。
+  /v1/images:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [sandbox]
+      operationId: imagesList
+      x-status: live
+      summary: Paginated sandbox-image catalog (principal-scoped visibility).
+      description: >
+        The READ-ONLY data source for a "pick a sandbox template" UI. Visibility is scoped to the request
+        principal by the server. Gated on a configured image index — otherwise the route is not mounted.
+        Paginate with `nextCursor` and treat the cursor as OPAQUE (never parse or synthesize one).
+      parameters:
+        - { name: profile, in: query, required: false, schema: { type: string } }
+        - { name: status, in: query, required: false, schema: { type: string, enum: [building, published, deprecated, failed] } }
+        - { name: capability, in: query, required: false, schema: { type: string }, description: 'filter to images having this capability (e.g. `browser`).' }
+        - { name: latest, in: query, required: false, schema: { type: string, enum: ['true'] }, description: 'string `"true"` ⇒ latest-per-profile only.' }
+        - { name: limit, in: query, required: false, schema: { type: integer } }
+        - { name: cursor, in: query, required: false, schema: { type: string }, description: 'echo `nextCursor` from the previous page verbatim.' }
+      responses:
+        '200':
+          description: 'Catalog page — `{ images, nextCursor? }`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [images]
+                additionalProperties: true
+                properties:
+                  images:
+                    type: array
+                    items: { $ref: '#/components/schemas/ImageIndexEntry' }
+                  nextCursor: { type: string, description: 'OPAQUE — pass back as `cursor`. Absent on the last page.' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/images/select:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [sandbox]
+      operationId: imagesSelect
+      x-status: live
+      summary: Resolve a profile to its newest published digest (UI PREVIEW only).
+      description: >
+        Pure resolution, no build. 🔴 The result is a PREVIEW, NOT a binding credential: to actually run on this
+        image, send `sandboxImageProfile` (a PROFILE) on the task request and let the server resolve + re-admit
+        under a trusted principal. A caller that sends/caches/recomputes a digest turns a fail-closed admission
+        into a fail-open one.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile]
+              additionalProperties: true
+              properties:
+                profile: { type: string, description: 'non-empty; missing/blank → 400.' }
+                capabilitiesNeeded:
+                  type: array
+                  items: { type: string }
+                  description: 'capability names that MUST be satisfied by the resolved image, else 409.'
+      responses:
+        '200':
+          description: The resolution preview.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ImageSelectResult' }
+        '400':
+          description: '`profile` missing/blank.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          description: 'No published image for that profile VISIBLE TO THIS PRINCIPAL (invisible and nonexistent are deliberately indistinguishable — no existence oracle).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '409':
+          description: 'The resolved image does not satisfy `capabilitiesNeeded` — body carries `missing[]`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                properties:
+                  error: { type: string }
+                  missing: { type: array, items: { type: string } }
+
   /metrics/summary:
     get:
       tags: [metrics]
@@ -1939,6 +2149,27 @@ components:
         Primary routing axis (one image serves many; unknown → "default"). Selects model/tools/skills/prompt.
       examples: ['default', 'oa', 'code-review', 'team']
 
+    ScenarioDetail:
+      # 新增(2026-07-25 回填批):`GET /v1/capabilities/scenarios/{name}` 此前**整条路径**都不在本文件里
+      # (只有 `Capabilities.scenarios` 那个名字数组)。形按 server 亲读取证(`http/server.ts:1517-1527`)。
+      type: object
+      description: >
+        One scenario's detail card (`GET /v1/capabilities/scenarios/{name}`). The LIST of names rides
+        `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.
+      required: [name, source, builtin, summary, toolset, tools, promptSummary, enabled]
+      additionalProperties: true
+      properties:
+        name: { type: string }
+        source: { type: string, enum: [builtin, center] }
+        builtin: { type: boolean }
+        summary: { type: string }
+        toolset: { type: string }
+        tools: { type: array, items: { type: string } }
+        promptSummary: { type: string, description: 'a human-readable prompt DIGEST — NOT the full prompt.' }
+        enabled: { type: boolean }
+
     RunStatus:
       type: string
       enum: [running, completed, failed, suspended, needs_review]
@@ -1958,7 +2189,96 @@ components:
         outputTokens: { type: integer }
         costUsd: { type: number }
         cacheHitRate: { type: number }
+        toolCalls: { type: integer }
+        cacheWriteTokens: { type: integer, description: Short-TTL cache-write tokens. }
+        cacheWriteTokensLong: { type: integer, description: Long-TTL (1h) cache-write tokens, priced separately. }
+        totalInputTokens:
+          type: integer
+          description: Normalized total input (prompt + cache reads) — the denominator most cost views want.
+        costMicroUsd:
+          type: integer
+          description: >
+            Integer micro-USD cost. Prefer this over the float `costUsd` for accounting (no FP drift). Both are
+            emitted; they describe the same spend.
+        costBreakdown:
+          description: >
+            Per-axis cost detail (LLM root / nested subagents / compaction / infra). Deliberately untyped — it is an
+            OPEN map whose axes grow with the engine; read defensively rather than modelling it.
+        humanReview:
+          type: object
+          description: MF-24 — human-in-the-loop wait ledger for this task (present once any gate was hit).
+          required: [count, totalWaitMs, gates]
+          properties:
+            count: { type: integer }
+            totalWaitMs: { type: integer }
+            gates:
+              type: array
+              description: One row per gate. OPEN objects — engine may add keys.
+              items:
+                type: object
+                required: [kind, waitMs]
+                additionalProperties: true
+                properties:
+                  kind: { type: string }
+                  waitMs: { type: integer }
+                  decision: { type: string }
+                  toolName: { type: string }
       required: [turns, tokens]
+      # 🔴 OPEN: the engine may carry fields not named here (live-observed, e.g. extra costBreakdown axes) — the SDK
+      # passes them through rather than dropping, so consumers must not assume this list is exhaustive.
+      additionalProperties: true
+
+    TaskAgentDefinition:
+      # 新增(2026-07-25 回填批)—— 取代 `TaskRequest.agents.items` 的 OPEN 对象(理由见那里的旁注)。
+      type: object
+      description: >
+        One per-task subagent definition (`TaskRequest.agents[]` item) — mirrors core `AgentDefinition` verbatim.
+        🔴 The server WHITELISTS exactly these keys: anything else is a 400 on the strict lane (so an
+        unrecognised key is a client bug, not a passthrough).
+      required: [name]
+      properties:
+        name: { type: string, description: 'the `subagent_type` the model passes to Task. Non-empty, ≤64 chars, UNIQUE per request.' }
+        whenToUse: { type: string, description: 'when the model should delegate to this agent (shown in the Task tool''s agent list). ≤4096 chars.' }
+        whenToUseLean: { type: string, description: 'compact variant of `whenToUse` for lean tool listings. ≤4096 chars.' }
+        allowTools: { type: array, items: { type: string }, description: 'allowlist of tool names. Omit ⇒ inherit ALL tools.' }
+        denyTools: { type: array, items: { type: string }, description: 'denylist (SUBTRACTIVE — applied after `allowTools`).' }
+        skills:
+          type: array
+          description: 'skills preloaded into the agent.'
+          items:
+            type: object
+            required: [name, description, content]
+            additionalProperties: true
+            properties:
+              name: { type: string }
+              description: { type: string }
+              content: { type: string }
+              manifest: { type: object, additionalProperties: true }
+              files:
+                type: array
+                items:
+                  type: object
+                  required: [path, content]
+                  additionalProperties: true
+                  properties: { path: { type: string }, content: { type: string } }
+        background: { type: boolean, description: 'run the agent in the background (the parent turn continues).' }
+        isolation: { type: string, enum: [worktree], description: '`worktree` = run the agent in an isolated git worktree.' }
+        model:
+          description: >
+            Shell-resolved REAL model name/id — or a Model object with a string `id`. 🔴 NOT an alias: the server
+            does no translation. Omit ⇒ inherit the parent model.
+          oneOf:
+            - type: string
+            - type: object
+              required: [id]
+              additionalProperties: true
+              properties: { id: { type: string } }
+        thinking: { type: string, enum: [off, minimal, low, medium, high, xhigh, max] }
+        systemPrompt: { type: string, description: 'the agent''s system prompt. ≤65536 chars.' }
+        maxTurns: { type: integer, minimum: 1, description: 'max agent turns before the subagent is stopped.' }
+        memory: { type: object, additionalProperties: true, description: 'memory spec (`{ scope?, scopes?, writeScope?, enabled?, scopeContract? }`).' }
+        observer: { type: string, description: 'observer prompt (agent-observes-agent lane). ≤4096 chars.' }
+        observerMessage: { type: string, description: 'message template the observer sends. ≤4096 chars.' }
 
     TaskRequest:
       type: object
@@ -2086,6 +2406,97 @@ components:
               properties:
                 count: { type: integer }
                 role: { type: string, description: A model role name. }
+        compactionModel:
+          type: string
+          description: >
+            Pin a SEPARATE (usually cheaper) model for compaction. Validated against the catalog on submit — an
+            unknown ref is a 400, not a silent fallback to the main model's price.
+        appendSystemPrompt: { type: string, description: Text appended to the assembled system prompt for this task. }
+        promptProfile:
+          type: string
+          enum: [simple, classic]
+          description: Which prompt-assembly profile to use.
+        clientContext:
+          type: object
+          description: Non-authoritative client hints (never trusted for authz).
+          properties:
+            timeZone: { type: string }
+            userEmail: { type: string }
+        sandboxImageProfile: { type: string, description: Sandbox image profile name for the execution env. }
+        capabilitiesNeeded:
+          type: array
+          items: { type: string }
+          description: Capability names the caller requires; the worker refuses up front rather than 501-ing mid-run.
+        memoryWrite: { type: boolean, description: Allow this task to WRITE user memory (read is governed separately). }
+        settings:
+          type: object
+          description: >
+            TOC `settings.json` contract carried to the worker (CC-parity v1: permissions/hooks/env/model/
+            outputStyle). The SDK owns the schema in `src/settings.ts` (`SemaSettings`) — it is deliberately NOT
+            duplicated here as a component: the service passes it through to core rather than interpreting it, so
+            the TS type is the single authority. OPEN object.
+          additionalProperties: true
+        cwd: { type: string, description: Working directory for the execution env. }
+        selfOrchestration: { type: boolean, description: Permit S8 self-orchestration (run_workflow) inside this task. }
+        enableFork: { type: boolean, description: Permit session forking from inside this task. }
+        # 原注是「形状归 SDK 的 TaskAgentDefinition 所有,这里刻意保持 OPEN 而不重复一遍」。2026-07-25 推翻该选择,
+        # 理由是那条推理只对 TS 消费方成立:TS 消费方本来就 import 得到 `TaskAgentDefinition`,从本文件生成客户端的
+        # 消费方(本文件存在的全部意义)拿到的却是一个「任意键的对象」——而这是**请求体**,写错键会被 server 的严格
+        # 通道 400 掉,恰恰是最需要 schema 的地方。⚠️ 代价诚实记下:这确实成了第二处需要跟着 core `AgentDefinition`
+        # 走的声明。因此反射式 drift 门(`test/spec-field-drift-gate.test.ts`)把 `TaskAgentDefinition` 纳入了逐字段
+        # 比对 —— types.ts 加字段而这里不加,门就会红。这就是"重复"这次可以接受的原因:它被机器看住了。
+        agents:
+          type: array
+          items: { $ref: '#/components/schemas/TaskAgentDefinition' }
+          description: Per-task sub-agent definitions (roster additions scoped to this task only).
+        interactiveTools: { type: boolean, description: Mount interactive (prompting) tools. }
+        retainBackgroundProcesses: { type: boolean, description: Keep background processes alive past the turn. }
+        excludeTools:
+          type: array
+          items: { type: string }
+          description: Tool names to withhold from this task's roster.
+        deferTools:
+          type: array
+          items: { type: string }
+          description: Tool names to DEFER (discoverable via tool search instead of mounted up front).
+        attachments:
+          type: object
+          description: >
+            Turn-boundary reminder attachments (design/133 + G1). Each flag opts INTO an injection; omitted = off.
+            `changedFiles` may also be an object to cap the listing.
+          additionalProperties: true
+          properties:
+            todoReminder: { type: boolean }
+            todoReminderMode: { type: string, enum: [baseline, off] }
+            changedFiles:
+              oneOf:
+                - { type: boolean }
+                - { type: object, properties: { maxFiles: { type: integer } } }
+            planModeReminder: { type: boolean }
+            budgetUsd: { type: boolean }
+            backgroundTasks: { type: boolean }
+            toolsDelta: { type: boolean }
+            agentListing: { type: boolean }
+            skillsListing: { type: boolean }
+            mcpInstructions: { type: boolean }
+        limits:
+          type: object
+          description: >
+            Per-task bounds. The three `false`-only switches are OPT-OUTS of engine defaults (there is no `true`
+            form — passing false disables that default behaviour).
+          properties:
+            timeoutSec: { type: integer }
+            maxOutputTokens: { type: integer }
+            maxTurns: { type: integer }
+            deadlineNudge: { type: boolean, enum: [false] }
+            callCapByDeadline: { type: boolean, enum: [false] }
+            gracefulFinalize: { type: boolean, enum: [false] }
+        outputRetries: { type: integer, description: How many times to retry a malformed structured output. }
+        compaction:
+          type: object
+          description: Compaction tuning for this task.
+          properties:
+            clampTolerance: { type: number }
 
     TaskResult:
       type: object
@@ -2096,6 +2507,46 @@ components:
         sessionId: { type: string }
         status: { $ref: '#/components/schemas/RunStatus' }
         result: { type: string }
+        model:
+          type: string
+          description: >
+            MF-25 — the EFFECTIVE model id that served this task: the RESOLVED `Model.id`, NOT the requested
+            `model` ref (which may be a role / catalog name / `@mention`). Lets a UI echo "served by X" instead of
+            the requested ref. A mid-run degradation is reported separately via `degraded`. Verified to reach the
+            wire by a real-HTTP regression pin on the server side (`test/effective-model-echo-wire.test.ts`).
+        salvagedOutput:
+          type: string
+          description: Partial output preserved when the run could not complete normally (best-effort salvage).
+        blockedReason:
+          type: string
+          description: Why a `blocked` status was reached (human-readable).
+        checkpointGate:
+          description: >
+            The gate kind that produced `checkpointToken` when the run suspended. Deliberately UNTYPED here —
+            the shape is core's and still evolving; treat it as opaque and branch on `status`/`errorCode` instead.
+        degraded:
+          type: object
+          description: >
+            Set when the run was served by a FALLBACK model after the requested one became unusable mid-run.
+            `from`/`to` are resolved `Model.id`s; `atTurn` is the turn index where the switch happened.
+          required: [from, to, reason, atTurn]
+          properties:
+            from: { type: string }
+            to: { type: string }
+            reason:
+              type: string
+              description: >
+                Open enum — known values `breaker_open` | `rate_limit` | `budget` | `server_error` |
+                `last_resort`; treat unknown values as opaque rather than failing closed.
+            chain:
+              type: array
+              items: { type: string }
+              description: The full fallback chain walked, when more than one hop occurred.
+            atTurn: { type: integer }
+        structuredOutput:
+          description: >
+            The task's structured (schema-constrained) output when one was requested. Shape is caller-defined,
+            so this is intentionally untyped.
         errorCode:
           type: string
           description: >
@@ -2144,6 +2595,37 @@ components:
           description: >
             System attribution DERIVED FROM the authenticating credential (unforgeable; body injection ignored).
             e.g. oa | cc-mcp | portal. LIVE (service cf1be73).
+        suggestions:
+          type: array
+          items: { type: string }
+          description: Follow-up prompt suggestions produced for this run (absent when none were generated).
+        supervisorCost: { $ref: '#/components/schemas/SupervisorCostBreakdown' }
+
+    SupervisorCostBreakdown:
+      type: object
+      description: >
+        Per-axis cost rollup for a supervised run. `llm` is `null` on a run whose LLM spend was not attributed
+        (e.g. no brain call). All amounts are integer micro-USD (no float drift).
+      required: [llm, infra, totalMicroUsd]
+      properties:
+        llm:
+          type: ['object', 'null']
+          required: [llmRootMicroUsd, nestedSubagentMicroUsd, memoryConsolidationMicroUsd, compactionMicroUsd]
+          properties:
+            llmRootMicroUsd: { type: integer }
+            nestedSubagentMicroUsd: { type: integer }
+            memoryConsolidationMicroUsd: { type: integer }
+            compactionMicroUsd: { type: integer }
+        infra:
+          type: object
+          description: Service-owned infra rates (the engine prices only LLM tokens); all default 0 when unpriced.
+          required: [toolCallMicroUsd, sandboxWalltimeMicroUsd, egressMicroUsd, totalMicroUsd]
+          properties:
+            toolCallMicroUsd: { type: integer }
+            sandboxWalltimeMicroUsd: { type: integer }
+            egressMicroUsd: { type: integer }
+            totalMicroUsd: { type: integer }
+        totalMicroUsd: { type: integer, description: llm + infra. }
 
     CancelAck:
       type: object
@@ -2155,6 +2637,13 @@ components:
         taskId: { type: string }
         status: { type: string }
         note: { type: string }
+        errorCode:
+          type: [string, "null"]
+          description: >
+            Present on the two real terminal paths (the common `"cancelled"` outcome, and an explicit `null` when a
+            concurrent reaper/another leg terminalized first — the ack reports the ACTUAL row, it does not fabricate
+            "cancelled"). OMITTED entirely on the plain `cancelling` / no-op branches, so treat absence as "unknown",
+            not as "no error".
 
     ResumeEvicted:
       type: object
@@ -2166,6 +2655,93 @@ components:
         error: { type: string }
         retainedFrom: { type: integer, description: Lowest event seq still retained; resume events from here. }
 
+    ImageIndexEntry:
+      # 新增(2026-07-25 回填批):sandbox 镜像目录条目。此前 `/v1/images` 整条路径不在本文件里。
+      # 🔴 为什么 21 个字段**全部** required:server 侧 `plugins/tidb-image-index.ts` 的 `mapRow()` 对每一行
+      #    恒全量赋值 —— nullable 的字段也至少给 `null`,**从不省略键**;`GET /v1/images` 的 handler 把 entries
+      #    原样 sendJson、零裁剪。所以「可空」在这里表达为 `type: [..., 'null']`,而不是从 required 里拿掉。
+      type: object
+      description: >
+        One sandbox-image catalog entry (`GET /v1/images` → `images[]`). Visibility is principal-scoped by the
+        server. READ-ONLY data source for a "pick a sandbox template" UI.
+      required:
+        [id, profile, bands, repo, tag, digest, toolchainVersions, capabilities, podContract, sizeBytes, status,
+         visibility, tenantId, manifestSha, recipeGitSha, generatorVersion, buildDate, supersedes, signed,
+         createdAt, updatedAt]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: 'deterministically derived from (repo, digest) — there is no explicit-id upsert path, so an id collision ⟺ a (repo, digest) collision.' }
+        profile: { type: string }
+        bands: { type: array, items: { type: string } }
+        repo: { type: string }
+        tag: { type: string }
+        digest:
+          type: string
+          description: >
+            The immutable digest a running sandbox is built from. 🔴 DISPLAY ONLY — a caller must NEVER send this
+            back to bind an image (bind by `profile`; the server re-resolves + re-admits under a trusted
+            principal, because trusting a caller-supplied digest would fail OPEN).
+        toolchainVersions: { type: object, additionalProperties: { type: string } }
+        capabilities:
+          type: object
+          additionalProperties: true
+          properties:
+            browser: { type: boolean }
+            db: { type: boolean }
+            nestedBuild: { type: boolean, description: 'can it build container images (back-compat boolean).' }
+            nestedBuildMode:
+              type: string
+              enum: [none, docker-cli-only, rootless-buildkit, privileged-dind]
+              description: 'HOW it nests (the posture). Refines `nestedBuild`; absent ⇒ fall back to the boolean.'
+        podContract:
+          type: object
+          additionalProperties: true
+          properties:
+            devShmMB: { type: integer }
+            minMemMB: { type: integer }
+            minCpu: { type: string }
+            readyTimeoutSec: { type: integer }
+            securityContext: { type: object, additionalProperties: true }
+        sizeBytes: { type: ['integer', 'null'] }
+        status: { type: string, enum: [building, published, deprecated, failed] }
+        visibility: { type: string, enum: [public, tenant] }
+        tenantId: { type: ['string', 'null'] }
+        manifestSha: { type: ['string', 'null'] }
+        recipeGitSha: { type: ['string', 'null'] }
+        generatorVersion: { type: ['string', 'null'] }
+        buildDate: { type: ['string', 'null'], description: 'ISO date-time string (the server projects Date/string uniformly to ISO).' }
+        supersedes: { type: ['string', 'null'], description: 'version-lineage anchor (optionally written by the server''s setStatus; semantics not further specified server-side — pass through).' }
+        signed: { type: boolean }
+        createdAt: { type: string, description: ISO date-time. }
+        updatedAt: { type: string, description: ISO date-time. }
+
+    ImageSelectResult:
+      # 新增(2026-07-25 回填批)。
+      type: object
+      description: >
+        `POST /v1/images/select` resolution result — a PREVIEW of "which digest/capabilities does this profile
+        resolve to" for the UI. 🔴 NOT a binding credential: to actually bind, send `sandboxImageProfile` on the
+        task request and let the server resolve under a trusted principal.
+      additionalProperties: true
+      properties:
+        profile: { type: string }
+        digest: { type: string }
+        repo: { type: string }
+        ref:
+          type: string
+          description: >
+            `${repo}@${digest}` — always present on a 200. This is the value a caller threads into the kata
+            adapter's per-sandbox image (the server handler says so itself), i.e. it is load-bearing, not decorative.
+        podContract: { type: object, additionalProperties: true }
+        capabilities:
+          type: object
+          additionalProperties: true
+          properties:
+            browser: { type: boolean }
+            db: { type: boolean }
+            nestedBuild: { type: boolean }
+        manifestSha: { type: string }
+
     QuotaError:
       type: object
       description: 429 per-principal cumulative-quota body (`quotaExceeded`).
@@ -2362,6 +2938,74 @@ components:
         memory:
           type: boolean
           description: Memory transparency endpoints (GET/DELETE /v1/memory) available. the pinned wire contract.
+        workflows: { type: boolean, description: "S8 self-orchestration workflow routes are mounted." }
+        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." }
+        rewindFilesTo: { type: boolean, description: "Restore to a SPECIFIC entry id (not just the latest snapshot)." }
+        manualCompact: { type: boolean, description: "`POST /v1/runs/:id/compact` (needs a run store)." }
+        sessions: { type: boolean, description: "Session read face (`GET /v1/sessions/:id`)." }
+        sessionList: { type: boolean, description: "`GET /v1/sessions` list/picker face." }
+        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." }
+        sessionPolicy: { type: boolean, description: "E6 per-session operator-tightened tool rules are durable." }
+        usage: { type: boolean, description: "Usage analytics face." }
+        policy: { type: boolean, description: "`GET /v1/policy` (autonomy/permission READ side)." }
+        permissionModeWrite: { type: boolean, description: "Runtime permission-mode WRITE. Advertised false by design — autonomy is CONFIG, not steer; the READ side is `policy`." }
+        modelSelection: { type: boolean, description: "`model` accepted per request." }
+        effortSelection: { type: boolean, description: "`reasoningEffort` accepted per request." }
+        compactionModel: { type: boolean, description: "A separate model may be pinned for compaction." }
+        appendSystemPrompt: { type: boolean, description: "Per-request system-prompt append is honoured." }
+        toolOutput: { type: boolean, description: "`tool_end` carries the model-facing output." }
+        messageIdentity: { type: boolean, description: "Content events carry `eventId` (+ `parentToolCallId` for sub-agents)." }
+        forwardSubagentEvents: { type: boolean, description: "Sub-agent events are forwarded onto the parent stream." }
+        subagentSteer: { type: boolean, description: "Mid-flight steer of a named sub-agent." }
+        subagentResume: { type: boolean, description: "Operator resume of a settled sub-agent." }
+        subagentOutput: { type: boolean, description: "Sub-agent output read face." }
+        subagentStream: { type: boolean, description: "Per-sub-agent event stream." }
+        taskHandles: { type: boolean, description: "Durable task handles (output/stop verbs by handle)." }
+        taskAgents: { type: boolean, description: "Per-task agent definitions are accepted." }
+        retainBackgroundProcesses: { type: boolean, description: "Background processes may be retained past the turn." }
+        interactiveTools: { type: boolean, description: "Interactive (prompting) tools are available." }
+        projectContext: { type: boolean, description: "Project-context injection is wired." }
+        mcp: { type: boolean, description: "MCP servers can be attached." }
+        mcpInjection: { type: boolean, description: "Per-request MCP injection is accepted." }
+        mcpElicitation: { type: boolean, description: "MCP elicitation round-trips are supported." }
+        askUserQuestion: { type: boolean, description: "AskUserQuestion gate is available (durable when approvals are)." }
+        toolApproval: { type: boolean, description: "Tool-approval gating is active." }
+        promptSuggestions: { type: boolean, description: "Follow-up prompt suggestions are generated." }
+        modelUsage: { type: boolean, description: "`GET /v1/runs/:id/model-usage` (needs a run store + usage plane)." }
+        scheduler: { type: boolean, description: "Assistant-scheduler face is mounted." }
+        sendUserFile: { type: boolean, description: "Outbound user-file delivery is wired." }
+        sendUserFileLedger: { type: boolean, description: "The send-file ledger (audit of deliveries) is available." }
+        excludeTools:
+          type: array
+          items: { type: string }
+          description: Tool names this worker will honour in a request's exclude list.
+        deferTools:
+          type: array
+          items: { type: string }
+          description: Tool names that can be DEFERRED (surfaced via search rather than mounted up front).
+        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.
+        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.
+          additionalProperties: true
+          properties:
+            permissions: { type: boolean }
+            permissionMode: { type: boolean }
+            model: { type: boolean }
+            outputStyle: { type: boolean }
+            env: { type: boolean }
+            hooks: { type: boolean }
         memoryWrite:
           type: boolean
           description: MF-30 — memory WRITE (append/edit/forget) available (deps.memory.append; server.ts:828).
@@ -2583,6 +3227,9 @@ components:
       properties:
         id: { type: string, description: 'Run id (= WorkflowRun.id).' }
         scope: { type: string, description: 'Tenant/group scope (= the creating principal).' }
+        name: { type: string, description: "The workflow script's declared `meta.name`." }
+        description: { type: string, description: "The workflow script's declared `meta.description` (one-liner)." }
+        currentPhase: { type: string, description: 'Title of the phase currently executing (absent once terminal).' }
         status: { $ref: '#/components/schemas/WorkflowRunStatus' }
         phaseCount: { type: integer, description: 'Phases recorded.' }
         agentCount: { type: integer, description: 'Agent-runs recorded.' }
@@ -2591,6 +3238,46 @@ components:
         endedAt: { type: integer, description: 'End epoch ms (absent while running).' }
         createdAt: { type: integer, description: 'Record-creation epoch ms (listByScope sort key).' }
 
+    WorkflowActivityBeat:
+      # 新增(2026-07-25 回填批)—— workflow 监视面 "Activity · last N of M tool calls" 的一拍。
+      type: object
+      description: >
+        One tool-call beat on a workflow agent's BOUNDED activity tail (source = core `ToolActivity`, projected
+        verbatim by the service detail handler).
+
+        🔴 `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.
+      additionalProperties: true
+      properties:
+        phase: { type: string, enum: [start, end] }
+        toolCallId: { type: string }
+        toolName: { type: string, description: 'the monitor renders `${toolName}(${arg})`.' }
+        arg: { type: string, description: 'SHORT, secret-scrubbed, ~80-code-point summary (set on `phase:"start"`). UNTRUSTED display text.' }
+        isError: { type: boolean, description: 'set on `phase:"end"` — whether the tool call errored.' }
+
+    WorkflowAgentRow:
+      # 新增(2026-07-25 回填批)—— 取代 `WorkflowRun.agents` 的 `items: {}`(零形状)。
+      type: object
+      description: >
+        One agent-run row in a workflow's detail. The shape is PERMISSIVE — read the known render fields below,
+        tolerate the rest as the projection evolves.
+      additionalProperties: true
+      properties:
+        label: { type: string, description: 'display label.' }
+        status: { type: string, description: 'lifecycle status (the input vocabulary the display derivation reads).' }
+        phase: { type: string, description: 'the phase title this agent ran under (groups it into a phase bucket).' }
+        model: { type: string, description: 'per-agent model DISPLAY label (e.g. "Opus 4.8 (1M context)"), not an id.' }
+        tokens: { type: integer }
+        turns: { type: integer }
+        toolCalls: { type: integer, description: 'total tool calls — the "M" in "last N of M tool calls".' }
+        activity:
+          type: array
+          description: 'the "Activity" tail — the LAST-N tool-call beats (bounded).'
+          items: { $ref: '#/components/schemas/WorkflowActivityBeat' }
+        prompt: { type: string, description: 'what the worker was ASKED (core-redacted + bounded). UNTRUSTED display text.' }
+        output: { type: string, description: 'the worker''s final OUTPUT (core-redacted + bounded). UNTRUSTED display text.' }
+
     WorkflowRun:
       type: object
       description: >
@@ -2601,9 +3288,17 @@ components:
       properties:
         id: { type: string }
         scope: { type: string }
+        name: { type: string, description: "The workflow script's declared `meta.name`." }
+        description: { type: string, description: "The workflow script's declared `meta.description` (one-liner)." }
         status: { $ref: '#/components/schemas/WorkflowRunStatus' }
         phases: { type: array, description: 'Phase records (permissive).', items: {} }
-        agents: { type: array, description: 'Agent-run records (permissive).', items: {} }
+        # `items: {}`(= 任意值,零形状)改为具名 $ref(2026-07-25 回填批):这是 workflow 监视面最吃重的数组,
+        # 空 schema 等于对非 TS 消费方完全没描述过它。`WorkflowAgentRow` 仍是 PERMISSIVE(additionalProperties)——
+        # 只钉住监视面真正 key 的那些字段,其余随投影演进。
+        agents:
+          type: array
+          description: 'Agent-run records (permissive — read the known render fields, tolerate the rest).'
+          items: { $ref: '#/components/schemas/WorkflowAgentRow' }
         stats:
           type: object
           description: 'Token stats — own at stats.tokens, nested at stats.nested.tokens (R-5 own/nested split).'
@@ -2873,6 +3568,18 @@ components:
             (they carry a RiskDescriptor); ABSENT for resource_limit/needs_review/plan_review — UI tolerates undefined.
         spentMicroUsd: { type: number, description: 'cumulative spend on the suspend chain (when a resource ledger is attached).' }
         deadline: { type: integer, description: 'awaiting-human SLA deadline (epoch ms).' }
+        contentKind:
+          type: string
+          description: >
+            Open enum (known value `content_ask`) distinguishing WHAT is being asked about, for gates whose payload
+            is content rather than a tool call. Treat unknown values as opaque.
+        sourceTaskId: { type: string, description: 'The task that produced this checkpoint (when distinct from sessionId).' }
+        principal: { type: string, description: 'The submitting principal, when the deployment records one.' }
+        createdAt: { type: integer, description: 'Creation time, epoch ms (NOTE — SessionRecord.createdAt is an ISO string).' }
+        preview:
+          description: >
+            Optional human-facing preview of what is being approved. Deliberately UNTYPED — the shape follows the
+            gate kind and is meant for display only; never branch on it.
 
     InboxRow:
       description: >
@@ -2883,6 +3590,20 @@ components:
         - type: object
           properties:
             objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
+            toolName:
+              type: ['string', 'null']
+              description: 'The gated tool, when the pause came from a tool call (null for non-tool gates).'
+            toolCallId: { type: string, description: 'The gated tool-call id.' }
+            boundCallId: { type: string, description: 'D-1 decision binding — echo it back on /decide.' }
+            boundInputHash:
+              type: string
+              description: >
+                D-1 decision binding — hash of the bound tool input. Echo on /decide so an approval cannot land on
+                a DIFFERENT call that was swapped in after the operator looked.
+            input:
+              description: >
+                REDACTED tool input for display. Untyped by design (per-tool shape) — and note the raw `toolInput`
+                is deliberately NOT on this row: the handler always strips it (along with `token`) before returning.
 
     InboxList:
       type: object
@@ -2894,27 +3615,79 @@ components:
           type: array
           items: { $ref: '#/components/schemas/InboxRow' }
 
-    AssistantTaskRow:
+    AssistantGate:
+      # 从 `AssistantTaskRow.gate` 的内联形提取为命名 schema(2026-07-25 回填批):内联的 schema 生成不出可复用
+      # 的具名类型,非 TS 消费方只能拿到匿名对象;且反射式 drift 门只按「命名 schema ↔ 同名 exported interface」
+      # 配对,内联形对它完全不可见 ⇒ 这里的字段漂移过去无人看守。
+      type: object
+      description: >
+        ASSISTANT-WIRE-CONTRACT §3 — the active gate inlined on an `AssistantTask` row.
+
+        🔴 LAYER NOTE (this schema and the SDK's `AssistantGate` type describe DIFFERENT layers, deliberately):
+        this file documents the WIRE, where `severity`/`spentMicroUsd`/`deadline` are sent as EXPLICIT `null`
+        when absent (server `http/server.ts` sends `severity: s.severity ?? null` — a present key holding null,
+        NOT an omitted key). The SDK's TS type declares them `?: number` because the SDK FOLDS null → omitted
+        key at its resource boundary (`resources/assistant.ts` `RawAssistantGate` + `normalizeGate()`), so a
+        TS consumer never observes the null. Both are correct for their layer — do NOT "fix" either to match
+        the other. A non-TS client generated from this file MUST tolerate the nulls itself.
+      required: [kind]
+      additionalProperties: true
+      properties:
+        kind:
+          type: string
+          description: >
+            Same open set as `CheckpointSummary.gateKind` — the FLATTENED projection of core's
+            `CheckpointGate`. (Nested-as-`gate` ⇒ the discriminator is named `kind`; flattened onto a row ⇒
+            `gateKind`. Same value domain, different position — a naming CONVENTION, not an inconsistency.)
+          enum: [human, irreversible_ask, resource_limit, needs_review, plan_review, task_done]
+          x-open-enum: true   # a future core kind must render generically, never crash — do not close this union
+        severity:
+          type: ['integer', 'null']
+          enum: [1, 2, 3, 4, 5, null]
+          description: >
+            Risk tier. `null` (or, post-SDK-normalization, absent) = this gate kind carries no RiskDescriptor
+            (resource_limit / needs_review / plan_review) — treat as "unknown", never as 0.
+        spentMicroUsd:
+          type: ['number', 'null']
+          description: >
+            Cumulative spend ALREADY INCURRED on the suspend chain (micro-USD). ⚠️ NOT the same concept as
+            `costMicroUsd` ("what this thing cost") — never treat the two as aliases.
+        deadline:
+          type: ['integer', 'null']
+          description: 'awaiting-human SLA deadline — epoch ms (the checkpoint family''s time convention; run-ledger rows use ISO strings instead).'
+
+    AssistantTask:
+      # 重命名自 `AssistantTaskRow`(2026-07-25):SDK 的 exported interface 叫 `AssistantTask`,而权威已在
+      # types.ts(见本文件顶注),spec 侧沿用另一个名字会让反射式 drift 门永远配不上对 ⇒ 以 TS 名为准对齐。
       type: object
       description: >
         ASSISTANT-WIRE-CONTRACT §3 — a scheduler-overview row = run-store `listRuns(owner)` joined with the core
         scheduler seam. ⚠️ `createdAt`/`updatedAt` are ISO date-time strings (unlike inbox/§1 epoch-ms).
-      required: [taskId, sessionId, status, needsAttention, createdAt, updatedAt]
+      required: [taskId, sessionId, status, needsAttention, gate, createdAt, updatedAt]
       additionalProperties: true
       properties:
         taskId: { type: string }
         sessionId: { type: string }
-        status: { type: string, enum: [running, suspended] }
-        needsAttention: { type: boolean, description: '= suspended on a HITL gate.' }
+        status:
+          type: string
+          # 🔴 `needs_review` 是 2026-07-25 补的:server 的行过滤器逐字是
+          #   `.filter(r => r.status === "running" || r.status === "suspended" || r.status === "needs_review")`
+          #   (`http/server.ts:4677`,已亲读取证)——本枚举此前只有前两个,是真陈旧,照它生成的客户端会把一个
+          #   合法的一等 triage 态判成非法值。字段级 drift 门只比字段名、比不到枚举值,所以它没抓到这条。
+          enum: [running, suspended, needs_review]
+          description: >
+            `running` — live. `suspended` — durably parked on a HITL gate (resolve via §4b resume / §4a decide).
+            `needs_review` — a FIRST-CLASS triage state: a plan_review / dry-run review park (NOT `suspended`);
+            carries `needsAttention:true` + `gate.kind` = `plan_review`/`needs_review` (severity absent) and
+            sorts FIRST. 🔴 Resolve it via §4c `POST /v1/assistant/tasks/:id/plan_review`, NOT §4b resume.
+            ⚠️ Distinct axis from `RunStatus.needs_review` (that one is a dry-run TERMINAL run status; this is a
+            park state on the overview row) — same name, different axis.
+        needsAttention: { type: boolean, description: '= parked on a HITL gate (`suspended` OR `needs_review`); server derives it as `!!gate`.' }
         gate:
-          type: ['object', 'null']
-          description: 'the active gate, or null. severity/spentMicroUsd/deadline may themselves be null on the wire.'
-          additionalProperties: true
-          properties:
-            kind: { type: string, description: 'same open set as gateKind.' }
-            severity: { type: ['integer', 'null'], enum: [1, 2, 3, 4, 5, null] }
-            spentMicroUsd: { type: ['number', 'null'] }
-            deadline: { type: ['integer', 'null'], description: epoch ms. }
+          description: 'the active gate, or null when the row is not parked.'
+          oneOf:
+            - $ref: '#/components/schemas/AssistantGate'
+            - type: 'null'
         createdAt: { type: string, description: ISO date-time. }
         updatedAt: { type: string, description: ISO date-time. }
 
@@ -2928,7 +3701,39 @@ components:
       properties:
         tasks:
           type: array
-          items: { $ref: '#/components/schemas/AssistantTaskRow' }
+          items: { $ref: '#/components/schemas/AssistantTask' }
+
+    AssistantTaskStatus:
+      # 新增(2026-07-25 回填批):§4b resume / §4c plan_review / §4d preempt 三条决策端点此前在本文件里都只声明
+      # 了 `{status}` 一个字段——与 SDK 三批核查前的旧类型同样陈旧。下面的形按 server 源码逐字取证:
+      #   • resume / plan_review 200(共用 `driveResumeIntoRunLog`,`http/server.ts:7688-7696`):
+      #       `{ taskId, sessionId, status, errorCode?, errorMessage?, retriable? }`(后三个条件 spread ⇒ 缺则省键)
+      #   • preempt 202(`http/server.ts:4726/4734/4737` 三个出口):`{ taskId, status, note }`
+      #     ⚠️ `status` 在 202 上**并非恒为 `"preempting"`**:两个 no-op 出口分别回 `run.status` 与
+      #        `now?.status ?? "failed"` —— 所以这里不能把它写成 const。
+      type: object
+      description: >
+        The response of the §4b/§4c/§4d decision endpoints (resume / plan_review / preempt). Union of the two
+        real body shapes — `sessionId` appears only on resume/plan_review, `note` only on preempt; everything
+        else is shared (absent keys are OMITTED, never null).
+      required: [taskId, status]
+      additionalProperties: true
+      properties:
+        taskId: { type: string, description: 'always present (all three response bodies carry it).' }
+        status:
+          type: string
+          description: >
+            OPEN string — do NOT narrow. Observed values include `completed` / `failed` / `suspended` /
+            `needs_review` / `preempting`, plus whatever run status a no-op preempt echoes back.
+        sessionId: { type: string, description: 'resume/plan_review ONLY — the session the decided checkpoint belongs to. Absent from the preempt body.' }
+        errorCode: { type: string, description: 'present on a failed resume/plan_review (e.g. `checkpoint.reopen_failed`).' }
+        errorMessage: { type: string, description: 'human-readable failure detail (server-side secret-redacted).' }
+        retriable:
+          type: boolean
+          description: >
+            `true` = the park is STILL PENDING (the server re-parked it), so re-fetching and deciding again is
+            meaningful. Emitted only when the store CONFIRMED the reopen — never inferred.
+        note: { type: string, description: 'preempt ONLY — human-readable explanation (incl. the honest "preempt is a no-op" cases). Absent from the resume/plan_review body.' }
 
     PlanReviewRequest:
       type: object
@@ -2960,6 +3765,10 @@ components:
           properties:
             provider: { type: string }
             modelId: { type: string }
+        window:
+          $ref: '#/components/schemas/SessionWindow'
+        promptEpoch:
+          $ref: '#/components/schemas/PromptEpoch'
         messages:
           type: array
           items: {}
@@ -2980,6 +3789,62 @@ components:
         runCount: { type: integer }
         objectivePreview: { type: ['string', 'null'] }
         lastStatus: { type: string }
+        lastRunId:
+          type: ['string', 'null']
+          description: The most recent run's id (null when the session has no run yet) — lets a picker deep-link.
+        title:
+          type: ['string', 'null']
+          description: >
+            Auto-generated session summary title (service-side `session-titler`: one cheap model call kicked off in
+            the background after the first submit, idempotent via an IS-NULL gate). Genuinely `null` until it lands,
+            so render a fallback rather than waiting on it.
+
+    SessionWindow:
+      type: object
+      description: >
+        Pagination window echoed by `GET /v1/sessions/:id` when the caller asked for a message slice.
+        OPEN object — additional keys may appear.
+      required: [offset, total]
+      additionalProperties: true
+      properties:
+        offset: { type: integer, description: Index of the first returned message within the full context. }
+        total: { type: integer, description: Total messages available (so a client can page). }
+
+    SessionMessageEnvelope:
+      # 新增(2026-07-25 回填批):`GET /v1/sessions/{id}?message=<index>` 的单条消息展开支路。本文件此前连
+      # `/v1/sessions/{id}` 的 query 参数都一个没声明,所以这条支路对生成式消费方等于不存在。
+      type: object
+      description: >
+        The single-message expand leg — `GET /v1/sessions/{sessionId}?message=<index>` returns THIS instead of a
+        `SessionRecord`. An out-of-range index → 404 (the error body carries `total`).
+      required: [sessionId, index, message]
+      additionalProperties: true
+      properties:
+        sessionId: { type: string }
+        floorEntryId:
+          type: ['string', 'null']
+          description: 'the compaction floor this index is relative to, when one applies.'
+        index: { type: integer, description: 'the requested message index (echoed).' }
+        message: { description: 'OPEN — the message payload as stored; shape belongs to the transcript format, not to this envelope.' }
+
+    PromptEpoch:
+      type: object
+      description: >
+        A session's prompt-epoch pin (server >=1.220, additive on `GET /v1/sessions/:id`). Identifies WHICH
+        assembled system-prompt artifact this session is pinned to, so a transcript stays reproducible across
+        prompt-pack releases. IDs/digests only — never prompt text. OPEN object.
+      required: [epoch, artifactDigest, packId, assemblyApi, activatedBy]
+      additionalProperties: true
+      properties:
+        epoch: { type: integer, description: Monotonic epoch counter within the session. }
+        artifactDigest: { type: string, description: 'Content digest of the assembled artifact (`sha256:<64 hex>`).' }
+        packId: { type: string, description: 'Prompt-pack identity, e.g. `sema-default@1`.' }
+        assemblyApi: { type: integer, description: Assembly-contract version (currently always 1). }
+        activatedBy:
+          type: string
+          description: >
+            Open enum — known values `session_start` | `compaction` | `legacy_migration`; treat unknown values as
+            opaque rather than failing closed.
 
     SessionListPage:
       type: object
@@ -3231,6 +4096,16 @@ components:
         - $ref: '#/components/schemas/Event_task_progress'
         - $ref: '#/components/schemas/Event_workspace_changed'
         - $ref: '#/components/schemas/Event_suspended'
+        # 🔴 以下 6 臂是 2026-07-25 补的:`events.ts` 的 `AgentEvent` 联合有 21 个 `type` 字面量,本文件此前只声明
+        #   15 个 —— 照本文件生成客户端的消费方会把 6 种合法帧当成非法值(事件面是最吃重的 wire 面,这个缺口比
+        #   字段级 drift 更伤)。字段级 drift 门只按「命名 schema ↔ 同名 exported interface」配对,联合缺臂对它
+        #   不可见,故这条只能靠人工核对 —— 补齐时是拿 `events.ts` 的 type 字面量集与本联合做机器 diff 得出的。
+        - $ref: '#/components/schemas/Event_file_link'
+        - $ref: '#/components/schemas/Event_prompt_assembled'
+        - $ref: '#/components/schemas/Event_model_usage'
+        - $ref: '#/components/schemas/Event_task_notification'
+        - $ref: '#/components/schemas/Event_diagnostics'
+        - $ref: '#/components/schemas/Event_steering_injected'
         - $ref: '#/components/schemas/Event_done'
         - $ref: '#/components/schemas/Event_failed'
       discriminator:
@@ -3249,6 +4124,12 @@ components:
           task_progress: '#/components/schemas/Event_task_progress'
           workspace_changed: '#/components/schemas/Event_workspace_changed'
           suspended: '#/components/schemas/Event_suspended'
+          file_link: '#/components/schemas/Event_file_link'
+          prompt_assembled: '#/components/schemas/Event_prompt_assembled'
+          model_usage: '#/components/schemas/Event_model_usage'
+          task_notification: '#/components/schemas/Event_task_notification'
+          diagnostics: '#/components/schemas/Event_diagnostics'
+          steering_injected: '#/components/schemas/Event_steering_injected'
           done: '#/components/schemas/Event_done'
           failed: '#/components/schemas/Event_failed'
 
@@ -3400,6 +4281,60 @@ components:
       properties:
         type: { const: workspace_changed }
         cwd: { type: string }
+    CheckpointGate:
+      # 从 `Event_suspended.gate` 的内联 oneOf 提取为命名 schema(2026-07-25 回填批)。两个理由:
+      #  ① 内联形生成不出可复用具名类型;② 反射式 drift 门只按「命名 schema ↔ 同名 exported interface」配对,
+      #     内联形对它不可见 —— 这块 wire 契约过去没有任何机器看守。
+      # 🔴 为什么同时写顶层 `properties` 和 `oneOf`:门解析有效属性集时只展开 `$ref`/`allOf`,**不认 `oneOf`**
+      #    (`test/spec-field-drift-gate.test.ts` 的 `effectiveSpecProps`)。若只留 oneOf,门会认为本 schema
+      #    「没有属性」从而当作整个 schema 缺席 ⇒ 回填等于没做。两者是合取关系(JSON Schema 语义):顶层
+      #    properties 给出字段全集(=门的比对面),oneOf 继续施加逐 kind 的形状校验,互不削弱。
+      # nullability 现在挂在**引用点**(`gate: oneOf[$ref, null]`),不再是本 schema 的一个 union 臂 ——
+      # 命名类型自身是对象形,更贴 TS 的 `gate?: CheckpointGate | null`。
+      type: object
+      description: >
+        CheckpointGate — OPEN DISCRIMINATED SET (design/80 D-0), mirrors core src/core/checkpoint-store.ts.
+        5 known kinds; consumers MUST branch on `kind` and render an UNKNOWN kind generically (core can mint a
+        kind this contract predates — a core→wire contract test fails CI, not prod). Tool args / question text
+        are NOT here — join the task's trace tool-call block via approvals' toolCallId.
+      required: [kind]
+      properties:
+        kind:
+          type: string
+          description: >
+            `human` — plain HITL approval (budget-auto-approvable). `irreversible_ask` — design/37
+            irreversibility / design/70 egress tighten; NOT budgetable (load-bearing safety gate).
+            `resource_limit` — design/74 cost/token/time slice boundary; resolve `{decision:"continue"}`.
+            `needs_review` — design/76 dry-run/shadow → durable `needs_review` TERMINAL (post-prediction
+            review, disjoint from the approval family). `task_done` — design/38 Path A background sub-task
+            handle (door B never sees it).
+          enum: [human, irreversible_ask, resource_limit, needs_review, task_done]
+          x-open-enum: true   # do not close this union — an unknown future kind is VALID on the wire
+        reason: { type: string, description: 'present on human / irreversible_ask / resource_limit / needs_review (not task_done).' }
+        toolName: { type: string, description: 'present on human / irreversible_ask.' }
+      oneOf:
+        - type: object       # plain human approval (budget-auto-approvable)
+          required: [kind, reason, toolName]
+          properties: { kind: { const: human } }
+        - type: object       # design/37 irreversibility / design/70 egress safety-tighten — NOT budgetable (load-bearing safety gate)
+          required: [kind, reason, toolName]
+          properties: { kind: { const: irreversible_ask } }
+        - type: object       # design/74 resource (cost/token/time) slice boundary — resolve { decision: "continue" }
+          required: [kind, reason]
+          properties: { kind: { const: resource_limit } }
+        - type: object       # design/76 dry-run/shadow → durable needs_review TERMINAL (POST-prediction review, disjoint from approval family)
+          required: [kind, reason]
+          properties: { kind: { const: needs_review } }
+        - type: object       # design/38 Path A background sub-task handle (door B never sees it)
+          required: [kind]
+          properties: { kind: { const: task_done } }
+        - type: object       # OPEN SET — unknown future kind (e.g. design/80 D-B plan_review); render generically, never crash
+          required: [kind]
+          # 🔴 the pinned wire contract: exclude the 5 KNOWN kinds so a known kind matches ONLY its const member above
+          #   (not also this fallback) → keeps `oneOf` unambiguous AND preserves each kind's shape validation.
+          #   This fallback matches ONLY a future kind this contract predates. Add new known kinds to the enum.
+          properties: { kind: { type: string, not: { enum: [human, irreversible_ask, resource_limit, needs_review, task_done] } } }
+
     Event_suspended:
       type: object
       description: HITL — the run paused on an F4 gate or AskUserQuestion. Resolve via approvals.decide, then resume.
@@ -3407,34 +4342,225 @@ components:
       properties:
         type: { const: suspended }
         gate:
-          description: >
-            CheckpointGate — OPEN DISCRIMINATED SET (design/80 D-0), mirrors core src/core/checkpoint-store.ts.
-            5 known kinds below; consumers MUST branch on `kind` and render an UNKNOWN kind generically (core
-            can mint a kind this contract predates — a core→wire contract test fails CI, not prod). Tool
-            args/question text are NOT here — join the task's trace tool-call block via approvals' toolCallId.
+          description: 'the gate the run paused on, or null.'
           oneOf:
-            - type: object       # plain human approval (budget-auto-approvable)
-              required: [kind, reason, toolName]
-              properties: { kind: { const: human }, reason: { type: string }, toolName: { type: string } }
-            - type: object       # design/37 irreversibility / design/70 egress safety-tighten — NOT budgetable (load-bearing safety gate)
-              required: [kind, reason, toolName]
-              properties: { kind: { const: irreversible_ask }, reason: { type: string }, toolName: { type: string } }
-            - type: object       # design/74 resource (cost/token/time) slice boundary — resolve { decision: "continue" }
-              required: [kind, reason]
-              properties: { kind: { const: resource_limit }, reason: { type: string } }
-            - type: object       # design/76 dry-run/shadow → durable needs_review TERMINAL (POST-prediction review, disjoint from approval family)
-              required: [kind, reason]
-              properties: { kind: { const: needs_review }, reason: { type: string } }
-            - type: object       # design/38 Path A background sub-task handle (door B never sees it)
-              required: [kind]
-              properties: { kind: { const: task_done } }
-            - type: object       # OPEN SET — unknown future kind (e.g. design/80 D-B plan_review); render generically, never crash
-              required: [kind]
-              # 🔴 the pinned wire contract: exclude the 5 KNOWN kinds so a known kind matches ONLY its const member above
-              #   (not also this fallback) → keeps `oneOf` unambiguous AND preserves each kind's shape validation.
-              #   This fallback matches ONLY a future kind this contract predates. Add new known kinds to the enum.
-              properties: { kind: { type: string, not: { enum: [human, irreversible_ask, resource_limit, needs_review, task_done] } } }
+            - $ref: '#/components/schemas/CheckpointGate'
             - type: 'null'
+    ModelUsageDelta:
+      # 新增(2026-07-25 回填批)。SDK 的 facade 审计把这个形状命名了一次(此前是在两个使用点各写一遍的匿名内联形:
+      # `AgentEvent` 的 `model_usage` 臂 与 `done.result.stats.modelUsage` 的值类型,同源同形)。
+      type: object
+      description: >
+        Per-model token/cost delta, keyed by model name in a `Record<string, ModelUsageDelta>`. Fields mirror
+        `turn_end.usage`; ALL optional (open contract — tolerates future core fields).
+      additionalProperties: true
+      properties:
+        inputTokens: { type: integer }
+        outputTokens: { type: integer }
+        cacheReadTokens: { type: integer }
+        cacheWriteTokens: { type: integer }
+        costMicroUsd:
+          type: number
+          description: >
+            What THIS model's slice cost (micro-USD). ⚠️ Distinct concept from `spentMicroUsd`
+            ("cumulative already-incurred spend") — never treat the two as aliases.
+
+    PromptManifest:
+      # 新增(2026-07-25 回填批):server ≥1.219 的 prompt-assembly manifest。此前本文件完全没有它(全文 0 次提及),
+      # 尽管它同时是 `AgentEvent.prompt_assembled` 臂和 trace 流 `prompt-assembled` 帧的载荷。
+      type: object
+      description: >
+        The prompt-assembly manifest (core's `prompt.assembled` trace contract verbatim). Carries ONLY
+        ids/digests/counts — NEVER prompt bodies (privacy boundary). 🔴 Hashes are PROCESS-SALTED: they are NOT
+        comparable across worker restarts, so a UI must never diff them cross-process. `constitution`/`blocks`/
+        `totalChars` are the v1 face; `sections`/`tools` are the v2 ADDITIVE face (absent on a v1-only engine).
+        ⚠️ One task can carry MULTIPLE manifests — a cascade/verify run re-prepares under one taskId and every
+        rung's manifest is persisted in emission order.
+      required: [constitution, blocks, totalChars]
+      additionalProperties: true
+      properties:
+        constitution:
+          type: string
+          description: 'who owned the constitution layer — `core` is the steady state; anything else is worth eyes.'
+          enum: [core, replaced, provider-assembled, legacy]
+          x-open-enum: true
+        blocks:
+          type: array
+          items:
+            type: object
+            required: [id, chars, hash]
+            additionalProperties: true
+            properties:
+              id: { type: string }
+              chars: { type: integer }
+              hash: { type: string, description: 'process-salted digest — never compare across restarts.' }
+        sections:
+          type: array
+          description: 'v2 additive face — absent on a v1-only engine.'
+          items:
+            type: object
+            required: [id, slot, carrier, cadence, cacheClass, chars, hash]
+            additionalProperties: true
+            properties:
+              id: { type: string }
+              slot: { type: string }
+              carrier: { type: string }
+              cadence: { type: string }
+              cacheClass: { type: string }
+              chars: { type: integer }
+              hash: { type: string }
+        tools:
+          type: array
+          description: 'v2 additive face — the tool contract summary.'
+          items:
+            type: object
+            required: [wireName, aliases, contractId, implementationRevision, cardId, shapeDigest, wireSchemaDigest]
+            additionalProperties: true
+            properties:
+              wireName: { type: string }
+              aliases: { type: array, items: { type: string } }
+              contractId: { type: string }
+              implementationRevision: { type: string }
+              cardId: { type: string }
+              shapeDigest: { type: string }
+              wireSchemaDigest: { type: string }
+        totalChars: { type: integer }
+
+    Event_file_link:
+      type: object
+      description: >
+        The engine SENT THE USER A FILE via a presigned link (probe `capabilities().sendUserFile` before
+        rendering affordances). 🔴 `url` EXPIRES after `ttlSec` seconds — render a fetch-soon affordance, never
+        persist the URL as durable.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, url, filename, size, ttlSec, status]
+      properties:
+        type: { const: file_link }
+        url: { type: string, description: 'presigned download URL — EXPIRING, do not persist.' }
+        filename: { type: string }
+        size: { type: integer }
+        ttlSec: { type: integer }
+        status: { type: string, enum: [normal, proactive], description: '`normal` = a turn deliverable; `proactive` = a mid-run push.' }
+        caption: { type: string }
+        display: { type: string, enum: [render, attach], description: 'absent = the consumer''s default.' }
+
+    Event_prompt_assembled:
+      type: object
+      description: >
+        DURABLE only (server ≥1.219) — the prepare's prompt-assembly manifest, FLATTENED onto the frame (the
+        manifest's own keys sit at the top level next to `type`, they are NOT nested under a `manifest` key).
+        Lands AHEAD of the first event of the turn it prepared. ⚠️ MULTIPLE per task on cascade/verify runs.
+      allOf:
+        - $ref: '#/components/schemas/PromptManifest'
+      required: [type]
+      properties:
+        type: { const: prompt_assembled }
+
+    Event_model_usage:
+      type: object
+      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).
+      required: [type, usage]
+      properties:
+        type: { const: model_usage }
+        usage:
+          type: object
+          additionalProperties: { $ref: '#/components/schemas/ModelUsageDelta' }
+
+    Event_task_notification:
+      type: object
+      description: >
+        A BACKGROUND task (bg agent / bash / monitor / workflow / external) settled or emitted a batch while THIS
+        run was live. The engine ALREADY injected the `<task-notification>` into the model in-process — this frame
+        is the UI/display projection only. `partial:true` = a KILLED child's salvaged remnant (render as
+        incomplete). `seq` = stop-cycle/batch counter (dedup key together with task_id + status).
+        🔴 summary/result/lines/diagnostics are UNTRUSTED redacted free text — render, never re-feed to a model.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, task_id, task_type, status, summary]
+      additionalProperties: true
+      properties:
+        type: { const: task_notification }
+        task_id: { type: string }
+        task_type: { type: string }
+        status: { type: string }
+        summary: { type: string, description: 'UNTRUSTED display text.' }
+        sessionId: { type: string }
+        toolUseId: { type: string }
+        seq: { type: integer }
+        source: { type: string }
+        lines: { type: array, items: { type: string } }
+        stoppedBy: { type: string }
+        exitCode: { type: integer }
+        partial: { type: boolean, description: '`true` = a KILLED child''s salvaged remnant — render as incomplete.' }
+        diagnostics: { type: string }
+        recentSteps:
+          type: array
+          items:
+            type: object
+            required: [tool, target, outcome]
+            additionalProperties: true
+            properties: { tool: { type: string }, target: { type: string }, outcome: { type: string } }
+        editedFiles:
+          type: array
+          items:
+            type: object
+            required: [path, edits]
+            additionalProperties: true
+            properties: { path: { type: string }, edits: { type: integer } }
+        resumable: { type: boolean }
+        result: { type: string, description: 'UNTRUSTED display text.' }
+        output_file: { type: string }
+        usage: { description: 'open shape — usage rollup of the background task.' }
+
+    Event_diagnostics:
+      type: object
+      description: >
+        NEW LSP diagnostics drained at a turn boundary (server-side redacted). The model already got the context
+        message in-process; this frame is the RENDER source.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, files]
+      additionalProperties: true
+      properties:
+        type: { const: diagnostics }
+        files:
+          type: array
+          items:
+            type: object
+            required: [uri, diagnostics]
+            additionalProperties: true
+            properties:
+              uri: { type: string }
+              diagnostics:
+                type: array
+                items:
+                  type: object
+                  required: [message]
+                  additionalProperties: true
+                  properties:
+                    message: { type: string }
+                    severity: { type: integer }
+                    range: { description: 'open shape (LSP Range).' }
+                    code: { type: ['string', 'integer'] }
+                    source: { type: string }
+        isNew: { type: boolean }
+
+    Event_steering_injected:
+      type: object
+      description: >
+        A mid-run system-reminder core injected into the model's context (todo / file-change / date-roll /
+        skills-delta / …). The model already got the injected text in-process; this frame is the RENDER source
+        (`source` picks the icon/label, `preview` is the truncated display text — server-side redacted).
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, source, preview]
+      additionalProperties: true
+      properties:
+        type: { const: steering_injected }
+        source:
+          type: string
+          description: 'OPEN string — deliberately NOT the closed core enum, so a future core source value cannot runtime-crash a strict switch.'
+        preview: { type: string, description: 'truncated, redacted display text — UNTRUSTED.' }
+
     Event_done:
       type: object
       description: Carries the full TaskResult (output string at .result, stats at .stats) — service Drift 4.