@sema-agent/sdk 17.1.0 → 18.0.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:
 
@@ -5595,6 +5599,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 +5867,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 an empty `root` (an empty prefix would silently promote a project rule to global)
+        '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' }
@@ -5931,8 +5994,8 @@ paths:
           required: false
           schema: { type: string, minLength: 1 }
           description: >
-            Filter to one scope, spelled `global` or `project:<root>` with a NON-EMPTY root. Unreadable ⇒ 400
-            `request.query_invalid` (never silently unfiltered). Matching is done on the CANONICAL form, so an
+            Filter to one scope, spelled `global` or `project:<root>` (which roots are accepted: see RuleScope). Unreadable
+            or a root the server does not accept ⇒ 400 `request.query_invalid` (never silently unfiltered). Matching is done on the CANONICAL form, so an
             equivalent-but-differently-spelled root filters to an empty page.
         - name: limit
           in: query
@@ -6015,7 +6078,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/RuleWriteResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.field_invalid — `behavior: "allow"` (whole-sentence refusal, NO `reason` key), or a content test refused it (closed `reason` + human `detail`: rule_rejected / scope_bidi_controls / scope_control_chars / row_inconsistent / …, the SAME table the local-import preview answers with). request.body_shape — body is not {behavior, rule, scope, principal?}, or `scope` is not `global`/`project:<non-empty root>` (same sentence as DELETE)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.field_invalid — `behavior: "allow"` (whole-sentence refusal, NO `reason` key), or a content test refused it (closed `reason` + human `detail`: rule_rejected / scope_bidi_controls / scope_control_chars / row_inconsistent / …, the SAME table the local-import preview answers with). request.body_shape — body is not {behavior, rule, scope, principal?}, or `scope` is not `global`/`project:<root>` with a root the server accepts (see RuleScope; same sentence as DELETE)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — writing another principal's rules without explicit OPERATOR_PRINCIPALS membership
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -6085,7 +6148,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/RuleRevokeResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {behavior, rule, scope, principal?} (server >= 7.67.0: `behavior` is REQUIRED and has no default), or `scope` is not `global`/`project:<non-empty root>`
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {behavior, rule, scope, principal?} (server >= 7.67.0: `behavior` is REQUIRED and has no default), or `scope` is not `global`/`project:<root>` with a root the server accepts (see RuleScope)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — revoking another principal's rule without explicit OPERATOR_PRINCIPALS membership
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -6339,7 +6402,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/DeviceEnrollResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape (unknown key / missing required); request.field_invalid (platformOs outside the v1 closed set `darwin|linux` — a third value is never silently accepted; a field over its byte column — a silently truncated value is a DIFFERENT value)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape (unknown key / missing required); request.field_invalid (platformOs outside the v1 closed set `darwin|linux` — a third value is never silently accepted; a field over its byte column — a silently truncated value is a DIFFERENT value; server >= 7.120.0: `workspaceRoot` not an absolute POSIX path — the token is not consumed)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: >
@@ -6589,7 +6652,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 +6680,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.
@@ -7250,6 +7318,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]
@@ -9221,6 +9305,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 +9343,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." }
@@ -9362,6 +9455,15 @@ components:
             server >= 7.118.0, hardcoded true (a version bit): the three approval decision doors read `decidedBy` (ApprovalDecidedBy).
             Send it only when this is present; absent = an older server (the durable doors and `plan_review` 400 it, the live
             `respond` drops it silently and answers 200).
+        sessionReadRedaction:
+          type: boolean
+          description: >-
+            server >= 7.120.0, hardcoded true (a predicate-class bit, same family as `approvalDecidedBy`): the session HISTORY read
+            (`GET /v1/sessions/:id`, the `messages` string leaves, every fetch form) passes the same redaction as the live and ledger
+            frames (see SessionRecord). Branch on the bit, not on the server version. Bit absent is NOT `false` and NOT "unredacted":
+            a server <= 7.118.x returns the archive as written; a 7.119.x server already redacts but does not report the bit. A true
+            bit does not mean the read face exists (that is `sessions`; without a session audit face that door answers 501 and this
+            bit is still true), nor that the archive holds no credential (the redaction is read-side only).
         approvalReach:
           type: boolean
           description: >-
@@ -12786,7 +12888,8 @@ components:
         tool results, shell output, compaction summaries) pass the SAME redaction as the live and ledger frames — a credential-shaped span reads
         `«redacted:…»`. Key set, count and segment order are verbatim; a history with no credential-shaped span is byte-identical; the archive itself is
         untouched (the redaction is read-side only), and `?blobCap=` truncation runs AFTER redaction. A caller that rebuilds a model context from this
-        read gets the placeholder, not the original string.
+        read gets the placeholder, not the original string. Server >= 7.120.0 reports this with the capability bit `sessionReadRedaction`
+        (a 7.119.x server redacts but does not report it).
       # 🔴 **暂不封闭**(census 轴一裁定,2026-07-30):本体是 core `StoredSession.buildContext()` 的投影
       # (server `audit.ts` auditFromStorage),再叠 server 自己的两条 additive 后处理(windowMessages /
       # truncateMessageBlobs)与路由层追加的 owner —— 键集由「core 投影 × 查询参数」共同决定,不是一个
@@ -15499,6 +15602,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
@@ -19583,10 +19697,54 @@ 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
         which cwds the rule is live under.
+
+        🔴 WHICH ROOTS ARE ACCEPTED — the one statement every other mention in this file points to (the cc-import
+        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 — 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
+        gets an `engine_notice` `permission.rule_row_dropped` naming them. Rewrite them with the project's full path.
+        An EMPTY root is refused on every version (an empty prefix contains every cwd). The root's truthfulness is
+        never validated — only its spelling.
       oneOf:
         - type: object
           additionalProperties: false
@@ -19598,7 +19756,7 @@ components:
           required: [kind, root]
           properties:
             kind: { type: string, enum: [project] }
-            root: { type: string, minLength: 1, description: 'The canonical directory this rule is scoped to. NEVER empty — an empty prefix contains EVERY cwd, which would silently promote a project rule to a global one.' }
+            root: { type: string, minLength: 1, description: 'The canonical directory this rule is scoped to. NEVER empty — an empty prefix contains EVERY cwd, which would silently promote a project rule to a global one. Server >= 7.120.0: a complete absolute path (see the RuleScope description).' }
 
     RuleBehavior:
       type: string
@@ -19674,9 +19832,12 @@ components:
         cloud deployment has no access to the user's filesystem — that is the deployment shape, not a bypass:
         what is read is still only the allow bucket.
 
-        🔴 `root` MUST be non-empty (an empty prefix contains every cwd — see RuleScope). 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".
+        🔴 `root` follows the RuleScope rule (server >= 7.120.0: a complete absolute path; otherwise 400
+        `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".
       # 封闭:server 侧 zod 是 `.strict()`(把 `content` 拼成 `contents` 的客户端应当场 400,而不是拿到
       # 一份「零候选」的预览去纳闷)。
       additionalProperties: false
@@ -19873,7 +20034,7 @@ components:
           allOf: [{ $ref: '#/components/schemas/RuleBehavior' }]
           description: 'Which of the three this row is. Part of the row''s IDENTITY — pass it back VERBATIM to revoke, or the delete aims at another behavior''s same-text row.'
         rule: { type: string, description: 'Canonical rule text — `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). Pass back VERBATIM to revoke.' }
-        scope: { type: string, description: 'Scope discriminant string: `global`, or `project:<root>` with a NON-EMPTY root. Pass back VERBATIM to revoke.' }
+        scope: { type: string, description: 'Scope discriminant string: `global`, or `project:<root>` (which roots: see RuleScope — on server >= 7.120.0 every listed project row has a complete absolute root; an older server may list relative ones). Pass back VERBATIM to revoke.' }
         tool:
           type: string
           # 🔴 只钉非空,**不借**输入面那条 `maxLength: 190`(server 的 `LocalImportRowSchema` 帽的是**收进来的**
@@ -19974,7 +20135,7 @@ components:
           type: string
           minLength: 1
           maxLength: 4104
-          description: 'The scope discriminant string — `global` or `project:<root>` with a NON-EMPTY root (an empty root would match every cwd). Unreadable ⇒ 400 `request.body_shape`, never guessed into `global`. Cap = "project:".length + server MAX_CWD_CHARS (8+4096), same source as RuleRevokeRequest.'
+          description: 'The scope discriminant string — `global` or `project:<root>` (which roots are accepted: see RuleScope; an empty root would match every cwd). Unreadable, or a root the server does not accept ⇒ 400 `request.body_shape`, never guessed into `global`. Cap = "project:".length + server MAX_CWD_CHARS (8+4096), same source as RuleRevokeRequest.'
         principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant write. Absent (or your own principal) = write your own rule. Gated exactly like the revoke half.' }
 
     RuleWriteResult:
@@ -20138,7 +20299,7 @@ components:
             at an `allow` that got defaulted onto the same-text `deny` deletes a refusal that was meant to stay,
             and hands the caller a 200. core's `sameRuleIdentity` names this exact failure.
         rule: { type: string, minLength: 1, maxLength: 1024, description: 'The canonical rule text, VERBATIM as `RuleListResult.rules[].rule` gave it.' }
-        scope: { type: string, minLength: 1, maxLength: 4104, description: 'The scope discriminant string — `global` or `project:<root>` with a NON-EMPTY root (an empty root would match every cwd). VERBATIM as the listing gave it. Cap = "project:".length + server MAX_CWD_CHARS (8+4096) — the 1088 previously written here was the same stale independent copy the server itself fixed (rules.ts MAX_RULE_SCOPE_CHARS 顶注), found by the A-335 anchor sweep.' }
+        scope: { type: string, minLength: 1, maxLength: 4104, description: 'The scope discriminant string — `global` or `project:<root>` (which roots are accepted: see RuleScope; an empty root would match every cwd; a root the server does not accept ⇒ 400 `request.body_shape`). VERBATIM as the listing gave it. Cap = "project:".length + server MAX_CWD_CHARS (8+4096) — the 1088 previously written here was the same stale independent copy the server itself fixed (rules.ts MAX_RULE_SCOPE_CHARS 顶注), found by the A-335 anchor sweep.' }
         principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant revoke. Absent (or your own principal) = revoke your own rule.' }
 
     RemovalLiveness:
@@ -20483,7 +20644,7 @@ components:
           description: 'The v1 CLOSED SET. A third value (e.g. `win32`) ⇒ 400 request.field_invalid — never silently accepted.'
         platformArch: { type: string, maxLength: 32, description: 'At most 32 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound, see the unit convention).' }
         displayName: { type: string, maxLength: 255, description: 'Echoed back by `GET /v1/devices` as `name`, and HONESTLY ABSENT there when empty. At most 255 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound).' }
-        workspaceRoot: { type: string, minLength: 1, maxLength: 1024, description: 'The device-side root every instruction resolves against. Required and non-empty. At most 1024 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound) ⇒ over it 400 request.field_invalid (a silently truncated value is a DIFFERENT value).' }
+        workspaceRoot: { type: string, minLength: 1, maxLength: 1024, description: 'The device-side root every instruction resolves against (and the `cwd` of `exec` / `execStream` when neither the session nor its delegation parents registered a working directory). Server >= 7.120.0: an ABSOLUTE POSIX path — empty, relative (`work`, `./w`) or `~/…` ⇒ 400 request.field_invalid, `error` starting "workspaceRoot must be an absolute POSIX path", the token NOT consumed (resolve the root on the device first). Server <= 7.119.x: only non-empty is checked, and a device registered with a relative root has its sessions refused when 7.120.0 builds their execution environment — re-enroll with an absolute root (new `deviceId`; revoke the old one). At most 1024 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound) ⇒ over it 400 request.field_invalid (a silently truncated value is a DIFFERENT value).' }
 
     DeviceEnrollResult:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "17.1.0",
+  "version": "18.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 ../.. && npm run prepack"
   },
   "devDependencies": {
-    "@sema-agent/settings-schema": "^8.0.0"
+    "@sema-agent/settings-schema": "^9.0.0"
   }
 }