@sema-agent/sdk 15.4.0 → 16.0.1

package/openapi.yaml

@@ -415,8 +415,8 @@ paths:
         For anything that may take minutes or hit a HITL gate, use `/v1/runs` instead (this call blocks).
         🔴 PREPARE-TIME REFUSALS ARE TRIAGED ON WORK DONE (server >= 7.104.0 / S-271, one rule for the whole table): a
         prepare-time refusal code that HAS a status in the server's per-code triage table (`resume_at.*`, governance codes,
-        `rewind.store_unconfigured` / `rewind.capture_disabled` / `rewind.child_scope_unsupported`, the registered `config.*`
-        codes incl. the three roster-bound ones, `corrupt_session`; codes outside the table, e.g. `rewind.invalid_spec`, stay
+        `rewind.store_unconfigured` / `rewind.capture_disabled` / `rewind.child_scope_unsupported` / `rewind_snapshot.unresolvable`, the
+        registered `config.*` codes incl. the three roster-bound ones, `corrupt_session`; codes outside the table, e.g. `rewind.invalid_spec`, stay
         200 with a failed body) answers its 4xx / 5xx ERROR BODY only when the whole submission did ZERO WORK (cumulative
         `stats.turns === 0` AND `stats.tokens === 0` — the common case: nothing billed, not idempotency-cached). When a
         `verify` / `cascade` run's earlier tier already ran turns and only the last tier is refused, the SAME code arrives
@@ -461,6 +461,10 @@ paths:
             history off (`fileHistory: "disabled"`) and asks to restore in the same breath; this server's request face
             refuses that combination earlier (400 `request.field_conflict`), so only a host building a TaskSpec directly can
             reach this code. `rewind.child_scope_unsupported` / `resume_at.*` also land here.
+            `rewind_snapshot.unresolvable` (server 7.114.0 `dist/runs.js` `resumeAtHttpStatus`: a `resumeAt` file restore —
+            `restoreFiles` — that finds no file-history boundary at / above the branch point) is in the same per-code table and lands
+            here too, on the same ZERO WORK condition (turns 0, tokens 0: nothing ran, nothing billed); a submission that already ran
+            turns gets 200 + a failed body carrying the code in `terminal.code` instead.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -1708,7 +1712,7 @@ paths:
         '404':
           description: >
             Non-owner / unknown session (no existence oracle) — or, with `?message=`, an out-of-range index, whose
-            body additionally carries `total`.
+            body additionally carries `total`. server >= 7.113.0 (S-989; wire VALUE change, no new key): the unknown arm AND the non-owner arm answer `errorCode: "not_found.session"` + `error: "session not found"`, byte-identical (status and body) — one door, one spelling, no existence oracle. server <= 7.112.0 answered the non-owner arm in the RUN spelling (`not_found.run` + the long run-not-found sentence) while the unknown arm already said `not_found.session` — two codes and two sentences on one endpoint WAS the oracle. The SDK lands both arms on `NotFoundError`: branch on the class, never on the code to tell "no such session" from "not yours" (that distinction is exactly what the server refuses to give); the run face `/v1/runs/{taskId}` is unchanged (`not_found.run`).
           content:
             application/json:
               schema:
@@ -1844,7 +1848,12 @@ paths:
                   leafId: { type: ["string", "null"], description: "null = session exists but has no entries yet." }
         '304': { description: 'Leaf unchanged since the presented ETag (no body).' }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { $ref: '#/components/responses/NotFound' }
+        '404':
+          description: >
+            Unknown session or another principal's session. server >= 7.113.0 (S-989; wire VALUE change, no new key): the unknown arm AND the non-owner arm answer `errorCode: "not_found.session"` + `error: "session not found"`, byte-identical (status and body) — one door, one spelling, no existence oracle. server <= 7.112.0 answered the non-owner arm in the RUN spelling (`not_found.run` + the long run-not-found sentence) while the unknown arm already said `not_found.session` — two codes and two sentences on one endpoint WAS the oracle. The SDK lands both arms on `NotFoundError`: branch on the class, never on the code to tell "no such session" from "not yours" (that distinction is exactly what the server refuses to give); the run face `/v1/runs/{taskId}` is unchanged (`not_found.run`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/sessions/{sessionId}/events:
@@ -1880,7 +1889,12 @@ paths:
             text/event-stream:
               schema: { type: string }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { $ref: '#/components/responses/NotFound' }
+        '404':
+          description: >
+            Unknown session or another principal's session (answered BEFORE the SSE `200` headers go out). server >= 7.113.0 (S-989; wire VALUE change, no new key): the unknown arm AND the non-owner arm answer `errorCode: "not_found.session"` + `error: "session not found"`, byte-identical (status and body) — one door, one spelling, no existence oracle. server <= 7.112.0 answered the non-owner arm in the RUN spelling (`not_found.run` + the long run-not-found sentence) while the unknown arm already said `not_found.session` — two codes and two sentences on one endpoint WAS the oracle. The SDK lands both arms on `NotFoundError`: branch on the class, never on the code to tell "no such session" from "not yours" (that distinction is exactly what the server refuses to give); the run face `/v1/runs/{taskId}` is unchanged (`not_found.run`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '500':
           description: >-
             (declared 2026-07-31) errorCode "internal.error" — `routes/sessions.ts`'s catch around the owner
@@ -2057,7 +2071,17 @@ paths:
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: 'No parked checkpoint for this session (nothing to wake), or session not visible to the caller.' }
-        '409': { description: 'Pending gate (`wake.gate_pending` — decide it through its own entry) or resume context missing.' }
+        '409':
+          description: >
+            Pending gate (`wake.gate_pending` — decide it through its own entry) or resume context missing; also the resume-leg refusals core
+            raises before the claim (`steering.blocked_by_hook` when the wake carried a `message` and the deployment's `userPromptSubmit`
+            hook crashed / timed out / refused — server >= 7.113.0 adds `retriable: true` there; `checkpoint.config_refused`). Value change on
+            the run row the wake minted for the refused attempt (server >= 7.113.0): it now ends `failed` with a structured terminal carrying
+            `terminal.code: "steering.blocked_by_hook"` and holds no session lock (before 7.113.0 it ended with a code-less terminal and
+            `result: null` — a zero-execution refusal recorded as an ordinary failure); the card itself stays pending.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ResumeLegConflictError' }
         '422': { description: '`steering.invalid_content` — the message failed the steering content gate.' }
         '429': { $ref: '#/components/responses/RateLimited' }
         '501': { $ref: '#/components/responses/NotImplemented' }
@@ -2280,6 +2304,20 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409': { $ref: '#/components/responses/Conflict' }
+        '500':
+          description: >-
+            `corrupt` (server >= 7.114.0 / core 7.39.2 on the local file-backed lane; the SQL-backed store already refuses a bad row
+            with the same code): this session's stored rules are PRESENT BUT UNREADABLE (a torn or hand-edited rules file). The door
+            REFUSES instead of answering "no rules" — session rules only ever tighten, so the row IS the restriction and reading a
+            damaged one as empty would silently drop it. DETERMINISTIC: a retry cannot change it (the SDK does not auto-retry this
+            code; it arrives as a bare `APIError` with `errorCode: "corrupt"`); the repair is the operator's — fix the file or
+            delete it (deleting = an explicit "no rules"). `error` names the session, the damage grade (`unreadable` /
+            `unparseable` / `malformed`) and both exits, with NO on-disk path (it reaches the end user; the path goes to the
+            operator's log). A rules file that is ABSENT is not this arm: it answers 200 `{ rules: { rev: 0 } }`.
+            Also `internal.error` (unclassified).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
     put:
       tags: [sessions]
@@ -2322,6 +2360,21 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409': { $ref: '#/components/responses/Conflict' }
+        '500':
+          description: >-
+            `corrupt` (server >= 7.114.0 / core 7.39.2 on the local file-backed lane; the SQL-backed store already refuses a bad row
+            with the same code): the read this write makes first finds the session's stored rules PRESENT BUT UNREADABLE (a torn or
+            hand-edited rules file). The door REFUSES instead of treating it as "no rules" — session rules only ever tighten, so
+            the row IS the restriction — and `PUT` never overwrites the damaged bytes (overwriting = losing the evidence): nothing is
+            written. DETERMINISTIC: a retry cannot change it (the SDK does not auto-retry this code; it arrives as a bare `APIError`
+            with `errorCode: "corrupt"`); the repair is the operator's — fix the file or delete it (deleting = an explicit "no
+            rules"). For a damaged rules row `error` names the session, the damage grade and both exits, with NO on-disk path.
+            ⚠️ The same code also comes from the write path's high-water-mark sidecar (`.hwm.json`) being unreadable, and that one
+            sentence STILL names the sidecar's on-disk path (server 7.114.0 discloses it as a known gap: core #1307 / #1309, core
+            7.41.0). Also `internal.error` (unclassified).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/sessions/{sessionId}/mcp:
@@ -3307,7 +3360,7 @@ paths:
             parked row carries no root-session anchor (refused before the claim, nothing consumed).
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/ErrorResponse' }
+              schema: { $ref: '#/components/schemas/ResumeLegConflictError' }
         # 🔴 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
@@ -6614,12 +6667,18 @@ components:
 
     RunStatus:
       type: string
-      enum: [running, completed, failed, suspended, needs_review]
+      enum: [running, completed, failed, suspended, needs_review, blocked]
       description: >
         `suspended` = HITL (an F4 policy gate or AskUserQuestion is waiting on a human) — NOT an error.
         `needs_review` (design/80 D-0) = durable TERMINAL of a dry-run/shadow review (POST-prediction),
         distinct from the mid-run `suspended` pause. A user-cancelled run is `failed` with `errorCode`
         "cancelled" (cancel is LIVE; `cancelling` is a cancel-ack field, NOT a member of this enum).
+        `blocked` = durable TERMINAL: the run ended without doing the work (`result.terminal.kind: "blocked"` — the agent's
+        `ReportBlocked`, or, server >= 7.113.0, a deployment `userPromptSubmit` hook keeping the prompt from being submitted, see
+        `TerminalBlockedDetail`); a governance verdict, not an error. The server's run-status table has it (`blocked`, an
+        unsuccessful terminal) and the SDK type has listed it since 2.1.4 (whose own note records the server passing core's status words
+        through verbatim from 3.x); this enum was the one place that did not (declared in sdk 16.0.0 when the real-projector pins
+        validated a blocked run row against it).
 
     TaskStats:
       type: object
@@ -7357,6 +7416,15 @@ components:
           description: >
             Turn-boundary reminder attachments (design/133 + G1). Each flag opts INTO an injection; omitted = off.
             `changedFiles` may also be an object to cap the listing.
+            🔴 BREAKING (server >= 7.113.0 / core 7.39.0 #1254; K-44): `planModeReminder` was retired and is no longer declared
+            here. A submit body that carries it — any value, `false` included (the server's gate tests `!== undefined`, not
+            truthiness) — is refused 400 `request.field_invalid` with a sentence naming the retirement; before 7.113.0 it was
+            accepted and the engine refused later, at prepare. The engine now states plan posture itself whenever the
+            permission mode is "plan" (first request, periodic reminders, exit frame): remove the key and send
+            `permissionMode: "plan"`. A stored body that still carries the key resumes with the key dropped (resume replays
+            are not refused). THIS schema stays open (`additionalProperties: true`), so a validator built from it will not
+            reject the key — the refusal is the server's, not this schema's. A server <= 7.112.x still accepts the key; this
+            package no longer declares it (sdk 16.0.0, major).
           additionalProperties: true
           properties:
             todoReminder: { type: boolean }
@@ -7365,7 +7433,6 @@ components:
               oneOf:
                 - { type: boolean }
                 - { type: object, properties: { maxFiles: { type: integer } } }
-            planModeReminder: { type: boolean }
             budgetUsd: { type: boolean }
             backgroundTasks: { type: boolean }
             toolsDelta: { type: boolean }
@@ -7504,11 +7571,42 @@ components:
     TerminalCause_blocked:
       type: object
       additionalProperties: false
-      description: 'The agent could not finish and said why (a governance verdict is NOT a failure).'
+      description: >
+        The run ended without doing the work (a governance verdict is NOT a failure). Two sources, told apart by `detail`: with NO
+        `detail` — the agent's own words from its `ReportBlocked` call; with `detail.kind: "prompt_blocked_by_hook"` (server >= 7.113.0 /
+        core #1277; K-43-class closed-object gap) — the engine's sentence about the deployment's `userPromptSubmit` hook, framed as a
+        reminder for the model-facing lane. Terminal: the run is over and nobody is being waited on (contrast `paused`).
+        Same shape on all four faces (the synchronous 200 body, the stream's `done.result`, `GET /v1/runs/{taskId}` -> `result`, the
+        ledger `done` row).
       required: [kind, reason]
       properties:
         kind: { const: blocked }
-        reason: { type: string, description: 'Why the agent could not finish.' }
+        reason: { type: string, description: 'Why the run ended without doing the work (the agent''s words, or the engine''s framed hook sentence — branch on `detail?.kind`, never on this prose).' }
+        detail:
+          allOf: [{ $ref: '#/components/schemas/TerminalBlockedDetail' }]
+          description: >
+            server >= 7.113.0 (core #1277) — WHO stopped the run, for the one shape a consumer offers its own way out of: the prompt was
+            NOT submitted (the objective never became a message and the loop never started), so changing it and sending again is
+            meaningful. PRESENT only on that terminal; ABSENT means the agent reported `ReportBlocked` ("I cannot go on"), or a server
+            before 7.113.0.
+
+    TerminalBlockedDetail:
+      type: object
+      additionalProperties: false
+      required: [kind, cause]
+      description: >
+        server >= 7.113.0 (core #1277; K-44) — the machine-readable account of a `blocked` terminal caused by the deployment's
+        `userPromptSubmit` hook. `kind` is closed (`prompt_blocked_by_hook`, one member today). `cause` is the closed four-word set of the hook seat's endings that keep a
+        prompt from being submitted (core `PROMPT_BLOCK_CAUSES`): `block` — the hook answered and refused (its words ride `hookReason`);
+        `crashed` — the hook threw or rejected (the seat is fail-closed: a screen that failed has not cleared the prompt); `timeout` — no
+        answer within the hook's `timeoutMs` bound (fail-closed the same way); `cancelled` — the task was cancelled while the hook was
+        still screening. `hookReason` is the hook's OWN words (present only on cause `block`, and only when the hook gave some): folded to
+        one line, bounded, with the engine's envelope tags defused and passed through the same secret redaction as `reason` — still the
+        hook's text, so render it as untrusted. A word outside the four is read as "the hook seat stopped the prompt, cause not recognised".
+      properties:
+        kind: { const: prompt_blocked_by_hook }
+        cause: { type: string, enum: [block, crashed, timeout, cancelled] }
+        hookReason: { type: string, description: 'The hook''s own refusal words (untrusted free text; present only on `block` and only when stated).' }
 
     PausedCause:
       type: object
@@ -7656,6 +7754,18 @@ components:
             verdict: { type: string, enum: [PASS, FAIL, PARTIAL, unverified] }
             rounds: { type: integer }
             findings: { type: array, items: { type: string } }
+        cancelContext:
+          allOf: [{ $ref: '#/components/schemas/CancelContext' }]
+          description: >
+            server >= 7.57.0 (S-94; contract §5.3; K-43 — named here in sdk 16.0.0, it was only readable through this schema's open
+            index before) — the SCENE SNAPSHOT of a USER CANCEL, a side key beside `abortCause` (both are minted by the same mint
+            point, `mintCancelledResult`, under the same "fill the empty seat only" gate; neither lives inside `terminal`).
+            PRESENT only on a cancelled terminal the server minted; ABSENT on a model's own failure / a normal completion, and
+            ABSENT as a whole when not one of its keys can be proven (the server never mints an empty object — absence reads as "no
+            cancel scene to look at", NOT "nothing was wrong at cancel time"). Landings: `GET /v1/runs/{taskId}` -> `result.cancelContext`
+            (and the same object rides the other cancelled-terminal landings listed on `abortCause`). Shape and per-key reading
+            rules: `CancelContext`.
+
         abortCause:
           allOf: [{ $ref: '#/components/schemas/AbortCause' }]
           description: >
@@ -7703,6 +7813,59 @@ components:
         CLOSED set, additive-only by the server's rule (a new word is a new server version in `wire-changes` AND a new SDK
         minor, in this enum in the same batch): read an unknown word as "the server aborted this run, cause not recognised".
 
+    CancelContext:
+      type: object
+      # 封闭(K-43,sdk 16.0.0):铸点 `run-cancel-context.js` `buildCancelContext` 是逐键条件 spread 的字面量(lastEventKind / lastEventAgeMs / lastBrainStatus / elapsedMs),
+      # `lastBrainStatus` 经 `turn-activity.js` `pickRunBrainStatus` 投成五键(刻意不含 provider 自由文本 `detail` 与相对量 `retryInMs`)—— 与本 schema 一一对上;
+      # `test/server-7113-wire.test.ts` K3 用真 `recordTurnActivity` + 真 `mintCancelledResult` 的字节逐键核。
+      additionalProperties: false
+      description: >
+        The scene snapshot of a user cancel (server >= 7.57.0 / S-94; contract §5.3; K-43): "how long since this server last heard
+        from this run" — triage material, never a state-machine input. 🔴 It is NOT the model-call phase: the server structurally
+        cannot see first-byte waits or retries (that half lives in the engine's stream layer); `lastEventAgeMs` is NOT "how long the
+        model has been hung" (a long tool call produces no ledger event either). Every key is optional and absence is honest:
+        `lastEventKind` / `lastEventAgeMs` come from a SAME-REPLICA in-process activity registry (a cross-replica cancel or a
+        replica restart cannot read it — absent means "this replica cannot prove it", never fold it to 0: that would render a
+        8-minute hang as "just alive"); `lastEventKind` is MORE likely to be absent than `lastEventAgeMs` (some activity seats advance
+        the clock without a word), so "age without kind" is a legal reading; `lastBrainStatus` is absent when the run never
+        emitted a `status` frame or the replica cannot read it; `elapsedMs` (run start to cancel, wall clock) is normally present
+        and absent only when the row's `createdAt` cannot be parsed (again never folded to 0). The side key `abortCause` says WHO
+        stopped the run; this object says what the server saw at that moment.
+      properties:
+        lastEventKind:
+          type: string
+          description: 'The type of the last event that entered this run''s durable ledger (`text` / `tool_start` / `status` / ...). Open string.'
+        lastEventAgeMs:
+          type: number
+          minimum: 0
+          description: 'Milliseconds since that last durable event (>= 0).'
+        lastBrainStatus:
+          allOf: [{ $ref: '#/components/schemas/CancelContextBrainStatus' }]
+          description: >
+            The last `status` (BrainStatus) frame at the tail of the run's ledger (an S-94 extension), as a five-key subset — "which
+            retry, waiting for what, which error class". STICKY: later text / tool events do not clear it. Absent when the run never
+            emitted a `status` frame or this replica cannot read it (never `null`).
+        elapsedMs:
+          type: number
+          minimum: 0
+          description: 'Wall-clock milliseconds from the run''s start to this cancel (>= 0).'
+
+    CancelContextBrainStatus:
+      type: object
+      additionalProperties: false
+      required: [phase]
+      description: >
+        The five-key subset of the last BrainStatus frame (`CancelContext.lastBrainStatus`; K-43). `phase` is the snapshot's reason to
+        exist (no phase, no snapshot — never half of one). Deliberately NOT carried: `detail` (provider free text) and `retryInMs` /
+        `retryInSec` (relative values go stale; `retryAtMs` is the cross-process one — a wall-clock instant on the SENDING process's
+        clock, an approximation, never compare it with a local monotonic timer).
+      properties:
+        phase: { type: string }
+        attempt: { type: number }
+        maxRetries: { type: number }
+        retryAtMs: { type: number }
+        errClass: { type: string }
+
     LegacyPlaneTaskResult:
       type: object
       additionalProperties: true
@@ -7912,10 +8075,14 @@ components:
         changed shape with it (`result.terminal`, no plane keys): the row's `errorCode` column is now projected
         from `result.terminal` (`src/http/routes/runs.ts` -> `persistedPlaneOf`, which also reads the flat bytes
         7.63.0 and earlier wrote to disk), NOT copied from a `result.errorCode` that no longer exists.
-      # 封闭(census 轴一,2026-07-30;A-075.21 回填后 12 键):铸造点 routes/runs.ts 是一个逐键写死的
+      # 封闭(census 轴一,2026-07-30;A-075.21 回填后 12 键;**K-43 / sdk 16.0.0 补 `heldBy` / `cancelRequested` 后 14 键**):铸造点 routes/runs.ts 是一个逐键写死的
       # 字面量(taskId/sessionId/status/msSinceLastActivity/crossSliceUsage/result/supervisorCost/
-      # suggestions/errorCode/error/jobId/source),与本 properties 一一对上;只有 taskId/sessionId/status
-      # 无条件在场(其余走 `?? undefined` / 条件 spread ⇒ JSON 丢键)⇒ required 维持 3 键。
+      # suggestions/errorCode/error/jobId/source/heldBy/cancelRequested),与本 properties 一一对上;只有 taskId/sessionId/status
+      # 无条件在场(其余走 `?? undefined` / 条件 spread ⇒ JSON 丢键)⇒ required 维持 3 键(`heldBy` / `cancelRequested` 在 server >= 7.73.0 上恒在场,
+      # 但 required 不抬:本包支持底线 3.0.0,老 server 没有这两键)。
+      # 🔴 K-43(既存缺口,与 abortCause 无关,K-41 同病):`heldBy` / `cancelRequested` 自 server 7.73.0(S-230 P-45)就在真 `GET /v1/runs/:id` 上,
+      # 而本封闭对象一直没声明它们 ⇒ 按本 schema 严格校验响应的消费方会得「$ must NOT have additional properties」;门 6 契约套抓不到,
+      # 由 `test/server-7113-wire.test.ts` K3(真 `handleRuns` 字节 × spec)抓。
       # (A-075.21:此前的「恰好 10 键」对 msSinceLastActivity(#245 S1)/crossSliceUsage([3833] S-4)
       # 两条铸键路径结构性失明 —— server test/producer-contract.test.ts 的 S-4 登记钉逐字记着这笔账。)
       additionalProperties: false
@@ -7983,6 +8150,29 @@ components:
           items: { type: string }
           description: Follow-up prompt suggestions produced for this run (absent when none were generated).
         supervisorCost: { $ref: '#/components/schemas/SupervisorCostBreakdown' }
+        heldBy:
+          type: [string, "null"]
+          description: >
+            server >= 7.73.0 (S-230 P-45; contract §5.5 (c); K-43 — the mint has carried it since 7.73.0, this closed schema
+            did not declare it) — the replica HOLDING this run NOW (the row's `instance_id`: written at create, TAKEN OVER by a
+            cross-replica resume claim), so it answers "where is the live leg", not "who created the row". Always present on a
+            server that has it, and an explicit `null` (never a missing key) means no replica holds it. 🔴 `heldBy` becoming
+            `null` OR the run reaching a terminal status = the claim is released (either one); on a terminal row `heldBy` reads
+            as a HISTORICAL fact ("which replica finished it"), not "still occupied". ⚠️ The one exception is the stale fold: a
+            `running` row older than the stale window is shown with `status: "failed"` + `error: "run stalled (instance lost?)"`
+            — that is the READ's judgement; the ledger row is still `running` and its claim is held until the reaper's next beat,
+            and `heldBy` still names the LOST replica (the one useful coordinate when debugging). A deployment-internal replica
+            identity, not a user-readable location. Absent on a server < 7.73.0.
+        cancelRequested:
+          type: boolean
+          description: >
+            server >= 7.73.0 (S-230 P-45; contract §5.5 (c); K-43) — the durable cancel flag (cross-replica; the holding replica
+            polls it on its heartbeat beat). ⚠️ It is a pending cancel: a run that has already been cancelled is spoken by `status` +
+            `errorCode: "cancelled"` (a park-arm cancel never goes through this flag — it finalizes the row directly), and a resume
+            claim CLEARS the flag (a cancel that landed on a suspend must not kill the run again after it resumes). So never read
+            `cancelRequested` flipping back to `false` as "the cancel completed" — wait for a terminal `status` + `errorCode:
+            "cancelled"`. The `cancelling` 202 ack of `POST /v1/runs/{taskId}/cancel` carries the same key
+            (`CancelAck.cancelRequested`). Absent on a server < 7.73.0.
 
     SupervisorCostBreakdown:
       type: object
@@ -8020,14 +8210,23 @@ components:
       description: >
         Synchronous ack for `POST /v1/runs/:id/cancel`. `status` is "cancelling" (accepted) or a terminal status
         (idempotent no-op). NOTE: "cancelling" is NOT a RunStatus enum member — it only appears here.
-      # 封闭(census 轴一,2026-07-30):cancel 面的 7 个 sendJson 铸造点(routes/runs.ts
-      # 495/505/512)键集的并集恰好 = {taskId, status, note?, errorCode?};taskId/status 无条件在场。
+      # 封闭(census 轴一,2026-07-30):cancel 面的 sendJson 铸造点键集的并集 = {taskId, status, note?, errorCode?, cancelRequested};
+      # taskId/status 无条件在场。🔴 K-43 / sdk 16.0.0 补 `cancelRequested`:自 server 7.73.0(S-230 P-45)每一个 2xx 受理体都带它,
+      # 而本封闭对象一直没声明 ⇒ 严格校验回执的消费方会得「$ must NOT have additional properties」;`test/server-7113-wire.test.ts` K3 抓(真 `handleRuns` 三臂字节 × spec)。
       additionalProperties: false
       required: [taskId, status]
       properties:
         taskId: { type: string }
         status: { type: string }
         note: { type: string }
+        cancelRequested:
+          type: boolean
+          description: >
+            server >= 7.73.0 (S-230 P-45; contract §5.5 (c); K-43) — the same predicate as `RunRecord.cancelRequested` (the durable
+            cancel flag), present on every 2xx ack the cancel verb mints: `true` on the `status: "cancelling"` branch (the CAS just
+            won — the flag is on the row and the holding replica's next beat reads it); `false` on the park-arm terminal branch (a
+            parked run is finalized directly, no flag was needed); on the idempotent no-op branches and the concurrent-terminalized
+            branch it reports the row's own flag value (`false` in the contract's account, §5.5 (c)). Absent on a server < 7.73.0.
         errorCode:
           type: [string, "null"]
           description: >
@@ -12282,7 +12481,9 @@ components:
           description: >-
             server >=7.110.0 (S-928 user-input acceptance ledger): user inputs this session LOST to a crash —
             the server had answered 200 `applied` (interrupt{text}: 202) but the process carrying that run died
-            before the run settled; whether the run consumed them is NOT known (see `engine_notice`
+            before the engine confirmed consuming them (server >= 7.113.0 / core 7.39.0 #1273: an acceptance the engine confirmed
+            consuming is settled `consumed` and is no longer listed here — the <= 7.112.x reading "whether the run consumed
+            them is not known" narrowed to this; it still does NOT say "never consumed"; see `engine_notice`
             `task.user_steer_undrained{cause:"crashed"}`). Converged rows only, one row per (taskId, messageId),
             newest 500. From server >=7.111.0 (S-966) the rows include SUBAGENT steers (recorded under the run on the
             receipt; same row shape, `kind` is still only `steer`; `messageId` = the subagent steer receipt's).
@@ -13067,7 +13268,9 @@ components:
             On 400 `request.field_invalid` for a `settings.permissions` bucket (server >= 7.106.0 / S-904): which bucket —
             `settings.permissions.allow` | `settings.permissions.deny` | `settings.permissions.ask`. (`rules.*` content refusals
             carry their own `field`.) Resume legs carry the same group on 409 `resume_blocked_by_policy`
-            (`blockedBy: "request.field_invalid"`). SDK: `err.extra.field`.
+            (`blockedBy: "request.field_invalid"`). Also on 409 `checkpoint.config_refused` (server >= 7.113.0): which part of the
+            row's configuration was refused — `taskConfig` (change the configuration, then decide the SAME card again) or
+            `inheritedGate` (the row's recorded mode seed is bad — the run can only be cancelled). SDK: `err.extra.field`.
         count:
           type: integer
           description: 'S-904 `reason: over_cap` only — how many entries the bucket had (server >= 7.106.0). SDK: `err.extra.count`.'
@@ -13086,6 +13289,38 @@ components:
             (S-607); before that it was absent when the original refusal carried no code. SDK:
             `ResumeBlockedByPolicyError.blockedBy` (`undefined` when the key is absent or not a string — never defaulted).
 
+    ResumeLegConflictError:
+      description: >
+        The 409 body of a RESUME LEG that core refused BEFORE the claim (`POST /v1/approvals/{sessionId}/decide`,
+        `POST /v1/sessions/{sessionId}/wake`): `ErrorResponse` plus the one key those 409s may add, `retriable`. The key is declared HERE and
+        not on the shared `ErrorResponse` on purpose (codex r1 [medium], sdk 16.0.0): `ErrorResponse` is the body of every error
+        response in this document, and declaring `retriable` there would offer a retry signal on 401 / 404 / 422 / 5xx bodies where the
+        server never mints it. (`ErrorResponse` stays open, so a validator cannot REJECT the key elsewhere; the confinement is that only
+        these 409 responses reference this schema, and a test pins that count.)
+      allOf:
+        - $ref: '#/components/schemas/ErrorResponse'
+        - type: object
+          properties:
+            retriable:
+              type: boolean
+              enum: [true]
+              description: >-
+                Only ever `true` (the server mints it from one conditional spread, `...(retriable ? { retriable: true } : {})`, in the
+                one place that builds the 409 for a core `CheckpointError`; the only 404 that place can build, `checkpoint.not_found`, is
+                never retriable) — absent otherwise, and absence means "the server did not say", NOT "not retriable". (The 200-status
+                `{ status, errorCode?, retriable? }` bodies of the same legs carry the same key under their own schemas,
+                `SessionWakeResult` and `ApprovalDecisionResult`.)
+                Reading, one reading for the whole family: `retriable: true` = the pending card is STILL pending (core refused BEFORE the
+                claim — the run row stays `suspended` and the card is untouched), NOT "a verbatim retry will succeed". server >= 7.113.0
+                added the key to `checkpoint.walltime_axis_retired` (a pending row whose ledger carries the retired cross-slice walltime
+                quota; a >= 7.39 engine refuses that row EVERY time, so the way out is `POST /v1/runs/{taskId}/cancel` first, then a new
+                task on the same session — or finishing the run on a worker with the previous engine; before 7.113.0 this code ended the
+                run `failed` with the session lock released and an orphaned card), to `steering.blocked_by_hook` on the `/wake` door (a
+                wake carrying a `message` hit the deployment's `userPromptSubmit` hook crashing / timing out / refusing: the card stays
+                pending and the same card can be woken again once the hook recovers; the live `steer` / `interrupt` doors answer the
+                same code with 422 and no key), and to the new mirror code `checkpoint.config_refused` (409; the body also carries `field`:
+                `taskConfig` | `inheritedGate`). Codes / status / `error` text are unchanged. SDK: `APIError.retriable`.
+
     # ── Streaming event taxonomy (the UX 命脉). Each SSE `data:` line is one JSON-serialized AgentEvent. ──
     # TWO vocabularies (the pinned wire contract Drift 3). ⚠️ The two lines below are the SHAPE-DEFINING
     # contrast (per-token deltas vs turn-aggregated), NOT an enumeration of either leg's arm set — the union
@@ -13409,8 +13644,8 @@ components:
 
     Settlement:
       description: >
-        HOW the wait an ask was in ENDED — a DISCRIMINATED union on `kind` (core 7.6.0 `SETTLEMENT_KINDS`,
-        12 words, CLOSED). It is deliberately NOT a free product of `kind` x `who`: a free product can express
+        HOW the wait an ask was in ENDED — a DISCRIMINATED union on `kind` (core `SETTLEMENT_KINDS`: 12 words at 7.6.0,
+        14 as of core 7.39.0 — `policy_refused` joined at 7.26.2 and `policy_allowed` with the policy party at 7.39.0 / server 7.113.0; CLOSED). It is deliberately NOT a free product of `kind` x `who`: a free product can express
         "human_allowed, ended by the engine's window" — a structurally complete record that contradicts itself.
         `who` says WHICH PARTY ended it and its shape is fixed BY the word; `when` is epoch ms written at the
         settlement site; a person's refusal carries the decider's own `note` when one was attached.
@@ -13421,6 +13656,7 @@ components:
         secret-redacted (and `note` length-bounded) before they reach this wire.
       oneOf:
         - $ref: '#/components/schemas/Settlement_human'
+        - $ref: '#/components/schemas/Settlement_policy'
         - $ref: '#/components/schemas/Settlement_approval_window_expired'
         - $ref: '#/components/schemas/Settlement_denial_limit_window_expired'
         - $ref: '#/components/schemas/Settlement_park_sla_expired'
@@ -13443,6 +13679,34 @@ components:
         when: { type: integer, format: int64, description: 'Epoch ms, written at the settlement site.' }
         note: { type: string, description: 'The refusing decider''s own words, when one was attached. A refusal WITHOUT a note is a bare "no".' }
 
+    Settlement_policy:
+      type: object
+      additionalProperties: false
+      description: >
+        The DEPLOYMENT'S OWN POLICY decided (server >= 7.113.0 / core 7.39.0 — the `policy` party; sdk 16.0.0, found by the
+        lockstep's completeness sweep, not in the release's own post): the approval channel reported that a MACHINE, not a
+        person, answered this ask. A person and a policy are the two DECIDERS — each answers either way and differs only in whose
+        decision the record names (`human_allowed` / `human_refused` name a person; `policy_allowed` / `policy_refused` name the
+        policy). Server 7.113.0 value changes (MIGRATION 7.113.0 "audit face"): on the unattended legs (leader worker / repair
+        leg / `sema` CLI and their resumes) the machine's class-answer allow is now settled `policy_allowed` with
+        `who.approver: "unattended_class_answer"` — it was `human_allowed` / `who.party: "person"` — and every policy refusal
+        (`UNATTENDED_APPROVAL_POLICY=deny`, a run-local refusal without a TTY, a decision with `settledBy: "policy"`) is
+        `policy_refused` with `who.party: "policy"` — it was `who.party: "none"` (still the shape on servers 7.93.3 – 7.112.x, where
+        `policy_refused` lives on `Settlement_fail_closed`; both spellings stay valid here). Readers that bucket by party read the new
+        word; a 7.112.x reader of a 7.113.0 ledger withholds the whole `gate` (it does not know the party). The refusal's own words
+        reach the model as the policy's words and are NOT on this record (no `note` seat).
+      required: [kind, who, when]
+      properties:
+        kind: { type: string, enum: [policy_allowed, policy_refused] }
+        who:
+          type: object
+          additionalProperties: false
+          required: [party]
+          properties:
+            party: { const: policy }
+            approver: { type: string, description: 'The seat that answered, secret-redacted (e.g. `unattended_class_answer`). Absent = the channel reported no name.' }
+        when: { type: integer, format: int64, description: 'Epoch ms, written at the settlement site.' }
+
     Settlement_approval_window_expired:
       type: object
       additionalProperties: false
@@ -13514,7 +13778,9 @@ components:
         thing — a person''s "no" is the user''s direction, a policy''s is a capability of this run; distinct
         from `no_approver` because a channel WAS wired and answered. This family carries NO `note` seat: the
         note seat belongs to the two human words, whose ABSENCE is a control-flow fact) · `task_aborted`
-        (the wait''s abort signal ended it).
+        (the wait''s abort signal ended it). 🔴 server >= 7.113.0 (core 7.39.0): a policy refusal is spelled with `who.party: "policy"`
+        and lives on `Settlement_policy`; `policy_refused` + `who.party: "none"` here is the 7.93.3 – 7.112.x shape, kept for the
+        servers inside the support window.
       required: [kind, who, when]
       properties:
         kind:
@@ -13598,9 +13864,13 @@ components:
         unattended leg run under `UNATTENDED_PERMISSION_MODE=dontAsk`).
     AskClass:
       type: string
-      enum: [content_question, hook, ancestor, unverifiable_delete, transcript_write, org_rule, governance_unavailable, rule_unreadable, ask_rule, denial_limit_fallback, operator_forced, write_protection_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, ordinary]
+      enum: [content_question, hook, ancestor, unverifiable_delete, transcript_write, org_rule, governance_unavailable, rule_unreadable, ask_rule, denial_limit_fallback, operator_forced, shell_floor, write_protection_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, ordinary]
       description: >
-        core 7.34.0 `ASK_CLASSES` (twenty words) — which CLASS an ask falls in (the columns of the mode × class arbitration table).
+        core `ASK_CLASSES` (twenty-one words as of core 7.39.0 — 7.34.0 minted twenty; `shell_floor` joined in 7.39.0 #1260 and rides
+        server >= 7.113.0) — which CLASS an ask falls in (the columns of the mode × class arbitration table).
+        `shell_floor` = the operator's `shellGate: "always"` floor on a shell-running seat (the question the `operator_always` mandate
+        word discloses), a class of its own so a set that holds another forced question still holds it; like `operator_forced` it is
+        bypass-IMMUNE (not releasable).
         CLOSED on the gate record (screened with core `isAskClass`). `bypassPermissions` releases only the nine RELEASABLE classes
         (`transcript_write` / `rule_unreadable` / `probe` / `write_protection` / `tool_marks_mcp` / `tool_marks_a2a` /
         `artifact_shared_read` / `mode` / `ordinary`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
@@ -14137,7 +14407,14 @@ components:
       required: [type, inputId]
       properties:
         type: { const: human_input }
-        inputId: { type: string, description: 'Stable per-input id (also the durable steering queue idempotency key).' }
+        inputId:
+          type: string
+          description: >
+            Stable per-input id (also the durable steering queue idempotency key). server >= 7.113.0 (wire VALUE change): for a LIVE steer
+            it is the receipt's `messageId` verbatim — keyless steers included (<= 7.112.0: an engine-minted uuid whenever no
+            `Idempotency-Key` was sent); with a key it is `idem-<sha256[:32]>` on both the live and the parked leg. 🚧 A keyless PARKED
+            steer is the exception (contract §19): the server passes no `inputId` with the parked entry, so this id does not join the
+            receipt's `messageId`.
         sessionSeq: { type: integer, description: 'Leg-scoped monotone sequence of human inputs.' }
         carrier: { type: string, description: 'Which carrier delivered it (steer / objective / a source word). Open on read.' }
         source: { type: string, description: 'objective | steer | next_turn | wake | external | system. Open on read.' }
@@ -18074,7 +18351,18 @@ components:
         taskId: { type: string }
         status: { type: string, description: 'The run status the server saw at delivery time (running | suspended | a terminal status).' }
         delivery: { type: string, enum: [applied, queued, parked_for_wake] }
-        messageId: { type: string, description: 'Server-minted, stable across all three legs.' }
+        messageId:
+          type: string
+          description: >
+            Server-minted, stable across all three legs (`idem-<sha256[:32]>` when an `Idempotency-Key` was sent, else a fresh uuidv7).
+            server >= 7.113.0 (wire VALUE change, no new key): on the LIVE leg (`delivery: "applied"`) the server ALWAYS hands this
+            same value to the engine as the steer's `inputId` — keyless steers included (<= 7.112.0 passed it only when a key was sent,
+            so a keyless live steer's `human_input.inputId` was an engine-minted uuid that never joined this receipt). So the
+            `human_input` frame of that steer (`delivery: "applied"` / `"queued"`) carries `inputId === messageId`, and the user-input
+            acceptance ledger (`userInputUndrained[].messageId`) is keyed by the same value. The PARKED legs: with a key,
+            `inputId === messageId` as before; 🚧 a KEYLESS parked steer (`delivery: "queued"` / `"parked_for_wake"`) is the documented
+            exception (contract §19) — the server passes no `inputId` with the parked queue entry, so this `messageId` is never that entry's
+            `inputId` and the later `human_input` frame does NOT join it.
         priority: { $ref: '#/components/schemas/SteerPriority' }
         note: { type: string, description: 'Human-readable note on the two parked legs; absent on `applied`.' }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "15.4.0",
+  "version": "16.0.1",
   "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",
@@ -52,6 +52,6 @@
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build && npm run typecheck --workspaces=false --prefix ../.. && npm test --workspaces=false --prefix ../.. && npm run prepack"
   },
   "devDependencies": {
-    "@sema-agent/settings-schema": "^6.4.0"
+    "@sema-agent/settings-schema": "^7.0.1"
   }
 }