@sema-agent/sdk 15.3.0 → 16.0.0

package/openapi.yaml

@@ -677,7 +677,8 @@ paths:
         (non-owner → 404, no existence leak; missing principal → 401). All responses are synchronous ACKs; actual
         termination is async (same-replica immediate; cross-replica ≈30s via the heartbeat tick). A cancelled run
         settles to `status` failed + `errorCode` "cancelled" (NO new status — distinguish via errorCode; the UI
-        shows "cancelled", not an error). A SUSPENDED (or `needs_review`) run IS cancellable here — the server
+        shows "cancelled", not an error). From server >= 7.112.0 the cancelled terminal also carries
+        `abortCause: "cancel_verb"` (see `TaskResult.abortCause`; `errorCode` "cancelled" is unchanged). A SUSPENDED (or `needs_review`) run IS cancellable here — the server
         settles its pending checkpoint (CAS `expire`, the reaper's "≈ deny" terminal — deliberately not a
         resume, since cancel means the run dies) and THEN terminalizes the row, releasing the session claim;
         the ack is 202. (Corrected 2026-07-31: this paragraph used to say "409 — cancel it by DENYING its
@@ -1707,7 +1708,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:
@@ -1843,7 +1844,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:
@@ -1879,7 +1885,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
@@ -2056,7 +2067,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' }
@@ -3306,7 +3327,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
@@ -6613,12 +6634,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
@@ -7356,6 +7383,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 }
@@ -7364,7 +7400,6 @@ components:
               oneOf:
                 - { type: boolean }
                 - { type: object, properties: { maxFiles: { type: integer } } }
-            planModeReminder: { type: boolean }
             budgetUsd: { type: boolean }
             backgroundTasks: { type: boolean }
             toolsDelta: { type: boolean }
@@ -7503,11 +7538,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
@@ -7655,6 +7721,117 @@ 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: >
+            server >= 7.112.0 (S-947; cli L-212; contract §5.0d; additive) — the machine-readable CAUSE of a SERVER-INITIATED
+            abort, a side key beside `cancelContext` (it is NOT inside `terminal`: `terminal` is the engine's cause, and one
+            object must not have two minters). PRESENT-IFF this result IS the cancelled terminal the server minted for that
+            abort (`terminal.kind: "failed"` + `terminal.code: "cancelled"`); a server >= 7.112.0 always stamps it on the
+            cancelled terminal it mints (the mint's cause parameter is mandatory; the engine never mints `cancelled` itself).
+            🔴 It sits BESIDE the cancel code and never replaces it: the row's `errorCode` column / `terminal.code`
+            (`"cancelled"`) stays the "this is a cancel" discriminant, unchanged — this key only answers "who made it stop".
+            ABSENT (not a cancelled terminal the server minted for its own abort): a detach disconnect
+            (`x-detach-on-disconnect: true`, the server does not abort); the engine's own failure; a normal completion;
+            `POST /v1/runs/{taskId}/interrupt` (terminal `completed` + `haltedByUser`); a park (including a #241 grace park);
+            a terminal that RACED the abort (the engine finished first / failed with its own code — "fill the empty seat
+            only": code, snapshot and cause are all left off together); a resume leg cancelled BEFORE its approved action
+            started (the engine rules `resume.reopened_unstarted` and the park reopens — the run was not ended); a
+            preempt (`paused`); an orderly shutdown or a dead-holder reap.
+            🔴 A cancelled row persisted by a server before 7.112.0 has NO `abortCause` and is never back-filled: a row with
+            `errorCode: "cancelled"` and the key absent = cause NOT RECORDED — do not fold it into any word.
+            Four landings, one value: `GET /v1/runs/{taskId}` -> `result.abortCause` (beside `result.cancelContext`) ·
+            `POST /v1/tasks/stream` -> `done.result.abortCause` · the `POST /v1/tasks` 200 body, at its TOP LEVEL (the body IS
+            the result, contract §5.0c) · `GET /v1/runs/{taskId}/events` -> the `done` row's `result.abortCause`; a cancelled
+            shape with NO `done` row to land on (a disconnect after which no done was read / the leg aborted before its
+            terminal threw) lands on the `failed` row at its TOP LEVEL instead (`Event_failed.abortCause`, beside `errorCode`).
+            Two wire VALUE changes ride the same release (not new keys): a resume leg cancelled AFTER the approved action
+            started now ends `failed` + `errorCode: "cancelled"` + a `cancelContext` snapshot + `abortCause: "cancel_verb"`
+            (before 7.112.0 it ended `failed` with NO code); an interactive `POST /v1/tasks/stream` that read no `done` and
+            was NOT aborted by the server now ends with the honest failure sentence `stream ended before a terminal event`
+            (no code, no `abortCause`; before 7.112.0 it was always minted as a "client disconnected" cancelled terminal).
+
+    AbortCause:
+      type: string
+      enum: [client_disconnected, ask_park_grace_exhausted, cancel_verb]
+      description: >
+        The closed three-word vocabulary of `abortCause` (server >= 7.112.0 / S-947; contract §5.0d) — who initiated a
+        server-side abort. Each word has one real site: `client_disconnected` — a non-detach `POST /v1/tasks/stream` client
+        disconnect while no in-stream ask was pending, aborted at once ("the connection dropped, the run was aborted" — not an
+        engine error); `ask_park_grace_exhausted` — the same disconnect arm but an in-stream ask WAS pending: the server first
+        turns the ask into a park through the window-expiry path and gives the engine a bounded grace (10 s) to finish
+        parking, and the park still had not landed when the grace ran out, so the run was aborted; `cancel_verb` —
+        `POST /v1/runs/{taskId}/cancel` (the same-replica fast path, a cross-replica durable cancel flag polled by the holding
+        replica on any of the four legs — interactive stream / non-streaming / background / resume —, and a parked run the
+        verb finalizes directly; the cause is the same word). First come, first served: a leg is aborted once, and the first
+        landing names the word — a cancel verb arriving after a disconnect, or a disconnect after a cancel, never rewrites it.
+        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
@@ -7865,10 +8042,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
@@ -7936,6 +8117,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
@@ -7973,14 +8177,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: >
@@ -12235,7 +12448,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).
@@ -13020,7 +13235,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`.'
@@ -13039,6 +13256,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
@@ -13362,8 +13611,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.
@@ -13374,6 +13623,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'
@@ -13396,6 +13646,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
@@ -13467,7 +13745,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:
@@ -13551,9 +13831,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,
@@ -14090,7 +14374,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.' }
@@ -16634,6 +16925,8 @@ components:
       type: object
       # 封闭 + 回填 `activeTaskId`(census 轴一,2026-07-30):[1833] G10 —— session 已有活跃 run 的冲突
       # 失败形会带上占用者 taskId(SDK events.ts 早已声明,spec 侧漏)。
+      # server 7.112.0(S-947;sdk 15.4.0 / K-42):+`abortCause`(没有 done 可落的取消形的成因落在本行顶层)。封闭对象不声明它,server 的真 `failed` 行对 15.3.0 spec 就是
+      # 「$ must NOT have additional properties」—— 门 6 契约套抓不到这一件,由 `test/server-7112-wire.test.ts` P2(真 `buildCancelledLedgerRow` × spec)抓。
       additionalProperties: false
       required: [type]
       properties:
@@ -16641,6 +16934,16 @@ components:
         errorCode: { type: string }
         errorMessage: { type: string }
         activeTaskId: { type: string, description: '冲突失败形:当前占着该 session 的 run —— 消费方可直接引导 cancel/attach。' }
+        abortCause:
+          allOf: [{ $ref: '#/components/schemas/AbortCause' }]
+          description: >
+            server >= 7.112.0 (S-947; contract §5.0d) — the cause of a cancelled shape that has NO `done` row to carry
+            `result.abortCause` (a disconnect after which no done was read / the leg was aborted before its terminal threw),
+            landing at this row's TOP LEVEL beside `errorCode` (the cancelled shape's `errorCode` is `"cancelled"`, unchanged).
+            Same closed words and the same present-iff gate as `TaskResult.abortCause`: PRESENT-IFF this row is the cancelled
+            shape the server minted for its own abort. A `failed` row WITHOUT `errorCode` / `abortCause` (only
+            `errorMessage`, e.g. `stream ended before a terminal event`) is an honest failure and is NOT a cancel — never
+            read it as "disconnected". A cancelled row persisted before 7.112.0 has no `abortCause` (cause not recorded).
 
     # ══════════════════════════════════════════════════════════════════════════════════════════════
     # 🔴 census 轴一(2026-07-30)补的**四个未登记臂**。它们不是「将来会有」——**今天就在 wire 上**:
@@ -18015,7 +18318,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.3.0",
+  "version": "16.0.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",