@sema-agent/sdk 2.1.4 → 2.2.0

package/openapi.yaml

@@ -210,6 +210,7 @@ paths:
               schema: { $ref: '#/components/schemas/TaskResult' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' } # (declared 2026-08-01) 带 `sessionId` 复用他人会话:归属不匹配 ⇒ 403(自公开快照起点即有,spec 此前漏登记)。server 3.15.0 起多一个触发条件:多租部署上 session store 无归属判别能力时,复用**任何** caller 自报的 sessionId 都 403(含本 worker 自己刚铸的 —— 无 register seam 时归属从未被记下)。core 2.11.0 起默认内存店自带该能力 ⇒ 该触发条件在默认部署上不再出现。
         '409': { $ref: '#/components/responses/Conflict' }
         '429': { $ref: '#/components/responses/RateLimited' }
         '503': { $ref: '#/components/responses/Unauthorized' }
@@ -262,7 +263,16 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/TaskList' }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '429': { $ref: '#/components/responses/RateLimited' }
+        # 🔴 429 REMOVED 2026-07-31 — `routes/trace-usage.ts` has zero rate/quota/lease gates in the whole file
+        # (the only gates on this route are the fleet-wide 401 and the run-store 501 below); nothing can emit it.
+        '501':
+          description: >-
+            errorCode "capability.run_store_required" — the trace API needs a durable run store
+            (`DB_BACKEND=mysql|pg`). Added 2026-07-31: the guard has always been there (it fires before the
+            list/turns/stream/artifacts dispatch) but no trace path declared the code.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/tasks/stream:
     parameters:
@@ -300,6 +310,7 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '429': { $ref: '#/components/responses/RateLimited' }
+        '503': { $ref: '#/components/responses/Unauthorized' } # (declared 2026-07-31) this path is in server.ts's isBillableSubmitPath set — same three 503 doors as POST /v1/tasks and /v1/runs (no service token / draining / model-roster-pending)
 
   /v1/runs:
     parameters:
@@ -381,8 +392,12 @@ paths:
         '404': { $ref: '#/components/responses/NotFound' }
         '416':
           description: >
-            Resume point evicted past retention. Match the STATUS 416 (there is NO `code` field); read
-            `retainedFrom`, full-sync via `GET /v1/tasks/:id/turns`, then resume from `retainedFrom`.
+            Resume point evicted past retention. Body carries `errorCode: "limit.retention_evicted"`
+            (matching the 416 STATUS alone also works); read `retainedFrom`, full-sync via
+            `GET /v1/tasks/:id/turns`, then resume from `retainedFrom`.
+            (Corrected 2026-07-31: this said "there is NO `code` field". It was true before the server moved
+            this site onto the shared `sendError`, which emits `errorCode` unconditionally — a stale denial
+            that steered consumers away from a field that is in fact on the wire.)
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ResumeEvicted' }
@@ -401,8 +416,12 @@ paths:
         (non-owner → 404, no existence leak; missing principal → 401). All responses are synchronous ACKs; actual
         termination is async (same-replica immediate; cross-replica ≈30s via the heartbeat tick). A cancelled run
         settles to `status` failed + `errorCode` "cancelled" (NO new status — distinguish via errorCode; the UI
-        shows "cancelled", not an error). A SUSPENDED run has no running stream to abort → 409; cancel it by
-        DENYING its approval instead. LIVE (service ced3d88).
+        shows "cancelled", not an error). A SUSPENDED (or `needs_review`) run IS cancellable here — the server
+        settles its pending checkpoint (CAS `expire`, the reaper's "≈ deny" terminal — deliberately not a
+        resume, since cancel means the run dies) and THEN terminalizes the row, releasing the session claim;
+        the ack is 202. (Corrected 2026-07-31: this paragraph used to say "409 — cancel it by DENYING its
+        approval instead". That was the pre-[868] behavior and it dead-ended when the deny itself was lost,
+        leaving the session locked with no release path.) LIVE (service ced3d88).
       responses:
         '202':
           description: >
@@ -414,7 +433,17 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
-          description: Run is suspended (HITL) — cancel by denying its approval (`/v1/approvals/:sessionId/decide`), not here.
+          description: >-
+            Concurrency loss on the suspended path only: someone else settled the pending checkpoint first
+            (an approve/deny won the CAS). Re-read the run — it is probably already resuming or terminal.
+            NOT "suspended runs are uncancellable" — those are cancelled here and 202.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '500':
+          description: >-
+            errorCode "internal.cancel_not_terminalized" — the checkpoint was settled but the run row could
+            not be terminalized after retries. Retry cancel; a stuck row is reaped after the stale window.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -433,8 +462,12 @@ paths:
         design/80 D-A. The core of *supervision* (vs mere approve/deny): inject direction into a running run.
         AT-MOST-ONCE — steer is NOT idempotent (no retry). `trusted` is NOT a body field — the server derives it
         from the authenticated operator (the BFF's operator role); a network steer defaults to untrusted. A
-        durable-`suspended` run → 409 `errorCode` "steering.not_running" (steer is not queued; resolve its
-        approval instead). The pendingSteer freeze / close-tag guard is server-side; the client only sends text.
+        durable-`suspended` run → the steer is PARKED on the pending checkpoint and answered **202**
+        `{status:"suspended", delivery:"queued"}`; it is injected when the run resumes. (Corrected 2026-07-31:
+        this paragraph used to say "409 — steer is not queued; resolve its approval instead", which the server
+        stopped doing — `routes/runs.ts` parks it. 409 now only means the park LOST: the checkpoint resolved or
+        expired between the read and the CAS.) A worker with no checkpoint store answers 501 instead.
+        The pendingSteer freeze / close-tag guard is server-side; the client only sends text.
       requestBody:
         required: true
         content:
@@ -444,6 +477,14 @@ paths:
               required: [text]
               properties:
                 text: { type: string, description: 'The steering direction (untrusted DATA; the server fences it).' }
+                priority:
+                  type: string
+                  enum: [now, next, later]
+                  description: >-
+                    🔴 Declared 2026-07-31 (always read + enum-validated + echoed, never documented). The
+                    handler 400s `request.field_invalid` on any other value and echoes the accepted one back
+                    in the 200/202 body. It was mentioned only in prose under `Capabilities.fleet`, never in
+                    this operation's own schema.
                 mode:
                   type: string
                   enum: [all, one-at-a-time]
@@ -454,11 +495,18 @@ paths:
                     per-call; the per-call mapping is pending D-A core.
       responses:
         '200': { description: Steer accepted and applied. }
-        '202': { description: Steer accepted (queued to the next turn-boundary drain). }
+        '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.
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
-          description: 'errorCode "steering.not_running" — the run is suspended/terminal, not running (steer is not queued).'
+          description: >-
+            errorCode "steering.not_running" — the run is terminal, is running on ANOTHER replica
+            (cross-replica live-steer is not wired), or the durable park lost its CAS (the checkpoint
+            resolved/expired in between). NOT the ordinary suspended case — that one parks and 202s.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -475,6 +523,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' } # (declared 2026-07-31) rateLimited||quotaExceeded||leaseDenied all gate this verb (routes/runs.ts)
 
   /v1/runs/{taskId}/subagents/{target}/steer:
     parameters:
@@ -524,6 +573,7 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '413':
           description: 'errorCode "steer.content_too_large" — content over the per-steer cap; shorten and resend (retrying verbatim never succeeds).'
+        '429': { $ref: '#/components/responses/RateLimited' } # (declared 2026-07-31) rateLimited||quotaExceeded||leaseDenied all gate this verb (routes/runs.ts)
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/runs/{taskId}/compact:
@@ -569,6 +619,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' } # (declared 2026-07-31) rateLimited||quotaExceeded||leaseDenied all gate this verb (routes/runs.ts)
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/runs/{taskId}/detach:
@@ -613,6 +664,14 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429':
+          description: >-
+            (declared 2026-07-31) errorCode "limit.rate_exceeded" only — `routes/runs.ts` gates this verb with
+            `rateLimited(req,res)` alone (no quota/lease gate; mutating but runs no model, parity with cancel).
+            `Retry-After` (seconds) set.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/runs/{taskId}/subagents/{target}/output:
@@ -624,6 +683,17 @@ paths:
         required: true
         schema: { type: string }
         description: 'Background-agent handle (`a*` short form) under this parent run.'
+      - name: session
+        in: query
+        required: false
+        schema: { type: string }
+        description: >-
+          🔴 Declared 2026-07-31 (it was ALWAYS read, never documented). For a session-bound run, a
+          non-operator caller MUST send the session id here — the handler compares it to the run's
+          `sessionId` and answers **404 "run not found"** on mismatch or absence, byte-identical to the
+          unknown-run 404. So a consumer following the old spec (principal + path params only) hit a
+          silent, indistinguishable 404. Operator/trace callers bypass this, as they do the owner gate;
+          a run with no sessionId is not conversation-bound and needs no assertion.
     get:
       tags: [runs]
       operationId: runsSubagentOutput
@@ -699,6 +769,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' } # (declared 2026-07-31) rateLimited||quotaExceeded||leaseDenied all gate this verb (routes/runs.ts) — BILLABLE (starts model work)
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/runs/{taskId}/subagents/{target}/stream:
@@ -710,6 +781,17 @@ paths:
         required: true
         schema: { type: string }
         description: 'Background-agent handle (`a*` short form) under this parent run.'
+      - name: session
+        in: query
+        required: false
+        schema: { type: string }
+        description: >-
+          🔴 Declared 2026-07-31 (it was ALWAYS read, never documented). For a session-bound run, a
+          non-operator caller MUST send the session id here — the handler compares it to the run's
+          `sessionId` and answers **404 "run not found"** on mismatch or absence, byte-identical to the
+          unknown-run 404. So a consumer following the old spec (principal + path params only) hit a
+          silent, indistinguishable 404. Operator/trace callers bypass this, as they do the owner gate;
+          a run with no sessionId is not conversation-bound and needs no assertion.
     get:
       tags: [runs]
       operationId: runsSubagentStream
@@ -744,6 +826,17 @@ paths:
         required: true
         schema: { type: string }
         description: 'EXACT task handle only (`b*` background bash, monitor, background agent) — agent-name / legacy-shellId resolution is deliberately not on the wire (fail-closed 404).'
+      - name: session
+        in: query
+        required: false
+        schema: { type: string }
+        description: >-
+          🔴 Declared 2026-07-31 (it was ALWAYS read, never documented). For a session-bound run, a
+          non-operator caller MUST send the session id here — the handler compares it to the run's
+          `sessionId` and answers **404 "run not found"** on mismatch or absence, byte-identical to the
+          unknown-run 404. So a consumer following the old spec (principal + path params only) hit a
+          silent, indistinguishable 404. Operator/trace callers bypass this, as they do the owner gate;
+          a run with no sessionId is not conversation-bound and needs no assertion.
     get:
       tags: [runs]
       operationId: runsTaskOutput
@@ -801,6 +894,11 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/SubagentOutputResult' }
+        '400':
+          # (declared 2026-07-31) shares the path-decode + `?filter=` validation of the sibling output verb
+          # (both ride `taskVerbMatch` in routes/runs.ts) — request.path_malformed (malformed subagent-path
+          # percent-encoding) and request.param_unsupported (`?filter=` is refused on the wire, GET and stop alike).
+          $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -808,6 +906,14 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429':
+          description: >-
+            (declared 2026-07-31) errorCode "limit.rate_exceeded" only — `routes/runs.ts` gates this verb with
+            `rateLimited(req,res)` alone (mutating but runs no model, parity with detach). `Retry-After`
+            (seconds) set.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/sessions:
@@ -835,6 +941,14 @@ paths:
           name: owner
           schema: { type: string }
           description: Fleet-wide credential only — scope the page to a tenant. Ignored for a principal caller.
+        - in: query
+          name: q
+          required: false
+          schema: { type: string, maxLength: 256 }
+          description: >-
+            🔴 Declared 2026-07-31 (always read, never documented). Case-sensitive SUBSTRING filter over the
+            row's objective preview; the server trims and caps it at 256 chars. A consumer following the old
+            spec had no way to know the search face existed.
       responses:
         '200':
           description: Keyset page of session summaries.
@@ -950,6 +1064,10 @@ paths:
                 required: [deleted]
                 properties:
                   deleted: { type: boolean }
+        '400':
+          # (declared 2026-07-31) errorCode "request.id_invalid" — the path sessionId must decode to a
+          # well-formed uuidv7 (`routes/sessions.ts`); a malformed id never reaches the store.
+          $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409': { $ref: '#/components/responses/Conflict' }
@@ -1065,6 +1183,14 @@ paths:
               schema: { type: string }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
+        '500':
+          description: >-
+            (declared 2026-07-31) errorCode "internal.error" — `routes/sessions.ts`'s catch around the owner
+            lookup / subscribe setup, sent only when it fires BEFORE the SSE `200` headers went out
+            (`!res.headersSent`); once streaming has started a failure just ends the connection instead.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
         '503': { description: 'Subscription connection cap exceeded — Retry-After set; fall back to polling /head.' }
 
@@ -1526,6 +1652,10 @@ paths:
                 required: [rules]
                 properties:
                   rules: { $ref: '#/components/schemas/StoredSessionRules' }
+        '400':
+          # (declared 2026-07-31) errorCode "request.id_invalid" — GET and PUT share the SAME id-shape check
+          # in `routes/sessions.ts` (uuidv7 required) ahead of the method branch; only PUT had this declared.
+          $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409': { $ref: '#/components/responses/Conflict' }
@@ -1805,7 +1935,10 @@ paths:
         2c session-sync PUSH Phase A — a SMALL metadata body (`entryIds, snapshots, policy, anchors, resolution?`); the
         entries stream in Phase B. The cloud classifies (§7), pre-checks blob presence (a missing referenced hash →
         422 `missing_blob` — PUT it first), guards the import lease + any active run (409), then mints a stagingId.
-        `identical` → `{ relation:"identical" }` with NO stagingId (skip Phase B); `fresh`/`fast_forward` →
+        `identical` → `{ relation:"identical", basis, payloadVerified }` with NO stagingId (skip Phase B);
+        `basis` is `"entry-ids+digest"` when the caller supplied a comparable digest and it matched, else
+        `"entry-ids"` (id-set equality only) — see the `ImportStaged` schema, which has carried these two
+        keys all along; only this prose said "one key". `fresh`/`fast_forward` →
         `{ stagingId, relation }`. 🔴 a `fork`/`stale` without `resolution:"overwrite-dst"` → 409
         `conflict` carrying the `relation` (the SDK surfaces SyncConflictError).
       requestBody:
@@ -1840,6 +1973,7 @@ paths:
               schema: { $ref: '#/components/schemas/SyncConflict' }
         '422': { $ref: '#/components/responses/UnprocessableEntity' }
         '501': { $ref: '#/components/responses/NotImplemented' }
+        '503': { $ref: '#/components/responses/Unauthorized' } # (declared 2026-08-01) E6 兄弟守卫:无 service token + 未开 ALLOW_UNAUTHED_WRITES 时,这条 import 提交腿与 `PUT …/policy` 写的是同一个 policy store ⇒ 同门同码 `auth.service_token_required`(server 3.15.0 起)
 
   /v1/sessions/{sessionId}/sync/import/{stagingId}/entries:
     parameters:
@@ -1896,6 +2030,15 @@ paths:
   /v1/approvals:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
+      - name: owner
+        in: query
+        required: false
+        schema: { type: string }
+        description: >-
+          🔴 Declared 2026-07-31 (always read, never documented). OPERATOR-only tenant scoping: an operator
+          caller narrows the view to one owner with this key; for a non-operator the server forces the scope
+          to the caller's own principal and ignores it. The sibling `/v1/assistant/inbox` has declared the
+          same-named param all along — this face just never caught up.
     get:
       tags: [approvals]
       operationId: approvalsList
@@ -1917,14 +2060,27 @@ paths:
   /v1/approvals/stream:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
+      - name: owner
+        in: query
+        required: false
+        schema: { type: string }
+        description: >-
+          🔴 Declared 2026-07-31 (always read, never documented). OPERATOR-only tenant scoping: an operator
+          caller narrows the view to one owner with this key; for a non-operator the server forces the scope
+          to the caller's own principal and ignores it. The sibling `/v1/assistant/inbox` has declared the
+          same-named param all along — this face just never caught up.
     get:
       tags: [approvals]
       operationId: approvalsStream
       x-status: live             # spec-path-gate 首批回填 2026-07-27(design/80 native push;SDK approvals.stream 消费)
       summary: SSE — pending-approval deltas (subscribe once instead of polling GET /v1/approvals).
       description: >
-        Frames: `meta` ({type,version,mode:"approvals-delta",pollMs}) then `pending`/`resolved` deltas (each
-        data payload mirrors its SSE event name in `data.type` — proxy-safe dispatch). Cross-replica by
+        Frames: `meta` ({type,version,mode:"approvals-delta",pollMs}), then `synced` ({type,count}) once the
+        first full snapshot has been emitted, then `pending`/`resolved` deltas; plus `heartbeat` ({type}) on the
+        keep-alive tick and a terminal `error` ({type,errorCode:"STREAM_MAX_DURATION",…}) when the 15-min cap
+        fires. (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
+        it silently drops three frame kinds it really receives.) Each data payload mirrors its SSE event name in
+        `data.type` — proxy-safe dispatch. Cross-replica by
         construction (polls the SHARED checkpoint table). 15-min cap + heartbeats; a DB blip retries, never
         kills the stream. Scope = the caller's principal (operator/trace token = fleet-wide).
       responses:
@@ -1962,6 +2118,18 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ApprovalDecisionResult' }
+        '400':
+          description: >-
+            (declared 2026-07-31) `routes/approvals-assistant.ts` has 9+ distinct 400 sites on this verb, all
+            `ErrorResponse`-shaped: "request.path_malformed" (sessionId %-decode) · "request.body_shape"
+            (`decision` missing/invalid, or a malformed `answer`) · "request.field_invalid" (`reason` not a
+            string; `remember` not `"session"`; `checkpointToken`/`boundCallId`/`boundInputHash` not a string)
+            · "request.field_conflict" (`remember` without `decision:"approve"`) · "remember_not_in_proof" /
+            "updated_input_not_in_proof" (`remember` / `updatedInput` on a direct-door worker — not covered by
+            the decision proof) · "remember_requires_binding" (`remember` without the D-1 binding echo).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -1971,17 +2139,19 @@ 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.
+            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:
+            refetch the inbox; this pending is gone. SDK → ApprovalStaleError. Note the bare CAS 409 has NO
+            `errorCode`, which is exactly how the three are told apart.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
-        '410':
-          description: >
-            design/80 D-1 `approval_stale` (`errorCode`, `terminal`: resolved|expired_abort|expired_sla) — the
-            checkpoint is already terminal (someone resolved it / abandonment-TTL GC / SLA resolve-deny). Client
-            action: refetch the inbox; this pending is gone. SDK → ApprovalStaleError.
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        # 🔴 REMOVED 2026-07-31 — the 410 that never was. `grep -rn "\b410\b" src/` across the whole server
+        # is ZERO hits: `approval_stale` ships as a **409** carrying `errorCode: "approval_stale"` (the CAS
+        # 409 stays bare → ConflictError, so the two 409s never collide). The `terminal` enum values
+        # `expired_abort`/`expired_sla` are likewise never assigned — only `"resolved"`, or the key is absent.
+        # A consumer branching on 410 to detect staleness had a branch that could not fire; see the 409 below.
         '413':
           description: >
             errorCode "reason_too_large" — `reason` exceeded 4096 chars (same cap on plan_review). REJECTED,
@@ -2017,6 +2187,41 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ExemptionList' }
+        '400':
+          description: >-
+            (declared 2026-07-31) errorCode "request.path_malformed" — the sessionId (or a present `:toolName`
+            segment) carried a malformed %-sequence (`decodeURIComponent` threw), shared decode gate in
+            `routes/approvals-assistant.ts` ahead of GET/DELETE.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501':
+          description: Worker has no exemption store backend (DB_BACKEND / LOCAL lane required).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+    delete:
+      tags: [approvals]
+      operationId: approvalsExemptionsRouteUnsupported
+      x-status: live             # (declared 2026-07-31) same `em` regex as the sibling per-tool DELETE also matches this shorter path (no `:toolName`) — approvals-assistant.ts.
+      summary: 'DELETE without a tool name — always 400 (use /exemptions/{toolName} instead).'
+      description: >
+        The route regex behind `GET /v1/approvals/{sessionId}/exemptions` also accepts `DELETE` on this
+        SAME (shorter) path — `routes/approvals-assistant.ts` runs the identical store/decode/owner gates
+        as the GET above (so a bad store → 501, a malformed %-encoded id → 400, an unknown/non-owned session
+        → 404 all still apply first), then — because this path has no `:toolName` segment to match — it
+        deterministically hits `request.route_unsupported` ("DELETE needs /exemptions/:toolName"). This
+        operation therefore never returns a 2xx; callers should use `DELETE /v1/approvals/{sessionId}/exemptions/{toolName}`.
+      responses:
+        '400':
+          description: >-
+            errorCode "request.route_unsupported" — "DELETE needs /exemptions/:toolName" (deterministic once
+            past the store/decode/owner gates below); OR "request.path_malformed" from the shared decode gate.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '501':
@@ -2060,6 +2265,14 @@ paths:
                 required: [revoked]
                 properties:
                   revoked: { const: true }
+        '400':
+          description: >-
+            (declared 2026-07-31) errorCode "request.path_malformed" — sessionId or toolName carried a
+            malformed %-sequence (shared decode gate in `routes/approvals-assistant.ts`, same as the sibling
+            GET .../exemptions).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '501':
@@ -2253,6 +2466,7 @@ paths:
               schema: { $ref: '#/components/schemas/TurnList' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' } # (declared 2026-07-31) `routes/trace-usage.ts`'s `!deps.runStore` guard fires before the /turns|/stream|/artifacts sub-dispatch — capability.run_store_required
 
   /v1/tasks/source-summary:
     parameters:
@@ -2348,6 +2562,7 @@ paths:
               schema: { $ref: '#/components/schemas/TraceStreamEvent' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' } # (declared 2026-07-31) `routes/trace-usage.ts`'s `!deps.runStore` guard fires before the /turns|/stream|/artifacts sub-dispatch — capability.run_store_required
 
   /v1/usage:
     parameters:
@@ -2380,7 +2595,10 @@ paths:
       summary: Windowed usage totals (usage-analytics face).
       description: >
         READ-ONLY analytics aggregate over the caller's principal (operator/trace token = fleet-wide). Query:
-        `from`/`to` (ISO), `owner` (fleet-wide callers only). Response is the analytics aggregate — an OPEN
+        `from`/`to` (ISO), `principal` (fleet-wide callers only — the handler reads this key; a JWT subject is
+        forced to itself and the param is ignored). (Corrected 2026-07-31: this said `owner`, which the handler
+        never reads — a hand-rolled caller sending `?owner=` got UNFILTERED results with no error. The shipped
+        SDK client has always sent `principal`.) Response is the analytics aggregate — an OPEN
         object (additive fields ride; consumers branch on known keys only).
       responses:
         '200':
@@ -2627,7 +2845,9 @@ paths:
             application/json:
               schema: { type: object, additionalProperties: true }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: side-query not enabled on this worker. }
+        # 🔴 REMOVED 2026-07-31 — `routes/side-query.ts` has no 501 branch at all, and
+        # `routes/capabilities.ts` reports `sideQuery: true` as a hardcoded constant (no deployment flag
+        # gates this route). The documented "not enabled on this worker" case is unreachable.
 
   /v1/workflows:
     parameters:
@@ -2653,6 +2873,13 @@ paths:
           required: false
           schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
           description: Max rows (server clamps to 1..100; default 50).
+        - in: query
+          name: session
+          required: false
+          schema: { type: string }
+          description: >-
+            🔴 Declared 2026-07-31 (always read, never documented). Filters the rows to one session — a
+            consumer following the old spec (status/limit only) silently got the whole scope back.
       responses:
         '200':
           description: Owner's workflow-run summaries.
@@ -2661,6 +2888,7 @@ paths:
               schema:
                 type: object
                 required: [workflows]
+                additionalProperties: false
                 properties:
                   workflows:
                     type: array
@@ -2737,6 +2965,13 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/AttachmentInfo' }
         '400': { description: 'missing/unsafe name, malformed mime' }
+        '401':
+          description: >-
+            (declared 2026-07-31) errorCode "auth.principal_required" — `routes/attachments.ts` requires a
+            principal ahead of the method dispatch when `requirePrincipal` is on.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '413': { description: 'attachment.too_large' }
         '415': { description: 'attachment.mime_not_allowed' }
         '501': { description: 'attachment store not configured' }
@@ -2754,7 +2989,15 @@ paths:
       summary: Download an attachment's bytes (owner-gated, no oracle — unknown and foreign both 404).
       responses:
         '200': { description: 'bytes; content-type = stored mime; content-disposition carries the sanitized name.' }
+        '401':
+          description: >-
+            (declared 2026-07-31) errorCode "auth.principal_required" — `routes/attachments.ts` gates the
+            store-presence check and the principal requirement ahead of the GET/DELETE method dispatch.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '404': { description: 'unknown or not owned' }
+        '501': { description: '(declared 2026-07-31) errorCode "capability.attachment_store_required" — no attachment store configured.' }
     delete:
       tags: [tasks]
       operationId: deleteAttachment
@@ -2762,10 +3005,33 @@ paths:
       summary: Delete an attachment (owner-gated; 204 on success).
       responses:
         '204': { description: 'deleted' }
+        '401':
+          description: >-
+            (declared 2026-07-31) errorCode "auth.principal_required" — same shared gate as the GET (store
+            presence + principal requirement) ahead of the method dispatch.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '404': { description: 'unknown or not owned' }
+        '501': { description: '(declared 2026-07-31) errorCode "capability.attachment_store_required" — no attachment store configured.' }
   /v1/fleet/stream:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
+      - name: session
+        in: query
+        required: false
+        schema: { type: string }
+        description: >-
+          🔴 Declared 2026-07-31 (always read, never documented). Scopes row visibility / content scrubbing
+          to one session.
+      - name: observe
+        in: query
+        required: false
+        schema: { type: string, enum: ['1'] }
+        description: >-
+          🔴 Declared 2026-07-31 (always read, never documented). `observe=1` opens the stream WITHOUT the
+          durable notification park-fencing (the workflow-completion inbox is not passed) — an observer view
+          that must not consume another consumer's parked notifications.
     get:
       tags: [fleet]
       operationId: fleetStream
@@ -2804,7 +3070,10 @@ paths:
         `LEADER_ENABLED` (default OFF) + `REMOTE_EXEC=e2b`. Mode is a SERVER deploy flag, not a client choice:
         `LEADER_FANOUT_ENABLED=true` (default) lets the router fan out to N isolated workers (= the value-HOLD
         correctness bet); `=false` pins a single worker. Either way it runs the E2B+git pipeline. Door B's brain
-        is the strong single agent via `/v1/tasks`+`/v1/runs`+`scenario`. When disabled → 501.
+        is the strong single agent via `/v1/tasks`+`/v1/runs`+`scenario`. When disabled (`LEADER_ENABLED` off)
+        the route is simply NOT REGISTERED → the generic **404** `not_found.route`, not 501.
+        (Corrected 2026-07-31: "When disabled → 501" was never true — no code path emits 501 here; a consumer
+        branching on 501 to detect "leader unavailable" never fires.)
       requestBody:
         required: true
         content:
@@ -2824,7 +3093,13 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/LeaderReceipt' }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { $ref: '#/components/responses/NotImplemented' }
+        '404':
+          description: >-
+            errorCode "not_found.route" — the leader lane is disabled on this worker, so the route is not
+            registered at all. (Was documented as 501 until 2026-07-31; no code path ever emitted that.)
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/leader/{leaderRunId}:
     parameters:
@@ -2879,7 +3154,7 @@ paths:
               schema:
                 type: object
                 required: [images]
-                additionalProperties: true
+                additionalProperties: false
                 properties:
                   images:
                     type: array
@@ -2897,9 +3172,17 @@ paths:
       summary: 'OPERATOR: register one image-index entry → { id }.'
       requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
       responses:
-        '200': { description: '{ id }.', content: { application/json: { schema: { type: object, required: [id], properties: { id: { type: string } }, additionalProperties: true } } } }
+        '200': { description: '{ id }.', content: { application/json: { schema: { type: object, required: [id], properties: { id: { type: string } }, additionalProperties: false } } } }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: >-
+            (declared 2026-07-31) errorCode "auth.operator_only" — EXPLICIT operator gate (not the bare
+            isOperator, whose empty-OPERATOR_PRINCIPALS "true-for-all" would make this index-mutating door
+            world-writable).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/images/{profile}:
     parameters:
@@ -2911,7 +3194,9 @@ paths:
       x-status: live
       summary: 'Newest PUBLISHED entry for a profile → { image }.'
       responses:
-        '200': { description: '{ image: entry } (open row shape).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        # 🔴 census 批2 四段:this arm was a bare open `{}` (no `image` key even declared) — the handler's real
+        # body is `{ image: entry }` (images.ts:478-484), entry = the SAME ImageIndexEntry as the list route.
+        '200': { description: '{ image: entry }.', content: { application/json: { schema: { type: object, required: [image], additionalProperties: false, properties: { image: { $ref: '#/components/schemas/ImageIndexEntry' } } } } } }
         '404': { $ref: '#/components/responses/NotFound' }
 
   /v1/images/digests/{digest}:
@@ -2924,7 +3209,8 @@ paths:
       x-status: live
       summary: 'Entry by immutable digest → { image }.'
       responses:
-        '200': { description: '{ image: entry }.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        # 🔴 census 批2 四段:same open-`{}` gap as imagesByProfile — real body `{ image: entry }` (images.ts:466-472).
+        '200': { description: '{ image: entry }.', content: { application/json: { schema: { type: object, required: [image], additionalProperties: false, properties: { image: { $ref: '#/components/schemas/ImageIndexEntry' } } } } } }
         '404': { $ref: '#/components/responses/NotFound' }
 
   /v1/images/bakes:
@@ -2940,11 +3226,31 @@ paths:
         busy ⇒ 409 {activeBakeId?, eventsUrl?}; submission rate-limit ⇒ 429 + retryAfterSec.
       requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
       responses:
-        '202': { description: '{ bakeId, eventsUrl, status, state? }.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '202': { description: '{ bakeId, eventsUrl, status, state }.', content: { application/json: { schema: { $ref: '#/components/schemas/BakeSubmitAck' } } } }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: (declared 2026-07-31) errorCode "auth.operator_only" — EXPLICIT operator gate (§P2.4a).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409': { description: 'Busy — { activeBakeId?, eventsUrl? }.' }
         '429': { description: 'Submission rate-limited (retryAfterSec).' }
+        '501':
+          description: >-
+            (declared 2026-07-31) errorCode "capability.unavailable" — the requested bake shape is not open
+            yet (custom/tenant P4), from the input-whitelist validator (`validateBake`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '503':
+          description: >-
+            (declared 2026-07-31) errorCode "state.no_sandbox_base" — a real (non-dryRun) build has no
+            concrete `sandbox-base` to build FROM (set `SANDBOX_BASE_REF` or publish one); a `dryRun` request
+            is resolve-only and is exempt.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/images/bakes/claim:
     parameters:
@@ -2955,9 +3261,16 @@ paths:
       x-status: live             # bake-runner credential face (machine-to-machine).
       summary: 'RUNNER: claim the oldest queued bake (discover+CAS in one step; 204 = queue empty).'
       responses:
-        '200': { description: 'BakeClaim { bakeId, argv, push, dryRun, logs, profile, bands, ingestSecret, leaseUntil }.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '200': { description: 'BakeClaim { bakeId, argv, push, dryRun, logs, profile, bands, ingestSecret, leaseUntil }.', content: { application/json: { schema: { $ref: '#/components/schemas/BakeClaim' } } } }
         '204': { description: 'Queue empty.' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: >-
+            errorCode "auth.bake_runner_only" — the caller is not the bake runner. (Was documented as 401
+            until 2026-07-31; the handler has always sent 403 with this code, so a consumer keyed on 401
+            never matched.)
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/images/bakes/{bakeId}:
     parameters:
@@ -2967,9 +3280,14 @@ paths:
       tags: [sandbox]
       operationId: bakesGet
       x-status: live
-      summary: 'One bake row → { bake } (open view: status/state/profile/bands/logs/digest…).'
+      summary: 'One bake row → { bake } (status/state/profile/bands/logs/digest…).'
       responses:
-        '200': { description: '{ bake }.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '200': { description: '{ bake }.', content: { application/json: { schema: { type: object, required: [bake], additionalProperties: false, properties: { bake: { $ref: '#/components/schemas/BakeRecordView' } } } } } }
+        '403':
+          description: (declared 2026-07-31) errorCode "auth.operator_only" — EXPLICIT operator gate.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '404': { $ref: '#/components/responses/NotFound' }
 
   /v1/images/bakes/{bakeId}/cancel:
@@ -2980,9 +3298,14 @@ paths:
       tags: [sandbox]
       operationId: bakesCancel
       x-status: live
-      summary: 'OPERATOR: request cancel → 202 { bakeId, cancelRequested: true, note? } (flag only; the runner kills the build on its next heartbeat; terminal rows = honest no-op note).'
+      summary: 'OPERATOR: request cancel → 202 { bakeId, cancelRequested: true, note } (flag only; the runner kills the build on its next heartbeat; terminal rows = honest no-op note).'
       responses:
-        '202': { description: '{ bakeId, cancelRequested, note? }.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '202': { description: '{ bakeId, cancelRequested, note }.', content: { application/json: { schema: { $ref: '#/components/schemas/BakeCancelAck' } } } }
+        '403':
+          description: (declared 2026-07-31) errorCode "auth.operator_only" — EXPLICIT operator gate.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '404': { $ref: '#/components/responses/NotFound' }
 
   /v1/images/bakes/{bakeId}/claim:
@@ -2995,7 +3318,12 @@ paths:
       x-status: live
       summary: 'RUNNER: claim THIS queued bake (single-flight CAS; losing the race ⇒ 409).'
       responses:
-        '200': { description: 'BakeClaim (same shape as claim-next).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '200': { description: 'BakeClaim (same shape as claim-next).', content: { application/json: { schema: { $ref: '#/components/schemas/BakeClaim' } } } }
+        '403':
+          description: (declared 2026-07-31) errorCode "auth.bake_runner_only" — the caller is not the bake runner (same code as the sibling claim-next).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409': { description: 'Claim race lost / not queued.' }
 
   /v1/images/bakes/{bakeId}/ingest:
@@ -3007,10 +3335,19 @@ paths:
       operationId: bakesIngest
       x-status: live
       summary: 'RUNNER: push one build.sh event line + lease heartbeat (x-bake-ingest-secret header from the claim).'
-      description: 'line = {event, …}; event=heartbeat renews the lease only. Response always carries { accepted, leaseValid, cancelRequested } — 409 = lease lost/stolen; cancelRequested=true ⇒ the runner should kill the build.'
+      description: 'line = {event, …}; event=heartbeat renews the lease only. 409 = lease lost/stolen; cancelRequested=true ⇒ the runner should kill the build.'
       requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
       responses:
-        '200': { description: '{ accepted, leaseValid, cancelRequested }.', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '200': { description: 'One of four shapes (heartbeat / non-terminal append / terminal done-success / terminal done-needs-flip) — see BakeIngestAck.', content: { application/json: { schema: { $ref: '#/components/schemas/BakeIngestAck' } } } }
+        '403':
+          description: >-
+            (declared 2026-07-31) two distinct causes share this status: errorCode "auth.bake_runner_only"
+            (the caller's credential isn't the configured bake-runner principal) and
+            "auth.ingest_secret_invalid" (the `x-bake-ingest-secret` header is missing or doesn't match the
+            per-bake secret minted at claim).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409': { description: 'Lease invalid / claimed by another runner.' }
 
   /v1/images/bakes/{bakeId}/events:
@@ -3021,9 +3358,14 @@ paths:
       tags: [sandbox]
       operationId: bakesEvents
       x-status: live
-      summary: 'Bake live SSE (run-trace-SSE framing; RESUMABLE — `id:` lines carry the event seq, Last-Event-ID resumes).'
+      summary: 'OPERATOR: Bake live SSE (run-trace-SSE framing; RESUMABLE — `id:` lines carry the event seq, Last-Event-ID resumes).'
       responses:
         '200': { description: 'SSE stream.', content: { text/event-stream: { schema: { type: string } } } }
+        '403':
+          description: (declared 2026-07-31) errorCode "auth.operator_only" — EXPLICIT operator gate (this summary previously did not mention the restriction at all).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '404': { $ref: '#/components/responses/NotFound' }
 
   /v1/images/select:
@@ -3097,14 +3439,19 @@ paths:
         The approval row carries the FULL tool-call args (commands/paths/contents of a high-risk op), so the
         by-id read enforces the same tenant boundary as the list: operators read across tenants; everyone else
         reads ONLY their own scope (the guard fires at the SQL layer — no cross-tenant args even if an id
-        leaks). Non-owner → 404 (never 403, no existence oracle). Present only on deployments with the
-        D-lane approval store; the checkpoint-lane decide verb is `/v1/approvals/{sessionId}/decide`.
+        leaks). Non-owner → 404 (never 403, no existence oracle).
+        🔴 AVAILABILITY (corrected 2026-07-31): present only on deployments that have the D-lane approval store
+        **AND NOT the checkpoint store**. When `DURABLE_APPROVAL` is on, the checkpoint lane takes precedence
+        for the whole `/v1/approvals*` prefix and this by-id route answers 404 `not_found.route` — deliberate,
+        not a bug; decide via `/v1/approvals/{sessionId}/decide` and list via `GET /v1/approvals`.
+        The old wording ("present only on deployments with the D-lane approval store") named one condition of
+        two, so a both-stores worker looked like it should serve this route.
       responses:
         '200':
           description: The approval row (full args projection).
           content:
             application/json:
-              schema: { type: object, additionalProperties: true }
+              schema: { $ref: '#/components/schemas/ApprovalRow' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
 
@@ -3135,11 +3482,14 @@ paths:
             application/json:
               schema:
                 type: object
+                # 🔴 census 批2 五段:CLOSED — exact literal `{ scope, exportedAt, entries }`
+                # (memory-policy.ts:58), no fourth key.
                 required: [scope, exportedAt, entries]
+                additionalProperties: false
                 properties:
                   scope: { type: string }
                   exportedAt: { type: string, format: date-time }
-                  entries: { type: array, items: { type: object, additionalProperties: true } }
+                  entries: { type: array, items: { $ref: '#/components/schemas/MemoryEntry' } }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -3175,7 +3525,7 @@ paths:
           description: 'The sync outcome (core reconcile/nextSyncBaseline projection).'
           content:
             application/json:
-              schema: { type: object, additionalProperties: true }
+              schema: { $ref: '#/components/schemas/MemorySyncResponse' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -3211,7 +3561,15 @@ paths:
           description: Aggregation rows.
           content:
             application/json:
-              schema: { type: object, additionalProperties: true }
+              schema:
+                type: object
+                # 🔴 census 批2 五段:path↔schema 脱钩修(same class as the earlier BakeClaim/usage-triplet
+                # finds) — `OutcomeRow` already existed named+correct (observability.ts:51's exact
+                # `{ outcomes: rows }`) but this path never `$ref`'d it, declaring a bare open `{}` instead.
+                required: [outcomes]
+                additionalProperties: false
+                properties:
+                  outcomes: { type: array, items: { $ref: '#/components/schemas/OutcomeRow' } }
         '403': { description: 'Multi-tenant worker: outcomes view is operator-only.' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
@@ -3253,9 +3611,13 @@ paths:
             application/json:
               schema:
                 type: object
+                # 🔴 census 批2 五段:path↔schema 脱钩修 (same class as /v1/outcomes above) — `SendfileLinkRow`
+                # already existed named+correct but this path's `links` items were a bare open `{}` instead
+                # of `$ref`ing it.
                 required: [links]
+                additionalProperties: false
                 properties:
-                  links: { type: array, items: { type: object, additionalProperties: true } }
+                  links: { type: array, items: { $ref: '#/components/schemas/SendfileLinkRow' } }
                   nextBefore: { type: string }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
@@ -3297,9 +3659,18 @@ paths:
               schema:
                 type: object
                 required: [runId, entries]
+                additionalProperties: false
                 properties:
                   runId: { type: string }
-                  entries: { type: array, items: { type: object, additionalProperties: true } }
+                  # 🔴 census 批2 四段:CLOSED against server's real `projectResult`/truncated-row shapes
+                  # (workflows.ts:127-165) — a row is EITHER the projected result OR an honest truncated stub
+                  # (a row whose stored TaskResult exceeded the 64KiB per-row gate never enters process memory).
+                  entries:
+                    type: array
+                    items:
+                      oneOf:
+                        - $ref: '#/components/schemas/WorkflowJournalEntry'
+                        - $ref: '#/components/schemas/WorkflowJournalEntryTruncated'
                   nextOffset: { type: integer }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -3340,6 +3711,14 @@ paths:
       responses:
         '200':
           description: 'Injected. Body `{ runId, label, status: "running", delivery: "applied", marker }`.'
+          # 🔴 census 批2 五段:spec-谎修——this 200 declared a bare `description` with NO `content`/`schema`
+          # at all (classify() reads it as "no-json", invisible to both the open- and closed-op ledgers)
+          # while the server genuinely sends a JSON body (workflows.ts:279). The named schema
+          # `WorkflowAgentSteerReceipt` already existed (path↔schema decoupling, same class as the earlier
+          # BakeClaim/usage-triplet finds) — wiring it up here, not inventing a new one.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/WorkflowAgentSteerReceipt' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -3350,6 +3729,14 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '413':
+          description: >-
+            (declared 2026-07-31) errorCode "steer.content_too_large" — content exceeds the server's
+            per-steer request cap (`STEER_IN_MAX_REQUEST_CHARS`, same family as the run/subagent steer caps);
+            REJECTED, never truncated. Shorten and resend.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /metrics/summary:
@@ -3369,7 +3756,12 @@ paths:
           description: Metrics summary (shape draft).
           content:
             application/json:
-              schema: { type: object, additionalProperties: true }
+              # 🔴 census 批2 五段:CLOSED against the real emitter — `sendJson(res, 200, { model,
+              # ...deps.metrics.summarize() })` (server.ts:794) is a fixed key set (server observability/
+              # metrics.ts `MetricsSummary`), not an ops free-for-all. Left `x-status: draft` / `x-sdk: none`
+              # untouched (still deliberately outside the SDK's wrapped surface) — closing the SHAPE and
+              # keeping it un-wrapped are independent axes.
+              schema: { $ref: '#/components/schemas/MetricsSummaryOps' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -3437,6 +3829,15 @@ components:
       content:
         application/json:
           schema: { $ref: '#/components/schemas/ErrorResponse' }
+    Forbidden:
+      description: >
+        Authorization denied on a resource the caller is authenticated for — 403. Distinct from Unauthorized
+        (401/503 = who are you / this worker refuses to serve): here the identity is established and rejected.
+        Today's only producer is session-ownership: reusing a `sessionId` that belongs to another principal.
+        Mapped to AuthError.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
     NotFound:
       description: >
         No such resource for this principal. Owner-scoped reads/cancel return 404 (not 403) for a non-owned or
@@ -4116,11 +4517,15 @@ components:
     ResumeEvicted:
       type: object
       description: >
-        416 body for an evicted SSE resume point (`GET /v1/runs/:id/events`). There is NO machine `code` field —
-        match the 416 STATUS and read `retainedFrom`, then full-sync via `/v1/tasks/:id/turns` (pinned SSE contract).
-      required: [error, retainedFrom]
+        416 body for an evicted SSE resume point (`GET /v1/runs/:id/events`). Carries the machine code
+        `errorCode: "limit.retention_evicted"`; matching the 416 STATUS alone is equally valid. Read
+        `retainedFrom`, then full-sync via `/v1/tasks/:id/turns` (pinned SSE contract).
+        (Corrected 2026-07-31 — see the 416 response note on that path: the "no machine code" claim predates
+        the site's move onto the shared `sendError`.)
+      required: [error, errorCode, retainedFrom]
       properties:
         error: { type: string }
+        errorCode: { type: string, enum: [limit.retention_evicted] }
         retainedFrom: { type: integer, description: Lowest event seq still retained; resume events from here. }
 
     ImageIndexEntry:
@@ -4136,7 +4541,7 @@ components:
         [id, profile, bands, repo, tag, digest, toolchainVersions, capabilities, podContract, sizeBytes, status,
          visibility, tenantId, manifestSha, recipeGitSha, generatorVersion, buildDate, supersedes, signed,
          createdAt, updatedAt]
-      additionalProperties: true
+      additionalProperties: false
       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 }
@@ -4150,26 +4555,8 @@ components:
             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 }
+        capabilities: { $ref: '#/components/schemas/ImageCapabilities' }
+        podContract: { $ref: '#/components/schemas/ImagePodContract' }
         sizeBytes: { type: ['integer', 'null'] }
         status: { type: string, enum: [building, published, deprecated, failed] }
         visibility: { type: string, enum: [public, tenant] }
@@ -4183,14 +4570,47 @@ components:
         createdAt: { type: string, description: ISO date-time. }
         updatedAt: { type: string, description: ISO date-time. }
 
+    ImageCapabilities:
+      # 抽成具名 schema(census 批2 四段)——此前在 ImageIndexEntry/ImageSelectResult 两处内联重复,
+      # ImageSelectResult 那份还漏了 `nestedBuildMode`(server 侧两处读的是同一个 ImageCapabilities,
+      # entry.capabilities 逐字透传;两侧同缺,不是刻意窄化)。server store-contracts.ts 全字段皆 optional。
+      type: object
+      description: What a sandbox image can do (server `ImageCapabilities`, plugins/store-contracts.ts).
+      additionalProperties: false
+      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.'
+
+    ImagePodContract:
+      # 抽成具名 schema(census 批2 四段)——同上,ImageSelectResult 那份此前连字段都没声明(裸 additionalProperties:true)。
+      type: object
+      description: Pod-shape hints for scheduling a sandbox off this image (server `ImagePodContract`).
+      additionalProperties: false
+      properties:
+        devShmMB: { type: integer }
+        minMemMB: { type: integer }
+        minCpu: { type: string }
+        readyTimeoutSec: { type: integer }
+        securityContext: { type: object, additionalProperties: true, description: 'k8s-shaped, genuinely arbitrary — Record<string,unknown> server-side.' }
+
     ImageSelectResult:
-      # 新增(2026-07-25 回填批)。
+      # 新增(2026-07-25 回填批)。🔴 census 批2 四段:closed against the real handler (images.ts:407-415) — ALL
+      # seven keys are unconditionally assigned every 200 (required tightened from none); `manifestSha` can be
+      # null (ImageIndexEntry.manifestSha is `string | null`, this was typed non-nullable — a spec lie); and
+      # `podContract`/`capabilities` now share the SAME closed schemas as ImageIndexEntry (no more drift/no
+      # more missing `nestedBuildMode`).
       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
+      required: [profile, digest, repo, ref, podContract, capabilities, manifestSha]
+      additionalProperties: false
       properties:
         profile: { type: string }
         digest: { type: string }
@@ -4200,15 +4620,9 @@ components:
           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 }
+        podContract: { $ref: '#/components/schemas/ImagePodContract' }
+        capabilities: { $ref: '#/components/schemas/ImageCapabilities' }
+        manifestSha: { type: ['string', 'null'], description: 'the source entry''s manifestSha — nullable (ImageIndexEntry.manifestSha is string|null; was wrongly non-nullable here).' }
 
     QuotaError:
       type: object
@@ -4350,17 +4764,32 @@ components:
 
     LeaderReceipt:
       type: object
+      description: >
+        202 receipt of POST /v1/leader (server leader/endpoint.ts:130 — exact literal
+        `{ leaderRunId, status: "running" }`; the POST ack is always the "running" value, the other
+        `status` enum members only ever appear on the GET twin below).
+      # 🔴 census 批2 五段:CLOSED — the POST handler's literal never carries a third key.
       required: [leaderRunId, status]
+      additionalProperties: false
       properties:
         leaderRunId: { type: string }
         status: { type: string, enum: [running, completed, failed] }
 
     LeaderRecord:
       type: object
+      description: >
+        200 body of GET /v1/leader/{leaderRunId} (server leader/endpoint.ts:142-150 — exact literal
+        `{ id, status, ...(result?{result}:{}), ...(error?{error}:{}) }`).
+      # 🔴 census 批2 五段:两处修——① CLOSED(result/error 是 OMIT-when-absent 的可选键,不是额外键);
+      # ② `status` 的第四值 `needs_human`(LEADER-REPAIRLOOP-INTEGRATION §5/§10.6 的第三终态,
+      # `statusForLeaderResult` 在 candidate_only/needs_human_oracle/conflict 三个 repairTerminal 上产出)
+      # 此前 SPEC LIES BY OMISSION——TS 侧 `LeaderRecord.status` 早就带这个第四值(types.ts:1607,亲验
+      # 已在场),只有 spec 的 enum 一直缺它,是个只有场景真触发才会现形的假红洞(一个真实合法帧被判违约)。
       required: [id, status]
+      additionalProperties: false
       properties:
         id: { type: string }
-        status: { type: string, enum: [running, completed, failed] }
+        status: { type: string, enum: [running, completed, failed, needs_human] }
         result: {}
         error: { type: string }
 
@@ -4399,6 +4828,30 @@ components:
             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.
 
+    ApprovalRow:
+      type: object
+      description: >
+        The legacy D-lane approval row of GET /v1/approvals/{approvalId} (server `ApprovalRow`,
+        plugins/approval-store-sql.ts:43 — the row is `sendJson`'d verbatim, approvals-assistant.ts:668).
+        Present only on deployments running the legacy `approvalStore` leg (no `checkpointStore` wired);
+        the durable F4 lane has no by-id GET (only list + decide).
+      # 🔴 census 批2 五段:CLOSED — byte-identical to the server row type, no extra keys.
+      required: [id, taskId, sessionId, owner, scope, toolName, args, status, reason, decidedBy, createdAt, decidedAt]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        taskId: { type: [string, 'null'] }
+        sessionId: { type: [string, 'null'] }
+        owner: { type: [string, 'null'] }
+        scope: { type: [string, 'null'], description: 'Single-DB fleet scope guard (tenant identity, owner-sourced).' }
+        toolName: { type: string }
+        args: { description: 'The reviewed tool-call args — full fidelity, not redacted (this IS the review surface).' }
+        status: { type: string, enum: [pending, approved, denied, expired] }
+        reason: { type: [string, 'null'] }
+        decidedBy: { type: [string, 'null'] }
+        createdAt: { type: string }
+        decidedAt: { type: [string, 'null'] }
+
     Capabilities:
       type: object
       description: >
@@ -4594,6 +5047,148 @@ components:
               egress: { type: boolean }
               irreversibility: { type: string, enum: [always, never] }
 
+    MemoryEntryFrontmatter:
+      type: object
+      description: >
+        core `MemoryEntryFrontmatter` (@sema-agent/core memory-engine/types.d.ts). All fields optional —
+        an entry with none of them is a bare note.
+      additionalProperties: false
+      properties:
+        name: { type: string }
+        description: { type: string }
+        type: { type: string }
+        deleted: { type: boolean }
+        provenance:
+          type: object
+          required: [kind, path, contentHash, ingestedAt]
+          additionalProperties: false
+          properties:
+            kind: { type: string, enum: [repo_file] }
+            path: { type: string }
+            contentHash: { type: string }
+            ingestedAt: { type: integer }
+        trust: { type: string, enum: [untrusted] }
+        extra: { type: array, items: { type: string } }
+
+    MemoryEntry:
+      type: object
+      description: >
+        core `MemoryEntry` (@sema-agent/core memory-engine/types.d.ts) — one memory-engine (DB twins)
+        note. Used verbatim by both GET /v1/memory/export's `entries` and POST /v1/memory/sync/{scope}'s
+        `serverEntries` (server never re-shapes it — memory-policy.ts:57 / memory-sync.ts:79 pass the core
+        array straight to `sendJson`).
+      required: [id, slug, frontmatter, body, rev, scope]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        slug: { type: string }
+        frontmatter: { $ref: '#/components/schemas/MemoryEntryFrontmatter' }
+        body: { type: string }
+        rev: { type: string }
+        scope: { type: string }
+
+    MemorySyncResponse:
+      type: object
+      description: >
+        200 body of POST /v1/memory/sync/{scope} — core `MemorySyncResponse` (server memory-sync.ts:74-86),
+        `sendJson`'d verbatim (memory-policy.ts:107). `pullTruncated` is OMIT-when-absent (present+`true`
+        only when `serverEntries` was cut by `?pull.limit`).
+      required: [applied, conflicts, serverEntries, serverDeletes, cursor]
+      additionalProperties: false
+      properties:
+        applied:
+          type: array
+          description: The center's own-round applied ops (backend `PatchReport.applied` verbatim; empty on an idempotent replay).
+          items:
+            type: object
+            required: [op, id]
+            additionalProperties: false
+            properties:
+              op: { type: string, enum: [add, update, delete] }
+              id: { type: string }
+              slug: { type: string }
+        conflicts:
+          type: array
+          items:
+            type: object
+            required: [id, reason]
+            additionalProperties: false
+            properties:
+              id: { type: string }
+              reason: { type: string }
+              baseRev: { type: string }
+              currentRev: { type: string }
+        serverEntries:
+          type: array
+          description: Pull half — entries new/changed at the center since the caller's baseRevs.
+          items: { $ref: '#/components/schemas/MemoryEntry' }
+        serverDeletes:
+          type: array
+          items:
+            type: object
+            required: [id, baseRev]
+            additionalProperties: false
+            properties:
+              id: { type: string }
+              baseRev: { type: string }
+        cursor:
+          type: object
+          required: [peer, baseRevs, updatedAtMs]
+          additionalProperties: false
+          properties:
+            peer: { type: string }
+            baseRevs: { type: object, additionalProperties: { type: string } }
+            updatedAtMs: { type: integer }
+        pullTruncated: { type: boolean, enum: [true] }
+
+    MetricsSummaryOps:
+      type: object
+      description: >
+        200 body of GET /metrics/summary — `{ model, ...MetricsSummary }` (server.ts:794; server
+        observability/metrics.ts `MetricsSummary` interface + `summarize()`, all keys unconditional).
+        Ops/observability face (`x-sdk: none` on the path) — closed here for census fidelity, but this
+        does NOT change its SDK-wrapping status.
+      required:
+        [model, runsActive, tasks, tokensTotal, costUsd, costUsdByModel, costUnknown, unpricedCalls,
+         taskDurationAvgSec, brainFirstTokenAvgMs, brainCallAvgMs, cacheHitRateAvg, promptCacheLowHit,
+         rateLimited, costQuotaRejected, budgetExceeded, degraded, degenerate, memoryConsolidationOps,
+         planCacheRecurrence, cascade, verifications, councilRuns, toolErrors]
+      additionalProperties: false
+      properties:
+        model: { type: string }
+        runsActive: { type: integer }
+        tasks: { type: object, additionalProperties: { type: integer } }
+        tokensTotal: { type: integer }
+        costUsd: { type: number }
+        costUsdByModel: { type: object, additionalProperties: { type: number } }
+        # D5 ([2122]): true ⇒ the window saw a cost-unknown brain.call (unpriced deployment) — costUsd/
+        # costUsdByModel are then a LOWER BOUND, not an exact total.
+        costUnknown: { type: boolean }
+        unpricedCalls: { type: integer }
+        taskDurationAvgSec: { type: [number, 'null'] }
+        brainFirstTokenAvgMs: { type: [number, 'null'] }
+        brainCallAvgMs: { type: [number, 'null'] }
+        cacheHitRateAvg: { type: [number, 'null'] }
+        promptCacheLowHit: { type: integer }
+        rateLimited: { type: integer }
+        costQuotaRejected: { type: integer }
+        budgetExceeded: { type: object, additionalProperties: { type: integer } }
+        degraded: { type: object, additionalProperties: { type: integer } }
+        degenerate: { type: object, additionalProperties: { type: integer } }
+        memoryConsolidationOps: { type: object, additionalProperties: { type: integer } }
+        planCacheRecurrence:
+          type: object
+          required: [tasks, hits, hitRate]
+          additionalProperties: false
+          properties:
+            tasks: { type: integer }
+            hits: { type: integer }
+            hitRate: { type: [number, 'null'] }
+        cascade: { type: object, additionalProperties: { type: integer } }
+        verifications: { type: object, additionalProperties: { type: integer } }
+        councilRuns: { type: object, additionalProperties: { type: integer } }
+        toolErrors: { type: object, additionalProperties: { type: integer } }
+
     ModelInfo:
       type: object
       description: >
@@ -4760,14 +5355,19 @@ components:
       type: object
       description: >
         GET /v1/workflows list row = core summarizeWorkflowRun projection (owner-scoped; scope = the creating
-        principal). All times are epoch MS. Open set.
+        principal). All times are epoch MS.
+        🔴 census 批2 四段(2026-07-30):CLOSED against core's real `summarizeWorkflowRun` (sema-core
+        src/core/workflow-run-store.ts:79-97) — `originatingSessionId`/`agentFailures` were emitted on the
+        wire (both conditional-spread, present only when defined) but absent from this schema (two-side same-gap).
       required: [id, scope, status, phaseCount, agentCount, tokens, startedAt, createdAt]
-      additionalProperties: true
+      additionalProperties: false
       properties:
         id: { type: string, description: 'Run id (= WorkflowRun.id).' }
         scope: { type: string, description: 'Tenant/group scope (= the creating principal).' }
+        originatingSessionId: { type: string, description: 'γ 批([1510]): the originating session id, so a LIST-face session filter needs no N+1 `get`. Absent for a direct runWorkflow call / sessionless deployment.' }
         name: { type: string, description: "The workflow script's declared `meta.name`." }
         description: { type: string, description: "The workflow script's declared `meta.description` (one-liner)." }
+        agentFailures: { type: integer, description: 'Count of agent-runs that ended failed — present only when > 0 (a "completed, with failures" flag without an N+1 get).' }
         currentPhase: { type: string, description: 'Title of the phase currently executing (absent once terminal).' }
         status: { $ref: '#/components/schemas/WorkflowRunStatus' }
         phaseCount: { type: integer, description: 'Phases recorded.' }
@@ -4787,25 +5387,40 @@ components:
         🔴 `arg` is a SHORT primary-arg SUMMARY (command→name, path→basename, url→origin+path), secret-scrubbed
         and truncated (~80 code points) by core. It exists for the monitor's `Read(path)` / `Bash(grep …)`
         display — it is NOT the full args. RENDER it; NEVER re-feed it to a model.
-      additionalProperties: true
+        🔴 census 批2 四段:CLOSED against core's real `ToolActivity` (sema-core src/core/types.ts:2332-2348) —
+        `at` (the [843]④a epoch-ms stamp, carried verbatim by both the start and end beat) was on the wire
+        but absent from this schema.
+      required: [phase, toolCallId, toolName]
+      additionalProperties: false
       properties:
         phase: { type: string, enum: [start, end] }
         toolCallId: { type: string }
         toolName: { type: string, description: 'the monitor renders `${toolName}(${arg})`.' }
+        at: { type: integer, description: '[843]④a: epoch ms, stamped on both the start and end beat — a consumer derives per-call duration (end.at − start.at) and inter-call idle. Additive/optional: older producers lack it (absence ≠ 0).' }
         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: {}`(零形状)。
+      # 🔴 census 批2 四段:CLOSED against the REAL wire projection — server's `summarizeWorkflowDetail`
+      # (src/http/routes/workflows.ts:358-394), not core's raw `WorkflowAgentRun`. The two differ: the server
+      # ADDS `displayStatus`/`callKey`/`groupId`/`lastActivityAt`/`durationMs`/`queuedAt`/`startedAt`/`endedAt`/
+      # `replayed` (all present on the wire but previously undeclared — same-side gap, no server change needed)
+      # and DROPS core's `errorCode`/`errorMessage`/`attempts`/`lastAttemptReason`/`sessionId` (never projected
+      # by this route — genuinely absent from the wire, not a spec lie).
       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
+        One agent-run row in a workflow's detail (server projection, not the raw core record).
+      required: [label, status, displayStatus, callKey, queuedAt]
+      additionalProperties: false
       properties:
-        label: { type: string, description: 'display label.' }
+        label: { type: string, description: 'display label (redacted — LLM-authored).' }
         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).' }
+        displayStatus: { type: string, description: 'core deriveAgentDisplayStatus: running|queued|done|failed|interrupted — the canonical glyph vocabulary, one source of truth shared with the shell.' }
+        taskStatus: { type: string, description: 'the underlying task''s terminal TaskStatus (open vocabulary; core enum verbatim).' }
+        callKey: { type: string, description: 'the stable deterministic identity of this ctx.agent call (resume-journal key).' }
+        groupId: { type: string, description: 'the nesting ctx.workflow sub-group this agent ran under; absent = top-level.' }
+        phase: { type: string, description: 'the phase title this agent ran under (redacted — LLM-authored); absent = unphased.' }
         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 }
@@ -4814,44 +5429,149 @@ components:
           type: array
           description: 'the "Activity" tail — the LAST-N tool-call beats (bounded).'
           items: { $ref: '#/components/schemas/WorkflowActivityBeat' }
+        lastActivityAt: { type: integer, description: 'the tail activity beat''s `at` timestamp — a historical view, so the shell derives idleness against its own clock rather than a served idleMs.' }
+        durationMs: { type: integer, description: 'endedAt − startedAt; absent while queued/running or if either end is unset (a queued agent has no running duration).' }
+        queuedAt: { type: integer, description: 'when the agent was ENQUEUED (before waiting on a concurrency slot). Always set.' }
+        startedAt: { type: integer, description: 'when the agent actually started running (post-queue). Absent while queued, or if aborted/finalized before it ran.' }
+        endedAt: { type: integer }
+        replayed: { type: boolean, description: 'set when this agent''s result was REPLAYED from a resume journal rather than freshly run.' }
         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:
+    WorkflowPhaseProgress:
+      # 新(census 批2 四段):此前 `WorkflowRun.phases` 是 `items: {}`(零形状)。真形 = server
+      # `summarizeWorkflowDetail`'s phases.map projection (workflows.ts:335-346) — a DERIVED progress view,
+      # not core's raw `WorkflowPhase` (drops `detail`/`model`/(phase-level) `agentFailures`; adds `done`/`total`).
       type: object
-      description: >
-        GET /v1/workflows/:id full run (core WorkflowRun). Non-owner → 404 (no existence oracle).
-        🔴 phases/agents/stats nested shapes may evolve → permissive (read length/known fields, tolerate the rest).
-      required: [id, scope, status, phases, agents, stats, startedAt, createdAt]
-      additionalProperties: true
+      description: One phase's progress in a workflow's detail (server-derived — done/total of the agents grouped under it).
+      required: [title, status, startedAt, done, total]
+      additionalProperties: false
       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: {} }
-        # `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:
+        title: { type: string, description: 'phase title (redacted — LLM-authored).' }
+        status: { type: string, description: 'core WorkflowItemStatus, plus "pending" for a meta-preregistered phase not yet adopted.' }
+        startedAt: { type: integer, description: 'adoption time for a pre-registered phase (0 while still pending).' }
+        endedAt: { type: integer }
+        durationMs: { type: integer, description: 'endedAt − startedAt; absent until the phase ends.' }
+        done: { type: integer, description: 'agents grouped under this phase whose status is a terminal (completed/failed).' }
+        total: { type: integer, description: 'agents grouped under this phase.' }
+
+    WorkflowGroupNode:
+      # 新(census 批2 四段):`WorkflowRun.groups` was undeclared entirely. Real shape = server's rebuilt nested
+      # tree (workflows.ts:399-441, GroupNode) — recursive, acyclic (a dangling/cyclic parentGroupId is grafted
+      # onto the root by the server, so this shape never actually cycles on the wire).
+      type: object
+      description: One node of the workflow's nested `ctx.workflow` group tree (rebuilt server-side from `parentGroupId`).
+      required: [groupId, status, startedAt, agentCallKeys, children]
+      additionalProperties: false
+      properties:
+        groupId: { type: string }
+        parentGroupId: { type: string, description: 'absent = top-level (a child of the implicit root).' }
+        status: { type: string, description: 'core WorkflowItemStatus (running/completed/failed).' }
+        startedAt: { type: integer }
+        endedAt: { type: integer }
+        durationMs: { type: integer, description: 'endedAt − startedAt; absent until the group ends.' }
+        agentCallKeys: { type: array, items: { type: string }, description: 'callKeys of the agents directly under this group.' }
+        children: { type: array, items: { $ref: '#/components/schemas/WorkflowGroupNode' }, description: 'nested child groups (recursive).' }
+
+    WorkflowRunStats:
+      # 新(census 批2 四段):此前 inline `stats` 只钉了 `tokens`/`nested.tokens` 两键;真形 = core
+      # `WorkflowRunStats`(sema-core src/orchestration/workflow-types.ts:105-110)——own/nested 各自还有
+      # `turns`/`costMicroUsd`,nested 另有 `tasks`。四键(own turns/costMicroUsd + nested 两键)此前两侧同缺。
+      type: object
+      description: 'Cumulative workflow usage. `own` (top-level) and `nested` (delegated sub-agents) are kept SEPARATE (R-5) — total spend = tokens + nested.tokens.'
+      required: [tokens, turns, costMicroUsd, nested]
+      additionalProperties: false
+      properties:
+        tokens: { type: integer }
+        turns: { type: integer }
+        costMicroUsd: { type: integer }
+        nested:
           type: object
-          description: 'Token stats — own at stats.tokens, nested at stats.nested.tokens (R-5 own/nested split).'
-          additionalProperties: true
+          required: [tokens, turns, tasks, costMicroUsd]
+          additionalProperties: false
           properties:
             tokens: { type: integer }
-            nested:
-              type: object
-              additionalProperties: true
-              properties:
-                tokens: { type: integer }
+            turns: { type: integer }
+            tasks: { type: integer }
+            costMicroUsd: { type: integer }
+
+    WorkflowRun:
+      # 🔴 census 批2 四段:CLOSED against the REAL wire projection — server's `summarizeWorkflowDetail`
+      # (src/http/routes/workflows.ts:317-475), which is a DERIVED view over core's `WorkflowRun`, not the raw
+      # record. This schema previously mirrored (a stale subset of) the core type; the actual wire adds
+      # `durationMs`/`unphased`/`groups` and drops core's `sourceTaskId`/`originatingSessionId`/`effectiveArgs`/
+      # `resultFull`/`completionId`/`resume`/`journalSkips` (never projected by this route — genuinely absent
+      # from the wire, not a spec lie). `agentFailures`/`rev`/`error`/`result` WERE on the wire but undeclared
+      # (two-side same-gap, this segment's fix).
+      type: object
+      description: 'GET /v1/workflows/:id full run detail (server-derived — Phases/agents/groups panels). Non-owner → 404 (no existence oracle).'
+      required: [id, scope, status, stats, startedAt, createdAt, phases, agents, groups]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        scope: { type: string }
+        name: { type: string, description: "The workflow script's declared `meta.name` (redacted)." }
+        description: { type: string, description: "The workflow script's declared `meta.description` (redacted, one-liner)." }
+        status: { $ref: '#/components/schemas/WorkflowRunStatus' }
+        agentFailures: { type: integer, description: 'run-level count of agents whose status ended failed — stamped at run end, only when > 0.' }
+        stats: { $ref: '#/components/schemas/WorkflowRunStats' }
         startedAt: { type: integer }
         endedAt: { type: integer }
         createdAt: { type: integer }
+        durationMs: { type: integer, description: 'endedAt − startedAt; absent while the run is still running.' }
+        rev: { type: integer, description: 'store optimistic-concurrency revision; unset for a pure in-memory run.' }
+        error: { type: string, description: 'set when status === "failed": the error the script threw.' }
+        result: { type: string, description: 'the script''s RETURN VALUE (bounded + redacted). Absent on failed/pre-1.234 runs.' }
+        phases:
+          type: array
+          description: 'Phase progress records.'
+          items: { $ref: '#/components/schemas/WorkflowPhaseProgress' }
+        unphased:
+          type: object
+          description: 'done/total of agents with no phase (or a stray phase matching no registered entry). Present only when non-empty.'
+          required: [done, total]
+          additionalProperties: false
+          properties:
+            done: { type: integer }
+            total: { type: integer }
+        agents:
+          type: array
+          description: 'Agent-run records.'
+          items: { $ref: '#/components/schemas/WorkflowAgentRow' }
+        groups:
+          type: array
+          description: 'The nested ctx.workflow group tree (roots only — children nest recursively). Empty when the script used no nesting.'
+          items: { $ref: '#/components/schemas/WorkflowGroupNode' }
+
+    WorkflowJournalEntry:
+      # 新(census 批2 四段):GET /v1/workflows/:id/journal row, the non-truncated arm (server `projectResult`,
+      # workflows.ts:127-134) — one agent()-call's cached TaskResult, bounded + redacted.
+      type: object
+      description: One journal entry — a completed agent() call's projected TaskResult (bounded + redacted).
+      required: [callKey, ordinal, status]
+      additionalProperties: false
+      properties:
+        callKey: { type: string }
+        ordinal: { type: integer, description: 'callKeyOrdinal(callKey) — the stable resume/display order.' }
+        status: { type: string, description: 'the TaskResult''s terminal status (open vocabulary; core enum verbatim).' }
+        error: { type: string, description: 'first line of errorMessage, clipped to 300 chars (redacted). Present only when the result carried an errorMessage.' }
+        result: { type: string, description: 'the result text, clipped to 2000 chars (redacted). Present only when the result carried one.' }
+        tokens: { type: integer, description: 'present only when the result carried stats.' }
+        turns: { type: integer, description: 'present only when the result carried stats.' }
+
+    WorkflowJournalEntryTruncated:
+      # 新(census 批2 四段):the truncated arm (workflows.ts:141-142/159-162) — an honest stub for a row whose
+      # stored TaskResult exceeded the per-row 64KiB gate (SQL stores) or byte length (file/in-memory
+      # fallback): the server never pulls the oversized payload into process memory.
+      type: object
+      description: A journal row too large to project — an honest "too big to show" stub, never a silent 2000-char truncation of the real result.
+      required: [callKey, ordinal, truncated, resultBytes]
+      additionalProperties: false
+      properties:
+        callKey: { type: string }
+        ordinal: { type: integer }
+        truncated: { type: boolean, enum: [true] }
+        resultBytes: { type: integer, description: 'the stored TaskResult''s byte length (so a UI can at least show the size).' }
 
     WorkflowStreamEvent:
       type: object
@@ -4878,8 +5598,11 @@ components:
     AttachmentInfo:
       type: object
       description: 'Upload receipt (POST /v1/attachments 201). `name` is the SANITIZED basename the server will materialize under `attachments/`.'
+      # 🔴 census 批2 五段(2026-07-30):CLOSED against the real emitter — `sendJson(res, 201, { id, name,
+      # mime, sha256, sizeBytes })` (server attachments.ts:90) is an EXACT 5-key object literal, never a
+      # superset.
       required: [id, name, mime, sha256, sizeBytes]
-      additionalProperties: true
+      additionalProperties: false
       properties:
         id: { type: string }
         name: { type: string }
@@ -6941,6 +7664,24 @@ components:
           description: 'Machine-branchable cause. CLOSED on the server side (fleet-bus.ts HookNotice.reason) but OPEN ON READ — branch known values, render anything else as the generic "could not evaluate".'
         detail: { type: string, description: 'Redacted supplement (e.g. why skipped). Additive / tolerate-absent.' }
 
+    BakeStatus:
+      # 新(census 批2 四段)——server `BakeStatus`(plugins/store-contracts.ts:83), the COARSE lifecycle
+      # bakeView/claimResponse/bakesCreate all key on.
+      type: string
+      enum: [queued, running, done, failed]
+
+    BakeState:
+      # 新(census 批2 四段)——server `BakeState`(store-contracts.ts:85-93), build.sh's finer 8-value state;
+      # null before the runner's first `state` line lands.
+      type: [string, 'null']
+      enum: [PENDING, BUILDING, PUSHING, VERIFYING, REGISTERING, COMPLETE, FAILED, CANCELLED, null]
+
+    BakeErrorCode:
+      # 新(census 批2 四段)——server `BakeErrorCode`(store-contracts.ts:96), the closed structured terminal
+      # code set (§P2.14 #2); null = success or an uncategorized failure.
+      type: [string, 'null']
+      enum: [band-conflict, duplicate, disk, timeout, cancelled, null]
+
     BakeClaim:
       type: object
       description: >
@@ -6949,8 +7690,11 @@ components:
         secret (minted at claim, echoed on every ingest via the x-bake-ingest-secret header) + the
         profile/bands the runner needs for its profile-aware hard deadline. The runner executes `argv`
         VERBATIM — it never assembles its own command line. 204 (no body) = queue empty.
-      required: [bakeId, argv, push, dryRun, profile, ingestSecret, leaseUntil]
-      additionalProperties: true
+        🔴 census 批2 四段:CLOSED + wired to both claim paths (this schema existed but neither path
+        `$ref`'d it — path↔schema 脱钩; both declared a bare open `{}` instead). `logs`/`bands` are
+        unconditionally assigned by claimResponse() but were absent from `required` — same-side gap.
+      required: [bakeId, argv, push, dryRun, logs, profile, bands, ingestSecret, leaseUntil]
+      additionalProperties: false
       properties:
         bakeId: { type: string }
         argv:
@@ -6959,23 +7703,128 @@ components:
           description: 'The server-assembled, whitelist-vetted build command — execute verbatim, never self-assemble.'
         push: { type: boolean }
         dryRun: { type: boolean }
-        logs: { description: 'Log routing config, passed through as stored (opaque to the claim contract).' }
+        logs: { type: boolean, description: 'Log routing config, passed through as stored.' }
         profile: { type: string }
-        bands: { description: 'Profile bands for the runner''s profile-aware hard deadline (opaque passthrough).' }
+        bands: { type: [array, 'null'], items: { type: string }, description: 'Profile bands for the runner''s profile-aware hard deadline (opaque passthrough); null when the bake carries none.' }
         ingestSecret: { type: string, description: 'Per-bake credential — the ONLY place it leaves image-api; echo it on every ingest.' }
         leaseUntil:
           description: 'Lease expiry (epoch ms or ISO timestamp depending on store backend).'
           oneOf: [{ type: number }, { type: string }]
 
+    BakeRecordView:
+      # 新(census 批2 四段)——GET /v1/images/bakes/{bakeId}'s `{ bake }` envelope. Exact key set = server
+      # `bakeView()` (images.ts:527-551): the durable BakeRecord MINUS the runner-internal secret/lease fields
+      # (ingestSecret/runnerId/leaseUntil/cancelRequested/argv — an ops surface, not the claim credential).
+      type: object
+      description: The operator poll view of one bake (server bakeView projection over the durable BakeRecord).
+      required:
+        [bakeId, status, state, profile, bands, baseRef, push, dryRun, logs, digest, repo, ref, indexId,
+         exitCode, error, errorCode, manifestSha, tag, requestedBy, createdAt, updatedAt]
+      additionalProperties: false
+      properties:
+        bakeId: { type: string }
+        status: { $ref: '#/components/schemas/BakeStatus' }
+        state: { $ref: '#/components/schemas/BakeState' }
+        profile: { type: string }
+        bands: { type: [array, 'null'], items: { type: string } }
+        baseRef: { type: [string, 'null'] }
+        push: { type: boolean }
+        dryRun: { type: boolean }
+        logs: { type: boolean }
+        digest: { type: [string, 'null'] }
+        repo: { type: [string, 'null'] }
+        ref: { type: [string, 'null'] }
+        indexId: { type: [string, 'null'] }
+        exitCode: { type: [integer, 'null'] }
+        error: { type: [string, 'null'] }
+        errorCode: { $ref: '#/components/schemas/BakeErrorCode' }
+        manifestSha: { type: [string, 'null'] }
+        tag: { type: [string, 'null'] }
+        requestedBy: { type: [string, 'null'] }
+        createdAt: { type: string, description: ISO date-time. }
+        updatedAt: { type: string, description: ISO date-time. }
+
+    BakeSubmitAck:
+      # 新(census 批2 四段)——POST /v1/images/bakes 202 body. All three code paths (attach-to-in-flight,
+      # atomic-admission-created, dryRun) produce this SAME shape (images.ts:193/206/213/217).
+      type: object
+      description: Acknowledgement of a submitted/attached-to bake.
+      required: [bakeId, eventsUrl, status, state]
+      additionalProperties: false
+      properties:
+        bakeId: { type: string }
+        eventsUrl: { type: string, description: '`/v1/images/bakes/{bakeId}/events` — the SSE resource to attach to.' }
+        status: { $ref: '#/components/schemas/BakeStatus' }
+        state: { $ref: '#/components/schemas/BakeState' }
+
+    BakeCancelAck:
+      # 新(census 批2 四段)——POST /v1/images/bakes/{bakeId}/cancel 202 body (images.ts:239-241). `note` is
+      # ALWAYS present (a ternary VALUE, not a conditional key) — the spec previously implied it was optional.
+      type: object
+      description: Cooperative-cancel acknowledgement (a durable flag; the runner kills the build at its next heartbeat).
+      required: [bakeId, cancelRequested, note]
+      additionalProperties: false
+      properties:
+        bakeId: { type: string }
+        cancelRequested: { type: boolean, enum: [true] }
+        note: { type: string, description: 'always one of two fixed strings: "cancel requested — …" or "bake already terminal — cancel is a no-op".' }
+
+    BakeIngestAck:
+      # 新(census 批2 四段)——POST /v1/images/bakes/{bakeId}/ingest 200 body. 🔴 FOUR distinct shapes share
+      # this one status code (images.ts:302-334): a heartbeat ack carries no `seq`; a non-terminal frame ack
+      # carries `seq` but no `terminal`; a terminal `done` carries `terminal`+`indexId` (success) OR
+      # `terminal`+`needsFlip` (the bounded-retry-exhausted non-throw path, still 200 — the runner re-POSTs the
+      # idempotent done to re-drive the flip). `cancelRequested`+`leaseValid` ride on every non-heartbeat shape
+      # (merged in at the send site); the heartbeat shape sets them directly instead.
+      description: One ingest acknowledgement (four shapes keyed by which fields are present).
+      oneOf:
+        - type: object
+          description: Heartbeat ack (lease renewed; no event appended).
+          required: [accepted, leaseValid, cancelRequested]
+          additionalProperties: false
+          properties:
+            accepted: { type: boolean, enum: [true] }
+            leaseValid: { type: boolean }
+            cancelRequested: { type: boolean }
+        - type: object
+          description: Non-terminal build.sh line appended (resolved/state/step/image/manifest/log).
+          required: [accepted, seq, cancelRequested, leaseValid]
+          additionalProperties: false
+          properties:
+            accepted: { type: boolean, enum: [true] }
+            seq: { type: integer }
+            cancelRequested: { type: boolean }
+            leaseValid: { type: boolean, enum: [true] }
+        - type: object
+          description: Terminal `done` — the coarse-status CAS was won and the register step succeeded (or the bake never registers, e.g. a non-COMPLETE terminal).
+          required: [accepted, terminal, indexId, cancelRequested, leaseValid]
+          additionalProperties: false
+          properties:
+            accepted: { type: boolean, enum: [true] }
+            terminal: { type: boolean }
+            indexId: { type: [string, 'null'] }
+            cancelRequested: { type: boolean }
+            leaseValid: { type: boolean, enum: [true] }
+        - type: object
+          description: Terminal `done` — the bounded setTerminal retry was exhausted; a non-terminal 200 asks the runner to re-POST the (lineOrd-idempotent) done to re-drive the flip.
+          required: [accepted, terminal, needsFlip, cancelRequested, leaseValid]
+          additionalProperties: false
+          properties:
+            accepted: { type: boolean, enum: [true] }
+            terminal: { type: boolean, enum: [false] }
+            needsFlip: { type: boolean, enum: [true] }
+            cancelRequested: { type: boolean }
+            leaseValid: { type: boolean, enum: [true] }
+
     OutcomeRow:
       type: object
       description: >
         One task-outcome ledger row of GET /v1/outcomes (envelope key `outcomes`; design/73 §7 read-only
         base). Shape = the SQL ledgers' per-(taskSignature, model) summary projection (server
-        tidb-outcome-ledger.ts:186 / pg-outcome-ledger.ts:124 — the only queryable sinks; a File sink
-        501s honestly). OPEN set — mechanical-signal read-only surface.
+        outcome-ledger-sql.ts `summary()` — the only queryable sink; a File sink 501s honestly).
+      # 🔴 census 批2 五段:CLOSED — the exact 5-key `.map()` projection, no sixth key.
       required: [taskSignature, model, n, passRate, meanCostMicroUsd]
-      additionalProperties: true
+      additionalProperties: false
       properties:
         taskSignature: { type: string }
         model: { type: string }
@@ -6990,8 +7839,10 @@ components:
         nextBefore?}`; server src/http/routes/sessions-list.ts — exact projection). A principal caller is PINNED to its
         own scope (?scope= ignored); a fleet credential may pass ?scope= (default = the single-user
         sentinel "_"). Page with `before` = a previous page's `nextBefore` (uuidv7; malformed → 400).
+      # 🔴 census 批2 五段:CLOSED — exact projection (sessions-list.ts:94-105); taskId/sessionId are the
+      # only OMIT-when-absent keys, no others.
       required: [id, filename, size, ttlSec, track, bucket, key, createdAt]
-      additionalProperties: true
+      additionalProperties: false
       properties:
         id: { type: string, description: 'uuidv7 link id — also the `before` pagination cursor.' }
         filename: { type: string }
@@ -7347,13 +8198,16 @@ components:
         The 200 receipt of POST /v1/workflows/{runId}/agents/{label}/steer (server src/http/routes/workflows.ts —
         exact literal: `status:"running"`, `delivery:"applied"`, `marker` = the engine-minted delivery
         marker; NO `note`, unlike the run-subagent verb).
-      required: [runId, label]
-      additionalProperties: true
+      # 🔴 census 批2 五段:CLOSED — all 5 keys are unconditional in the literal
+      # `{ runId: wfRunId, label, status: "running", delivery: "applied", marker }` (workflows.ts:279);
+      # this schema previously existed but no path `$ref`'d it (see the path fix above).
+      required: [runId, label, status, delivery, marker]
+      additionalProperties: false
       properties:
         runId: { type: string }
         label: { type: string }
-        status: { type: string, description: 'Literal "running" on today''s server.' }
-        delivery: { type: string, description: 'Literal "applied" on today''s server.' }
+        status: { type: string, const: running, description: 'Literal "running" on today''s server.' }
+        delivery: { type: string, const: applied, description: 'Literal "applied" on today''s server.' }
         marker: { type: string, description: 'Engine-minted delivery marker.' }
 
     WorkspaceSnapshotRow: