@sema-agent/sdk 7.4.0 → 8.1.0

package/openapi.yaml

@@ -2533,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
@@ -2541,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` /
@@ -2560,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"
@@ -5764,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
@@ -7271,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)。
@@ -7677,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:
@@ -8806,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:
@@ -8852,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
@@ -10195,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:
@@ -10212,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:
@@ -10878,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
@@ -10994,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
@@ -11016,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.
@@ -12128,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "7.4.0",
+  "version": "8.1.0",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",