@sema-agent/sdk 4.1.0 → 4.3.0

package/openapi.yaml

@@ -494,12 +494,20 @@ paths:
                     turn (FIFO), spread across turns. FORWARD-DRAFT: core's steer is harness-level today, not
                     per-call; the per-call mapping is pending D-A core.
       responses:
-        '200': { description: Steer accepted and applied. }
+        '200':
+          description: Steer accepted and APPLIED to the live run on this replica (`delivery:"applied"`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SteerReceipt' }
         '202':
           description: >-
-            Steer accepted and QUEUED. Two shapes share this code: a live run queues to the next turn-boundary
-            drain; a durable-`suspended` run parks on its pending checkpoint
-            (`{status:"suspended", delivery:"queued"}`) and drains on resume.
+            Steer accepted and PARKED. Two shapes share this code — branch on `delivery`, not the status:
+            a durable-`suspended` run parks on its pending checkpoint (`delivery:"queued"`) and drains on resume;
+            an ALREADY-ENDED run gets a freshly-minted `task_done` checkpoint (`delivery:"parked_for_wake"`) and
+            the message is delivered only by POST /v1/sessions/{sessionId}/wake.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SteerReceipt' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -1278,9 +1286,10 @@ paths:
           description: Delivered onto the live stream.
           content:
             application/json:
+              # 封闭(census 批2 第三段,2026-07-30):live 臂铸造点 `routes/notify-wake.ts:98` 是两键字面量。
+              # 4.3.0:形提成具名 `SessionNotifyResult` 的 live 臂(SDK 同批给了判别联合返回型)。
               schema:
                 type: object
-                # 封闭(census 批2 第三段,2026-07-30):live 臂铸造点 `routes/notify-wake.ts:86` 是两键字面量。
                 additionalProperties: false
                 required: [sessionId, delivery]
                 properties:
@@ -1290,9 +1299,9 @@ 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 无条件。
               schema:
                 type: object
-                # 封闭 + note 补 required:parked 臂铸造点 `routes/notify-wake.ts:104` 是三键字面量,note 无条件。
                 additionalProperties: false
                 required: [sessionId, delivery, note]
                 properties:
@@ -1387,26 +1396,11 @@ paths:
           description: The snapshot listing.
           content:
             application/json:
-              schema:
-                type: object
-                # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:621-626`(信封)与
-                # `:616`(行)。条件键=信封 `latest`(零快照即省略)、行 `bytes`(blobSizes 面缺席=诚实省略)。
-                additionalProperties: false
-                required: [sessionId, snapshots, total]
-                properties:
-                  sessionId: { type: string }
-                  snapshots:
-                    type: array
-                    items:
-                      type: object
-                      additionalProperties: false
-                      required: [key, files]
-                      properties:
-                        key: { type: string }
-                        files: { type: integer }
-                        bytes: { type: integer }
-                  latest: { type: string }
-                  total: { type: integer }
+              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:624-629`(信封)与
+              # `:620`(行)。条件键=信封 `latest`(零快照即省略)、行 `bytes`(blobSizes 面缺席=诚实省略)。
+              # 4.3.0:形提成具名 `WorkspaceSnapshotPage`(SDK 同批把返回位的内联字面量也提成了 exported type,
+              # 让 spec-resource-schema-gate 罩得住 —— CAPS-OPS-8)。
+              schema: { $ref: '#/components/schemas/WorkspaceSnapshotPage' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -1447,27 +1441,10 @@ paths:
           description: One page of the tree.
           content:
             application/json:
-              schema:
-                type: object
-                # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:648-654`(信封)与
-                # `:651`(行)。条件键=信封 `nextOffset`(尾页省略)、行 `size`(blobSizes 面缺席省略)。
-                additionalProperties: false
-                required: [sessionId, key, entries, total]
-                properties:
-                  sessionId: { type: string }
-                  key: { type: string }
-                  entries:
-                    type: array
-                    items:
-                      type: object
-                      additionalProperties: false
-                      required: [path, hash]
-                      properties:
-                        path: { type: string }
-                        hash: { type: string }
-                        size: { type: integer }
-                  total: { type: integer }
-                  nextOffset: { type: integer }
+              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:651-657`(信封)与
+              # `:654`(行)。条件键=信封 `nextOffset`(尾页省略)、行 `size`(blobSizes 面缺席省略)。
+              # 4.3.0:形提成具名 `WorkspaceTreePage`(理由同 list 腿 —— CAPS-OPS-8)。
+              schema: { $ref: '#/components/schemas/WorkspaceTreePage' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -1688,7 +1665,11 @@ paths:
         2c session-sync PULL — the THIN snapshot: entry IDS (oldest-first, NOT payloads — those stream via
         `/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 a non-uuidv7 id; 501 without a durable session store.
+        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
+        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.
       responses:
         '200':
           description: The manifest, wrapped as `{ manifest }`.
@@ -1731,7 +1712,7 @@ paths:
         at 200 BEFORE the first line, so a mid-stream failure ends the body WITHOUT the trailer — the trailer's
         ABSENCE (or a count mismatch) is the SOLE truncation signal (NO 5xx mid-stream). The SDK reader throws
         `SyncTruncatedError` on a missing trailer / count mismatch. Owner-scoped (404); 400 on a bad afterSeq /
-        non-uuidv7 id; 501 without a durable entry-streaming store.
+        non-uuid-SHAPED id (ANY uuid version passes — see the manifest leg); 501 without a durable entry-streaming store.
       responses:
         '200':
           description: The NDJSON entry stream (begin / entry× N / end-trailer).
@@ -1836,7 +1817,8 @@ paths:
       description: >
         2c session-sync PLAN — classify the §7 relation between the LOCAL peer's `entryIds` (oldest-first, the SOURCE)
         and the cloud's current log (the DST), WITHOUT writing. Returns the `SyncRelation` (`fresh` for a fresh cloud
-        session). own-or-FRESH gate; 400 on a non-string-array body / non-uuidv7 id. Unlike import, plan NEVER 409s —
+        session). own-or-FRESH gate; 400 on a non-string-array body / a non-uuid-SHAPED id (ANY uuid version passes —
+        see the manifest leg). Unlike import, plan NEVER 409s —
         a fork/stale is REPORTED in the relation, not raised.
       requestBody:
         required: true
@@ -1893,6 +1875,20 @@ paths:
                 policy: { type: array, items: { $ref: '#/components/schemas/SessionRulesRecord' } }
                 anchors: { type: array, items: { $ref: '#/components/schemas/SyncAnchor' } }
                 resolution: { type: string, enum: [overwrite-dst], description: Override a fork/stale loss-of-history conflict. }
+                logDigest:
+                  type: string
+                  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`
+                    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"
+                    is structurally possible and would be reported as already-synced. Supply this and the server
+                    recomputes the digest over its own log: equal ⇒ `basis:"entry-ids+digest"` + `payloadVerified:true`;
+                    different or not comparable ⇒ it does NOT short-circuit and stages a full sync (safe direction).
+                    A malformed value is NOT rejected — it is treated as absent (a digest mismatch must never become
+                    an error, a 409, or a refusal to sync).
       responses:
         '200':
           description: Staged (or `identical` no-op).
@@ -2070,7 +2066,17 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { $ref: '#/components/responses/NotFound' }
+        '404':
+          description: >
+            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
+            NotFoundError while the rest of the family maps to ConflictError. Client action: refetch the inbox —
+            do not retry this decide.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409':
           description: >
             Either a session-CAS conflict (`ErrorResponse.activeTaskId`), OR a design/80 D-1
@@ -2078,6 +2084,20 @@ paths:
             NOT match the current pending action (TOCTOU/swap). The SDK splits these by `errorCode` into
             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
+            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` /
+            `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
+            information instead of collapsing anonymously). The one non-409 member is `checkpoint.not_found`,
+            which the same mint point sends as a 404 (see below).
             THIRD member (moved here from a documented-but-nonexistent 410, 2026-07-31): `approval_stale`
             (`errorCode`; `terminal:"resolved"` when attributable, else the key is absent) — the checkpoint is
             already terminal (someone resolved it / abandonment-TTL GC / SLA resolve-deny). Client action:
@@ -2981,7 +3001,12 @@ paths:
         per-row delta for every transition. Frame order: `event: meta` `{version, scoped}` → `event: snapshot`
         `{tasks, workflows, ts}` → then `event: task`/`event: workflow` UPSERTS (each `data: {row, ts}` is the
         POST-MERGE FULL row — replace by `row.id`, NOT a sparse patch) + `event: task_remove`/`event:
-        workflow_remove` `{id, ts}` departures. Heartbeat `: hb` comment frames keep the connection alive.
+        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
+        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.)
         🔴 OWNER-SCOPED by the credential-derived principal (NOT a spoofable header) UNLESS fleet-wide (an operator
         / deployment trace token sees every tenant's rows). The row `scope` is WIRE-STRIPPED after the owner-gate —
         it never appears on a row; the `meta.scoped` flag tells the consumer which view this is (true = owner-scoped).
@@ -3981,6 +4006,17 @@ components:
         objective:
           type: string
           description: The task. Put per-request context here (keep `systemPrompt` stable/cacheable).
+        taskId:
+          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
+            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
+            original 202 receipt (`{taskId, sessionId, status}`); nothing re-runs, nothing re-bills.
+            Shape-gated: a non-uuidv7 value is 400 `request.id_invalid`. Owner-gated: a taskId owned by another
+            principal answers 409 `conflict.run_exists` (no cross-tenant id oracle). Omit ⇒ the server mints one.
         scenario: { $ref: '#/components/schemas/Scenario' }
         sessionId:
           type: string
@@ -4201,6 +4237,30 @@ components:
           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. }
+        forwardSubagentEvents:
+          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`).
+            ⚠️ 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.
+            (Declared 2026-08-02 — the capability bit had been registered here since 3.x, the request key never was.)
+        retainSubagentSessions:
+          oneOf:
+            - type: boolean
+            - type: object
+              additionalProperties: false
+              properties:
+                ttlMs: { type: integer, description: 'Retention window; server CLAMPS to ≤ 24 h (task-workflow.ts:77-83).' }
+                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
+            `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
+            were both already documented, only the knob that turns retention on was missing.)
         excludeTools:
           type: array
           items: { type: string }
@@ -4776,6 +4836,20 @@ components:
           description: >
             Approve-with-edit (design/37 last-wins): operator's rewritten tool args, applied AFTER the binding
             check. `boundInputHash` STILL binds the ORIGINAL input the human saw — never hash updatedInput.
+        remember:
+          type: string
+          enum: [session]
+          description: >-
+            [2400] HITL-4 (declared 2026-08-02) — the "don't ask again in this session" grant: lands a
+            per-session, per-toolName approval EXEMPTION alongside the decision (server
+            `routes/approvals-assistant.ts` reads it; the SDK has typed it since the facade audit, the spec had
+            not). It is an approval MEMORY, not a policy loosen — a deny / neverAuto always outranks it.
+            Constraints (all server-enforced): only with `decision:"approve"` (else 400
+            `request.field_conflict`); requires the D-1 binding echo in the same body (else 400
+            `remember_requires_binding`); REFUSED on a direct-door worker (400 `remember_not_in_proof` — it is
+            not inside the HMAC payload, so accepting it unsigned would be tamperable); 501 without an exemption
+            store. On the parked-background-agent leg the grant lands on the child's ROOT/HOST session (the whole
+            session tree shares it). The 200 body echoes `rememberApplied` when a store is wired.
 
     ApprovalRow:
       type: object
@@ -5597,6 +5671,42 @@ components:
         result: { type: string }
         seq: { type: integer, minimum: 1 }
         source: { type: string, maxLength: 190 }
+    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),两臂都是字面量。
+      description: >
+        POST /v1/sessions/{sessionId}/notify 的判别联合。分支 `delivery`:`live` = 会话有活流、通知已送达
+        (HTTP 200);`parked` = 无活流,排队到下次开流才 drain(HTTP 202)。消费方不得把两者都渲染成"已通知"。
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [sessionId, delivery]
+          properties:
+            sessionId: { type: string }
+            delivery: { type: string, enum: [live] }
+        - type: object
+          additionalProperties: false
+          required: [sessionId, delivery, note]
+          properties:
+            sessionId: { type: string }
+            delivery: { type: string, enum: [parked] }
+            note: { type: string }
+    SessionWakeResult:
+      # 4.3.0(SM-9):wake 200 形提成具名 schema(形与下面 /wake 路径的 200 逐字同源)。
+      type: object
+      description: >
+        POST /v1/sessions/{sessionId}/wake 的 200 形。⚠️ 200 也可能带 `errorCode`(core 侧 `wake.*` 拒了) ——
+        按机器码分支,别只看 HTTP 状态码。
+      additionalProperties: false
+      required: [sessionId, status]
+      properties:
+        sessionId: { type: string }
+        status: { type: string, description: 'The run''s resulting status (core TaskStatus verbatim).' }
+        taskId: { type: string, description: 'The active run id; OMITTED when no active row.' }
+        errorCode: { type: string, description: 'Failure code when the resumed leg failed / was refused.' }
+        errorMessage: { type: string, description: 'Human-readable failure detail (server-side secret-redacted).' }
+        retriable: { type: boolean, description: 'true = the park is STILL pending (re-parked); refetch and retry.' }
     WorkflowJournalRow:
       # 🔴 census 批2 四段:CLOSED against server's real projected/truncated row shapes — a row is EITHER the
       # projected result OR an honest truncated stub(超 64KiB 的行从不进程内存,投影为 truncated stub)。
@@ -5646,9 +5756,18 @@ components:
     WorkflowStreamEvent:
       type: object
       description: >
-        One frame of GET /v1/workflows/:id/stream (streamWorkflowRun). FIRST frame is `event:meta`
-        `{version, runId}`; subsequent frames carry a core WorkflowEvent (its `type` is the SSE event name). NOT
-        resumable (replica-local, in-process; no id/Last-Event-ID). `data` is permissive (core-internal, evolves).
+        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
+        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
+        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.
         NOTE: on the wire this is SSE framing (event name + JSON data), not a JSON body — schema describes one
         decoded frame.
       required: [event, data]
@@ -5752,12 +5871,19 @@ components:
       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 是对的那一边)。
+        # 按它 codegen 的第三方会得到一个永远 undefined 的 `workflowRow.sourceLane`,并照 FleetTaskRow 那条
+        # 「run-leg composite rows only」的描述写出一个**永不触发**的 workflow 行去重分支。
         id: { type: string }
-        sourceLane: { type: string, description: 'run-leg composite rows only (server >=3.6.0, [2070]-1 yield half); BCE-lane rows omit it.' }
         name: { type: string }
         description: { type: string }
         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` 真发。
+        startedCount: { type: integer, description: 'Agents actually STARTED (vs `totalCount` = planned, queued included). CC 2.1.220 的 `⚠ Large workflow` 规模告警用它当分母 —— 漏了它那条告警根本渲染不出来。' }
         totalCount: { type: integer }
         failedCount: { type: integer }
         elapsedMs: { type: integer }
@@ -5768,7 +5894,9 @@ components:
         wire this is SSE framing (the `type` here = the SSE `event` name; the object = the decoded `data:` JSON).
         Emit order: `meta` (FIRST) → `snapshot` (connect-time full set) → per-row `task`/`workflow` upserts +
         `task_remove`/`workflow_remove` departures. The SDK PRODUCES these frames; the consumer maintains the
-        active-set state (update-in-place by `row.id`, remove by `id`). Heartbeat `: hb` comments are not frames.
+        active-set state (update-in-place by `row.id`, remove by `id`).
+        🔴 The keep-alive IS a frame: `event: heartbeat` / `data: {}` @15 s (corrected 2026-08-02 — this line
+        previously said "`: hb` comments are not frames", which described a superseded shape). Swallow it by NAME.
         OPEN set — branch on `type`, ignore an unknown future frame.
       oneOf:
         - $ref: '#/components/schemas/FleetFrame_meta'
@@ -5792,12 +5920,22 @@ components:
           hook_notice: '#/components/schemas/FleetFrame_hook_notice'
     FleetFrame_meta:
       type: object
-      description: 'FIRST frame — `{version, scoped}`. `scoped:true` ⇒ owner-scoped view; `false` ⇒ fleet-wide (operator/trace token).'
-      required: [type, version, scoped]
+      # 🔴 FW-10(2026-08-02):此前只声明三键,而铸造点 `src/http/routes/fleet.ts:79` **无条件**发五键 ——
+      # `sessionScoped` / `bgNotifyFailClosed` 不在任何条件分支里。这两个键正是「server 契约方复审 F1
+      # (行为错·最高)」的当事键:它们曾被一次白名单重构静默剥掉,导致 cli 的让位臂全程死代码。
+      # SDK 侧已上锁(`test/fleet.test.ts` 有专门的透传回归钉),spec 侧一直空白 —— 按 spec 生成的客户端
+      # 拿不到 `bgNotifyFailClosed`,只能保留帧级 own/foreign 判别(或更糟:以为拿不到就是老 server),
+      # 代际让位机制对这类消费方永远不生效。
+      description: >
+        FIRST frame — `{type, version, scoped, sessionScoped, bgNotifyFailClosed}` (all five UNCONDITIONAL on
+        server >= 1.247). `scoped:true` ⇒ owner-scoped view; `false` ⇒ fleet-wide (operator/trace token).
+      required: [type, version, scoped, sessionScoped, bgNotifyFailClosed]
       properties:
         type: { const: meta }
         version: { type: integer }
         scoped: { type: boolean }
+        sessionScoped: { type: boolean, description: 'true ⇒ this connection carried `?session=` (rows and notifications are filtered by the host session).' }
+        bgNotifyFailClosed: { type: boolean, description: 'GENERATION marker — true ⇒ this server''s bg_notification injection path fails CLOSED for scoped subscribers, so a new-generation shell may drop its frame-level own/foreign checks entirely. ABSENT (older server) ⇒ keep them.' }
     FleetFrame_snapshot:
       type: object
       description: 'Connect-time FULL state (the visible, scope-stripped rows). Seed the active-set Map from this.'
@@ -6779,6 +6917,13 @@ components:
         - $ref: '#/components/schemas/Event_message_committed'
         # [2373]A-2(2026-08-03,server 5.0.0):compaction_outcome 三腿同源批的 spec 半场(SDK 臂 20867e1 同批)。
         - $ref: '#/components/schemas/Event_compaction_outcome'
+        # [2400] ch2(SDK 4.2.0):CB-1 流控帽帧 + TR-7 durable 五臂 —— 两侧同缺,见各 schema 处的注。
+        - $ref: '#/components/schemas/Event_error'
+        - $ref: '#/components/schemas/Event_question'
+        - $ref: '#/components/schemas/Event_question_complete'
+        - $ref: '#/components/schemas/Event_elicitation'
+        - $ref: '#/components/schemas/Event_elicitation_complete'
+        - $ref: '#/components/schemas/Event_workflow_complete'
       discriminator:
         propertyName: type
         mapping:
@@ -6809,6 +6954,12 @@ components:
           needs_review: '#/components/schemas/Event_needs_review'
           message_committed: '#/components/schemas/Event_message_committed'
           compaction_outcome: '#/components/schemas/Event_compaction_outcome'
+          error: '#/components/schemas/Event_error'
+          question: '#/components/schemas/Event_question'
+          question_complete: '#/components/schemas/Event_question_complete'
+          elicitation: '#/components/schemas/Event_elicitation'
+          elicitation_complete: '#/components/schemas/Event_elicitation_complete'
+          workflow_complete: '#/components/schemas/Event_workflow_complete'
 
     # 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
@@ -7728,6 +7879,102 @@ components:
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
 
+    # ══════════════════════════════════════════════════════════════════════════════════════════════
+    # [2400] 说明书审计 ch2(SDK 4.2.0)补的**六个未登记臂**:一个流控帧(CB-1/TR-6)+ 五个 HITL/workflow
+    # 帧(TR-7)。同一个盲区:`spec-union-arm-gate` 比的是 spec ↔ SDK 两侧的臂集,这六个两侧同缺 ⇒ 那道门
+    # 对它们结构性失明;抓到它们靠的是拿 server 的 `res.write("event: …")` / `append("…")` 铸造点第三方对账。
+    # ══════════════════════════════════════════════════════════════════════════════════════════════
+    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
+        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
+        it as a terminal would declare a live task dead. `done` / `failed` are the terminal arms; this one is not.
+        Known `errorCode`: `STREAM_MAX_DURATION` (open set — branch on the code, degrade unknown codes to the
+        generic "reconnectable stream-control signal").
+      additionalProperties: false
+      required: [type, errorCode]
+      properties:
+        type: { const: error }
+        errorCode: { type: string, description: 'STREAM_MAX_DURATION (open set).' }
+        message: { type: string }
+    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
+        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).
+      additionalProperties: false
+      required: [type, questionId]
+      properties:
+        type: { const: question }
+        questionId: { type: string }
+        questions:
+          type: array
+          items: { $ref: '#/components/schemas/AskQuestion' }
+    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.
+      additionalProperties: false
+      required: [type, questionId]
+      properties:
+        type: { const: question_complete }
+        questionId: { type: string }
+        outcome: { type: string, enum: [answered, unanswered] }
+    Event_elicitation:
+      type: object
+      description: >
+        Inbound-MCP elicitation OPEN frame (server src/elicitation.ts:42 `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
+        rejected upstream as a phishing surface).
+      additionalProperties: false
+      required: [type, elicitationId, mcpServerName]
+      properties:
+        type: { const: elicitation }
+        elicitationId: { type: string }
+        mcpServerName: { type: string }
+        message: { type: string }
+        requestedSchema: {}
+        mode: { type: string, enum: [form] }
+    Event_elicitation_complete:
+      type: object
+      description: 'Inbound-MCP elicitation CLOSE frame; `action` is how it settled (the dialog-dismiss reason).'
+      additionalProperties: false
+      required: [type, elicitationId, mcpServerName]
+      properties:
+        type: { const: elicitation_complete }
+        elicitationId: { type: string }
+        mcpServerName: { type: string }
+        action: { type: string, enum: [accept, decline, cancel] }
+    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
+        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
+        session may double-emit) — consumers MUST dedup on `runId`. `summary` is redacted free text
+        (UNTRUSTED-for-display).
+      additionalProperties: false
+      required: [type, runId, status, summary]
+      properties:
+        type: { const: workflow_complete }
+        runId: { type: string }
+        status: { type: string }
+        summary: { type: string }
+
     # ── 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).
@@ -8048,6 +8295,40 @@ components:
         taskId: { type: string, description: 'Issuing task, when recorded. Additive / tolerate-absent.' }
         sessionId: { type: string, description: 'Issuing session, when recorded. Additive / tolerate-absent.' }
 
+    SteerPriority:
+      type: string
+      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
+        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.
+
+    SteerReceipt:
+      type: object
+      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
+        turn boundary (`status:"running"`);
+        `queued` (202, `:641`) — 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 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),不是引擎透传形。
+      additionalProperties: false
+      properties:
+        taskId: { type: string }
+        status: { type: string, description: 'The run status the server saw at delivery time (running | suspended | a terminal status).' }
+        delivery: { type: string, enum: [applied, queued, parked_for_wake] }
+        messageId: { type: string, description: 'Server-minted, stable across all three legs.' }
+        priority: { $ref: '#/components/schemas/SteerPriority' }
+        note: { type: string, description: 'Human-readable note on the two parked legs; absent on `applied`.' }
+
     SubagentSteerReceipt:
       type: object
       description: >
@@ -8403,6 +8684,43 @@ components:
         delivery: { type: string, const: applied, description: 'Literal "applied" on today''s server.' }
         marker: { type: string, description: 'Engine-minted delivery marker.' }
 
+    WorkspaceSnapshotPage:
+      # 4.3.0(CAPS-OPS-8):把 GET …/workspace 的 200 信封提成具名 schema。SDK 侧此前是 `list()` 返回位上的
+      # **内联闭合字面量**,两道 spec 门(field-drift 只扫 types.ts / resource-schema 只扫 resources 的 exported
+      # type)对方法返回位的内联形都是盲的 —— 于是它漏了这里一直标为 required 的 `sessionId`,CI 全绿。
+      type: object
+      description: >
+        GET /v1/sessions/{sessionId}/workspace 的 200 信封(server src/http/routes/sessions.ts:624-629)。
+        ⚠️ `total` = **本页行数**(`snapshots.length`),不是快照总数,且这条腿没有任何分页游标 —— 与同族
+        `WorkspaceTreePage.total`(真·全量)**同名反义**。`latest` 与展示行同源(防 ghost key)。
+      additionalProperties: false
+      required: [sessionId, snapshots, total]
+      properties:
+        sessionId: { type: string }
+        snapshots:
+          type: array
+          items: { $ref: '#/components/schemas/WorkspaceSnapshotRow' }
+        latest: { type: string, description: 'Newest snapshot key; absent when the session has none.' }
+        total: { type: integer, description: 'ROWS ON THIS PAGE — not the snapshot count.' }
+
+    WorkspaceTreePage:
+      # 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)。
+        `total` 在这条腿上是**全量**(`all.length`)—— 与 `WorkspaceSnapshotPage.total` 语义相反。
+        `key` 回的是解析后的真实键(请求可传 `latest` 别名)。
+      additionalProperties: false
+      required: [sessionId, key, entries, total]
+      properties:
+        sessionId: { type: string }
+        key: { type: string, description: 'The RESOLVED snapshot key (a `latest` alias in the request comes back resolved).' }
+        entries:
+          type: array
+          items: { $ref: '#/components/schemas/WorkspaceTreeEntry' }
+        total: { type: integer, description: 'FULL entry count (not the page size).' }
+        nextOffset: { type: integer, description: 'Present ⇒ more pages; send it back as ?offset=.' }
+
     WorkspaceSnapshotRow:
       type: object
       description: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -48,6 +48,6 @@
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build && npm run typecheck --workspaces=false --prefix ../.. && npm test --workspaces=false --prefix ../.."
   },
   "devDependencies": {
-    "@sema-agent/registry-core": "^0.10.24"
+    "@sema-agent/registry-core": "^0.13.0"
   }
 }