@sema-agent/sdk 17.2.0 → 18.1.0

package/openapi.yaml

@@ -184,6 +184,10 @@ tags:
     description: v2 leader pipeline (gated; E2B + git push). NOT the default door-B brain.
   - name: metrics
     description: Worker health/cost (ops; uses metricsToken, not a principal).
+  - name: admin
+    description: >
+      Operator-only `/v1/admin/*` actions on THIS engine instance. Today: the drain endpoint (server >= 7.121.0 contract
+      body `DrainRequest` / receipt `DrainReceipt`, owned by `@sema-agent/settings-schema` `./fleet`).
 
 paths:
 
@@ -3230,7 +3234,9 @@ paths:
         Frames: `meta` ({type,version,mode:"approvals-delta",pollMs}), then `synced` ({type,count}) once the
         first full snapshot has been emitted, then `pending`/`resolved` deltas; plus `heartbeat` ({type}) on the
         keep-alive tick and a terminal `error` ({type,errorCode:"STREAM_MAX_DURATION",…}) when the 15-min cap
-        fires. (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
+        fires — or, server >= 7.122.0, `error` with `errorCode:"draining"` at the moment the instance enters drain (same code and
+        sentence as the billable-submit 503 `draining`; the server closes the stream right after the frame, reconnect to the
+        replacement instance). (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
         it silently drops three frame kinds it really receives.) Each data payload mirrors its SSE event name in
         `data.type` — proxy-safe dispatch. Cross-replica by
         construction (polls the SHARED checkpoint table). 15-min cap + heartbeats; a DB blip retries, never
@@ -3731,8 +3737,12 @@ paths:
             `ErrorResponse`-shaped. Codes: "request.body_shape" (bad/missing `decision`, OR an unrecognised
             top-level key — server >= 7.86.0 / S-438 key closure, the body carries `unknownKeys` /
             `unsupportedKeys`) · "request.field_conflict" (`edit` without a non-empty `editedPlan`;
-            `editedPlan` present on approve/reject; `permissionModeAfter` sent with `edit`/`reject`;
-            `permissionModeAfter` on a task that was not submitted with `permissionMode:"plan"`) ·
+            `editedPlan` present on approve/reject; `permissionModeAfter` sent with `reject`;
+            `permissionModeAfter` on a task whose stored permission mode is not `plan`) — match these two by CODE;
+            server >= 7.122.0: `approve` and `edit` both carry the plan out of plan mode and both take the key, and a
+            run's mode word has ONE source, the stored submit body (an operator `AUTONOMY=plan` task is stored as `plan`
+            and takes the key); <= 7.121.x only `approve` took it and the second conflict read "not submitted with
+            `permissionMode:"plan"`" ·
             "request.field_invalid" (non-string `reason`; `permissionModeAfter` outside the two-word closed
             set — zero widening arm) · "request.path_malformed" (a bad percent-encoded path segment —
             server >= 7.86.0 / S-430 turned that family from 500 `internal.error` into a 400 across 16 doors).
@@ -4664,7 +4674,8 @@ paths:
         (`LEADER_ENABLED` off) the answer depends on the server: server >= 7.116.0 mounts the route unconditionally and answers
         **501 `capability.leader_endpoint_required`** (new code; under multi-tenant the identity gate's 401 still comes first);
         <= 7.115.x did not register the route at all → the generic **404** `not_found.route`. Detect "leader unavailable" by
-        `errorCode` (or the `capabilities.leader` bit, which reads the same fact as the gate), not by the status alone.
+        `errorCode` (or the `capabilities.leader` bit — server >= 7.122.0 also reads false on a deployment whose operator runs `AUTONOMY=plan`, where a submit answers
+        422 `request.autonomy_lane_refused` instead; see `Capabilities.leader`), not by the status alone.
 
 
         🔴 IDEMPOTENCY (server >= 7.24.0): this POST now consumes the `Idempotency-Key` header — the header is
@@ -4713,6 +4724,20 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: >-
+            errorCode "request.autonomy_lane_refused" (server >= 7.122.0) — the deployment runs the operator `AUTONOMY=plan`: every task starts
+            in plan mode and leaves it only when a person approves its plan through plan review, and a leader task's workers have no plan
+            review channel, so they could neither write nor hand their plan to anyone who can approve it. REFUSED at the door, NO run created;
+            a replay with the same `Idempotency-Key` gets the same 422 (the idempotency key is not consumed). The `capabilities.leader` bit
+            reads false on such a deployment (the same judgement as this refusal) — read it, or `GET /v1/policy` `autonomy`, beforehand. Exits: submit the work as a run (`POST /v1/runs`, plan reviewed through
+            `POST /v1/assistant/tasks/{taskId}/plan_review`), or ask the operator to set `AUTONOMY=read-only` or `ask` (leader tasks run
+            there). Not the hosted-posture refusal (`request.host_posture_refused`): that one is the tenant axis, this one is the AUTONOMY
+            axis. A change to `plan` after acceptance is caught where the run is born: the 202'd run ends with the same sentence in
+            `GET /v1/leader/{leaderRunId}` `error` and no worker is started.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409':
           description: >-
             errorCode "conflict.leader_run_exists" (server >= 7.24.0) — your `Idempotency-Key` hit a leader run
@@ -5595,6 +5620,65 @@ paths:
         '403': { description: 'Multi-tenant worker: wiring diagnostics are operator-only (`auth.operator_only`). With an EMPTY `OPERATOR_PRINCIPALS` the answer is instead 501 `capability.operator_principals_required` (server >= 7.116.0; any identity, ahead of authorization — branch on `errorCode`, not the status).' }
         '404': { description: 'This worker serves no wiring diagnostics (older server, or a process not assembled by the composition root).' }
 
+  /v1/admin/drain:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [admin]
+      operationId: adminDrain
+      x-status: live             # server >= 7.121.0 contract body; 7.35.0–7.120.x took a retired `{reason}` body.
+      summary: Put THIS engine instance into draining by a deadline (operator-only).
+      description: >
+        Server >= 7.121.0. The body is the contract `DrainRequest` (owned by `@sema-agent/settings-schema` >= 9.0.0 `./fleet`), the answer
+        the contract `DrainReceipt`. Entering drain: new work is refused (billable submits 503 `draining`; HITL answers — including the
+        durable `/decide` — and resumes are ADMITTED), `GET /readyz` turns 503, preemptible in-flight legs park durably at their next clean
+        turn boundary, live approval cards are re-routed to durable parks; the engine stops itself when in-flight reaches zero or at
+        `deadlineAt` (fixed when entered — a later hot change to the drain window does not move it). After a drain entered through this
+        endpoint, the FIRST stop signal the platform sends is absorbed (deadline unchanged) and only a later one, at least the minimum gap
+        apart, hard-stops — so the platform stop timeout (Docker `stop_grace_period`, systemd `TimeoutStopSec`, k8s
+        `terminationGracePeriodSeconds`) must be >= the requested deadline.
+        IDENTITY — the request names WHICH instance, compared field by field (no state change on a mismatch, 409 `conflict.fleet_identity`
+        naming the field, never echoing the value): `worker` = the engine's worker name (`SEMA_REGISTRY_WORKER`; an engine without a center
+        lane has none, so every request mismatches); `expectedGeneration` = the fleet generation (`/health.generation`), ABSENT AGAINST ABSENT
+        (omitting it is the standalone form, not a wildcard — it mismatches a fleet member); `scope` = the tenant scope, both sides read as a
+        value (the engine's = env `FLEET_SCOPE`; unset on the engine and omitted in the request both read as the default scope `global`);
+        `instanceId` (`/health.instanceId`) is compared only when present.
+        IDEMPOTENT — the same `actionId` (or any other action) while already draining answers 200 `already_draining` and echoes the FIRST
+        drain's `since` / `deadlineAt`, changing nothing. Clients do not auto-retry this POST; re-send with the same `actionId` to retry.
+        RETIRED (zero alias): the 7.35.0–7.120.x `{reason}` "shutdown reason declaration" body (it only recorded a sentence and never
+        drained) now answers 400 `request.field_invalid`; `/health.drainReason` and the `reason` key on 503 `draining` bodies are gone too.
+        Gate order (same as every operator face): identity -> authorization -> body shape -> drain entry -> four-part identity.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/DrainRequest' }
+      responses:
+        '200':
+          description: Draining (this call entered it) or already draining (the first drain's facts, unchanged).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DrainReceipt' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.field_invalid — the body is not a DrainRequest (including the retired `{reason}` form); nothing was changed
+        '401': { $ref: '#/components/responses/Unauthorized' }      # auth.unauthorized (credential gate) / auth.principal_required (REQUIRE_PRINCIPAL deployment, no usable identity)
+        '403': { description: '`auth.operator_only` — OPERATOR_PRINCIPALS is non-empty and the caller is not in it.' }
+        '409':
+          description: >-
+            `conflict.fleet_identity` (server >= 7.121.0) — the request's four-part identity (`scope` / `worker` / `expectedGeneration` /
+            `instanceId`) does not match this engine; the sentence names the mismatched fields (never the values). Nothing was changed.
+            Compare with the target engine's `GET /health` (`instanceId` / `generation`), its worker name and `FLEET_SCOPE`, then re-send.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501':
+          description: >-
+            `capability.operator_principals_required` — OPERATOR_PRINCIPALS is empty, so no identity is an operator on this deployment (any
+            deployment shape, ahead of authorization). `capability.drain_state_required` — the host has no shutdown chain wired (an embedded
+            engine), so there is no drain to enter (answered after the body check). Branch on `errorCode`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/sendfile-links:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -5804,7 +5888,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/CcImportPrepareResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or a layer `root` the server does not accept (server >= 7.120.0: not a complete absolute path — see RuleScope; sentence "scope must be 'global' or 'project:<root>' with an absolute root", no ticket minted; <= 7.119.x: an empty `root`, answered with the body-shape sentence)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or a layer `root` the server does not accept (server >= 7.120.0: not a complete absolute path — see RuleScope; sentence "layers[<i>].root must be an absolute path" on >= 7.121.0, the scope sentence on 7.120.x; no ticket minted; <= 7.119.x: an empty `root`, answered with the body-shape sentence)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '413': { $ref: '#/components/responses/PayloadTooLarge' }   # request.payload_too_large — more than 200 candidates across all submitted layers; SHORTEN and resend (retrying the same payload cannot help)
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -6589,7 +6673,12 @@ components:
         ⚠️ On the billable submit set (every POST that starts a model turn — the server's
         `isBillableSubmitPath`, which is wider than the three task/run endpoints) this
         503 slot is SHARED with producers that are not auth at all, so `errorCode` — not the status — is the
-        branch key: `draining` (this replica is shutting down; retry against a replacement -> DrainingError),
+        branch key: `draining` (this replica is shutting down; retry against a replacement -> DrainingError; server >= 7.121.0
+        refuses only NEW work while draining — HITL answers, including the durable `/decide`, and resumes are admitted — and the body
+        carries no `reason` key any more),
+        `state.lease_expired` (server >= 7.121.0: this fleet member's serving lease has expired and the center has been unreachable
+        for the deployment's `FLEET_LEASE_OUTAGE_MAX_MS`; new work only — HITL answers and resumes pass, in-flight runs are untouched;
+        it lifts when the center grants again; retry later or route elsewhere -> ServiceStateError),
         `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.
@@ -6612,7 +6701,7 @@ components:
           schema: { type: integer }
           description: >
             Seconds to wait before retrying. Presence is per producer, not per status:
-            `draining` always sends it (15), `state.model_roster_pending` always sends it (5),
+            `draining` always sends it (15), `state.model_roster_pending` always sends it (5), `state.lease_expired` always sends it (60),
             `memory.admission_required` sends it ONLY when the engine supplied a hint — a steady-state refusal
             (no resolver wired) honestly carries neither this header nor the body's `retryAfterSec`.
             The auth legs (401 bad token / 503 missing token) never send it.
@@ -7138,7 +7227,12 @@ components:
             `config.permission_mode_unavailable`. `bypassPermissions` RELEASES the ten releasable ask classes (server >= 7.115.0: the tenth is `unstated`, a server-tool call nobody stated)
             and DISCLOSES each (`tool_end.gate.disposition.released` + one `engine_notice` `permission.ask_released_by_mode` per (mode, class) per run);
             immune classes (deployment-authored, ask / org rules, hooks, ancestors, questions …) still ask; a write whose protection
-            cannot be judged is refused (`deniedBy: mode`). Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
+            cannot be judged is refused (`deniedBy: mode`) on the file tools — and, from server >= 7.122.0 / core 7.47.0, RELEASED on the SHELL face
+            (an eleventh class, `write_protection_unresolved`, for a caller-supplied tool whose wire name is exactly `Bash` or `Monitor` and which
+            declares a write-path target; see `ModeRelease.reason`). `plan` (server >= 7.122.0): the engine's plan mode and nothing the service adds —
+            the tool table equals `default`'s, the engine mounts the plan-presenting tool, and a write or any non-read-only call is asked AT CALL TIME by the
+            engine's plan gate (a card where somebody can answer, a refusal where nobody can; a delegated sub-agent inherits plan as its ceiling); up to
+            7.121.x the service also mapped `plan` to read-only hands, withheld the delegation tool and refused `Workflow`. Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
             "auto-refuse" mode, is accepted and passes through verbatim: the ENGINE refuses the calls that would ask (no card, no parked row,
             `tool_end.gate.disposition = { kind: denied, deniedBy: mode, mode: dontAsk, … }`), the run ends normally, and it is never looser
             than `default`. One exception: a PreToolUse hook's OWN ask, when no other class in that ask's set backs it, is still handed to a person
@@ -7148,7 +7242,7 @@ components:
             hold for <= 7.105.0 only.
             CC-parity permission-mode INTENT — the values THIS wire's closed submit-gate accepts (the first five on server <= 7.118.x,
             plus `dontAsk` from 7.119.0 = the engine's whole mode vocabulary, `capabilities.permissionModes`). The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
-            `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research);
+            `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research) — that is the <= 7.121.x reading; server >= 7.122.0: see the `plan` sentence in the first block;
             `default` adds the manual ask gate on non-exempt writes (scratchpad dirs / remembered session
             exemptions still auto-allow — not literally every Write/Edit); the server emits the SAME gate-policy
             for `auto` as for `default` — sending `auto` is NOT itself what arms core's auto-mode classifier; that
@@ -7250,6 +7344,22 @@ components:
             Pin a SEPARATE (usually cheaper) model for compaction. Validated against the catalog on submit — an
             unknown ref is a 400, not a silent fallback to the main model's price.
         appendSystemPrompt: { type: string, description: Text appended to the assembled system prompt for this task. }
+        outputStyle:
+          type: object
+          required: [name]
+          additionalProperties: false
+          description: >-
+            Server >= 7.121.0 (send only when `capabilities.outputStyle` is true; an older server answers 400 `request.body_shape` for the
+            top-level key): the output style's PER-TURN line, handed verbatim to the engine's seat of the same name. Each attachment cycle the
+            engine states "<name> output style is active. <turnReminder>" in its own marker frame (the engine's default sentence when
+            `turnReminder` is absent), echoed on the stream as `steering_injected` with `source: "output_style"`. One fact, one seat: the
+            style's BODY (the guide text) still goes in `settings.outputStyle`; this key carries only the name and the per-turn line.
+            The value's owner is the engine (exactly these two keys, `name` non-empty and at most 256 characters, `turnReminder` a non-empty
+            string when present); the server does not judge it — a bad value is accepted and refused at prepare, the run ends `failed` with
+            code `config.output_style_invalid` (never silently ignored).
+          properties:
+            name: { type: string, minLength: 1, maxLength: 256 }
+            turnReminder: { type: string, minLength: 1 }
         promptProfile:
           type: string
           enum: [simple, classic]
@@ -8993,7 +9103,16 @@ components:
         asyncRuns: { type: boolean }
         artifacts: { type: boolean }
         approvals: { type: boolean }
-        leader: { type: boolean }
+        leader:
+          type: boolean
+          description: >-
+            The `POST /v1/leader` lane. server >= 7.122.0 reads the conjunction of two facts: the leader face is mounted (`LEADER_ENABLED` etc.) AND the
+            operator entry floor takes leader submissions — the same judgement as the 422 `request.autonomy_lane_refused` at the door (a leader task's
+            workers have no plan review channel). So on a deployment whose operator runs `AUTONOMY=plan` the bit reads false and a direct submit still
+            answers 422 `request.autonomy_lane_refused`; with `AUTONOMY=read-only` / `ask` / unset the bit follows the face. A false bit from an absent face
+            answers 501 `capability.leader_endpoint_required` on submit (404 `not_found.route` on <= 7.115.x) — tell the two falses apart by the submit's
+            `errorCode`, or read `GET /v1/policy` `autonomy` beforehand. <= 7.121.x (historical reading): the bit read the face only — true on a `plan`
+            deployment, no prediction of the refusal.
         version: { type: string }
         scenarios:
           type: array
@@ -9221,6 +9340,8 @@ components:
                 bgNotifyFailClosed: { type: boolean }
                 steerPriority: { type: string }
                 hookFailureNotice: { type: boolean, description: 'server >= 7.48.0 (#281): this binary emits a SECOND `hook_notice` kind, `hook_non_blocking_failure` (the user''s own hook broke: exit != 0 and != 2 / timeout / spawn failure / bad JSON). Absent = an older worker that only emits `hook_decision_unavailable` — branch by `kind`, never crash on an unknown one.' }
+                leaseClient: { type: boolean, description: 'server >= 7.121.0, a version bit (always true, rides with the `fleet` object): this binary carries the serving-lease CLIENT — when the engine is a fleet member (`FLEET_GENERATION`) and the center declares in its heartbeat reply that it answers renewals (`servingLease`), the engine renews and is governed by the lease. Deliberately NOT named `servingLease` (that is the center''s bit): this says the client exists, not that a lease is in force — read `/health.leaseState` for that. Absent = an older worker.' }
+                generationEcho: { type: boolean, description: 'server >= 7.121.0, a version bit (always true, rides with the `fleet` object): this binary echoes env `FLEET_GENERATION` as `generation` on the heartbeat and on `/health` (with `leaseState` / `leaseUntil`), and the drain endpoint `POST /v1/admin/drain` compares the four-part identity including `expectedGeneration`. Absent = an older worker.' }
         workspace:
           description: >
             #3 (server 1.299–7.51): workspace-browse capability family — an OBJECT when the E19 snapshot-store
@@ -9257,6 +9378,13 @@ components:
         effortSelection: { type: boolean, description: "`reasoningEffort` accepted per request." }
         compactionModel: { type: boolean, description: "A separate model may be pinned for compaction." }
         appendSystemPrompt: { type: boolean, description: "Per-request system-prompt append is honoured." }
+        outputStyle:
+          type: boolean
+          description: >-
+            server >= 7.121.0, hardcoded true (a predicate-class bit, same family as `approvalDecidedBy` / `sessionReadRedaction`): the
+            top-level request key TaskRequest.outputStyle (the output style's per-turn line) is accepted and handed verbatim to the engine.
+            Send the key only when this is present; absent = an older server, which answers 400 for it. Not the same thing as
+            `taskSettings.outputStyle` (that bit says `settings.outputStyle`, the style BODY, is accepted) — two seats, two facts.
         toolOutput: { type: boolean, description: "`tool_end` carries the model-facing output." }
         messageIdentity: { type: boolean, description: "Content events carry `eventId` (+ `parentToolCallId` for sub-agents)." }
         forwardSubagentEvents: { type: boolean, description: "Sub-agent events are forwarded onto the parent stream." }
@@ -9835,13 +9963,16 @@ components:
         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"`)
+            server >= 7.95.0 (S-591; value meaning refined at 7.96.0 / S-613; mint `routes/capabilities.ts` =
+            `taskWriteFaceRefusal(deps.config) === undefined && autonomyKeepsOpenWriteFace(deps.config.autonomy)` from server >= 7.122.0;
+            up to 7.121.x the right half was `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
+            `422 request.host_posture_refused`; (2) the deployment runs `AUTONOMY=read-only` ⇒ the request is
+            accepted but the write face is clamped back to roots — the declaration silently does nothing; server >= 7.122.0: `AUTONOMY=plan`
+            reads `false` too, but because the entry mode word is clamped to `plan` at admission (the engine's plan mode runs instead of
+            `bypassPermissions`; up to 7.121.x it was the same read-only-hands + roots clamp as `AUTONOMY=read-only`, and a hosted deployment answered 422 `request.host_posture_refused` where it now accepts the request into plan). 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.
@@ -12755,8 +12886,9 @@ components:
         REQUIRED iff `decision==="edit"` (FORBIDDEN otherwise → 400).
         🔴 THE BODY KEY SET IS CLOSED (server >= 7.86.0 / S-438): an unrecognised top-level key is refused with
         400 `request.body_shape` plus the `unknownKeys` / `unsupportedKeys` machine tables — refused rather
-        than dropped, because a misspelled `permissionModeAfter` would otherwise silently leave the task
-        read-only after its plan was approved.
+        than dropped, because a misspelled `permissionModeAfter` would otherwise silently fold to `default`
+        (the task keeps asking before each write after its plan was approved) while the caller believes the
+        mode was settled.
       required: [decision]
       additionalProperties: false
       properties:
@@ -12767,18 +12899,35 @@ components:
           type: string
           enum: [default, acceptEdits]
           description: >
-            server >= 7.86.0 (S-433, P1; mints `routes/approvals-assistant.ts:1021/1024/1148`) — WHICH
-            PERMISSION MODE THIS TASK CONTINUES IN once the plan is approved. Before this key, approving a plan
-            was a BLANK CHEQUE: the plan was approved while the read-only clamp stayed on and every write kept
-            asking. `acceptEdits` = writes stop asking; `default` = keep asking (AND is the folded value when
-            the key is absent, so an older shell executes plans unchanged).
-            🔴 THREE 400s, each with its own code: a value outside the two-word closed set ⇒
+            server >= 7.86.0 (S-433, P1) — WHICH PERMISSION MODE THIS TASK CONTINUES IN once the plan is approved.
+            `acceptEdits` = writes stop asking; `default` = keep asking (AND is the folded value when the key is
+            absent, so an older shell executes plans unchanged). The decision writes the mode back into the task's
+            stored submit body, so every later park -> resume continues in it and never falls back to plan.
+            🔴 server >= 7.122.0 — ONE JUDGE, ONE SOURCE: plan is only the engine's `permissionMode:"plan"`. Since 7.122.0
+            the service adds no read-only clamp of its own, so there is none to lift: the tool table equals `default`'s,
+            and a write or any non-read-only call is asked (somebody can answer) or refused (nobody can) AT CALL TIME by
+            the engine's plan gate. A run's mode word has ONE source, the stored submit body; its two writers are the submit door
+            and this write-back. A decision that carries the plan out of plan mode — `approve` (the original plan) or
+            `edit` (the person's revised plan; the engine proceeds with it) — writes this key back (absent => `default`);
+            only `reject` (the review goes back to redo the plan, plan mode stays) does not. Before 7.122.0 the service
+            also mapped plan to read-only hands; this key was added in 7.86.0 because, before it, approving a plan was a
+            BLANK CHEQUE (the plan was approved while the read-only clamp stayed on and every write kept asking); and on
+            7.86.0-7.121.x `edit` + this key was a 400 while `edit` itself wrote back `plan`, the continuation still held
+            by the read-only hands. All of that is gone since 7.122.0.
+            (A deployment's `AUTONOMY=read-only` static fence is a separate thing: since 7.122.0 it is all the service's governance
+            layer re-folds on each resume, it has nothing to do with approving a plan, and approval does not lift it.)
+            🔴 THREE 400s, each with its own code (match by CODE, not by sentence — the two `request.field_conflict`
+            sentences were reworded in 7.122.0, codes unchanged): a value outside the two-word closed set =>
             `request.field_invalid` (ZERO widening arm — this bit decides whether the model has hands after
             approval, so folding a misspelling into either mode is a silent downgrade on the security axis);
-            sending it with `edit`/`reject` ⇒ `request.field_conflict` (core: those two send the plan back to be
-            redone and the read-only clamp stays — dropping it there would let the caller believe the mode was
-            settled); sending it for a task that was NOT submitted with `permissionMode:"plan"` ⇒
-            `request.field_conflict` (approving the plan lifts no read-only restriction there).
+            sending it with `reject` => `request.field_conflict`, server sentence `permissionModeAfter is only valid with a
+            decision that carries the plan out ('approve' or 'edit'; got 'reject')` (a silent drop there would let the caller
+            believe the mode was settled); sending it for a task whose STORED permission mode is not `plan` (the model
+            entered plan mode itself, so approving returns it to the mode it was in before planning) =>
+            `request.field_conflict`, server sentence `permissionModeAfter does not apply to this task: it was not
+            started in plan mode (its stored permission mode is not "plan"), so approving the plan returns it to the mode
+            it was in before planning`. A task STARTED in plan mode is one the request put there, or one an operator
+            `AUTONOMY=plan` stamped at the submit door (its stored word is `plan`): the key is accepted for both.
             ⚠️ DIRECT-DOOR deployments: this key rides the HMAC envelope's TRAILING EXTENSION OBJECT (server
             7.87.0: `{answer?, permissionModeAfter?}`, present keys in lexicographic order; 7.86.0's bare
             trailing slot is DELETED with zero double-read) ⇒ a signer must sign the new shape, and mixed
@@ -13624,6 +13773,14 @@ components:
             `writeFace: open`; read `capabilities.taskWriteFaceOpen` first); (2) server >= 7.106.0 / S-895: `inheritEnv: "all"` on a
             hosted deployment (`REQUIRE_PRINCIPAL=true`; reach = the hosted posture only; read `capabilities.projectContext` first).
             Remove the key (or send `inheritEnv: "scrub"`) and resend. Resume legs fold it into 409 `resume_blocked_by_policy`.
+            🔴 `request.autonomy_lane_refused` (422, server >= 7.122.0): the deployment's operator `AUTONOMY` does not take tasks on this LANE.
+            Today's only trigger is `AUTONOMY=plan` × `POST /v1/leader` — plan leaves plan mode only through a person approving the plan (plan
+            review), a leader task's workers have no plan review channel, so the refusal is at the door and NO run is created (a replay with the
+            same `Idempotency-Key` gets the same 422 and does not consume the key). Same family as `host_posture_refused` but a different axis:
+            that one is the hosted / tenant posture axis (remove the key and resend); this one is the AUTONOMY axis (nothing to remove — submit
+            as a run via `POST /v1/runs`, or ask the operator for `AUTONOMY=read-only` / `ask`, under which leader tasks run). Read the live
+            config: a hot change takes effect on the next request; read `GET /v1/policy` `autonomy` beforehand (the `capabilities.leader` bit
+            reads false on such a deployment).
         error: { type: string }
         errorMessage: { type: string }
         activeTaskId:
@@ -14362,7 +14519,9 @@ components:
         bypass-IMMUNE (not releasable).
         CLOSED on the gate record (screened with core `isAskClass`). `bypassPermissions` releases only the ten RELEASABLE classes
         (`transcript_write` / `rule_unreadable` / `probe` / `write_protection` / `tool_marks_mcp` / `tool_marks_a2a` /
-        `artifact_shared_read` / `mode` / `unstated` / `ordinary`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
+        `artifact_shared_read` / `mode` / `unstated` / `ordinary`) — on every face — plus, from server >= 7.122.0 / core 7.47.0, an eleventh on the SHELL
+        face only: `write_protection_unresolved` (core `releasableAskClassesFor(face)`: shell 11, other faces 10; on the file tools that class is
+        refused, `deniedBy: mode`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
         ancestor, content question, …) asks under every mode.
     ModeRelease:
       type: object
@@ -14384,8 +14543,19 @@ components:
         mandate: { $ref: '#/components/schemas/PersistedRuleMandate' }
         reason:
           type: string
-          enum: [rule_unreadable]
-          description: '`rule_unreadable` = the release went over a rule this call could not be read against (the rule store was unreadable — a security-axis fail-open direction the server discloses on its own).'
+          enum: [rule_unreadable, write_protection_unresolved]
+          description: >
+            WHAT the release went over — one word: the FIRST member (in core `MODE_RELEASE_REASONS` array order) that the ask's class
+            set holds; ABSENT when the set holds none. CLOSED set — the server screens it with core `isModeReleaseReason`, so a word
+            outside it withholds the whole `gate` from the frame (and a consumer that dispatches on the word must learn each new one).
+            `rule_unreadable` = the release went over a rule this call could not be read against (the rule store was unreadable — a
+            security-axis fail-open direction the server discloses on its own).
+            `write_protection_unresolved` (server >= 7.122.0 / core 7.47.0) = the release went over a write whose target the
+            write-protection judge could not RESOLVE (whether it lands on the protected table is unknown). It is released on the SHELL
+            face only: a caller-supplied tool whose wire name is exactly `Bash` or `Monitor` and which declares a write-path target,
+            under `bypassPermissions`; on the file tools the same unresolved write is still refused (`deniedBy: mode`). The engine's
+            own `Bash` / `Monitor` cannot mint this class and the server mounts no such tool — it comes from a caller-embedded tool of
+            those names. Before server 7.122.0 / core 7.47.0 the set was `rule_unreadable` alone.
 
     GateClassifierAttribution:
       # sdk 9.5.0:具名 —— 同一份形挂在 `GateDisposition` 的两只臂上,内联会立刻是两份会各自漂的镜像。
@@ -15509,6 +15679,17 @@ 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".
+        `server.model_unreachable` (server-minted, audience `user`; server >= 7.108.0, `taskId` added in server 7.121.0) — a model call on
+        this leg ended in error and its last request failed AT CONNECT (VPN switched mid-session / the proxy read at boot went stale / the
+        gateway is gone) — not the provider's answer. `{ code, targetHost, proxyInUse?, remedy, sessionId, taskId? }`: `code` one of the
+        connect-failure set (`ECONNREFUSED` / `ENOTFOUND` / `EAI_AGAIN` / `EHOSTUNREACH` / `ENETUNREACH` / `UND_ERR_CONNECT_TIMEOUT`),
+        `targetHost` the model endpoint's `host:port` (a proxy address never rides this frame), `proxyInUse` present only when this hop
+        went through a proxy and only as the variable NAME (`HTTP_PROXY` / `HTTPS_PROXY`), `remedy` a fixed sentence. `taskId`
+        (server >= 7.121.0) = this leg's run resource id (streaming leg: `X-Task-Id` / the `meta` frame's `taskId`; background leg: the
+        submit receipt's `taskId`; resume leg: the resumed run's id) — the same value as that run's terminal and its run-domain codes'
+        `detail.taskId`; absent when the leg has no run resource (a streaming leg on a deployment without a run store) or on an older
+        server. NO `runId` (the model-call layer cannot see the engine's run identity): a resume leg and its original leg share the
+        `taskId`. Once per leg per target; it says "this endpoint is unreachable", not "this run failed".
         `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
@@ -17767,13 +17948,16 @@ components:
         🔴 Its arrival means the RUN IS STILL ALIVE — the 15-minute stream cap fired. The correct handling is to
         RECONNECT with `Last-Event-ID` and keep reading (the durable leg stamps `id:` on every frame); rendering
         it as a terminal would declare a live task dead. `done` / `failed` are the terminal arms; this one is not.
-        Known `errorCode`: `STREAM_MAX_DURATION` (open set — branch on the code, degrade unknown codes to the
-        generic "reconnectable stream-control signal").
+        Known `errorCode`: `STREAM_MAX_DURATION` (the 15-minute cap) · `draining` (server >= 7.122.0: the instance entered drain / is being
+        replaced — each of the eight read-only subscription streams gets this frame at the moment drain begins and is then closed by the server;
+        same code and sentence as the billable-submit 503 `draining`, same reconnect protocol: reconnect with `Last-Event-ID`, the replacement
+        instance serves it; NOT a run failure; the same reason family as the cap — the server closes a stream for flow control)
+        (open set — branch on the code, degrade unknown codes to the generic "reconnectable stream-control signal").
       additionalProperties: false
       required: [type, errorCode]
       properties:
         type: { const: error }
-        errorCode: { type: string, description: 'STREAM_MAX_DURATION (open set).' }
+        errorCode: { type: string, description: 'STREAM_MAX_DURATION | draining (server >= 7.122.0) (open set).' }
         message: { type: string }
     Event_question:
       type: object
@@ -19593,6 +19777,33 @@ components:
         The three user-editable CC settings layers this version reads (core `ImportedSettingsLayer`). The two
         layers it does NOT read are named in `CcImportPreview.uncovered` rather than being silently absent.
 
+    DrainRequest:
+      type: object
+      required: [actionId, worker, deadlineAt]
+      description: >-
+        The drain endpoint's request (contract `DrainRequest`, `@sema-agent/settings-schema` >= 9.0.0 `./fleet`): "put this instance into
+        draining by this deadline". See `POST /v1/admin/drain` for how the identity fields are compared.
+      properties:
+        actionId: { type: string, minLength: 1, description: 'Idempotency key: the same id again answers `already_draining` and changes nothing. Hand-issued actions pick their own (e.g. `manual:<uuid>`).' }
+        worker: { type: string, minLength: 1, description: The engine's worker name (`SEMA_REGISTRY_WORKER`). }
+        deadlineAt: { type: integer, minimum: 0, description: Epoch milliseconds by which the engine stops on its own. }
+        scope: { type: string, minLength: 1, description: 'The tenant scope; omitted = the default scope `global` (compared against env `FLEET_SCOPE`, unset = `global`).' }
+        expectedGeneration: { type: string, pattern: '^(0|[1-9][0-9]*)$', description: 'The fleet generation as a canonical decimal string (`/health.generation`); absent against absent — omit it only for a non-member.' }
+        instanceId: { type: string, minLength: 1, description: The engine's per-process identity (`/health.instanceId`); compared only when present. }
+        term: { type: string, minLength: 1, description: The claim term the sending executor holds for this action (center-issued, opaque); absent on a direct or hand-issued call. }
+    DrainReceipt:
+      type: object
+      required: [actionId, since, deadlineAt, state]
+      additionalProperties: false
+      description: >-
+        The drain endpoint's answer (contract `DrainReceipt`): the engine's drain fact plus how this call found it. `state: draining` = this
+        call entered drain; `already_draining` = it already was (including a drain the engine entered on its own), and the receipt reports the
+        FIRST drain's facts.
+      properties:
+        actionId: { type: string, minLength: 1, description: The action that entered this drain. }
+        since: { type: integer, minimum: 0, description: 'Epoch ms the drain began (the same value as `/health.drainingSince`).' }
+        deadlineAt: { type: integer, minimum: 0, description: Epoch ms the engine stops on its own (fixed when the drain was entered). }
+        state: { type: string, enum: [draining, already_draining] }
     RuleScope:
       description: >
         Where a persisted rule applies (core `RuleScope`). `project.root` is the directory prefix that decides
@@ -19602,9 +19813,12 @@ components:
         layer `root`, and the `project:<root>` discriminant string on write / revoke / the list filter):
         server >= 7.120.0 accepts only a COMPLETE ABSOLUTE PATH — POSIX `/…`, a Windows drive root `X:\…` / `X:/…`,
         or a UNC root `\\host\…` (the engine's durable-scope predicate; every server entry calls it rather than
-        keeping a copy). A relative root (`proj`, `./x`, `~/x`) or a drive without a root (`C:`, `C:x`) is a 400 whose
-        `error` is exactly "scope must be 'global' or 'project:<root>' with an absolute root" — code
-        `request.body_shape` on write / revoke / cc-import prepare, `request.query_invalid` on the list filter.
+        keeping a copy). A relative root (`proj`, `./x`, `~/x`) or a drive without a root (`C:`, `C:x`) is a 400 — code
+        `request.body_shape` on write / revoke / cc-import prepare, `request.query_invalid` on the list filter. Branch on `errorCode`;
+        the sentence is for people: on write / revoke / the list filter the `error` is exactly "scope must be 'global' or
+        'project:<root>' with an absolute root"; on cc-import prepare (whose body has no `scope` field) server >= 7.121.0 answers
+        "layers[<i>].root must be an absolute path" (`<i>` = the first refused layer, from 0; same predicate), while 7.120.x
+        answered with the scope sentence.
         Server <= 7.119.x checks only that the root is non-empty and keeps relative roots as written; such rows take
         no part in any check on 7.120.0 — SQL backends delete them with a one-time migration at boot, while on the
         file (`local`) backend they stay in the store, are absent from the listing, cannot be revoked, and each run
@@ -19699,8 +19913,8 @@ components:
         what is read is still only the allow bucket.
 
         🔴 `root` follows the RuleScope rule (server >= 7.120.0: a complete absolute path; otherwise 400
-        `request.body_shape` with "scope must be 'global' or 'project:<root>' with an absolute root" and no ticket
-        minted). It applies to ALL layers alike — a `userSettings` layer's root never becomes a scope, but it is the
+        `request.body_shape` and no ticket minted — the `error` is "layers[<i>].root must be an absolute path" on server >= 7.121.0,
+        naming the first refused layer, and the scope sentence on 7.120.x). It applies to ALL layers alike — a `userSettings` layer's root never becomes a scope, but it is the
         same field under the same check. On <= 7.119.x only an empty root is refused (with the body-shape sentence).
         Its TRUTHFULNESS is deliberately NOT validated: the server has no such tree to check against, and pretending
         to validate would be a lie. It is the user's own label for "which cwds should this rule be live under".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "17.2.0",
+  "version": "18.1.0",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -52,6 +52,6 @@
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build && npm run typecheck --workspaces=false --prefix ../.. && npm test --workspaces=false --prefix ../.. && npm run prepack"
   },
   "devDependencies": {
-    "@sema-agent/settings-schema": "^8.0.0"
+    "@sema-agent/settings-schema": "^9.0.0"
   }
 }