@sema-agent/sdk 7.3.0 → 8.0.0

package/openapi.yaml

@@ -1962,6 +1962,73 @@ paths:
               schema: { $ref: '#/components/schemas/McpStatusPanel' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
+  /v1/sessions/{sessionId}/memory-status:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsMemoryStatus
+      x-status: live             # S-53 seam① (server 7.53.0; core 7.0.2 #511 item 1 / design/383 §S-7); SDK sessions.memoryStatus.
+      summary: Session memory status — the pure-derivation projection of core's `sessionMemoryStatus`.
+      description: >
+        S-53 seam① (server >=7.53, core 7.0.2 #511 item 1; board [5785]/[5786] key shapes). 200 body =
+        `{sessionId}` + core `MemoryEngine.sessionMemoryStatus(sessionId)` (`SessionMemoryStatus`) projected
+        KEY BY KEY (each of the five optional keys is copied only when present). 🔴 ABSENCE IS HONEST, NOT A
+        DEFAULT — but its meaning is PER KEY (read off core 7.0.2 `engine.js sessionMemoryStatus`, not off a
+        blanket rule): `captureOptedOut` absent = the record store faulted (then `optOutSource:"fault"` rides
+        along; indeterminate ≠ false); `optOutSource` absent = store readable and NO opt-out record (the
+        HEALTHY default — it is only minted as `record`/`fault`); `committedCount` absent = lineage ledger
+        unreadable (a session with no contribution gets `0`, not absence); `lastCaptureAt` absent = ledger
+        unreadable OR no committed contribution at all (a healthy empty session omits it); `foldedCount`
+        absent = ledger unreadable, or the backend cannot enumerate scopes, or the product read failed (`0`
+        when there is nothing to fold). A zero-history session therefore reads
+        `{sessionId, captureOptedOut:false, committedCount:0, foldedCount:0}` — two keys absent and NOTHING
+        degraded. The server never coins a `false`/`0` stand-in for a faulted source. Gate order, same family as the erase
+        face: 401 (multi-tenant, no principal — BEFORE any store read: zero existence oracle) → 501
+        `capability.memory_engine_required` (no owner audit face: a deployment without one must not fake a 404)
+        → 404 `not_found.session` (unknown AND non-owner — SAME code, SAME message; anti-enumeration) → 501
+        `capability.memory_engine_required` (status face absent: engine not wired / the pg+tidb memory backends
+        do not own the control plane — same code as the first 501) → 200. 400 `request.path_malformed` on a bad
+        percent-encoded id segment. Non-billable, non-mutating; served through a short-TTL single-flight cache
+        per session id. 🔴 NO capability bit advertises this face (deliberately — [5785]/[5786] fixed no bit
+        name): the route answers for itself; probe by calling it, a 501 is the honest "not on this deployment".
+        🔴 VERSION SKEW (codex R2; the SDK support floor is far below 7.53): a supported OLDER server
+        (<7.53) has no such route and answers the version-stable generic fallback 404 `not_found.route` —
+        treat it like the 501 ("face not here"), and distinguish it BY errorCode from this op's own 404
+        `not_found.session` (unknown/non-owner session). Same HTTP status, different codes — never collapse
+        the two.
+        Cross-incarnation caveat (server-side, cannot be fixed at this layer): the capture record and the
+        lineage ledger are keyed by the BARE sessionId and outlive the session, so a re-claimed id reads the
+        PREVIOUS incarnation's counts/opt-out (metadata only, no content bytes).
+      responses:
+        '200':
+          description: >-
+            The session's memory status. Absence is PER-KEY (see SessionMemoryStatusResponse): a healthy
+            zero-history session omits `optOutSource`/`lastCaptureAt` while answering
+            `captureOptedOut:false, committedCount:0, foldedCount:0` — nothing degraded; the other keys are
+            absent only when their source could not be read.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionMemoryStatusResponse' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500':
+          description: >-
+            errorCode "internal.error" — `routes/sessions.ts`'s catch around `face.status(sessionId)`: core
+            promises the face never throws, so reaching this arm is an assembly defect; the server fails LOUD
+            (500) rather than answering a plausible all-keys-absent body. The SDK maps it to
+            `InternalServerError`. (codex R1 of the 7.3.1 batch: the arm exists in the shipped 7.53.0 route and
+            was missing here.)
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
   # ── 2c session-sync (P1d) — the cloud as a SYNC PEER ──────────────────────────────────────────────────────────
   # The local shell's local backend ⇄ this cloud service. PULL a session's whole state out, or PUSH the local
   # peer's in. Gate the whole surface off `capabilities.sessionSync` — a FOUR-way conjunction (durable backend
@@ -2466,7 +2533,11 @@ paths:
             member since core 5.7.0/RB-459: the content-ask `answer` payload was refused) — your binding does
             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.
+            to the human, NEVER auto-retry. (S-57, server >= 7.54.0: the `field:"boundCallId"` shape is
+            intercepted in steady state by the `approval_stale` second trigger source below — the server
+            compares the echoed boundCallId against the current pending pre-CAS and answers 409
+            `approval_stale` + `currentPending`; this code's boundCallId arm covers only the remaining race
+            window between that compare and the core CAS. The hash/answer arms are unchanged.)
             FOURTH member ([2400] CB-2, declared 2026-08-02): `gate_not_tool_approval` — the suspension this
             sessionId is parked on is NOT a tool-approval gate (`src/http/server.ts` rejects pre-CAS when the
             gate kind is neither `human` nor `irreversible_ask`: nothing is consumed, no model leg burns). It is
@@ -2474,6 +2545,14 @@ paths:
             `gate_not_plan_review` (§4c) → SDK `GateNotToolApprovalError`. Client action: route by the row's
             `gateKind` — `plan_review` → `POST /v1/assistant/tasks/{taskId}/plan_review`, `resource_limit` →
             `POST /v1/assistant/tasks/{taskId}/resume`. Retrying the same body never succeeds.
+            SIXTH group (A-075.10, TIME-BASED retry-later pair): `resume.usage_window_exhausted` (#449 G1,
+            core 5.60.1 — the deployment governance window on this run's ledger key is full; NOTHING was
+            consumed or unpinned, the SAME token with the SAME decision redeems once the window slides) and
+            `resume.preflight_rejected` (#376, core 5.65 retry-later form). Both are PRE-CAS (the checkpoint
+            stays pending) and their body ADDITIVELY carries `retryAfterSec` (seconds, ceil, min 1; the
+            server mints the key ONLY on these two codes with a finite positive wait) → SDK
+            `ResumeRetryLaterError` (a `SubagentResumeConflictError` subclass so existing family catches
+            keep matching; `.retryAfterSec` is the actionable wait).
             FIFTH group ([2400] CB-2): the core `checkpoint.*` family the server mirrors verbatim
             (`src/http/server.ts`) — `checkpoint.gate_mismatch` / `checkpoint.reopen_failed` /
             `checkpoint.reopen_revote` / `checkpoint.already_exists` / `checkpoint.resume_aborted` /
@@ -2493,11 +2572,15 @@ paths:
             checkpointToken. Absent when there is no pending / the gate is not a tool approval / the row read
             failed (loud fail-open ledger arm) / an older server. Owner domain = the route's owner gate (no
             new disclosure surface). SDK: `ApprovalStaleError.currentPending`, whole-or-absent guard.
-            REACHABILITY (codex 复审 R1-[medium] 采纳成文): the stale arm fires only for callers that ECHO a
-            `checkpointToken`; this SDK's ApprovalDecision deliberately has no such field (removed in 1.0.0 —
-            resume credentials never ride the compliant decide), so decides issued through this SDK never
-            trigger it. The key is documented for the wire contract's sake: legacy shells and non-SDK callers
-            that still echo tokens DO reach it, and the SDK's read side stays typed for whatever arrives.
+            REACHABILITY (REWRITTEN for S-57, server >= 7.54.0): the stale arm now has TWO trigger sources —
+            (1) a caller echoing a legacy `checkpointToken` (this SDK's ApprovalDecision deliberately has no
+            such field, removed in 1.0.0 — resume credentials never ride the compliant decide), and
+            (2) an echoed `boundCallId` that does not match the session's CURRENT pending row (the COMPLIANT
+            SDK shape — the server compares pre-CAS and answers this 409 + `currentPending` directly; this
+            form never carries `terminal`). So a decide issued through this SDK DOES reach this 409 under
+            coordinate rotation (before S-57 that shape fell through to `approval_binding_mismatch` +
+            `field:"boundCallId"` with no pointer key; that arm now covers only the race window between the
+            server-side compare and the core CAS).
             ALSO an S-02 behavior NARROWING on this arm: an echoed `checkpointToken` that does NOT belong to
             this session, when the session has NO pending, now folds into the byte-identical 404
             `not_found.approval` (it used to 409 — a single-bit cross-tenant "who is parked on an approval"
@@ -5697,15 +5780,42 @@ components:
         Run state (`GET /v1/runs/:id`) — live shape per the pinned wire contract Drift 2: `result` is the NESTED TaskResult
         object (output text in result.result, stats in result.stats; NO top-level stats), and the error text
         field is `error` (not errorMessage; errorCode is floated up from result.errorCode).
-      # 封闭(census 轴一,2026-07-30):铸造点 routes/runs.ts 是一个逐键写死的字面量,恰好 10 键
-      # (taskId/sessionId/status/result/supervisorCost/suggestions/errorCode/error/jobId/source),与本
-      # properties 一一对上;只有前三键无条件在场(其余走 `?? undefined` ⇒ JSON 丢键)⇒ required 维持 3 键。
+      # 封闭(census 轴一,2026-07-30;A-075.21 回填后 12 键):铸造点 routes/runs.ts 是一个逐键写死的
+      # 字面量(taskId/sessionId/status/msSinceLastActivity/crossSliceUsage/result/supervisorCost/
+      # suggestions/errorCode/error/jobId/source),与本 properties 一一对上;只有 taskId/sessionId/status
+      # 无条件在场(其余走 `?? undefined` / 条件 spread ⇒ JSON 丢键)⇒ required 维持 3 键。
+      # (A-075.21:此前的「恰好 10 键」对 msSinceLastActivity(#245 S1)/crossSliceUsage([3833] S-4)
+      # 两条铸键路径结构性失明 —— server test/producer-contract.test.ts 的 S-4 登记钉逐字记着这笔账。)
       additionalProperties: false
       required: [taskId, sessionId, status]
       properties:
         taskId: { type: string }
         sessionId: { type: string }
         status: { $ref: '#/components/schemas/RunStatus' }
+        msSinceLastActivity:
+          type: integer
+          description: >
+            #245 S1 (server >= 7.18) — ms since the run's last activity (poll-face liveness evidence; same key
+            and semantics as the 409 conflict body). SAME-REPLICA BEST-EFFORT: absent when the poll lands on a
+            replica that never ran this run. Absence = cannot prove, NOT 0/fresh.
+        crossSliceUsage:
+          type: object
+          description: >
+            [3833] S-4 (server >= 7.48.0) — cross-slice governance-window usage, present only on a running
+            (non-stale) row polled on the replica that registered the window. Reading discipline: values are
+            LOWER BOUNDS (ledgered at turn boundaries, delegation subtree excluded); the three axes come in
+            PAIRS (an unconfigured cap omits its pair; spentMicroUsd may also be absent when unpriced — 0
+            would lie); WHOLE-KEY ABSENCE does NOT mean "nothing spent" (no cap / not running / wrong replica
+            / ledger unavailable are indistinguishable); on resumed legs the totals stay frozen on the first
+            slice's ledger, never overwritten by current env.
+          additionalProperties: false
+          properties:
+            totalTokens: { type: integer }
+            spentTokens: { type: integer }
+            totalBudgetMicroUsd: { type: integer, description: 'Integer micro-USD (display divides by 1e6).' }
+            spentMicroUsd: { type: integer, description: 'Integer micro-USD; absent on unpriced deployments (unknown, not 0).' }
+            maxSlices: { type: integer }
+            sliceCount: { type: integer }
         result: { $ref: '#/components/schemas/TaskResult' }
         errorCode:
           type: string
@@ -6358,6 +6468,20 @@ components:
             `resumeAt`); absent ⇒ an older server, send the old spelling. `rewindFiles` keeps its name (same
             affordance — "rewind can move files"); this bit is what tells the two epochs apart.
         manualCompact: { type: boolean, description: "`POST /v1/runs/:id/compact` (needs a run store)." }
+        configCatalog:
+          type: boolean
+          description: >-
+            S-32 (server >=7.53, `routes/capabilities.ts:731`): the `GET /v1/config/catalog` operator lane
+            (DESIGN-278 §5 S2 — deployment config self-description) is mounted on this DEPLOYMENT. TWO-term
+            conjunction, written against the route's own refusal arms: ① the `CONFIG_CATALOG_ENABLED` knob is
+            on (default on; a compliance deployment that turns it off makes the path a 404 — the valve-family
+            precedent) AND ② the operator principal list is NON-EMPTY (with an empty list the route 403s every
+            identity). 🔴 DEPLOYMENT-LEVEL AVAILABILITY, NOT THE CALLER'S AUTHORIZATION: the caller's own
+            identity is NOT in the predicate — the route additionally requires the CURRENT principal to be an
+            explicit operator (`routes/config-catalog.ts` `explicitOperatorOk`, else 403 `auth.operator_only`),
+            so a non-operator reads `true` and still gets 403. Show/invoke the catalog only for an identity you
+            have ALREADY established as an operator; the bit tells you whether that operator's control exists
+            here at all. `false` does not say WHICH term failed. ABSENT = an older server (<7.53), not "off".
         sessions: { type: boolean, description: "Session read face (`GET /v1/sessions/:id`)." }
         sessionList: { type: boolean, description: "`GET /v1/sessions` list/picker face." }
         sessionSearch: { type: boolean, description: "Server-side session search." }
@@ -7190,19 +7314,25 @@ components:
             note: { type: string }
     SessionWakeResult:
       # 4.3.0(SM-9):wake 200 形提成具名 schema(形与下面 /wake 路径的 200 逐字同源)。
+      # A-075.1(车AE,2026-09-01):#354 只修了 inline 路径 200,这只具名形停在旧二键 required、封闭形下
+      # 缺 `bindingEnforced` ⇒「逐字同源」自称为假、严格生成客户端拒收真响应。现与 inline 重新逐字对齐
+      # (spec.test.ts 的 A-075.1 组机器看守同源等式)。
       type: object
       description: >
         POST /v1/sessions/{sessionId}/wake 的 200 形。⚠️ 200 也可能带 `errorCode`(core 侧 `wake.*` 拒了) ——
-        按机器码分支,别只看 HTTP 状态码。
+        按机器码分支,别只看 HTTP 状态码。ACCEPTANCE form (durable row present, [3833] S-1): status
+        "resuming", the leg keeps running server-side. SYNCHRONOUS form (no durable run row): status is the
+        run's resulting terminal enum. `bindingEnforced` is always true on BOTH forms (both mint points).
       additionalProperties: false
-      required: [sessionId, status]
+      required: [sessionId, status, bindingEnforced]
       properties:
-        sessionId: { type: string }
-        status: { type: string, description: 'The run''s resulting status (core TaskStatus verbatim).' }
         taskId: { type: string, description: 'The active run id; OMITTED when no active row.' }
-        errorCode: { type: string, description: 'Failure code when the resumed leg failed / was refused.' }
-        errorMessage: { type: string, description: 'Human-readable failure detail (server-side secret-redacted).' }
-        retriable: { type: boolean, description: 'true = the park is STILL pending (re-parked); refetch and retry.' }
+        sessionId: { type: string }
+        status: { type: string, description: 'ACCEPTANCE form (durable row present, [3833] S-1): "resuming" — the leg keeps running server-side; follow GET /v1/runs/:id or the events tail for the outcome. SYNCHRONOUS form (no durable run row): the run''s resulting status (completed/failed/suspended/needs_review/blocked — core TaskStatus verbatim; "timeout" retired in core 5.8.0: walltime exhaustion now lands as failed + errorCode limits.max_walltime_exceeded).' }
+        bindingEnforced: { type: boolean, description: '[2400] HITL-12 generation probe — this server enforces decision-action binding. Always true (present on BOTH 200 forms).' }
+        errorCode: { type: string, description: 'Failure code when the resumed leg failed (e.g. `cancelled`). Synchronous form only — never on the acceptance form.' }
+        errorMessage: { type: string, description: 'Human-readable failure detail (server-side secret-redacted). Synchronous form only.' }
+        retriable: { type: boolean, description: 'true = the park is STILL pending (re-parked); refetch and retry. Synchronous form only.' }
     WorkflowJournalRow:
       # 🔴 census 批2 四段:CLOSED against server's real projected/truncated row shapes — a row is EITHER the
       # projected result OR an honest truncated stub(超 64KiB 的行从不进程内存,投影为 truncated stub)。
@@ -7596,27 +7726,29 @@ components:
         parentToolCallId: { type: string, description: 'The parent tool_use id VERBATIM (E2 domain, engine-minted) — [1832] P1-2, server >= 1.290 / engine 1.432; the terminal notification frame carries it too. Additive / tolerate-absent.' }
         ts: { type: integer }
     FleetFrame_hook_notice:
-      type: object
       description: >
-        server 1.280.0 (cli [1786]) — a hook adjudication FAILED TO COMPLETE this cycle (observability frame,
-        pure observe: it does not block, resume, or inject anything). Semantics are "could not evaluate", NOT
-        "evaluated to fail" — render as "this cycle went unguarded, allowed through", never "the guard is broken".
-        Wire is FLAT (`send("hook_notice", { type, ...wire, ts })`, http/server.ts SSE outlet — the server-internal
-        `{notice}` nesting never reaches the wire). Visibility is fail-CLOSED like bg_notification: the owner keys
-        ownerScope/ownerSessionId gate delivery and are STRIPPED before send.
-      required: [type, kind, event, reason, ts]
+        Hook observability frame, TWO kinds (both pure observe — never block, resume, or inject anything;
+        visibility fail-CLOSED like bg_notification: the owner keys ownerScope/ownerSessionId gate delivery
+        and are STRIPPED before send; wire is FLAT — `send("hook_notice", { type, ...wire, ts })`, the
+        server-internal `{notice}` nesting never reaches it). codex R1-F4: modeled as the discriminated union
+        it really is — the common `{type, ts}` frame base composed with each kind's payload arm — so a
+        generated client gets the SAME per-kind narrowing as the TS type (a second-family frame missing
+        hookName/entryType is invalid, not silently accepted). `kind` is CLOSED two-member on the server but
+        OPEN ON READ: degrade an unknown future kind to a generic observability row.
+      oneOf:
+        - allOf:
+            - $ref: '#/components/schemas/FleetHookNoticeFrameBase'
+            - $ref: '#/components/schemas/FleetHookDecisionUnavailable'
+        - allOf:
+            - $ref: '#/components/schemas/FleetHookNoticeFrameBase'
+            - $ref: '#/components/schemas/FleetHookNonBlockingFailure'
+
+    FleetHookNoticeFrameBase:
+      type: object
+      description: 'The hook_notice frame envelope shared by both kinds: the SSE frame discriminant and the server timestamp.'
+      required: [type, ts]
       properties:
         type: { const: hook_notice }
-        kind:
-          type: string
-          enum: [hook_decision_unavailable]
-          description: 'Only one kind today; an enum slot so the next observability frame kind needs no new frame arm.'
-        event: { type: string, description: 'Which hook event (Stop / PreToolUse / …) — defined by "a hook adjudication did not complete", not any single feature.' }
-        reason:
-          type: string
-          enum: [no_content, unparsed, skipped]
-          description: 'Machine-branchable cause (same taxonomy as the server''s structured log lines). CLOSED on the server side but OPEN ON READ — an unknown future value must not crash a consumer.'
-        detail: { type: string, description: 'Redacted supplement (e.g. why skipped). Additive / tolerate-absent.' }
         ts: { type: integer }
 
     TraceStreamEvent:
@@ -7902,6 +8034,22 @@ components:
             presence may differ between the two legs for one ask. Derived from hot-reloadable governance knobs —
             long subscribers follow the stream's re-emitted frames. Absence ≠ "not governance-forced"; it means
             "no governance-origin evidence". Never written as false.
+        hasBidiControls:
+          type: boolean
+          enum: [true]
+          description: >
+            S-30① (server >=7.53; core 5.60.0 #438), ADDITIVE, present ONLY when true: the parked action's
+            execution payload contains at least one DIRECTIONAL formatting control (Trojan Source — what a
+            human reads may not be the byte order that executes). Value is ENTIRELY core-minted (the
+            `PendingAction.hasBidiControls` bit at park time; the SQL store denormalises it into the row's
+            `has_bidi_controls` column and reads `=== 1`, the local file store reads the parked
+            `pendingAction` bit `=== true` — neither recomputes). Rides BOTH durable
+            read faces through the same projection (this row on `GET /v1/approvals` and the `pending` frame of
+            `/v1/approvals/stream`). Never null, never false: ABSENCE = "not detected" (clean / core's bounded
+            scan did not reach it / a row parked before the column existed) and MUST NOT be read as "confirmed
+            clean". The live-card leg's sibling key is `inputHasBidi` (E-14, computed by the server over the
+            frame's own serialised args) — a different name on purpose. Display/triage only; never part of
+            resume / gate / CAS.
 
     # ── assistant-scheduler wire (ASSISTANT-WIRE-CONTRACT.md, service main 6cd0164 / core 1.110.0, LIVE) ──
     CheckpointSummary:
@@ -7966,6 +8114,17 @@ components:
         severity: { type: integer, minimum: 1, maximum: 5, description: 'Sort key; only human/irreversible_ask carry it.' }
         spentMicroUsd: { type: number, description: 'Accumulated spend on the suspend chain (micro-USD).' }
         deadline: { type: number, description: 'Awaiting-human SLA deadline (epoch ms).' }
+        hasBidiControls:
+          type: boolean
+          enum: [true]
+          description: >-
+            server >=7.53 (S-30① / core 5.60.0 #438), ADDITIVE, present ONLY when true: the parked action's
+            payload carries a DIRECTIONAL formatting control (Trojan Source). Third read face of the same
+            core-minted bit (`routes/approvals-assistant.ts` inbox whitelist arm `s.hasBidiControls === true`;
+            `summarizeCheckpoint` back-fills it for pre-bit rows on THIS face, so the absent set differs from
+            the /v1/approvals row's — the reading of absence does not). Absence = "not detected", never
+            "confirmed clean". Declared here because this schema is CLOSED — without the key a strict validator
+            rejects every >=7.53 inbox row that carries it.
         objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
         input:
           description: >
@@ -8334,6 +8493,53 @@ components:
           items: { $ref: '#/components/schemas/McpServerStatus' }
         degraded: { type: boolean }
 
+    SessionMemoryStatus:
+      type: object
+      description: >
+        core 7.0.2 `SessionMemoryStatus` (design/383 §S-7, #511 item 1; `dist/core/memory-engine/engine.d.ts`) —
+        SAME NAME, SAME SHAPE as core's export. Every key is optional, and each key's absence has ITS OWN
+        meaning (below, read off `engine.js sessionMemoryStatus`): two of them (`optOutSource`, `lastCaptureAt`)
+        are legitimately absent on a healthy session, the other three are absent only when their source could
+        not be read. A fault never coins a `false`/`0` stand-in.
+      # 封闭:core 的接口恰是这五键;server 逐键条件拷贝(禁 spread)⇒ 闭集本身。
+      additionalProperties: false
+      properties:
+        captureOptedOut:
+          type: boolean
+          description: 'TRUE = a standing capture opt-out record; FALSE = store readable, no record (capture on). ABSENT = the record store faulted — indeterminate (`optOutSource: "fault"` accompanies).'
+        committedCount:
+          type: integer
+          description: 'Committed entries carrying this session''s lineage contribution. Absent = ledger unreadable.'
+        foldedCount:
+          type: integer
+          description: 'Of those, entries already folded into consolidation products (lineage × `distilled.inputs`); `0` when the session has no contribution. Absent = lineage ledger unreadable, or the backend cannot enumerate scopes, or the product read failed.'
+        optOutSource:
+          type: string
+          enum: [record, fault]
+          description: 'WHY `captureOptedOut` reads as it does: `record` = a standing one-way record (rides with `captureOptedOut:true`); `fault` = the store faulted and the capture state is INDETERMINATE (rides with `captureOptedOut` ABSENT). ABSENT = store readable and no record (`captureOptedOut:false`) — the healthy default, NOT a fault. Closed two-value set, same as core.'
+        lastCaptureAt:
+          type: integer
+          description: 'Newest lineage `lastAt` for this session (ms epoch) — rides the same single ledger read as `committedCount`. Absent = ledger unreadable, or no committed contribution exists at all.'
+
+    SessionMemoryStatusResponse:
+      type: object
+      description: >
+        `GET /v1/sessions/{sessionId}/memory-status` 200 body (server >=7.53, S-53 seam①): `sessionId` + the
+        five `SessionMemoryStatus` keys copied ONE BY ONE when present (the server forbids spreading and forbids
+        defaults — the five conditional copies ARE the closed set). Per-key absence meaning = exactly
+        `SessionMemoryStatus` (a healthy zero-history session omits `optOutSource` and `lastCaptureAt`). Keys
+        are mirrored locally rather than via allOf so the closed schema stays self-describing (spec rule:
+        closed + allOf must mirror every key).
+      additionalProperties: false
+      required: [sessionId]
+      properties:
+        sessionId: { type: string, description: 'The session the status is about (echo of the path segment, percent-decoded).' }
+        captureOptedOut: { type: boolean, description: 'See SessionMemoryStatus.captureOptedOut — absent = indeterminate, never a coined false.' }
+        committedCount: { type: integer, description: 'See SessionMemoryStatus.committedCount.' }
+        foldedCount: { type: integer, description: 'See SessionMemoryStatus.foldedCount.' }
+        optOutSource: { type: string, enum: [record, fault], description: 'See SessionMemoryStatus.optOutSource — absent = no opt-out record (healthy), never a fault by itself.' }
+        lastCaptureAt: { type: integer, description: 'See SessionMemoryStatus.lastCaptureAt (ms epoch) — absent on a session with no committed contribution (healthy) as well as on an unreadable ledger.' }
+
     # ── 2c session-sync (P1d) — the cloud-as-a-SYNC-PEER schemas ──────────────────────────────────────────────
     SyncEntry:
       type: object
@@ -8651,10 +8857,12 @@ components:
         #   had no arm to switch on and dropped approval cards. Each arm is `allOf: [<the frame schema>, the
         #   narrowed discriminant]` — the key set stays owned by ToolApprovalFrame / ApprovalRequestFrame,
         #   so a frame gaining a key (7.5.0's governanceForced) needs no edit here.
-        #   `approval_revoke` is deliberately ABSENT: it is live-only and never appended.
+        #   `approval_revoke` joined as the FOURTH arm ([5924]/S-58, server >= 7.55.0): the bg/resume durable
+        #   legs append it to the run's ledger now (the sync leg stays live-SSE-only), so it replays here too.
         - $ref: '#/components/schemas/Event_tool_approval'
         - $ref: '#/components/schemas/Event_tool_approval_complete'
         - $ref: '#/components/schemas/Event_approval_request'
+        - $ref: '#/components/schemas/Event_approval_revoke'
       discriminator:
         propertyName: type
         mapping:
@@ -8697,6 +8905,7 @@ components:
           tool_approval: '#/components/schemas/Event_tool_approval'
           tool_approval_complete: '#/components/schemas/Event_tool_approval_complete'
           approval_request: '#/components/schemas/Event_approval_request'
+          approval_revoke: '#/components/schemas/Event_approval_revoke'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
@@ -9017,6 +9226,16 @@ components:
       properties:
         type: { const: task_progress }
         taskId: { type: string, description: 'The subagent task id (the delegated sub-run).' }
+        seq:
+          type: integer
+          description: >-
+            core 5.36.0 (#258), server-forwarded: the GENERATION number of the child's `a*` registry row
+            (fresh spawn = 1, +1 per revival; same axis as `TaskNotificationPayload.seq` and the fleet
+            `BackgroundChildEvent.seq`). Lets a consumer tell a late first frame of a known generation (same
+            value) from an un-folded revival (greater). ABSENT = the run has no `a*` row (sync delegated child /
+            workflow `wa*` / top-level) — no generation concept exists, do NOT read absence as cycle 1.
+            core-minted number, no user content. (codex R2 of the SDK 7.3.1 batch: this key was really on the
+            wire and this closed arm omitted it — a strict validator rejected every generation-tagged tick.)
         taskType:
           type: string
           description: >
@@ -9034,6 +9253,15 @@ components:
             durationMs: { type: integer }
         status: { type: string, description: 'running 为主;core [1414]#3 的 settle 终态 tick 亦可为 completed/failed(开集,按未知值兜底渲染)。' }
         name: { type: string, description: '子代的人类展示名(UNTRUSTED,已 redactSecrets)。缺席 ⇒ 无名,别回退到 objective。' }
+        model:
+          type: string
+          description: >-
+            server >=7.53 (core 7.0.1 #508①, P-42): the resolved catalog id of the model this child leg was
+            PREPARED with — same value/meaning as `TaskResult.model` (a mid-run degrade does NOT rewrite it; the
+            switch is disclosed on `TaskResult.degraded`). Minted unconditionally by both core task_progress
+            sites (running tick + settle terminal tick) and forwarded verbatim by the server whitelist on all
+            three live legs + the durable ledger row. ABSENT = an older producer (core <7.0.1 / server <7.53)
+            or unstated — never read absence as "no model". core-minted, no user content.
         parentTaskId: { type: string, description: '嵌套子代的上级 taskId;缺席 ⇒ 一级子代。' }
         currentAction: { type: string, description: '子代最近一次 tool_start 的一行人话("Bash npm test");UNTRUSTED,已 redactSecrets。' }
         workflowRunId: { type: string, description: 'core 1.401:后台 workflow 子代的不透明 run id(下游据此跳过与 fleet 行的重复渲染)。' }
@@ -10021,9 +10249,14 @@ components:
         clears that batch's local cards (whitelist-pick by `askIds`) and waits for the new askIds a resume mints.
 
         Siblings already DECIDED are NOT in `askIds` (an accepted decision is not affected by revocation).
-        Revoke frames CAN BE LOST (frames produced by the reconciler / orphan legs have no seq to allocate and
-        ride the live plane only) — the structural compensation is the open-stream preamble baseline (see
-        ApprovalRequestFrame), not a redelivery of this frame.
+        Emission is PER CONTEXT (S-58, server >= 7.55.0 — the old "reconciler/orphan legs have no seq, live
+        plane only" wording pinned a mint-site constraint on the delivery plane and is retired): the sync leg
+        stays live-SSE-only, the bg/resume durable legs append the frame to the run's own ledger and
+        GET /v1/runs/:id/events replays it (see Event_approval_revoke). Revoke frames CAN STILL BE LOST on any
+        leg (shell offline, connection drop, emit-target churn, ledger write failure — the frame is a
+        notification, the row is the source of truth) — the structural compensation is the open-stream preamble
+        baseline (see ApprovalRequestFrame), not a redelivery of this frame; a ledger-replayed revoke frame is
+        for timeline rendering only.
       required: [type, schemaVersion, batchId, askIds, reason, serverNowMs]
       additionalProperties: true
       properties:
@@ -10038,6 +10271,15 @@ components:
             `aborted` = the run was cancelled. Read as OPEN: an unknown reason is handled as a generic revoke
             (clear the cards), never specially.
         serverNowMs: { type: integer }
+        taskId:
+          type: string
+          description: >
+            S-58 (server >= 7.55.0, always sent there; ABSENT on <= 7.54.0 — the frame family was live-only
+            then, hence not in `required`): the ORIGIN run''s wire id (= the `taskId` of the same ask''s card
+            frame; server buildRevokeFrame''s originTaskId). The dispatch set is session-shaped ((owner,
+            sessionId) closure) and can contain OTHER runs'' contexts — durable legs ledger the frame into
+            their own run, so without this key an orphan revoke row (no paired card frame) could not be
+            attributed or filtered; consumers ignore frames whose taskId is not theirs.
 
     AskDecidedConflictBody:
       allOf:
@@ -10704,6 +10946,30 @@ components:
           required: [type]
           properties:
             type: { type: string, enum: [approval_request] }
+    Event_approval_revoke:
+      description: >
+        The design/172 batch-level card REVOCATION frame as an AgentEvent arm ([5924]/S-58, server >= 7.55.0).
+        Emission is PER CONTEXT: the sync stream leg carries it live-SSE-only (unchanged, never ledgered),
+        while the bg/resume durable legs append it to the run's own ledger — so GET /v1/runs/:id/events
+        tails/replays it, and a durable consumer can finally tell "actively revoked (halt/cancel/park
+        degradation)" from "stream ended". On <= 7.54.0 the durable leg never carries this frame.
+
+        🔴 THIS ARM IS THE OPEN ENVELOPE, NOT `ApprovalRevokeFrame` — same ruling as Event_approval_request:
+        narrow with `schemaVersion == 1` (SDK: `isApprovalRevokeFrameV1`) before touching
+        `batchId`/`askIds`/`taskId`; a frame that does not narrow is handled as a generic revoke (clear that
+        batch's local cards), never specially.
+
+        🔴 Consumption discipline: (a) attribute/filter by `taskId` (always present >= 7.55.0) — a run that
+        joined the dispatch set late can carry an ORPHAN revoke ledger row with no paired card frame; "not
+        mine" is safely ignored. (b) A replayed revoke frame is for TIMELINE RENDERING ONLY — the card-set
+        reconciliation baseline stays the open-stream preamble (the frame can be lost on any leg: it is a
+        notification, the row is the source of truth). (c) Siblings already DECIDED are never in `askIds`.
+      allOf:
+        - $ref: '#/components/schemas/ApprovalFrameEnvelope'
+        - type: object
+          required: [type]
+          properties:
+            type: { type: string, enum: [approval_revoke] }
 
     # ── resources/*.ts schema backfill, batch 2 (2026-07-28) — the 28-item WIRE_PENDING ratchet zeroed.
     #    Each schema below is cross-checked against the server source (file:line cited in its description
@@ -10729,6 +10995,14 @@ components:
         sessionId: { type: string, description: '`resolved` frames: which pending settled.' }
         toolCallId: { type: string, description: '`resolved` frames: the settled pending''s bound tool-call id (absent when the pending carried none).' }
         count: { type: integer, description: '`synced` frames: how many pendings the connect-time snapshot carried.' }
+        hasBidiControls:
+          type: boolean
+          enum: [true]
+          description: >-
+            `pending` frames only (server >=7.53, S-30①): the spread PendingCheckpoint row's bidi-presence bit —
+            SAME projection as the `GET /v1/approvals` row (`projectPendingForWire`), declared here explicitly so
+            a stream consumer sees it typed instead of through the open index signature. Present ONLY when true;
+            absence = "not detected", never "confirmed clean" (see PendingCheckpoint.hasBidiControls).
 
     ParkedDecideAccepted:
       type: object
@@ -10812,21 +11086,31 @@ components:
         parentToolCallId: { type: string, description: 'The parent tool_use id VERBATIM (E2 domain, engine-minted) — [1832] P1-2, server >= 1.290 / engine 1.432. Additive / tolerate-absent.' }
 
     FleetHookNotice:
+      description: >
+        Hook observability payload, TWO kinds (service fleet-bus.ts `HookNotice` minus the wire-stripped
+        ownerScope/ownerSessionId — the payload view of FleetFrame_hook_notice; a discriminated union on
+        `kind`, mirroring the SDK type verbatim). Both kinds are pure observe — never block, resume, or
+        inject. Visibility is fail-CLOSED: a ?session= subscriber only receives notices provably owned by
+        that session. `kind` is a CLOSED two-member set on the server (exhaustive-switch discipline) but
+        OPEN ON READ: degrade an unknown future kind to a generic observability row, never crash.
+      oneOf:
+        - $ref: '#/components/schemas/FleetHookDecisionUnavailable'
+        - $ref: '#/components/schemas/FleetHookNonBlockingFailure'
+      discriminator:
+        propertyName: kind
+        mapping:
+          hook_decision_unavailable: '#/components/schemas/FleetHookDecisionUnavailable'
+          hook_non_blocking_failure: '#/components/schemas/FleetHookNonBlockingFailure'
+
+    FleetHookDecisionUnavailable:
       type: object
       description: >
-        A hook adjudication FAILED TO COMPLETE this cycle (service fleet-bus.ts `HookNotice` minus the
-        wire-stripped ownerScope/ownerSessionId — the payload view of FleetFrame_hook_notice). Semantics
-        are "could not evaluate", NOT "evaluated to fail": render as "this cycle went unguarded, allowed
-        through", never "the guard is broken". Pure observe — it does not block, resume, or inject.
-        Visibility is fail-CLOSED: a ?session= subscriber only receives notices provably owned by that
-        session.
+        Kind 1 — a hook adjudication FAILED TO COMPLETE this cycle ("could not evaluate", NOT "evaluated to
+        fail": render as "this cycle went unguarded, allowed through", never "the guard is broken").
       required: [kind, event, reason]
       additionalProperties: true
       properties:
-        kind:
-          type: string
-          enum: [hook_decision_unavailable]
-          description: 'Only one kind today; an enum slot so the next observability frame kind needs no new frame arm.'
+        kind: { type: string, enum: [hook_decision_unavailable] }
         event: { type: string, description: 'Which hook event (Stop / PreToolUse / …) — defined by "a hook adjudication did not complete", not any single feature.' }
         reason:
           # 🔴 NO `enum` — same ruling as `FleetTaskRow.retiredBy` (codex R1-F3, family case): the description
@@ -10834,9 +11118,31 @@ components:
           # so a closed enum here would make a strict generated client drop the whole hook_notice frame the day the
           # server mints a fourth cause word — and that frame is the ONLY disclosure that a guard cycle went unwatched.
           type: string
-          description: 'Machine-branchable cause. CLOSED on the server side (fleet-bus.ts HookNotice.reason) but OPEN ON READ — THE KNOWN WORDS TODAY ARE no_content | unparsed | skipped (named here rather than pinned as an `enum`, deliberately — see the comment above): branch known values, render anything else as the generic "could not evaluate".'
+          description: 'Machine-branchable cause. CLOSED on the server side (fleet-bus.ts) but OPEN ON READ — KNOWN WORDS TODAY: no_content | unparsed | skipped (named here rather than pinned as an `enum`, deliberately — see the comment above): 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.' }
 
+    FleetHookNonBlockingFailure:
+      type: object
+      description: >
+        Kind 2 (server >= 7.48.0, #281 — A-075.17): the CONFIGURED HOOK ITSELF BROKE (non-blocking failure:
+        exit nonzero-and-not-2 / timeout / spawn failure / bad JSON). Render "<hookName> hook error" + stderr
+        (CC-parity attachment shape) — this one IS "this hook is broken", unlike kind 1.
+      required: [kind, event, reason, hookName, entryType]
+      additionalProperties: true
+      properties:
+        kind: { type: string, enum: [hook_non_blocking_failure] }
+        event: { type: string, description: 'Which hook event (PreToolUse / Stop / …).' }
+        reason:
+          # 🔴 NO `enum` — same open-on-read ruling as kind 1 (SDK type is `... | (string & {})`).
+          type: string
+          description: 'Machine-branchable failure shape. CLOSED server-side, OPEN ON READ — KNOWN WORDS TODAY: exit_nonzero | timeout | spawn_failed | bad_json.'
+        hookName: { type: string, description: 'Hook identity (statusMessage, else command/URL/prompt; redacted + bounded, http entries stripped of query/fragment). Always sent.' }
+        entryType: { type: string, description: 'command | http | prompt | agent — without it, hookName''s nature is a guess. Closed server-side, open on read. Always sent.' }
+        exitCode: { type: integer, description: 'Absent for timeout/spawn_failed (no exit code exists — the server never mints a legit-looking 0).' }
+        toolName: { type: string, description: 'Present on tool events (PreToolUse/PostToolUse/PostToolUseFailure).' }
+        stderr: { type: string, description: 'Redacted + truncated stderr digest (512-char cap incl. marker). Empty stderr => absent.' }
+        detail: { type: string, description: 'Redacted supplement (e.g. where an exit-2 had no venue). Additive / tolerate-absent.' }
+
     BakeStatus:
       # 新(census 批2 四段)——server `BakeStatus`(plugins/store-contracts.ts), the COARSE lifecycle
       # bakeView/claimResponse/bakesCreate all key on.
@@ -11946,29 +12252,45 @@ components:
             never hand it to another user.
         expiresAtMs: { type: integer, description: 'Absolute server-clock expiry (the window is 10 minutes — one interaction, not a session).' }
 
+    CcImportRedeemedMember:
+      type: object
+      description: >
+        One member of the redeem 200 (core `RedeemedBatchMember`, the 200-REACHABLE arm verbatim — core d.ts
+        permission-rule-consent.d.ts). The union's third arm `{status:"refused", reason}` is STRUCTURALLY
+        UNREACHABLE on this route's 200: any refused member makes the server treat the whole redeem as
+        indeterminate, release the claim and answer 503 `state.rule_import_retry` (server rules-consent.ts) —
+        so this schema honestly describes the two-value `status` only.
+      additionalProperties: false
+      required: [candidateIndex, rule, scope, status, alreadyRedeemed, dot]
+      properties:
+        candidateIndex: { type: integer, description: 'Index into the prepare preview''s candidate set (candidate space).' }
+        rule: { type: string, description: 'Canonical rule text.' }
+        scope: { $ref: '#/components/schemas/RuleScope' }
+        status:
+          type: string
+          enum: [persisted, deduped]
+          description: '`persisted` = landed this redeem; `deduped` = an equal rule was already in the store (the consent took effect — not a failure).'
+        alreadyRedeemed: { type: boolean, description: 'true = this outcome was REPLAYED verbatim from the ticket row (lost-response retry; idempotency evidence — zero double-mint).' }
+        dot: { $ref: '#/components/schemas/RuleDot' }
+
     CcImportResult:
       type: object
       description: >
-        What the import ACTUALLY did (core `ImportResult`) — a different moment and a different contract from
-        the preview, because dedup, concurrency and redemption-time validation can each move an entry between
-        the two.
+        What the import ACTUALLY did (server >= 7.46.0, BREAKING #2 there / core 5.58.0 redeemRuleBatch
+        members passthrough) — a different moment and a different contract from the preview, because dedup,
+        concurrency and redemption-time validation can each move an entry between the two.
 
-        ⚠️ `skippedAtRedeem` is empty on every success arm of THIS lane: the server treats a non-empty one as
-        INDETERMINATE, releases the claim and answers 503 `state.rule_import_retry` instead of returning a 200
-        that quietly means "half of it did not land". The field stays on the shape because it is core's.
+        🔴 SHAPE CHANGE (A-075.13): the old three-bucket form `{persisted[], deduped[], skippedAtRedeem[],
+        rev}` left the wire in server 7.46.0 — a consumer reading `result.persisted.length` gets undefined.
+        This schema describes the real wire since then; the SDK type changed with it (a staleness fix, not a
+        behavior change).
       additionalProperties: false
-      required: [persisted, deduped, skippedAtRedeem, rev]
+      required: [members, rev]
       properties:
-        persisted:
-          type: array
-          items: { $ref: '#/components/schemas/RuleCandidate' }
-        deduped:
+        members:
           type: array
-          items: { $ref: '#/components/schemas/RuleCandidate' }
-          description: 'Already in the store — not a failure.'
-        skippedAtRedeem:
-          type: array
-          items: { $ref: '#/components/schemas/CcImportSkippedRule' }
+          items: { $ref: '#/components/schemas/CcImportRedeemedMember' }
+          description: 'Per-candidate outcome (discriminate on `status`; refused never rides a 200 — see CcImportRedeemedMember).'
         rev: { type: integer, description: 'The rule store''s monotonic revision after the batch.' }
 
     CcImportRedeemResult: