@sema-agent/sdk 11.3.0 → 12.0.0

package/openapi.yaml

@@ -2322,6 +2322,106 @@ paths:
         '422': { $ref: '#/components/responses/UnprocessableEntity' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
+  /v1/sessions/{sessionId}/background:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsBackgroundList
+      x-status: live             # S-745 (server 7.102.0; core 7.32.0 #1107); SDK sessions.background.
+      summary: The session's background tasks (the exit sheet's "keeps running / will stop" material).
+      description: >
+        S-745 (server >= 7.102.0; core 7.32.0 #1107; contract §16 "embedded-shape contract"; mint
+        `src/http/routes/background.ts`). 200 `{ rows }` — each row is core `TaskRegistry.list()`'s row projected
+        KEY BY KEY by an explicit whitelist (`task_id` renamed `id`; `toolUseId` / `updatedAt` deliberately
+        stripped). Only THIS session's rows: the access tuple is the session's own `{owner: sid, sessionId: sid,
+        scope}` and visibility is core's fail-closed `canAccess` (the session's session-resident shells, the run row
+        whose task id is the session id, workflows this session started, background agents rooted at this
+        session). `retained` rides ONLY when true (core's retain predicate: env / task lane / row mark) — present =
+        "keeps running" on the exit sheet; absent = an `includeRetained:false` stop WILL stop it. `description` is
+        the model's description, falling back to the launch command text (content family: redacted, cut at 500
+        chars). At most 500 rows (core `list()`'s own cap). 🔴 IN-PROCESS: only rows on THIS replica.
+        Zero model work: not billable, not refused by drain. Gates (same family as `mcp/reconnect`): 501
+        `capability.session_ownership_required` (no `sessionStorage.ownerOf`) · 404 `not_found.session` — unknown
+        session AND someone else's session answer the SAME code and SAME message (no existence oracle); an EXPLICIT
+        operator may read any session · 400 `request.path_malformed`. Probe with `capabilities.background.listFace`;
+        ABSENT key = an older server, where this path is 404 `not_found.route` (same status, different code).
+      responses:
+        '200':
+          description: The session's background rows (read the row schema for the `retained` / `status` readings).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionBackgroundList' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/background/stop:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: sessionsBackgroundStop
+      x-status: live             # S-745 (server 7.102.0; core 7.32.0 #1107); SDK sessions.backgroundStop.
+      summary: Stop the session's background tasks — soft, then one grace, then a synchronous hard kill; receipts are complete before 200.
+      description: >
+        S-745 (server >= 7.102.0; contract §16; mint `src/http/routes/background.ts`). The SAME session-level
+        convergence function as the `DELETE /v1/sessions/{sessionId}` cascade: SOFT (core's session anchor SIGTERMs
+        and settles the session's background agents / workflows; every still-running shell row the hard face will
+        revisit gets a per-row soft stop — with `includeRetained:true` the retained live services receive SIGTERM
+        here too) → GRACE (the hard face waits until every row it will revisit is past "its soft-stop instant +
+        `HOST_BG_KILL_GRACE_MS`", default 1000 ms; nothing to wait for ⇒ no wait) → HARD (core
+        `killAllBackgroundShellsNow` — a synchronous process-group SIGKILL; a shell ignoring SIGTERM does not
+        survive it). 🔴 THE RECEIPTS ARE COMPLETE BEFORE THE 200: with background rows the answer is one grace
+        slower — budget the shell's exit wait in seconds.
+        Body `{ includeRetained }` is REQUIRED with NO default (core's rule: the caller states which kind of stop
+        this is): `true` = also stop the explicitly retained live services (the shell's "Exit and stop tasks");
+        `false` = keep them (they come back as `retained_skipped`; `sema kill`'s session-level reap). The body
+        gate is STRICT — absent / non-boolean / an extra key ⇒ 400 `request.body_shape`.
+        Receipts carry SHELL rows only (`background_bash` / `monitor`); `outcome` is core's four words passed
+        through VERBATIM — `killed` (a live process group was reaped now) · `already_gone` (already exited, or
+        already hard-killed — incl. exiting within the grace) · `retained_skipped` (kept by
+        `includeRetained:false`) · `no_pgid` (NO synchronous hard kill landed: remote / sandbox lanes have no
+        host-local process group — e2b / k8s·kata / local-docker / ssh / device / adb always answer it — or win32 /
+        a refused signal; core already sent an ordinary kill ⇒ "MAY STILL BE RUNNING", neither a failure nor ever
+        "stopped").
+        🔴 CREDENTIAL-GATED (server >= 7.102.0 as released): on a worker with no service credential
+        (`SERVICE_AUTH_TOKEN(S)`) and without `ALLOW_UNAUTHED_WRITES`, this path answers 503
+        `auth.service_token_required` BEFORE routing (same code and sentence as every other mutating door) — the
+        principal header is self-asserted there, and stopping background processes is irreversible.
+        `capabilities.background.exitFaces` does NOT include "credentials ready" (the same family gap as the
+        `memoryCompliance` row) — branch on that code. Other gates as the list path: 501
+        `capability.session_ownership_required` · 404 `not_found.session` (unknown and foreign sessions alike) · 400
+        `request.path_malformed`; this path is rate-limited (429). NOT called by run cancel (Esc): session-resident
+        background shells live across turns (CC parity). A delegated helper's shells hang on the helper's own
+        session and are out of this door's reach. Probe with `capabilities.background.exitFaces`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SessionBackgroundStopRequest' }
+      responses:
+        '200':
+          description: The receipts (shell rows only). Read `no_pgid` as "may still be running".
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionBackgroundStopResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+        '503': { $ref: '#/components/responses/Unauthorized' } # `auth.service_token_required` — the credential-gated write door (no service credential and no ALLOW_UNAUTHED_WRITES), before routing.
+
   /v1/sessions/{sessionId}/memory-status:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -3031,6 +3131,15 @@ paths:
             (REOPENED) and re-appears on `/v1/approvals`. SDK → ParkedResumeStartupError. Client action:
             re-fetch the pending list and decide again, fixing what was rejected. (Before 5.12.0 this shape
             collapsed into the 409 `decide.revive_rejected`.)
+            🔴 core 7.32.0 (#1110) ADDS A CAUSE (server >= 7.102.0; contract appendix A.1, MIGRATION 7.102.0): an
+            `approve` on a child parked on an INHERITED tool (a tool family the child inherits from the scenario
+            layer — the task tools, WebFetch …) whose redemption cannot hand over the inherited seat ⇒ core refuses
+            BEFORE consuming the approval: the approval stays PENDING and a `deny` still settles it. From server 7.102.0
+            a ONE-LEVEL row (its root session = the parent session, and that root session STILL belongs to this card's
+            tenant) is redeemed with the seat re-resolved from the root session, so it no longer lands here; a DEEPER
+            (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.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -3854,6 +3963,23 @@ paths:
                     NOT strict (hand-written parser, unknown keys are ignored), so an older server answers 200 and
                     records nothing. Bit absent = old server, do not offer the field. Bit present ⇒ read the
                     per-call truth from the ack's `noteRecorded`.
+                readRootGrant:
+                  type: string
+                  minLength: 1
+                  description: >-
+                    S-720 (server >= 7.102.0 / core 7.32.0 #1093), ADDITIVE — "Yes, and add directory": the frame's
+                    `readRootCandidate.dir` sent back BYTE FOR BYTE (a STRING — never normalised, cut or composed; not an
+                    object). Beside `allow` it also adds that directory to THIS RUN's read directories (read faces only).
+                    🔴 `decision:"allow"` ONLY — on `allow_session` / `deny` the server refuses BEFORE the decision with 400
+                    `request.body_shape` (the card stays open; answer the same `approvalId` again). SHAPE gate: a non-empty
+                    string of at most core's `READ_ROOT_CANDIDATE_DIR_MAX`, else the same 400 (an over-long value is refused
+                    whole, never cut — a cut directory is another directory). The server judges SHAPE, never VALUE: whether
+                    it equals the card's string is the ENGINE's call, and the verdict arrives only as an `engine_notice` —
+                    `approval.read_root_granted` (the run's read roots really widened) or `approval.read_root_grant_rejected`
+                    (nothing changed; the decision stands). The 200 never says which. Reach: THIS RUN only (the ask row has no
+                    such column, so replay / failover / durable resume do not carry it) and THIS DOOR only (the durable
+                    `/decide` and the in-stream `…/asks/{askId}/decision` doors do not read it). An older server ignores the
+                    unknown key and answers 200 with a plain allow (no capability bit yet) — trust the notice.
       responses:
         '200':
           description: Ack (`decision` echoed).
@@ -6558,15 +6684,27 @@ components:
         rewindFiles:
           type: boolean
           description: >
-            CC Rewind parity (E18). On a NORMAL turn ⇒ CAPTURE a working-tree snapshot at turn end (per-turn, by leaf;
-            required so later rewinds have something to restore). On a resumeAt turn ⇒ RESTORE the tree to resumeAt's
-            snapshot ("both"). Needs a fileSnapshotStore wired (capabilities.rewindFiles).
+            RETIRED SPELLING (the whole-tree snapshot epoch; S-15 / design/381, server >= 7.52 — note corrected in sdk
+            11.4.0, the same stale-note family as `rewindFilesTo`, board [8437] U3). Server `src/http/wire-types.ts`: still
+            accepted on the wire — its capture sense (true, no resumeAt) is a tolerated no-op with a deprecation disclosure;
+            its restore sense (true + resumeAt) is core's TYPED migration rejection naming `restoreFiles` (restore semantics
+            really changed: whole tree ⇒ tracked set; the server never remaps it silently). Send `restoreFiles` (probe
+            `capabilities.restoreFiles`); this key stays declared only for <= 7.51 servers.
         rewindFilesTo:
           type: string
           description: >
-            CC Rewind "code"-only (core 1.166.0 TaskSpec.rewindFilesTo). Restore the working tree to this user-message
-            entryId's snapshot WITHOUT forking the conversation (no setLeafId). Use instead of resumeAt+rewindFiles when
-            the user wants only files reverted. Target = a user-message SessionTreeEntry.id.
+            CC Rewind "code"-only (core 1.166.0 TaskSpec.rewindFilesTo; server "R8"). Converge the files this session
+            edited (the TRACKED set) to the history boundary at a prior USER message WITHOUT forking the conversation (the
+            session leaf is untouched — only the files move). Use instead of resumeAt+restoreFiles when the user wants only
+            files reverted. 🔴 The value is a HANDLE, not an entry id (corrected in sdk 11.4.0, board [8437] U3): the SAME
+            kind of handle as `resumeAt`, resolved through the SAME anchor store — typically the `taskId` from that turn's
+            202 receipt (the server keys the user-message anchor by the run's taskId). Server `src/boot/resolve-spec.ts:686-697`:
+            `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
+            (resume legs strip it, server >= 7.72.0).
         restoreFiles:
           type: boolean
           description: >-
@@ -8187,7 +8325,16 @@ components:
             with no explicit allowlist); ABSENT = an older server (degrade to not teaching, not validating).
         resumeAt: { type: boolean, description: "E18 resume-at-message anchors are resolvable." }
         rewindFiles: { type: boolean, description: "E19 working-tree snapshot/restore is wired." }
-        rewindFilesTo: { type: boolean, description: "Restore to a SPECIFIC entry id (not just the latest snapshot)." }
+        rewindFilesTo:
+          type: boolean
+          description: >-
+            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"`).
         restoreFiles:
           type: boolean
           description: >-
@@ -8751,6 +8898,70 @@ components:
           properties:
             provider: { type: string, description: 'host | e2b | k8s | ssh | adb | local-docker | device — typed from the server''s RemoteExecProvider; `REMOTE_EXEC` unset ⇒ `host`.' }
             toolsOnThisHost: { type: boolean, description: 'The tools run on the process that answered this request (server-absolute paths mean something to the model''s tools).' }
+        taskWriteFaceOpen:
+          type: boolean
+          description: >
+            server >= 7.95.0 (S-591; value meaning refined at 7.96.0 / S-613; mint `routes/capabilities.ts:653` =
+            `taskWriteFaceRefusal(deps.config) === undefined && autonomyOverrides(deps.config.autonomy).writeFace !== "roots"`)
+            — DISCLOSURE BIT OF THE WRITE-CONTAINMENT FACE: does this deployment honour the task-level "open the write
+            fence" declaration (`permissionMode:"bypassPermissions"` ⇒ `TaskSpec.writeFace:"open"`, writes outside the
+            workspace roots)? `false` has two forms: (1) the hosted-posture gate refuses ⇒ sending that mode gets
+            `422 request.host_posture_refused`; (2) the deployment runs `AUTONOMY=read-only|plan` ⇒ the request is
+            accepted but the write face is clamped back to roots — the declaration silently does nothing. Three states
+            are folded into one bit on purpose: the caller has exactly one decision (send that key or not); tier and
+            evidence live in the refusal body and the operator's `GET /v1/diagnostics/wiring`. It speaks ONLY for the
+            write-containment cell — the other two columns of `bypassPermissions` are unaffected.
+            ABSENT = an older worker (<= 7.94) ⇒ read as `true` (contract appendix B.1: nothing refused it back then).
+        taskApproverPosture:
+          type: boolean
+          description: >
+            server >= 7.95.0 (S-591 leg ③; mint `routes/capabilities.ts:659` = `taskApproverPostureHonored(deps.config)`,
+            the SAME predicate as the real consumer) — DISCLOSURE BIT OF `approverPosture`: does this deployment honour
+            the submit body's host-posture statement ("this run's approval cards are auto-answered by the host
+            itself")? `false` ⇒ the key is IGNORED (the request is still 202-accepted; the server logs
+            `task_approver_posture_ignored`) — deliberately NOT refused: the resume legs replay the persisted body
+            verbatim and the caller cannot remove it, so a refusal would brick a parked task forever. Same reach as
+            the hosted-gate half of `taskWriteFaceOpen` (hosted posture ⇒ both false); `AUTONOMY=read-only|plan`
+            only clears `taskWriteFaceOpen`, never this bit.
+            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`).
+        background:
+          type: object
+          additionalProperties: true
+          description: >
+            server >= 7.102.0 (S-745 / core 7.32.0 #1107; mint `routes/capabilities.ts:308` = `{ listFace:
+            sessionBackgroundFacesAvailable(deps), exitFaces: sessionBackgroundFacesAvailable(deps) }`) — presence of the
+            session background-task doors: `listFace` = `GET /v1/sessions/{sessionId}/background`, `exitFaces` =
+            `POST /v1/sessions/{sessionId}/background/stop` (contract §16). Both bits use the SAME predicate as the two
+            doors' 501 (the session-ownership face `sessionStorage.ownerOf`), so "says yes but 501s" is structurally
+            impossible; without it both bits are explicitly `false` and both doors answer 501
+            `capability.session_ownership_required`. ENDPOINT-GATE FORM: `false` ⇒ do not call. True only promises the
+            endpoint — not that this replica holds any background row of that session (the registry is in-process).
+            ⚠️ `exitFaces` does NOT cover "credentials ready": on a worker with no service credential and without
+            `ALLOW_UNAUTHED_WRITES` the bit is true while the stop door answers 503 `auth.service_token_required` —
+            branch on that code (the same family gap as `memoryCompliance`). ABSENT = an older server (both doors 404)
+            ⇒ the shell's exit dialog offers only "Stay / Exit", never "Exit and stop tasks".
+          required: [listFace, exitFaces]
+          properties:
+            listFace: { type: boolean }
+            exitFaces: { type: boolean }
     WriteProtectionCapability:
       type: object
       additionalProperties: false
@@ -10806,6 +11017,13 @@ components:
         sessionId: { type: string }
         requiresRealApproval: { type: boolean, enum: [true] }
         governanceForced: { type: boolean, enum: [true] }
+        mandated: { type: boolean, enum: [true], description: 'server >= 7.101.0 (T4①): the mandated bit, same layer and shape as the two flags above (present only when true); the SAME value as `frame.mandated` (read once when the entry is minted).' }
+        mandate:
+          allOf: [{ $ref: '#/components/schemas/PersistedRuleMandate' }]
+          description: 'server >= 7.102.0 (S-721): which word the mandated bit stands on — same layer and shape as `mandated`, the SAME value as `frame.mandate`. Absence never names a word.'
+        origin:
+          allOf: [{ $ref: '#/components/schemas/AskOrigin' }]
+          description: 'server >= 7.102.0 (S-755 / cli L-695): WHO raised this ask, read once together with `frame.origin` when the entry is minted. The durable `pending[]` rows of the same response carry it top-level too — one reading for both row families. OPEN set (see AskOrigin).'
         fromSubagent: { type: boolean, enum: [true], description: 'The ask originates from a delegated subagent.' }
         originTaskId: { type: string, description: 'S-52 C2 (server ≥7.52, A-075.87): the delegated child taskId (= the child''s core runSourceTaskId, uuid) — correlates this live ask to the child run row. Minted by the SAME conditional spread as `fromSubagent`: the two keys are always both present or both absent (三键恒等亲证在案).' }
         contentKind: { type: string, description: 'S-62 (server >= 7.6x): content-question kind — `content_ask` when the gated tool is AskUserQuestion (the SAME word as the two durable read faces and core''s summarize face). Absent = an ordinary tool ask. Display/triage only; it NEVER takes part in decision routing.' }
@@ -11114,6 +11332,27 @@ components:
             presence may differ between the two legs for one ask. Derived from hot-reloadable governance knobs —
             long subscribers follow the stream's re-emitted frames. Absence ≠ "not governance-forced"; it means
             "no governance-origin evidence". Never written as false.
+        # ── park-row facts (server `src/approval-card.ts` `ParkRowFacts` — the five facts core mints on the parked
+        #    `PendingAction.tool_approval` arm, projected by `parkRowFacts`, the SAME projection on both stores and on the
+        #    `/stream` `pending` frame). DISPLAY / TRIAGE projection, never a permission input; each present only when
+        #    true / a word. sdk 11.4.0 declares all five (the first three were already on the wire since 7.100.0 / 7.101.0).
+        requiresRealApproval:
+          type: boolean
+          enum: [true]
+          description: 'server >= 7.100.0 (S-700): this parked ask can only be cleared by a REAL HUMAN (core park-row twin seat, strict `=== true`). Absent = not marked, never "clearable without a person".'
+        mandated:
+          type: boolean
+          enum: [true]
+          description: 'server >= 7.101.0 (S-663 part 2 / core 7.31.0 #1079): the durable twin of the mandated bit (no rule can clear this ask). Independent of `requiresRealApproval` (which implies it) and `ruleOffersAbsence` — projected bit by bit, never inferred.'
+        mandate:
+          allOf: [{ $ref: '#/components/schemas/PersistedRuleMandate' }]
+          description: 'server >= 7.102.0 (S-721): which word the mandated bit stands on — the park-row twin seat read through `readClosedWordSeat(…, "mandate")` (core `isPersistedRuleMandate`); an out-of-set word reads as absent. Answers the same as the inbox row for the same row.'
+        origin:
+          allOf: [{ $ref: '#/components/schemas/AskOrigin' }]
+          description: 'server >= 7.102.0 (S-755 / cli L-695 / C-R111): WHO raised this ask — the park-row twin seat `PendingAction.tool_approval.origin` read through `readClosedWordSeat(…, "origin")` (core `isAskOrigin`). Same word as the live card frame and the inbox row. Absent = an old row (parked before core 7.5.0) or an out-of-set word — NOT "policy".'
+        ruleOffersAbsence:
+          allOf: [{ $ref: '#/components/schemas/RuleOffersAbsence' }]
+          description: 'server >= 7.100.0 (S-700): WHY the park row offers no rule — the same narrow read and closed three-word set as the live card frame and `card_json`.'
         hasBidiControls:
           type: boolean
           enum: [true]
@@ -11220,6 +11459,20 @@ components:
             🔴 NEVER minted as `false` (the OMIT contract this row's other flags follow); absence is "not marked",
             never "confirmed clearable without a person". The value comes WHOLE from core (`summarizeCheckpoint`
             projects the park row's own bit) — the server neither recomputes nor redacts it.
+        mandated:
+          type: boolean
+          enum: [true]
+          description: >-
+            server >= 7.101.0 (S-663 part 2 / core 7.31.0 #1079), ADDITIVE, present ONLY when true: the durable twin of
+            the mandated bit (core `summarizeCheckpoint` screens the park row's `PendingAction.tool_approval.mandated`
+            to a literal `true`; the server mints the key on strict `=== true`). Declared in sdk 11.4.0 — this schema is
+            CLOSED, so before that a strict validator rejected every row that carried it.
+        mandate:
+          allOf: [{ $ref: '#/components/schemas/PersistedRuleMandate' }]
+          description: >-
+            server >= 7.102.0 (S-721 / core 7.32.0 #1092): which word the mandated bit stands on (core
+            `CheckpointSummary.mandate`, already screened by core's `isPersistedRuleMandate`; the server does not screen
+            twice). Answers the same as the operator queue row for the same park row.
         denialLimitFallback:
           $ref: '#/components/schemas/DenialLimitFallback'
           description: >-
@@ -11849,6 +12102,73 @@ components:
             budgetMs: { type: integer }
             error: { type: string }
 
+    SessionBackgroundRow:
+      type: object
+      description: >
+        One row of `GET /v1/sessions/{sessionId}/background` (S-745, server >= 7.102.0; mint
+        `src/http/routes/background.ts` `SessionBackgroundRow`) = core `TaskRegistry.list()`'s row projected key by
+        key (`task_id` renamed `id`; `toolUseId` / `updatedAt` stripped). The three word sets are OWNED BY CORE
+        (7.32.1 `SemaTaskType` / `SemaTaskStatus`), transcribed verbatim. 🔴 IN-PROCESS: only rows on this replica.
+        Response projection: declared key by key AND open (additive keys between SDK releases must not make a legal
+        row unreadable — the LivePendingRow ruling).
+      additionalProperties: true
+      required: [id, type, status, createdAt, sessionScoped]
+      properties:
+        id: { type: string, description: 'core `task_id` (renamed). A receipt''s `id` is the same value.' }
+        description: { type: string, description: 'The model''s description, falling back to the launch command text (core keeps no separate raw command). Content family: redacted, cut at 500 characters. UNTRUSTED for display.' }
+        type: { type: string, enum: [background_bash, workflow, background_agent, monitor], description: 'core `SemaTaskType`.' }
+        status: { type: string, enum: [pending, running, parked, completed, failed, killed, cancelled], description: 'core `SemaTaskStatus` (`parked` = a background agent suspended on a pending approval — neither live nor terminal).' }
+        createdAt: { type: integer, description: 'Registration time (epoch ms).' }
+        sessionScoped: { type: boolean, description: '`true` = session-resident (lives across turns); `false` = run-scoped.' }
+        retained:
+          type: boolean
+          enum: [true]
+          description: >-
+            core's retain predicate (env declaration / task lane / row mark — any ⇒ kept) — present ONLY when true,
+            never minted as false, and only ever on a shell row (`background_bash` / `monitor`; core `list()` row
+            doc). Present = "keeps running" on the exit sheet; absent = an `includeRetained:false` stop WILL stop it.
+    SessionBackgroundList:
+      type: object
+      description: '`GET /v1/sessions/{sessionId}/background` 200 body (contract §16). An idle session answers `{ rows: [] }`.'
+      additionalProperties: true
+      required: [rows]
+      properties:
+        rows:
+          type: array
+          items: { $ref: '#/components/schemas/SessionBackgroundRow' }
+    SessionBackgroundStopRequest:
+      type: object
+      description: >
+        `POST /v1/sessions/{sessionId}/background/stop` body — server `StopBodySchema = z.object({ includeRetained:
+        z.boolean() }).strict()`: EXACTLY this key, REQUIRED, NO default. `true` = also stop explicitly retained live
+        services ("Exit and stop tasks"); `false` = keep them (`retained_skipped`). Absent / non-boolean / an extra
+        key ⇒ 400 `request.body_shape`.
+      additionalProperties: false
+      required: [includeRetained]
+      properties:
+        includeRetained: { type: boolean }
+    SessionBackgroundReceipt:
+      type: object
+      description: >
+        One receipt of the stop door — SHELL rows only (`background_bash` / `monitor`). `outcome` = core 7.32.1
+        `BackgroundShellHardKillReceipt.outcome` (`BackgroundHardKillOutcome` ∪ `retained_skipped`), passed through
+        VERBATIM: `killed` / `already_gone` (both = "this row is reaped") · `retained_skipped` (kept, process alive) ·
+        `no_pgid` (no synchronous hard kill landed — MAY STILL BE RUNNING; never render it as stopped).
+      additionalProperties: true
+      required: [id, outcome]
+      properties:
+        id: { type: string, description: 'The row id (core taskId).' }
+        outcome: { type: string, enum: [killed, already_gone, retained_skipped, no_pgid] }
+    SessionBackgroundStopResult:
+      type: object
+      description: '`POST /v1/sessions/{sessionId}/background/stop` 200 body. The receipts are COMPLETE before the 200 (soft → grace → hard is awaited).'
+      additionalProperties: true
+      required: [receipts]
+      properties:
+        receipts:
+          type: array
+          items: { $ref: '#/components/schemas/SessionBackgroundReceipt' }
+
     # ── 2c session-sync (P1d) — the cloud-as-a-SYNC-PEER schemas ──────────────────────────────────────────────
     SyncEntry:
       type: object
@@ -13651,6 +13971,17 @@ components:
         spec-resolver, which now passes the notice seat). Consequence for consumers that assert on ledger
         CONTENTS: a resume leg's ledger MAY now carry one extra `engine_notice` row it did not before — assert
         "may appear", never an exact row count or order (and consume idempotently: reconnect replay shows it again).
+        `approval.read_root_granted` / `approval.read_root_grant_rejected` (server >= 7.102.0 / S-720 / core 7.32.0
+        #1093) — the ENGINE's verdict on a `readRootGrant` answer (POST /v1/tool-approvals/{id}/respond), at most one
+        frame per answered ask. GRANTED = this run's read directories really include it now (core: the ONLY evidence the
+        run widened; read faces only, this run only) — `{dir, covers?, root, toolName, toolCallId, sessionId, runId,
+        taskId?}`, `root` = the canonical spelling the engine holds. REJECTED = nothing changed and the decision stands
+        (say so plainly) — `{reason, offered?, requested?, toolName, toolCallId, sessionId, runId, taskId?}`, `reason` one of
+        core's eight words (`on_refusal` / `not_a_string` / `no_candidate` / `mismatch` / `unresolvable` /
+        `resolves_elsewhere` / `admits_artifact_store` — the directory contains, lies inside or is the local artifact
+        store; unreachable on a server 7.102.0 deployment, which wires no artifact host — / `no_read_roots`), passed
+        through verbatim by the server (echo-only, not enumerated) — read it as an OPEN set. `toolCallId` joins to the
+        `tool_approval` frame.
         `delegation.ask_unresolvable` (server >= 7.69.0 / core 7.10.0 #648) — an `ask` reached a FINAL DENY with
         NOBODY having ruled on it: the approver consulted for the call answered `unavailable` and no durable park
         caught it afterwards. The deny itself is unchanged (`tool_end.gate.settlement.kind:"approver_unavailable"`
@@ -14324,8 +14655,18 @@ components:
           description: >
             (server >= 7.93.0, core 7.26.0 #997) This card was MANDATED — a read-station / rule-lane forced ask (a rule can
             never clear it; an approver's yes cannot release a deny-listed read). Present only when true, literal `true`;
-            absent = an ordinary ask. The durable parked row carries no twin bit: read `ruleOffersAbsence: "mandated"` there
-            (the same fact on the durable face).
+            absent = an ordinary ask. ⚠️ CORRECTED (sdk 11.4.0): the durable parked row DOES carry a twin bit since core
+            7.31.0 #1079 (`PendingAction.tool_approval.mandated`), projected since server 7.101.0 onto the operator queue
+            row / the `/stream` `pending` frame / the inbox row (S-663 part 2) and the `livePending` row top level (T4①)
+            — four faces, one bit. `card_json` does not carry it (`ApprovalCardSchema` is `.strict()`).
+        mandate:
+          allOf: [{ $ref: '#/components/schemas/PersistedRuleMandate' }]
+          description: >-
+            server >= 7.102.0 (S-721 / core 7.32.0 #1092), "tool_approval" only, ADDITIVE — which word the `mandated`
+            bit stands on (server `src/tool-approval.ts:841`, read through `readClosedWordSeat(req, "mandate")` =
+            core's `isPersistedRuleMandate` screen). Present only when the WHOLE cause of `mandated:true` is that one
+            word; absence never names a word and is not "not mandated". Same value on the `livePending` row, the
+            operator queue row and the inbox row; NOT on `card_json` / `approval_request`.
         denialLimitFallback: { $ref: '#/components/schemas/DenialLimitFallback' }
         parked:
           type: boolean
@@ -14627,6 +14968,13 @@ components:
 
         The SAME type is the `origin` member of `GateOutcome` on `tool_end` — one vocabulary, two faces.
 
+        server >= 7.102.0 (S-755 / cli L-695 / C-R111): the word now also rides the `livePending` row top level
+        (read once with the frame's) and the operator queue row (`GET /v1/approvals` `pending[]` + the `/stream`
+        `pending` frame — the park-row twin seat, screened by core's `isAskOrigin`), besides the frame and the inbox
+        row — five faces, one word. `card_json` / the `approval_request` frame still do not carry it (the card is
+        `.strict()`). The eleven known words are exported at runtime as the SDK's `ASK_ORIGINS` (core 7.32.1
+        `ASK_ORIGINS`, verbatim and in order) — known words, NOT an enforcement table.
+
     RuleOffersAbsence:
       type: string
       enum: [mandated, shadowed, lane_cannot_speak]
@@ -14644,6 +14992,26 @@ components:
         server-side narrow read, so both faces carry identical values; a word outside the set is treated as
         malformed and the key is not minted at all (the server never passes an unknown word through).
 
+    PersistedRuleMandate:
+      type: string
+      enum: [operator_always, tool_marks, probe_mandate, probe_unanswered, write_protection, write_protection_unresolved]
+      description: >
+        WHICH WORD a mandated ask stands on (server >= 7.102.0 / S-721 / core 7.32.0 #1092) — core's
+        `PERSISTED_RULE_MANDATES` six words, transcribed verbatim and in order (core 7.32.1
+        `dist/core/ask-origin.d.ts:349`; the vocabulary's owner is core). Rides FOUR faces with one value: the
+        `tool_approval` frame, the `livePending` row top level, the operator queue row (`GET /v1/approvals`
+        `pending[]` + the `/v1/approvals/stream` `pending` frame) and the inbox row. NOT on `card_json` / the
+        `approval_request` frame (live or reconnect replay — `ApprovalCardSchema` is `.strict()`), same as `mandated`.
+        🔴 A TRUE CLOSED SET, deliberately unlike `AskOrigin`: on every face the server screens it through core's
+        `isPersistedRuleMandate` (`approval-card.ts` `readClosedWordSeat`; the inbox face is screened by core's own
+        `summarizeCheckpoint`) and an out-of-set word reads as ABSENT, never on the wire.
+        🔴 ABSENCE NEVER NAMES A WORD and is NOT "not mandated": another door (governance / hook / ancestor) or more
+        than one reason ⇒ absent; whether the ask is mandated is `mandated`. For an ENGINE-MINTED value, present ⇒
+        `mandated` is true (core: present ⇔ that word is the bit's WHOLE reason); the converse does not hold. ⚠️ On the
+        durable faces (queue row / inbox row) the server projects the two seats INDEPENDENTLY (it does not bind `mandate`
+        to `mandated`, `approval-card.ts` `readClosedWordSeat`), so a hand-edited or generation-skewed row may carry one
+        without the other — read `mandated` for the bit, never infer it from this word. Echo-only — the server never
+        branches on the word.
     DenialLimitKind:
       type: string
       enum: [consecutive, total]
@@ -15199,14 +15567,15 @@ components:
       type: object
       description: >
         Decision-maker identity assertion (design/171 §5.1; the cross-repo source of truth is
-        `@sema-agent/registry-core` ActorAssertionWire — the SDK holds a value copy).
+        `@sema-agent/settings-schema` ActorAssertionWire — the SDK holds a value copy; the package was named
+        `@sema-agent/registry-core` before 1.0.0).
 
         NORMATIVE, not a style note: an ACTOR NEVER PARTICIPATES IN THE PERMISSION DECISION — authority always
         belongs to the principal; this shape exists only for audit/echo/presentation. `id` is ALWAYS server-minted
         (= the verified principal; an auth-off deployment mints the `"_"` sentinel), and a wire requester may
         submit ONLY `label`.
       required: [id]
-      additionalProperties: false   # registry-core's ActorAssertionWire is .strict()
+      additionalProperties: false   # settings-schema's ActorAssertionWire is .strict()
       properties:
         id: { type: string, minLength: 1, maxLength: 256, description: 'Server-minted principal ("_" sentinel when auth is off). Never submittable by the requester.' }
         label: { type: string, maxLength: 256, description: 'Unverified display text — the ONLY field a requester may submit (server redacts + bounds it). UNTRUSTED.' }
@@ -15217,7 +15586,7 @@ components:
           description: >
             Audit axis for which authorization path accepted the decision: `owner` (row owner) or `operator`
             (explicit operator seat). CLOSED — verbatim-equal to the owning schema
-            (registry-core ActorAssertionWire). Widening it here without widening the owner is copy drift.
+            (settings-schema ActorAssertionWire). Widening it here without widening the owner is copy drift.
 
     AskDecisionBody:
       type: object
@@ -15866,6 +16235,20 @@ components:
             SAME projection as the `GET /v1/approvals` row (`projectPendingForWire`), declared here explicitly so
             a stream consumer sees it typed instead of through the open index signature. Present ONLY when true;
             absence = "not detected", never "confirmed clean" (see PendingCheckpoint.hasBidiControls).
+        # sdk 11.4.0 (che-OV adversarial review [low] F5): the `pending` frame spreads the PendingCheckpoint row and the
+        # `live_pending` frame (server >= 7.87.0) spreads the LivePendingRow — so the rows' park-row facts / mandate bit /
+        # origin word ride these frames with the same names and values. Declared for the same reason as hasBidiControls.
+        requiresRealApproval: { type: boolean, enum: [true], description: '`pending` / `live_pending` frames — see PendingCheckpoint / LivePendingRow.requiresRealApproval.' }
+        mandated: { type: boolean, enum: [true], description: '`pending` / `live_pending` frames (server >= 7.101.0) — see the row schemas.' }
+        mandate:
+          allOf: [{ $ref: '#/components/schemas/PersistedRuleMandate' }]
+          description: '`pending` / `live_pending` frames (server >= 7.102.0 / S-721) — see PendingCheckpoint.mandate / LivePendingRow.mandate.'
+        origin:
+          allOf: [{ $ref: '#/components/schemas/AskOrigin' }]
+          description: '`pending` / `live_pending` frames (server >= 7.102.0 / S-755) — see PendingCheckpoint.origin / LivePendingRow.origin. OPEN set.'
+        ruleOffersAbsence:
+          allOf: [{ $ref: '#/components/schemas/RuleOffersAbsence' }]
+          description: '`pending` frames only (server >= 7.100.0 / S-700) — see PendingCheckpoint.ruleOffersAbsence.'
 
     ParkedDecideAccepted:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "11.3.0",
+  "version": "12.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/registry-core": "^0.17.1"
+    "@sema-agent/settings-schema": "^5.0.0"
   }
 }

package/registry-openapi.yaml

@@ -4,7 +4,8 @@ info:
   version: "0.1.0"
   description: >
     ⚠️ AUTHORITY POSTURE (read first): the registry SERVER lives in the sema-registry repo (web AI);
-    the machine contract single-source is `@sema-agent/registry-core` (zod schemas + path constants —
+    the machine contract single-source is `@sema-agent/settings-schema` (renamed from
+    `@sema-agent/registry-core` at 1.0.0, 2026-08-26; zod schemas + path constants —
     AUTH_V1_PATHS/SCOPES_V1_PATHS etc.; the SDK keeps value-copies with same-source anchor tests).
     THIS file documents the surface the SDK's registry subpath actually calls, so a consumer generating
     a client from spec sees the full face — it mirrors, it does not rule. Backfilled 2026-07-28 from
@@ -12,7 +13,7 @@ info:
     `registry-spec-path-gate.test.ts` (reflective: every /api path the SDK hits must be here, zero baseline).
     USER-PLANE paths carry real request/response shapes; the ADMIN family (RegistryAdmin, user-JWT
     role-gated — "admin" is a registry-side ROLE, not a separate credential) is documented loose
-    (operator tooling; shapes live in registry-core/zod and the registry server).
+    (operator tooling; shapes live in settings-schema/zod and the registry server).
   x-sdk-subpath: "@sema-agent/sdk/registry"
 paths:
   /api/healthz:
@@ -27,7 +28,7 @@ paths:
     post:
       operationId: registryDeviceCode
       summary: Start the device-authorization flow (requestDeviceCode).
-      requestBody: { required: false, content: { application/json: { schema: { type: object, additionalProperties: true, description: 'registry-core DeviceCodeRequest (open: client metadata).' } } } }
+      requestBody: { required: false, content: { application/json: { schema: { type: object, additionalProperties: true, description: 'settings-schema DeviceCodeRequest (open: client metadata).' } } } }
       responses:
         '200':
           description: '{device_code, user_code, verification_uri(_complete)?, interval, expires_in}.'
@@ -36,7 +37,7 @@ paths:
     post:
       operationId: registryDeviceToken
       summary: Poll the device flow (pollUntilApproved's leg).
-      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [grant_type, device_code], properties: { grant_type: { type: string, description: 'The RFC 8628 device grant type constant (registry-core DEVICE_GRANT_TYPE).' }, device_code: { type: string } } } } } }
+      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [grant_type, device_code], properties: { grant_type: { type: string, description: 'The RFC 8628 device grant type constant (settings-schema DEVICE_GRANT_TYPE).' }, device_code: { type: string } } } } } }
       description: >
         OAuth device-token semantics: `authorization_pending` keeps the interval, `slow_down` adds +5s,
         `access_denied`/`expired_token` are terminal (typed errors in the SDK). Success = the token pair.
@@ -85,7 +86,7 @@ paths:
       operationId: registryScopesList
       summary: List the caller's scopes (listScopes; `?counts=` optional).
       responses:
-        '200': { description: 'ScopesListResponse (registry-core schema).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
+        '200': { description: 'ScopesListResponse (settings-schema schema).', content: { application/json: { schema: { type: object, additionalProperties: true } } } }
     post:
       operationId: registryScopesCreate
       summary: 'ADMIN: create a scope/space.'