@sema-agent/sdk 12.0.0 → 13.0.0

package/openapi.yaml

@@ -413,6 +413,15 @@ paths:
       description: >
         Synchronous run-to-completion. Auto `Idempotency-Key` (→ retry-safe). Supports `verify`/`cascade`.
         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
+        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
+        as 200 with a failed body (`terminal.code`; billed; a same-key resend replays). Multi-tier callers must read both
+        forms. On a park the 200 body is the result itself plus the three poll-receipt keys (`SyncSubmitResult`, S-173).
       parameters:
         - $ref: '#/components/parameters/IdempotencyKey'
       requestBody:
@@ -422,15 +431,49 @@ paths:
             schema: { $ref: '#/components/schemas/TaskRequest' }
       responses:
         '200':
-          description: Task result.
+          description: >-
+            The task result (`SyncSubmitResult`): the sealed + redacted engine result; on a park (`terminal.kind:"paused"`)
+            it additionally carries the poll receipt `{taskId, sessionId, status}` with `status` ∈ {suspended, needs_review}
+            (server >= 7.104.0 / S-173 — before that a park answered ONLY those three keys). Terminal bodies carry no `status`
+            on >= 7.64; a server <= 7.63 answers the flat form instead (terminal word in `status`, no `terminal`) — see SyncSubmitResult.
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/TaskResult' }
+              schema: { $ref: '#/components/schemas/SyncSubmitResult' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403': { $ref: '#/components/responses/Forbidden' } # (declared 2026-08-01) 带 `sessionId` 复用他人会话:归属不匹配 ⇒ 403(自公开快照起点即有,spec 此前漏登记)。server 3.15.0 起多一个触发条件:多租部署上 session store 无归属判别能力时,复用**任何** caller 自报的 sessionId 都 403(含本 worker 自己刚铸的 —— 无 register seam 时归属从未被记下)。core 2.11.0 起默认内存店自带该能力 ⇒ 该触发条件在默认部署上不再出现。 ⚠️ (declared 2026-08-05,server >=7.0.0)`memory.admission_denied` 也走本状态 —— 本状态的 producer 全清单与分支判据写在 `Forbidden` 组件的 description 里(**那段是被解析的**,本行注释只是指路,不复述以免两处漂移)。
-        '409': { $ref: '#/components/responses/Conflict' }
+        '409':
+          description: >-
+            Conflict (ConflictError). 409 — session already has an active run (`conflict.session_active_run`, `activeTaskId`,
+            `pendingGate`), OR an idempotency/session-CAS conflict. ⚠️ The SDK surfaces it as a TYPED ConflictError and does
+            NOT silently resolve it to that run: `activeTaskId` may be the caller's own first attempt OR an unrelated
+            concurrent run on the same session — 409 alone cannot tell (same text as the `Conflict` response component).
+            K-24 (server >= 7.104.0 / S-724, zero-work submissions only): `rewind.store_unconfigured` — this
+            deployment has NO file-history store but the request asks to restore files; the request is well-formed, the
+            deployment shape conflicts with it (change the deployment, not the request; `capabilities.rewindFiles` is false
+            there). Before 7.104.0 it arrived as 200 with a failed body.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: >-
+            Semantically unprocessable. K-24 (server >= 7.104.0 / S-724): `rewind.capture_disabled` — the run turned file
+            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.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '429': { $ref: '#/components/responses/RateLimited' }
+        '500':
+          description: >-
+            K-24 (server >= 7.104.0 / S-612): `corrupt_session` — this session's saved log cannot be read at all (file backend:
+            no meta header; SQL backends: one `session_event.payload` row is not a readable entry). Nothing ran, nothing
+            billed; `error` is the engine / store sentence (no on-disk path). DETERMINISTIC: a retry cannot change it (the SDK
+            does not auto-retry this code); the repair is the operator's. Also `internal.error` (unclassified).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '503': { $ref: '#/components/responses/Unauthorized' } # ⚠️ (declared 2026-08-05,server >=7.0.0)本操作的 503 producer 不止 auth 门 —— producer 清单在 `Unauthorized` 组件的 description、等待提示的在场矩阵在该组件的 `headers.Retry-After`(**两段都是被解析的**;本行只指路,不复述以免漂移)。
     get:
       tags: [trace]
@@ -1649,6 +1692,13 @@ paths:
         rows. Owner-scoped (non-owner → 404). Idempotent (`{deleted:false}` when nothing existed). 🔴 409 while a run
         is LIVE on the session (`activeTaskId` in the body) — cancel it first so the session lock isn't orphaned.
         501 without a durable session store.
+        🔴 K-24 / S-790 (server >= 7.104.0): the delete FIRST ends the background children rooted at this session (parked
+        ones are retired — their cards leave the pending list and a later decide on such a card answers 409
+        `decide.not_parked`; running ones on this replica are stopped) and only then deletes the record. A child it cannot
+        stop (typically running on ANOTHER replica) ⇒ the delete is refused and the session record stays (contract: nothing
+        deleted; int-7104 `4a7f72e4` moves that check before every destructive step): 409 `conflict.session_children_alive`
+        with `remaining`. A log that cannot be read at all, when the ownership probe has to open it (cold owner table after
+        a restart) ⇒ 500 `corrupt_session` (S-612; the bad log stays on disk).
       responses:
         '200':
           description: Delete result (idempotent).
@@ -1669,7 +1719,21 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
-        '409': { $ref: '#/components/responses/Conflict' }
+        '409':
+          description: >-
+            Two conflicts, told apart by `errorCode` (both ConflictError): `conflict.session_active_run` — a run is LIVE on the
+            session (`activeTaskId`), cancel it first; `conflict.session_children_alive` (server >= 7.104.0 / S-790) — some
+            background children rooted at this session could not be stopped from here, NOTHING was deleted, and `remaining`
+            lists their ids (the same strings as `GET /v1/agents/roster`'s `handle`): wait for them to finish or stop them
+            where they run, then retry the delete verbatim (idempotent). Not a server fault — do not back off as for a 5xx.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '500':
+          description: '`corrupt_session` (server >= 7.104.0 / S-612): the session log cannot be read at all and the ownership probe had to open it (cold owner table); the delete is refused and the log stays as it is. Deterministic — not auto-retried. Also `internal.error` (int-7104 `4a7f72e4`: children this replica could stop but did not stop cleanly — the session record stays, a retry converges).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/sessions/{sessionId}/fork:
@@ -3114,6 +3178,12 @@ paths:
             `not_found.approval` (it used to 409 — a single-bit cross-tenant "who is parked on an approval"
             oracle); a legitimately-owned old token (a shell retrying its own already-decided row) keeps the
             attributable 409 + `terminal:"resolved"` verbatim.
+            PARKED-CHILD lane, K-24 (server >= 7.104.0 / S-790) — two codes gain a trigger, same code, same body keys:
+            `decide.not_parked` (DecideParkMovedError) now also answers when the child's ROOT SESSION was deleted, or deleted
+            and the same id re-registered as a new session (the decide leg reads the root session's occupant before and after
+            the claim and rolls back when it is gone or different) — a 7.104.0 session delete retires such cards, so this form
+            mostly meets cards left by a pre-7.104.0 delete; `decide.row_unrevivable` (DecideError) now also answers when the
+            parked row carries no root-session anchor (refused before the claim, nothing consumed).
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -3140,6 +3210,13 @@ paths:
             (grandchild) row, or one whose root session was deleted / changed owner, still does (core #1112 pending) —
             render it as "this card can only be denied / wait for a server upgrade". Not a regression: 7.31.x children
             never had those tools.
+            🔴 THE TWO CAUSES ARE TOLD APART BY `cause` (server S-818, riding core #1161; ADDITIVE, optional): the body may
+            carry `cause` — core's CAUSE WORD for this startup failure, relayed VERBATIM from the engine receipt's `details`
+            (no rewrite, no default; absent when the engine did not say, i.e. every server before S-818 and every core before
+            #1161). The closed set is core's (#1161 exports it as a constant, named in core 7.34.1's release notes); this
+            spec copies no word list, so treat it as an OPEN string with a default arm. Absent ⇒ "cannot tell": offer both
+            ways out. SDK → `ParkedResumeStartupError.startupCause` (`undefined` when absent or not a string; the wire key stays
+            `cause` — the SDK does not put it on the standard `Error.cause`, which means a chained error).
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -4034,7 +4111,7 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/AskDecisionAck' }
         '400':
-          description: 'Malformed body — `request.invalid_json` (unparseable) or `request.body_shape` (schema reject, e.g. an `actor` carrying anything but `label`).'
+          description: 'Malformed body — `request.invalid_json` (unparseable) or `request.body_shape` (schema reject, e.g. an `actor` carrying anything but `label`, or — on a server < 7.104.0 — a `settledBy` key). Server >= 7.104.0 (S-843) adds the `settledBy` refusals shared with the durable `/decide` leg: `request.field_conflict` (with a non-deny decision), `settled_by_not_in_proof` (direct-door worker), `request.field_invalid` (non-string, or outside the 1..16-character column) — see AskDecisionBody.settledBy.'
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -6267,6 +6344,11 @@ components:
         `state.model_roster_pending` (roster not loaded yet; retry -> ServiceStateError), and (server >=7.0.0,
         synchronous `POST /v1/tasks` only) `memory.admission_required` — the org-memory admission directory is
         transiently undecidable, refused fail-closed BEFORE any model call, mapped to MemoryAdmissionError.
+        K-24 (server >= 7.104.0 / S-271, synchronous `POST /v1/tasks` only, and only when the submission did zero work):
+        `config.tool_name_too_long` / `config.tool_contract_too_long` / `config.tool_roster_bound` — a tool the DEPLOYMENT
+        declared exceeds the roster bound (name 128, contract id / revision 64, `modelGate` 64); the caller cannot route
+        around it and a verbatim retry never changes it (DETERMINISTIC — the SDK does not auto-retry these codes; they land
+        on ServiceStateError via the 503 tail, with no wait hint); only the deployment fixing its declaration helps.
         Which of them carry a wait hint is stated ONCE, under `headers.Retry-After` below (kept in one place so
         the two statements cannot drift apart).
       headers:
@@ -6369,8 +6451,16 @@ components:
     Scenario:
       type: string
       description: >
-        Primary routing axis (one image serves many; unknown → "default"). Selects model/tools/skills/prompt.
-      examples: ['default', 'oa', 'code-review', 'team']
+        Primary routing axis (one image serves many). Selects model/tools/skills/prompt. OPEN: a stock server's builtin
+        table is `code` (factory default) / `default` / `code-review` / `scan` (SDK `KNOWN_SCENARIOS`, checked against the
+        published server's `buildScenarios()` table) plus `discuss` — still accepted today, deliberately not in
+        `KNOWN_SCENARIOS` because it sits inside core #1056's (7.35.0) retirement sweep (server S-630 ②) — and a deployment may
+        register more through the registry. A name
+        the caller SENDS that the deployment does not serve is a loud 400 `scenario_unknown` (server >= 5.1.0, the body
+        carries the live vocabulary) — the silent fold to `default` exists only on the server-side ASSIGNMENT chain.
+        Retired, no alias: `oa` (5.0.0), `autonomous` ([2400] CAPS-OPS-11), `team` (renamed `discuss`, server #273 / C-R14;
+        alias withdrawn at #342 — the discuss scenario's body key `team`, which picks the roster template, kept its name).
+      examples: ['code', 'default', 'code-review', 'scan']
 
     ScenarioDetail:
       # 新增(2026-07-25 回填批):`GET /v1/capabilities/scenarios/{name}` 此前**整条路径**都不在本文件里
@@ -6702,8 +6792,11 @@ components:
             `resumeAnchorStore.resolve(sessionId, handle, principal)` → entry id; unknown handle ⇒ 404
             `rewind_files_to.unknown_event`; no session ⇒ 422 `rewind_files_to.no_session`; no anchor store / no getLeafId ⇒
             501. ⚠️ The 501 is NOT the capability's whole predicate: `capabilities.rewindFilesTo` also requires the
-            file-history store (capture face); without it the server does not 501 — core refuses in the run with
-            `rewind.store_unconfigured` — so probe the bit first. Honored ONLY when `resumeAt` is absent. One-shot at submit
+            file-history store; without it the server does not 501 — core refuses at prepare with
+            `rewind.store_unconfigured` (server >= 7.104.0 / S-724: a 409 error body on the synchronous `POST /v1/tasks` when
+            the submission did zero work; the async / live legs keep a terminal run row with the same code; and
+            `FILE_HISTORY_CAPTURE=false` no longer triggers it) — so probe the bit first. Riding together with
+            `fileHistory: "disabled"` ⇒ 400 `request.field_conflict`. Honored ONLY when `resumeAt` is absent. One-shot at submit
             (resume legs strip it, server >= 7.72.0).
         restoreFiles:
           type: boolean
@@ -6726,6 +6819,19 @@ components:
             🔴 Applies to BOTH restore legs (codex R2 correction): `resumeAt`+`restoreFiles` AND the
             code-only `rewindFilesTo` — a code-only caller omitting it gets the loud terminal too. Recovery
             either way: re-run the same restore (per-file idempotent, converges).
+        fileHistory:
+          type: string
+          enum: [disabled]
+          description: >-
+            K-24 (server >= 7.104.0 / S-724; core 7.31.0 #1048 `TaskSpec.fileHistory`) — the REQUEST-LEVEL file-history off
+            word. ONE word, `disabled`: this run takes no first-touch backup of an edited file and mints no turn boundaries
+            (delegates inherit it); absent = the deployment's setting (there is no `enabled` spelling). Any other value ⇒ 400
+            `request.field_invalid` ("fileHistory must be the string 'disabled' when present …"), fresh and resume legs alike.
+            🔴 Riding together with ANY restore key (`restoreFiles` / `rewindFilesTo` / the retired `rewindFiles`) ⇒ 400
+            `request.field_conflict` AT ADMISSION ("fileHistory: 'disabled' cannot ride with a file restore …"), session and
+            files untouched — drop it to restore. The leg's own verdict is `wiring_manifest.fileHistory`; whether to render a
+            "don't capture this session" switch is `capabilities.fileHistoryCapture === "on-optional"` (the switch = send this
+            key on every submit of that session). ⚠️ A server < 7.104.0 answers 400 `request.body_shape` (unknown key).
         permissionMode:
           type: string
           enum: [default, plan, acceptEdits, bypassPermissions, auto]
@@ -7436,6 +7542,54 @@ components:
         sessionId: { type: string }
         status: { $ref: '#/components/schemas/RunStatus' }
 
+    SealedKeyCapability:
+      type: object
+      description: >
+        K-24 (server >= 7.104.0 / S-737) — the `GET /v1/capabilities` `sealedKey` segment: EXACTLY three keys, key-for-key
+        the server's `src/sealed-key.ts` `SealedKeyCapability`. Private keys, the custody path, the held key-id list and
+        `createdAt` never reach the wire.
+      additionalProperties: false
+      required: [alg, publicKeyId, publicKey]
+      properties:
+        alg:
+          type: string
+          enum: [libsodium-sealedbox-x25519]
+          description: 'v1 sole value, the same word as settings-schema `SEALED_BOX_ALG`; another alg is a loud per-model refusal.'
+        publicKeyId: { type: string, description: 'Goes into `sealedApiKey.publicKeyId` (server default mint `exec-<first 12 hex of sha256(raw public key)>`; treat as opaque); the engine opens with EXACTLY this key.' }
+        publicKey: { type: string, description: 'STANDARD base64 of the 32-byte X25519 public key (44 chars). Public — safe to log.' }
+    SyncParkReceipt:
+      type: object
+      description: >
+        K-24 (server >= 7.104.0 / S-173) — the three POLL-RECEIPT keys a synchronous `POST /v1/tasks` adds on a PARK (the
+        whole park body before 7.104.0, values byte-identical), key-for-key the server's `http/sync-submit-body.ts`
+        `SyncParkReceipt`. `status` is the word on the `GET /v1/runs/{taskId}` row — the server derives the two words from
+        its `RUN_STATUS_CLASS` table (the `parked` class).
+      additionalProperties: false
+      required: [taskId, sessionId, status]
+      properties:
+        taskId: { type: string, description: 'The durable run id minted at submit — the `GET /v1/runs/{taskId}` poll key.' }
+        sessionId: { type: string }
+        status: { type: string, enum: [suspended, needs_review] }
+    SyncSubmitResult:
+      description: >
+        K-24 — the synchronous `POST /v1/tasks` 200 body (server name `SyncSubmitBody`, one mint `buildSyncSubmitBody`).
+        ONE RULE (contract §5.0c): it is ALWAYS the result itself (the sealed + redacted engine result — `TaskResult`); when
+        the run is parked (`terminal.kind === "paused"`) it additionally carries the `SyncParkReceipt` keys, so `status`
+        appears ONLY on a park — terminal bodies carry none (since 7.64.0). A park here is byte-identical to the same park
+        on `/v1/tasks/stream`'s `done.result` except for the identity keys; the resume credential is never on it.
+        Read "is it parked" off `terminal.kind === "paused"`; the old reading `status ∈ {suspended, needs_review}` still
+        holds. ⚠️ THREE GENERATIONS behind one type (the SDK's support floor is 3.0.0): server <= 7.63 answers the FLAT form
+        (`LegacyPlaneTaskResult`: `status` is the terminal word — completed / failed / blocked or a park word — and there is
+        no `terminal`); 7.64–7.103 answers the current `terminal` form on terminal bodies but a park with ONLY the three receipt
+        keys (no `terminal`, no `stats`); >= 7.104 follows the rule above. Read `status` for "parked" first (all three carry
+        a park word on a park), then tell the generations apart by whether `terminal` is present.
+      allOf:
+        - $ref: '#/components/schemas/TaskResult'
+        - type: object
+          properties:
+            status:
+              allOf: [{ $ref: '#/components/schemas/RunStatus' }]
+              description: 'Poll-receipt word on a park (>= 7.64: suspended / needs_review only), or the flat terminal word of a server <= 7.63 (LegacyPlaneTaskResult.status).'
     RunRecord:
       type: object
       description: >
@@ -7492,12 +7646,18 @@ components:
             current cause form on anything server >= 7.64.0 wrote, and the retired flat form on rows written
             before the upgrade. The service passes the stored blob through verbatim (redaction only) and does
             NOT back-fill `terminal`. Narrow on `"terminal" in result`.
+            🔴 K-24 / S-173 (server >= 7.104.0, contract §5.0c): the key always describes the CURRENT state — a parked row
+            (`suspended` / `needs_review`) carries the result it stopped with (`terminal.kind === "paused"`, credential
+            stripped; = the synchronous 200 body minus `status`); a `running` row (incl. one claimed for resume) has none;
+            a terminal row replaces it whole; an approval-expiry / stale reap clears it. READ `status` FIRST — `result`
+            present does not mean finished.
         errorCode:
           type: string
           description: >
             Result-level terminal code (e.g. `budget.exceeded`, `cancelled`); NOT an HTTP error. This ROW COLUMN
             is unchanged at 7.64.0 — only its source moved (projected from `result.terminal`, or read straight
-            off a legacy flat blob).
+            off a legacy flat blob). ⚠️ K-24 / S-173 (server >= 7.104.0): on a `needs_review` PARK row it is core's canonical
+            `review.pending` (absent before) — never read "errorCode present" as "failed"; read `status` first.
         error: { type: string }
         jobId:
           type: string
@@ -8331,10 +8491,12 @@ components:
             Code-only rewind (`TaskRequest.rewindFilesTo`) is wired — mint `routes/capabilities.ts:839` =
             `Boolean(deps.fileHistoryStore && deps.resumeAnchorStore && deps.sessionStorage?.getLeafId)`: it needs the
             file-history store (to restore) AND the anchor map (to resolve the target HANDLE). Corrected in sdk 11.4.0
-            (board [8437] U3): the store is the FILE-HISTORY store (not the pre-S-15 whole-tree snapshot store), and since
-            server 7.97.0 (S-589) that seat is the CAPTURE face = backend AND the `FILE_HISTORY_CAPTURE` knob — a deployment
-            that turns capture off reports this bit false together with `rewindFiles` / `restoreFiles` / `sessionSync`
-            (and `fileHistoryCapture: "off"`).
+            (board [8437] U3): the store is the FILE-HISTORY store (not the pre-S-15 whole-tree snapshot store).
+            🔴 K-24: on server 7.97.0–7.103.x that seat was the CAPTURE face (backend AND the `FILE_HISTORY_CAPTURE` knob), so a
+            deployment that turned capture off reported this bit false together with `rewindFiles` / `restoreFiles` /
+            `sessionSync`. Since server 7.104.0 (S-724) the knob ONLY turns capture off (the store stays wired, stored history
+            still restores and syncs) — this bit and those three no longer depend on it; they read "is there a file-history
+            store" (= a storage backend). Gate rewind entries on this bit / `rewindFiles`, never on `fileHistoryCapture`.
         restoreFiles:
           type: boolean
           description: >-
@@ -8926,22 +9088,40 @@ components:
             ABSENT = an older worker (<= 7.94) ⇒ read as `true` (contract appendix B.1: it passed through back then).
         fileHistoryCapture:
           type: string
-          enum: ['off', on-always]
-          description: >
-            server >= 7.97.0 (S-589; mint `routes/capabilities.ts:847` = `fileHistoryCaptureOf(deps.fileHistoryStore)`,
-            closed word set owned by the server's `src/file-history-capture.ts` `FILE_HISTORY_CAPTURE_WORD_SET`) —
-            CAN FILE-HISTORY CAPTURE BE TURNED OFF. Derived from the ASSEMBLY RESULT (capture face = backend AND the
-            `FILE_HISTORY_CAPTURE` deployment knob), NOT an echo of the knob — a deployment without the backend is
-            `off` too; the SAME judgement as `rewindFiles` / `restoreFiles` / `rewindFilesTo` / `sessionSync`.
-            `off` = this deployment captures no first-touch snapshots and has no rewind / restore / code-only rewind /
-            session-sync ⇒ render neither a "turn capture off" switch nor a rewind entry. `on-always` = capturing, and
-            it CANNOT be turned off per session (core's first-touch capture is process-wide) ⇒ render one read-only true
-            sentence, never a switch that cannot switch.
-            🔴 A third word `on-optional` ("this session may skip capture") is DELIBERATELY UNDECLARED by the server (it
-            waits for a per-session no-capture seat in core); when it lands it is an additive server change and this
-            enum grows with it. Keep a default arm (unknown word ⇒ treat as unknown, render no switch). Turning capture
-            off does NOT delete what was already captured.
-            ABSENT = an older worker (<= 7.96) ⇒ fall back to `rewindFiles` (`true` ⇒ `on-always`, `false` ⇒ `off`).
+          enum: ['off', on-optional, on-always]
+          description: >
+            server >= 7.97.0 (S-589), WORDS CHANGED at 7.104.0 (S-724; mint int-7104 `routes/capabilities.ts:846` =
+            `fileHistoryCaptureOf(deps.fileHistoryStore, deps.config.fileHistoryCapture)`, closed word set owned by the
+            server's `src/file-history-capture.ts` `FILE_HISTORY_CAPTURE_WORD_SET`) — IS FILE-HISTORY CAPTURE ON, AND CAN A RUN
+            TURN IT OFF. Derived from the ASSEMBLY RESULT (store present AND the `FILE_HISTORY_CAPTURE` knob not off), NOT an
+            echo of the knob — a deployment without the backend is `off` too. Read it EXHAUSTIVELY:
+            `off` = this deployment captures no first-touch snapshots ⇒ render no "turn capture off" switch. 🔴 Since 7.104.0
+            it no longer implies "no rewind": the knob only stops capture, stored history still restores / syncs — gate rewind
+            entries on `rewindFiles` / `rewindFilesTo`, not on this bit.
+            `on-optional` = capturing, and a run CAN turn it off: send `fileHistory: "disabled"` on the submit ⇒ render the
+            switch (off = send it on every submit of that session; the resume legs replay the same body).
+            ⚰️ `on-always` is a RETIRED word: server 7.104.0 no longer sends it (once the request word is wired "capturing and
+            cannot be turned off" is structurally unreachable), but a 7.97.0–7.103.x worker still does = capturing and it
+            CANNOT be turned off per session ⇒ render one read-only true sentence, never a switch that cannot switch (contract
+            appendix B.1). It stays in this enum while the SDK's support floor (3.0.0) is below 7.104.0 — removing it would make
+            a valid 7.103 capabilities response fail this schema. An unknown word is treated as unknown (never guess by
+            prefix). Turning capture off does NOT delete what was already captured.
+            ABSENT = an older worker (<= 7.96, no knob at all) ⇒ fall back to `rewindFiles` (`true` ⇒ `on-always`, `false` ⇒ `off`).
+        sealedKey:
+          allOf: [{ $ref: '#/components/schemas/SealedKeyCapability' }]
+          description: >
+            K-24 (server >= 7.104.0 / S-737; mint int-7104 `routes/capabilities.ts:969`, a plain member
+            `sealedKey: projectSealedKeyCapability(deps.sealedKeyPublic)`) — the PUBLIC-KEY DISCOVERY face for sealed model
+            keys: the newest X25519 public key in this process's model-key custody store, exactly three keys. Seal a model key
+            (its UTF-8 bytes) with `crypto_box_seal` against `publicKey`, encode the ciphertext as STANDARD base64 and write it
+            with `alg` / `publicKeyId` into `ModelEntry.sealedApiKey` (local lane: `config.d/models.json`; server USAGE §9.10).
+            Sealed wins over `apiKeyEnv`; a key that cannot be opened fails that model on every call (no fallback to
+            `apiKeyEnv`, none to the gateway key).
+            🔴 PRESENT-IFF — the one per-key exception on this surface (contract appendix B.1): ABSENT means an older server
+            (< 7.104.0) OR this engine built no custody store today (the same body's `version` tells them apart); either way
+            do NOT seal — use `apiKeyEnv`, or fix the custody directory and restart. Absent is a missing key, never `null`.
+            🔴 ONE STORE PER HOST (`<data root>/sealed-key/`): replicas that do not share that directory answer different
+            keys, and a ciphertext sealed against replica A's key is `stale_ciphertext` on replica B.
         background:
           type: object
           additionalProperties: true
@@ -12421,6 +12601,13 @@ components:
             catch and answered 500 `internal.error` — a caller-side mistake reported as a server fault, which
             also made it a retry-worthy-looking code. A consumer that branched on 500 for those paths must move
             the branch to the 400 (the fix is the caller's either way: re-encode the id).
+            🔴 DETERMINISTIC failure codes (K-24): a few codes arrive on a status that normally means "retry may help" (500 /
+            503) while the server contract says a verbatim retry NEVER changes the verdict. The SDK's retry arm exempts them
+            by code: `corrupt_session` (500, server >= 7.104.0 / S-612 — the session's saved log cannot be read),
+            `config.tool_name_too_long` / `config.tool_contract_too_long` / `config.tool_roster_bound` (503, server >=
+            7.104.0 / S-271 — a deployment-declared tool exceeds the roster bound), `corrupt` (500 — the session rule store
+            cannot read its own bytes) and `internal.memory_control_plane_corrupt` (500 — the memory control plane refuses
+            fail-closed). Every other 5xx code keeps the status-based retry.
         error: { type: string }
         errorMessage: { type: string }
         activeTaskId:
@@ -12441,6 +12628,30 @@ components:
             🔴 NOT interchangeable with `taskId`: the workflow-child park lane mints no taskId at all (this
             decision never landed on any run, so minting one would be a lie), and the other two decide lanes
             mint no runId. Branch by `errorCode`, never fall back from one handle to the other.
+        cause:
+          type: string
+          description: >-
+            server S-818 (riding core #1161), on `parked_resume.startup_failed` (422) ONLY: core's CAUSE WORD for the parked
+            resume's startup failure, relayed verbatim (never rewritten, never defaulted; absent when the engine did not say).
+            An OPEN string here — the closed set is core's (#1161 exports it; the constant's name is in core 7.34.1's release
+            notes). Absent ⇒ cannot tell which of the two causes (see the `/v1/approvals/{sessionId}/decide` 422 text).
+            SDK reads it as `ParkedResumeStartupError.startupCause`.
+        remaining:
+          type: array
+          items: { type: string }
+          description: >-
+            K-24 (server >= 7.104.0 / S-790), on 409 `conflict.session_children_alive` ONLY (`DELETE /v1/sessions/{sessionId}`):
+            the ids of the background children rooted at this session that are still alive (count = length) — the SAME
+            strings as the `handle` on `GET /v1/agents/roster` rows. Nothing was deleted; wait for them to finish (or stop
+            them where they run) and retry the delete verbatim. SDK: `err.extra.remaining` on the ConflictError.
+        blockedBy:
+          type: string
+          description: >-
+            On 409 `resume_blocked_by_policy` ONLY: the `errorCode` the folded refusal would have carried had it gone out
+            directly — the original code when it had one, else the status-derived coarse code (`request.rejected` /
+            `not_found.resource` / `request.unprocessable` / `capability.unavailable` …). ALWAYS PRESENT on server >= 7.104.0
+            (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).
 
     # ── 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
@@ -13687,6 +13898,17 @@ components:
             server >= 7.66.0 (core 7.8.0 design/388 B-4) — this leg's WHOLE tool roster. The service passes it
             through verbatim only after core's own typebox check accepted it; a roster that fails that check is
             ABSENT as a whole (never half a roster on the wire). Effective half only (never on the static half).
+        fileHistory:
+          type: string
+          description: >
+            K-24 (server >= 7.104.0 / S-724; core 7.31.0 #1048 / #1050; contract appendix G.20) — TENANT and OPERATOR faces
+            alike: does THIS LEG capture file history. `on` = edited files are backed up before the first touch and turn
+            boundaries are minted; `disabled` = no capture, whatever the cause (the request word `fileHistory:"disabled"`,
+            the deployment knob `FILE_HISTORY_CAPTURE=false`, no history store, no filesystem on this leg). Effective half only.
+            🔴 `disabled` ≠ "cannot restore": with the deployment knob off stored history still restores
+            (`capabilities.rewindFiles`); only a run the REQUEST word turned off cannot restore itself.
+            OPEN on read: the server does not enumerate the word (a present non-string is dropped), a third word passes
+            through — treat it as unknown. ABSENT = an older engine / external derivation, never "capturing".
         eventId: { type: string }
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
@@ -13992,6 +14214,21 @@ components:
         was armed but declined/failed (check the store, check authorisation), `false` = there was no lane at all
         (wire one up). The two recovery verbs differ, so a consumer MUST render them apart — NEVER fold them into
         one "nobody approved it".
+        `session.records_skipped` (K-24; server >= 7.104.0 / S-612 form B; contract §17.4 / appendix D.3) — 🔴 SERVER-MINTED
+        (not in core's register; owner, audience `user` and mint all live in the server). The session's saved log was
+        OPENED and some records could not be read and were skipped (file session backend only — both SQL backends refuse a
+        bad row with `corrupt_session`); the session woke up and THIS TURN RUNS, but the model sees a shorter history.
+        `{ dropped, entriesKept, sessionId }`: `dropped` = records skipped by this replay, `entriesKept` = surviving entries
+        counted after the open succeeded (the meta header not counted); both are observed counts — do NO arithmetic (there
+        is no "total"); `entriesKept === 0` = header present, no entry left (empty context, the turn still runs). NO `runId`
+        (minted inside the session store's open; attribution = whichever run's stream / ledger it lands on). Deduplicated
+        ONCE PER OPEN: until the log is repaired every real open emits again; a turn served from the server's session cache
+        (`SESSION_CACHE_TTL_SEC`, default 300 s) does not reopen and emits nothing — an event, not a standing state. Only an
+        open "for this session itself" mints it (a list / export / head / ownership probe reading another session's bad log
+        does not). ⚠️ When a skipped record is an ancestor of the current leaf the turn then fails `invalid_session` in
+        prepare (core #1077) — the frame still arrives first. ⚠️ The non-streaming synchronous `POST /v1/tasks` registers no
+        notice delivery (every `engine_notice` code alike), so there it reaches the operator log only. A log that cannot be
+        read AT ALL (no meta header) emits no frame — that turn is refused with 500 `corrupt_session`.
         Starter whitelist (server 7.36): `memory.session_polluted` `{reason, sessionId?}` ·
         `memory.harvest_quarantined` `{count, moved, escalated, reason?}` — `moved` and `escalated` MUST NOT be
         subtracted from each other (an in-place tombstone counts as both) · `memory.delegation_static_mark_waived`
@@ -15629,6 +15866,25 @@ components:
           additionalProperties: false
           properties:
             label: { type: string, maxLength: 256 }
+        settledBy:
+          type: string
+          enum: [policy]
+          description: >-
+            server S-843 (>= 7.104.0), ADDITIVE — the SETTLEMENT SOURCE of this decision. Same word, same source, same
+            sentence as the durable decide leg's key (`POST /v1/approvals/{sessionId}/decide`, ApprovalDecision.settledBy —
+            see that schema for the full account; the server judges this door and `/decide` with one function, and the live
+            respond leg reads the same two refusal sentences under its own `request.body_shape` family):
+            `"policy"` = the deployment's own policy answered this card, not a person; ABSENT = today's shape.
+            `decision:"deny"` only (an approve carrying it ⇒ 400 `request.field_conflict`); REFUSED on a direct-door worker
+            (400 `settled_by_not_in_proof`); a non-string ⇒ 400 `request.field_invalid`. 🔴 An UNKNOWN word is the OPPOSITE of
+            `/decide` here: this door does not judge the word, so it answers 200 and the word is stored with the decision (the
+            card is settled as `deny`; its source cannot be corrected afterwards, and an idempotent replay replays it), and the
+            engine refuses the word fail-closed at settlement — NOT `/decide`'s 409 `resume_outcome_invalid` with the card left
+            pending for a corrected re-decide. THIS leg only: the value lands in a fixed-width
+            `settled_by` column — outside 1..16 characters ⇒ 400 `request.field_invalid` before the CAS; none of the three
+            response bodies echoes it. OLDER SERVERS (< 7.104.0): this body schema is strict, so the key is an unknown key ⇒
+            400 `request.body_shape` and nothing is decided — a loud refusal, not a silent drop. No capability bit; gate on
+            the server version.
 
     AskDecisionAck:
       type: object
@@ -16710,7 +16966,7 @@ components:
         🔴 ONE RULE FOR EVERY "EFFECTIVE HALF ONLY" KEY (sdk 9.7.0, after a codex adversarial-review [high]):
         this schema's only consumer today is `GET /v1/diagnostics/wiring`'s `static` half, and every key marked
         "effective half only" (`leg`, `ask.effective`, `configFingerprint`, `tools`, `hooks`, `lsp`,
-        `modelGate`, `autoMode`, `writeProtection`, `readDeny`, `autoConsolidation`) is ALWAYS ABSENT on that
+        `modelGate`, `autoMode`, `writeProtection`, `readDeny`, `autoConsolidation`, `fileHistory`) is ALWAYS ABSENT on that
         wire ⇒ THEIR ABSENCE HERE CARRIES NO INFORMATION. The per-key absence readings ("absent = not armed",
         "absent = a third state", …) hold for the LIVE FRAME (`Event_wiring_manifest`) and must not be carried
         over to this response. For the facts behind those keys: a tenant reads
@@ -16885,6 +17141,12 @@ components:
             the operator LIVE projection; for "is this deployment armed", read
             `GET /v1/sessions/{sessionId}/memory-status`'s `autoConsolidationArmed` (always present, a real
             boolean). Full per-key contract: see Event_wiring_manifest.autoConsolidation.
+        fileHistory:
+          type: string
+          description: >
+            K-24 (server >= 7.104.0 / S-724) — does this leg capture file history (`on` / `disabled`, OPEN word). EFFECTIVE
+            HALF ONLY ⇒ ALWAYS ABSENT ON THIS ENDPOINT; the deployment-level reading is `capabilities.fileHistoryCapture`.
+            Full per-key contract: see Event_wiring_manifest.fileHistory.
     WiringManifestWriteProtection:
       # sdk 9.7.0:与 `WiringManifestMcpEntry` / `WiringManifestLspSeam` 同一条裁定 —— 同一段形被 live 帧与
       # 静态诊断面两处引用,内联就是两份会各自漂的镜像,所以具名单源。

package/package.json

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

package/registry-openapi.yaml

@@ -129,9 +129,12 @@ paths:
         🔴 CAS axis = the `updatedAt` STRING (verbatim echo), NOT a version number — the scopes/config
         face below uses a NUMBER `version` axis; the two axes must never be mixed (pinned). 409 carries
         `currentUpdatedAt` (typed ConfigCasConflictError; retryOn409 merge-callback retries ONCE).
+        409 SCOPE-GONE (web-admin W41F, 2026-09-27): the scope this token is bound to no longer exists ⇒
+        `409 {error:"scope_gone", error_description}` — NO `currentUpdatedAt`, nothing written, NOT a CAS conflict:
+        never refetch+merge+retry it (the SDK throws `ScopeGoneError` and skips the merge leg; `classifyRegistryConflict`).
       responses:
         '200': { description: Written. }
-        '409': { description: '{currentUpdatedAt} — concurrent write; refetch+merge+retry once.' }
+        '409': { description: '{error:"conflict", currentUpdatedAt} — concurrent write; refetch+merge+retry once. OR {error:"scope_gone"} — the token''s scope no longer exists; nothing written; do NOT retry.' }
   /api/v1/users/{u}/config/{domain}:
     parameters:
       - { in: path, name: u, required: true, schema: { type: string } }
@@ -145,7 +148,7 @@ paths:
       summary: Managed CAS-write (same updatedAt axis + 409 semantics as me/config).
       responses:
         '200': { description: Written. }
-        '409': { description: '{currentUpdatedAt}.' }
+        '409': { description: '{error:"conflict", currentUpdatedAt} — CAS conflict. OR {error:"scope_gone"} — the token''s scope no longer exists; nothing written; do NOT retry (SDK ScopeGoneError).' }
 
   # ── scope config draft / publish (CAS on the version NUMBER axis) ─────────────────────────────
   /api/v1/scopes/{s}/config/{domain}:
@@ -174,7 +177,12 @@ paths:
       summary: CAS-write the draft (putScopeConfigDraft; version NUMBER axis — not updatedAt).
       responses:
         '200': { description: Written. }
-        '409': { description: 'Version conflict.' }
+        '409':
+          description: >
+            `{error:"conflict", currentVersion?}` — version conflict (SDK ScopeConfigCasConflictError: re-read, re-base, retry).
+            OR `{error:"scope_gone", error_description}` (web-admin W41F / KL-24) — the scope was deleted, or deleted and re-created
+            under the same name, while this write was in flight (or the optional `baseIncarnation` no longer matches): NO
+            `currentVersion`, nothing written, NOT retryable — a re-read reads the REPLACEMENT scope (SDK ScopeGoneError).
   /api/v1/scopes/{s}/publish:
     parameters:
       - { in: path, name: s, required: true, schema: { type: string } }
@@ -274,7 +282,12 @@ paths:
     get: { operationId: adminAuthProvidersShow, summary: 'ADMIN: one auth provider.', responses: { '200': { description: OK } } }
   /api/v1/scopes/{s}/rollback:
     parameters: [{ in: path, name: s, required: true, schema: { type: string } }]
-    post: { operationId: adminScopeRollback, summary: 'ADMIN: rollback a scope''s published config.', responses: { '200': { description: OK } } }
+    post:
+      operationId: adminScopeRollback
+      summary: 'ADMIN: rollback a scope''s published config.'
+      responses:
+        '200': { description: OK }
+        '409': { description: '{error:"scope_gone"} — the scope was deleted / re-created under the same name while the rollback was in flight; nothing written; do NOT retry (SDK ScopeGoneError, still a RegistryApiError). Other 409s stay a plain RegistryApiError.' }
   /api/v1/usage/me:
     get: { operationId: adminUsageMe, summary: 'Usage of the caller.', responses: { '200': { description: OK } } }
   /api/v1/usage/summary: