@sema-agent/sdk 8.1.0 → 8.3.0

package/openapi.yaml

@@ -1453,7 +1453,7 @@ paths:
                 required: [sessionId, leafId]
                 properties:
                   sessionId: { type: string }
-                  leafId: { type: string, nullable: true, description: "null = session exists but has no entries yet." }
+                  leafId: { type: ["string", "null"], description: "null = session exists but has no entries yet." }
         '304': { description: 'Leaf unchanged since the presented ETag (no body).' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -3358,31 +3358,21 @@ paths:
                 decision: { type: string, enum: [allow, allow_session, deny] }
                 updatedInput: { description: 'ctrl+g edited tool args (replaces the asked args on allow).' }
                 persistRule:
-                  type: object
-                  # 刻意**不**封闭:server 的 `parseToolApprovalResponse` 只读 `rule`,对象里多给的键它**忽略**
-                  # (与 `updatedInput` 同一条宽收姿势)。写 `additionalProperties:false` 会让照 spec 生成的
-                  # 客户端拒发一个 server 其实会受理的请求 —— 那是我们自己造的漂移,不是上游的约束。
-                  required: [rule]
-                  properties:
-                    rule: { type: string, minLength: 1, maxLength: 512, description: 'Non-empty (the server parser rejects an empty string); at most MAX_RULE_TEXT_CHARS = 512.' }
+                  allOf: [{ $ref: '#/components/schemas/PersistRuleSelection' }]
                   description: >
-                    server #154 车二, ADDITIVE — the person ticked "don't ask again": echo back, VERBATIM, the
-                    `rule` of the chosen entry of the frame's `ruleSuggestions`. Allow-family only (on `deny`
-                    the server tolerantly ignores it, same posture as `updatedInput`).
-
-                    🔴 A CANDIDATE, NOT FREE TEXT: the server locates this string in the candidate table the
-                    engine minted and refuses if it does not match (`ruleRefusal: "rule_not_offered"`). Do not
-                    hand-build it, re-case it or append `:*` — take it from the frame.
-                    🔴 Together with `updatedInput` the persistence is refused (`rule_input_edited`): the call
-                    that takes effect is the edited one while the candidates came from the ORIGINAL command.
-                    The decision itself still stands.
-                    ⚠️ If the frame carried no `ruleSuggestions`, do not send this key — there is nothing
-                    redeemable for THIS card and the answer is necessarily `rulePersisted:false` +
-                    `rule_lane_unavailable` (the missing material short-circuits BEFORE any candidate
-                    comparison, so it is never `rule_not_offered`). Absence has THREE possible causes — no rule
-                    store wired, the engine minted no candidate for this command (compound / redirect /
-                    substitution), or the command bytes were unreadable — so do NOT diagnose the deployment's
-                    rule lane from one frame or from that refusal.
+                    The person ticked "don't ask again". TWO MUTUALLY EXCLUSIVE ARMS — the candidate/edited arm
+                    `{ rule, edited? }` and the batch arm `{ batchOfferIndex }`; the shapes, the server's four
+                    verbatim 400 texts, the two capability bits to probe first and the `deny` posture are on
+                    the PersistRuleSelection schema. Allow-family only (on `deny` the whole field is ignored).
+
+                    ⚠️ If the frame carried neither `ruleOffers` nor `ruleSuggestions`, do not send this key —
+                    there is nothing redeemable for THIS card and the answer is necessarily
+                    `rulePersisted:false` + `rule_lane_unavailable` (the missing material short-circuits BEFORE
+                    any candidate comparison, so it is never `rule_not_offered`). Absence has several causes —
+                    no rule store wired, the engine minted no offer for this command (compound / redirect /
+                    substitution), the command bytes were unreadable, or this ask belongs to one of the seven
+                    families that never get offers — so do NOT diagnose the deployment's rule lane from one
+                    frame or from that one refusal.
                 note:
                   type: string
                   maxLength: 2048
@@ -6603,6 +6593,39 @@ components:
             `noteRecorded` (a live-card-only deployment has no row to write, and a flapping store cannot write
             one; both answer `false` while the decision itself still stands). This bit only says "this build
             knows the key" — same family as `permissionRulesRevoke`, deliberately gated on no facility.
+        respondFreeFormRules:
+          type: boolean
+          description: >
+            server >= 7.44.0 (#340), hard-coded true in the capability object — the VERSION PROBE for the
+            free-text arm of POST /v1/tool-approvals/{id}/respond (`persistRule.edited: true`): the rule to
+            persist is text the person HAND-EDITED on the card, not one of the engine's candidates.
+
+            PROBE IT BEFORE RENDERING THE EDITABLE INPUT. The live respond body validator is a NON-STRICT
+            hand-written parser, so an older worker DROPS the unknown `edited` key and judges the text AS A
+            CANDIDATE, answering `rule_not_offered` — honest, but a person reads it as "I typed it wrong".
+            Absent means an older worker: do not render the affordance.
+
+            IT DOES NOT PROMISE THIS ONE WILL LAND (deliberately no facility predicate, same family as
+            `approvalDecisionNote`): that is per-call and answered by `rulePersisted` / `ruleRefusal` —
+            `edit-unsupported` (this card has no binding anchor, STOP rendering the box) versus
+            `edit-rejected` (fix it and try again). Whether the LANE exists at all is `permissionRules`,
+            computed per caller; read the two bits together.
+        respondBatchRuleOffers:
+          type: boolean
+          description: >
+            server >= 7.46.0 (design/377), hard-coded true — the VERSION PROBE for the batch arm of the same
+            endpoint (`persistRule.batchOfferIndex`): the person ticked a `kind: "batch"` offer, and the
+            selection key is that offer's index in the frame's `ruleOffers`.
+
+            PROBE IT BEFORE RENDERING A REDEEMABLE BATCH AFFORDANCE: an older worker drops the unknown key and
+            then fails the `rule` shape check with a 400 — honest, but it cannot tell a batch was ticked. With
+            the bit absent, render batch offers read-only.
+
+            Same posture as above: it only says "this binary knows this key". Whether THIS redemption lands is
+            answered per call by `rulePersisted` / `ruleRefusal`, with `persistedRules` on success and (server
+            >= 7.48.0) the per-entry anchors `persistedRuleAnchors` — that additive key deliberately gets NO
+            second capability bit, since it rides the same batch redemption channel and a consumer just reads
+            whether it is there.
         promptSuggestions: { type: boolean, description: "Follow-up prompt suggestions are generated." }
         modelUsage:
           type: boolean
@@ -6661,6 +6684,217 @@ components:
             and the history PULL answers the no-oracle 404 `not_found.blob`, while the REST of the sync
             surface keeps working.
 
+        # ─── S-139(sdk 8.3.0):对 server 7.60.0 的整体重对账补齐的 19 位 ───────────────────────
+        # 行号 = server 7.60.0 树的 `src/http/routes/capabilities.ts`。语义与谓词的全文在
+        # `packages/sdk/src/types.ts` 的 `Capabilities` 同名成员上(逐条亲读 server 源码转述);
+        # 这里只留 codegen 需要的形与一句定性。机械对账门 = `test/server-keyset-parity.test.ts`。
+        deviceExecutor:
+          description: >
+            device lane (capabilities.ts:162). Object OR `false` — same tri-state family as `fleet`.
+            Predicate = `deps.deviceHub` present, byte-identical to the `GET /v1/device/ws` upgrade
+            handler's mount condition. `wsPath` is deliberately on the wire (hard-coding it downstream
+            would turn a path change into a cross-repo breaking change). Device COUNT / online state are
+            deliberately NOT advertised (that is the `/v1/devices/*` admin face).
+          oneOf:
+            - type: boolean
+              enum: [false]
+            - type: object
+              required: [enabled, protocolVersion, maxInflightPerDevice, wsPath]
+              additionalProperties: true
+              properties:
+                enabled: { type: boolean, enum: [true] }
+                protocolVersion: { type: integer }
+                maxInflightPerDevice: { type: integer }
+                wsPath: { type: string }
+        memoryEngine:
+          description: >
+            Memory ENGINE posture (capabilities.ts:210 = `projectMemoryEngineCapability`). Object = the
+            memory face is really lit, `false` = dark. NOT the same thing as `memory`/`memoryWrite` (those
+            advertise the RETIRED MemoryStore HTTP verbs and stay false forever) — the engine has NO HTTP
+            verbs, so a true here does NOT mean there are memory read/write endpoints to call.
+            `vectorMode: null` = this leg has no rung indicator (the `file` engine), NOT "the rung is null".
+          oneOf:
+            - type: boolean
+              enum: [false]
+            - type: object
+              required: [backend, vectorMode]
+              additionalProperties: true
+              properties:
+                backend: { type: string, enum: [file, pg, tidb] }
+                # 🔴 openapi **3.1**:可空用 `type: [T, "null"]`,`nullable` 不是 3.1 关键字(会被静默忽略)。
+                # `null` 也必须进 enum,否则真校验器把 file 引擎的常态答判非法。
+                vectorMode: { type: ["string", "null"], enum: [native, portable, lexical, null] }
+        sql:
+          type: ["object", "null"]
+          additionalProperties: true
+          description: >
+            This deployment's SQL transaction read semantics (capabilities.ts:216 =
+            `projectSqlEngineCapability`), read back AFTER connection initialization set it — same source as
+            the operator `GET /v1/diagnostics/wiring` `sqlEngine` section. `null` = NO SQL backend here
+            (env-only worker / local file backend), NOT "could not read it". `txnMode: null` = this engine
+            has no such indicator, NOT "optimistic".
+          required: [engine, isolation, txnMode]
+          properties:
+            engine: { type: string, enum: [tidb, innodb, pg] }
+            isolation: { type: string }
+            txnMode: { type: ["string", "null"], enum: [pessimistic, null] }
+        sessionBackgroundable:
+          type: boolean
+          description: >
+            The REMOTE lane can detach (capabilities.ts:233 = `Boolean(deps.runStore)`): `POST
+            /v1/tasks/stream` with `x-detach-on-disconnect: true` survives client disconnect; come back via
+            the `X-Task-Id` response header and `GET /v1/runs/{id}` + `/events`. Deployment half only — the
+            per-request half (caller must pass `sessionId`) is not in this bit. Scope is the REMOTE lane;
+            never repurpose it to disable local backgrounding.
+        runMemoryCaptureOptOut:
+          type: boolean
+          description: >
+            `POST /v1/runs/{id}/memory/capture-optout` mid-run flip verb is present (capabilities.ts:237 =
+            `Boolean(deps.runStore)`). Absent ⇒ do not render the affordance. True only promises the
+            ENDPOINT exists, not that THIS run is live (non-live ⇒ 409 with a signposting body).
+        memoryBundle:
+          type: boolean
+          description: >
+            Governance carry-out bundle pair `POST /v1/memory/{export,import}` (operator lane) —
+            capabilities.ts:261, two conjuncts: both engine seams wired AND `operatorPrincipals` NON-EMPTY
+            (an empty roster makes those routes 403 for every identity). True does not promise the backend
+            has the bundle composite face (core then refuses loudly with `memory.export_incomplete`).
+        memoryCompliance:
+          type: boolean
+          description: >
+            Provenance / erasure compliance pair `GET /v1/memory/entries/{entryId}/provenance` and
+            `POST /v1/memory/erase` (operator lane) — capabilities.ts:273, same two-conjunct family as
+            `memoryBundle`. Deliberately NOT the same source as `memoryBundle` (a deployment can have the
+            bundle composite face without control-plane ownership, and vice versa).
+        memoryOrigin:
+          type: boolean
+          description: >
+            External-origin marking face (three routes under `/v1/memory/origin/*`, operator lane) —
+            capabilities.ts:287, same two-conjunct family. Same predicate as `memoryCompliance` TODAY but a
+            deliberately separate bit (two products; a deployment may want only one). True does not promise
+            the `GET …/external` answer is complete — there is no scope enumeration face, so an empty answer
+            must never be read as "the store is clean".
+        memoryConsolidationDriver:
+          type: boolean
+          description: >
+            Consolidation valve pair (`POST /v1/admin/memory/consolidation/run`, `GET
+            /v1/admin/memory/consolidation`, operator lane) — capabilities.ts:301. FALSE ⇒ those routes are
+            **404** (whole domain unmounted), NOT 501: do not branch on 501 here. Contrast
+            `memoryOptOutGrant`, whose false arm IS a 501.
+        memoryOptOutGrant:
+          type: boolean
+          description: >
+            memory-capture opt-out GRANT table admin (four routes under `/v1/admin/memory-optout`,
+            operator-only) — capabilities.ts:307. FALSE ⇒ **501** `capability.memory_optout_grant_required`
+            (change the deployment shape), as opposed to `memoryConsolidationDriver`'s 404 (turn the knob on).
+        permissionModeAuto:
+          type: object
+          additionalProperties: true
+          description: >
+            Default-state disclosure for `permissionMode: "auto"` (capabilities.ts:463; adjudicated by
+            `src/auto-mode-face.ts`). The parts are deliberately NOT folded into one boolean — "this binary
+            does not know auto" and "it knows auto but this box has no entitlement source" would collapse to
+            the same false, and a shell must do different things for those. `reason` is present ONLY when
+            `armed` is false; read its vocabulary as an OPEN set (server already grew it from four words to
+            six). `model` is omitted when the classifier route cannot be resolved (the server logs the
+            engine's refusal rather than 500-ing the read face). `?permissionMode=<five words>` folds the
+            caller's INTENT into the verdict; anything outside the five words is a 400
+            `request.field_invalid`.
+          # 🔴 required 只有**三位**:武装三键(intentArming / armed / reason)是 server >= 7.57.0 (S-80)
+          # 才有的,而本包的支持地板是 3.0.0 => every 7.x <= 7.56.0 server is inside the promised face and
+          # emits ONLY these three (verified verbatim against server tags v7.50.0 / v7.56.0). Requiring the
+          # arming triple would make a SUPPORTED server's legitimate response invalid.
+          required: [accepted, classifierSeat, entitlementSource]
+          properties:
+            accepted: { type: boolean, enum: [true] }
+            classifierSeat: { type: boolean }
+            entitlementSource: { type: boolean }
+            intentArming: { type: boolean, description: 'server >= 7.57.0 only. ABSENT together with `armed`/`reason` on <= 7.56.0.' }
+            armed:
+              type: boolean
+              description: >
+                server >= 7.57.0 only. Read as THREE states, not two: true = will arm; false = will not, and
+                `reason` is then present; ABSENT = an older server that does not report arming at all — never
+                fold that absence into false (it would render a 7.50 box that IS arming as "auto == default").
+            reason:
+              type: string
+              enum: [mode_not_auto, deployment_incapable, org_denied, local_denied, settings_denied, resolver_fault]
+            model: { type: string }
+        readFace:
+          type: ["string", "null"]
+          enum: [open, roots, null]
+          description: >
+            The EFFECTIVE READ containment rung this deployment explicitly declared (capabilities.ts:484 =
+            `deps.config.readFace ?? null`; env `READ_FACE` or config-center's `readFace.face` — same config
+            key, so this bit does not distinguish org-pushed from local). `null` = this deployment pinned
+            NOTHING and the engine default takes over; the server deliberately does NOT fold `null` into
+            `roots` (copying an upstream default onto the wire becomes a lie the day core changes it).
+            Minimal disclosure — the deny table itself is never on the capability face. There is NO
+            per-request `readFace` field on TaskRequest.
+        callerCwd:
+          type: boolean
+          description: >
+            Whether a caller-supplied `cwd` is actually HONORED (capabilities.ts:541 =
+            `cwdHonored(config) || deviceCwdHonored(config)`) — single-user `host` lane OR the `device` lane.
+            Byte-identical predicate to the submit-side gate in `boot/resolve-spec.ts`. Prefer this bit;
+            when absent (older worker) fall back to `projectContext` — that is the verbatim pre-bit behavior.
+        a2a:
+          type: boolean
+          description: >
+            The A2A CLIENT read face `GET /v1/sessions/{id}/a2a` exists (capabilities.ts:555, unconditional
+            `true` — like `mcp`): with no peers configured it returns an honest empty panel, so there is no
+            501 path to gate on. Deliberately a DIFFERENT predicate from `a2aInjection`.
+        a2aInjection:
+          type: boolean
+          description: >
+            This deployment HONORS a caller-supplied `body.a2aPeers` (capabilities.ts:556 =
+            `a2aInjectionHonored(config)`; three vetoes owned by `task-a2a.ts`: single-user AND `a2a`
+            unlocked AND compliance permits). FALSE is a FIELD gate, not a 4xx: the request still 200s and
+            the field is warned + ignored — EXCEPT under a config lock, where submit refuses 400
+            `config.locked_key`.
+        a2aServe:
+          type: boolean
+          description: >
+            Server-as-peer knob (capabilities.ts:564 = `config.a2aServe !== undefined`): true ⟺
+            `GET /.well-known/agent-card.json` and `POST /v1/a2a` exist; false ⟺ both 404. Scope is ROUTE
+            EXISTENCE, not "every method runs" — `message/send` / `tasks/get` additionally need a durable run
+            store (without it they answer a named JSON-RPC `-32004`).
+        agentRoster:
+          type: boolean
+          description: >
+            `GET /v1/agents/roster` background-agent roster read face (capabilities.ts:640 =
+            `Boolean(deps.backgroundAgentStore)`, byte-identical to that route's 501 gate). Scope is the
+            ENUMERATION face (content-free projection); subagent OUTPUT bodies go through
+            `/v1/runs/{id}/subagents/{handle}/output`, gated by `subagentOutput`.
+        retention:
+          type: ["object", "null"]
+          additionalProperties: true
+          description: >
+            Managed-retention deployment facts (capabilities.ts:654). `null` = the sweep lane is off
+            (default). `mode: audit-only` = it runs and judges but calls NO destructive method; `enforce` =
+            it really deletes. The predicate looks only at config because a box with `intervalSec > 0` and no
+            real executor CANNOT BOOT (`boot/retention-lane.ts` refuses at startup).
+          required: [mode, maxAgeDays]
+          properties:
+            mode: { type: string, enum: [audit-only, enforce] }
+            maxAgeDays: { type: integer }
+        workflowsGate:
+          type: object
+          additionalProperties: true
+          description: >
+            Self-orchestration denial disclosure (capabilities.ts:739). The two parts are deliberately not
+            folded: `engineCan` = core's `workflowsCapability`; `denial` = the DEPLOYMENT-level admission
+            refusal (closed set, today's only member `entitlement_resolver_absent`), `null` = this layer does
+            not refuse. Non-null means the engine is there but this deployment can grant it to NO principal
+            (half-configured) — signpost the OPERATOR, do not tell the user to retry. `denial: null` does NOT
+            mean "you are authorized" (that is per-principal). `workflows` is the PRODUCT of the two factors.
+          required: [engineCan, denial]
+          properties:
+            engineCan: { type: boolean }
+            denial:
+              type: ["string", "null"]
+              enum: [entitlement_resolver_absent, null]
+
     SkillSpec:
       type: object
       description: A per-request skill (passed as an object; core-native TaskSpec.skills shape).
@@ -8023,6 +8257,27 @@ components:
             display order; an EXACT entry, when present, is always first. core contract caps candidates at 2;
             the server enforces a tolerance cap of 4 on read-back — lay out for 4. Absent = pre-column row
             (parked before the column existed) OR no candidates; render both as "no candidates", never an error.
+        ruleOffers:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/RuleOffer' }
+          description: >
+            server >= 7.46.0 (core 5.58.0, design/375) — the discriminated-union successor of the retired
+            `ruleSuggestions` above on the DURABLE queue row (core `PendingAction.ruleOffers`, the same
+            contract as the sync leg's `AskRequest.ruleOffers`). A >= 7.46.0 row carries only the new key;
+            pre-5.58 rows fail the new narrow read entry by entry and land as "no supply" (no compatibility
+            read — a stale schema means re-ask).
+
+            🔴 THE INDEX ON THIS LEG IS NOT A SELECTION KEY. This projection drops malformed offers one by one
+            and COMPACTS, so an excision shifts every later index forward. That is only sound because this leg
+            has NO redemption mouth (POST /v1/approvals/{sessionId}/decide takes no rule field). Using it as
+            `persistRule.batchOfferIndex` would redeem a different rule than the one the person clicked. The
+            live card leg is the opposite (pure prefix truncation, no per-entry drops) and is where redemption
+            actually happens.
+
+            🔴 DISPLAY / TRIAGE ONLY, and ABSENT MEANS THERE REALLY IS NO SUPPLY (rule lane unarmed, the
+            command yields no rule, no rule could silence this ask, or an old row) — never "the projection
+            dropped it", which is precisely the bug this key exists to close. Never `null`, never `[]`.
         governanceForced:
           type: boolean
           enum: [true]
@@ -9889,6 +10144,38 @@ components:
             replica ⇒ redeemable; after a restart / on another replica that `approvalId` 404s and the person
             must use the durable decide leg, which carries NO rule field in v1 (its body is strict — an extra
             `persistRule` is a loud 400, not a silent drop).
+        ruleOffers:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/RuleOffer' }
+          description: >
+            server >= 7.46.0 (core 5.58.0, design/375), "tool_approval" only — the ENGINE-minted "don't ask
+            again" OPTIONS for this ask, as a DISCRIMINATED UNION (`single` | `batch`). It is the BREAKING
+            REPLACEMENT of `ruleSuggestions` above: a >= 7.46.0 engine mints the old key nowhere, there is no
+            alias, and the two keys are declared side by side only so one type surface covers both generations.
+
+            🔴 READ `kind` TO TELL THE ARMS APART, never a positional assumption. ORDER IS CONTRACT: a
+            whole-string exact `single` is index 0 when present and a `batch` is always last; core's own
+            cardinality is <= 2 while the server enforces a tolerance cap of 4.
+
+            🔴 INDEX SEMANTICS DIFFER PER LEG, and only one leg can redeem. On THIS leg (and on the
+            `approval_request` card and the durable replay of both) the server prefix-truncates and never drops
+            an entry, so the index equals core's offer index and IS a legal selection key for
+            `persistRule.batchOfferIndex`. On the durable queue row (PendingCheckpoint.ruleOffers) the server
+            drops malformed entries and COMPACTS, so indexes shift there and that leg has no redemption mouth
+            at all. A consumer that drops entries itself must keep every survivor's ORIGINAL wire index, or
+            suppress its persistence actions entirely (core's normative clause) — a compacted index means the
+            k-th option the person clicked is not the k-th rule the server redeems.
+
+            🔴 PRESENCE IS THE PROMISE (same as `ruleSuggestions`): present only where a permission-rule store
+            is really wired. The converse does not hold — a wired deployment still omits it for mandated /
+            requiresRealApproval / shadowed / hook-produced / inherited-unresolved / ancestor-resolved /
+            anonymous asks. Absence reads as "THIS CARD has no such option", never as "this deployment has no
+            rule lane" (that is `capabilities.permissionRules`) and never as "your rule broke" (that is
+            `persistedRuleShadowed`).
+
+            ⚠️ REDEMPTION SCOPE is the live respond leg keyed by this frame's `approvalId` only; a replayed
+            offer on another replica is not a promise that it is still redeemable.
         persistedRuleShadowed:
           type: string
           description: >
@@ -10013,6 +10300,53 @@ components:
             parentToolCallId: { type: string }
             depth: { type: integer }
             agentName: { type: string }
+        # ─── S-139(sdk 8.3.0):对 server 7.60.0 的整体重对账补齐的 9 位 ────────────────────────
+        # 长 description 的单一真源在 `packages/sdk/src/resources/tool-approvals.ts` 的同名成员上;
+        # 这里只留 codegen 需要的形与硬条款一句。机械对账门 = `test/server-keyset-parity.test.ts`。
+        requiresRealApproval:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.30.0 (core 5.37, #283), "tool_approval" only, ADDITIVE: the SAFETY-class provenance
+            bit core stamps at the gate. Present (true) or ABSENT — never encoded as false. Deliberately a
+            DIFFERENT contract from the card's `risk.requiresRealApproval` (which is an always-present
+            boolean): the card form needs the durable ask store, and this key is what lets a LIVE-ONLY
+            deployment read the bit at all. Present ⇒ every automatic allowance (remembered rules,
+            bypassPermissions posture) stands down.
+        origin: { $ref: '#/components/schemas/AskOrigin' }
+        inputHasBidi:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.45.0 (E-14), "tool_approval" only, ADDITIVE: the TO-BE-EXECUTED input (`args`)
+            contains Unicode bidi control characters — what the eye reads may not be the byte order that
+            runs. DISCLOSURE bit, bytes unchanged (sanitising would change the bytes about to execute, which
+            is WORSE than not disclosing); rendering is the shell's. Present (true) or ABSENT; absence !=
+            "verified clean". Computed BEFORE the byte cap, so it can ride a frame whose `args` were omitted.
+        expiresAtMs:
+          type: integer
+          description: >
+            server >= 7.34.0 (#288), "tool_approval" only, ADDITIVE: window triple (with `expiresInMs` and
+            `serverNowMs`, same names/semantics as on ApprovalRequestFrame) so the LEGACY frame family can
+            render a countdown too. `expiresAtMs` = this ask's absolute deadline on the server clock. The
+            three keys are BORN AND ABSENT TOGETHER — any frame that gets emitted carries all three.
+        expiresInMs:
+          type: integer
+          description: 'Window triple (see expiresAtMs): max(0, expiresAtMs - serverNowMs), computed at mint time.'
+        serverNowMs:
+          type: integer
+          description: 'Window triple (see expiresAtMs): the server clock at FRAME MINT time — the countdown anchor; use it to correct local clock skew.'
+        ruleOffersAbsence: { $ref: '#/components/schemas/RuleOffersAbsence' }
+        denialLimitFallback: { $ref: '#/components/schemas/DenialLimitFallback' }
+        parked:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.42.0 (#329), "tool_approval_complete" ONLY, ADDITIVE: the explicit discriminator for
+            the PARK sense of `outcome: "expired"` (which is one word with three landings). Present ⇔ THIS ask
+            settled through the park route ⇒ render "moved to the background queue", not "the card died".
+            🔴 ABSENCE MUST NOT BE READ AS "really denied": a store-less deployment, a deny policy, and a
+            sibling VOIDed in a batch all emit no such key — absence only means "no park evidence".
         outcome:
           type: string
           enum: [allowed, denied, expired]
@@ -10123,6 +10457,15 @@ components:
             the PRESENCE-IS-THE-PROMISE clause (present only where a rule store is wired) and the redemption
             scope are stated verbatim on ToolApprovalFrame.ruleSuggestions — the live frame, the stored
             `card_json` and the replayed frame carry the SAME material.
+        ruleOffers:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/RuleOffer' }
+          description: >
+            server >= 7.46.0 (core 5.58.0, design/375) — the discriminated-union replacement of
+            `ruleSuggestions` above. Same material as the live frame and the stored `card_json` (the server
+            projects all three through one `copyRuleOffer`), so semantics, order-is-contract, presence-is-the-
+            promise and the per-leg index rules are stated verbatim on ToolApprovalFrame.ruleOffers.
         persistedRuleShadowed:
           type: string
           description: >
@@ -10141,6 +10484,10 @@ components:
         probeCause: { type: object, additionalProperties: true, description: 'server >= 7.17.0: structured reversibility-probe tightening cause — same shape and semantics as ToolApprovalFrame.probeCause ({code, roots:{shown,total}, further?:{shown,total}}); frame and card carry the SAME value (one narrow-read function server-side). See that key for the full contract.' }
         ruleEvidence: { type: object, additionalProperties: true, description: 'server >= 7.23.0: rule-provenance evidence — same shape and semantics as ToolApprovalFrame.ruleEvidence (each member a value or a NAMED absence word; display/reconciliation metadata, never adjudication input). Frame and card carry the SAME value. See that key for the full contract.' }
         delegation: { $ref: '#/components/schemas/ApprovalCardDelegation' }
+        # S-139(sdk 8.3.0):同 A-057.④ 的理由 —— server 早随卡投出(帧与卡同一只窄读函数 ⇒ 同值),
+        # 但本 schema 此前只在帧上公示过。长 description 的单一真源在 ToolApprovalFrame 的同名键。
+        ruleOffersAbsence: { $ref: '#/components/schemas/RuleOffersAbsence' }
+        denialLimitFallback: { $ref: '#/components/schemas/DenialLimitFallback' }
 
     RuleSuggestion:
       type: object
@@ -10163,13 +10510,332 @@ components:
           description: '`exact` = this one command only (`Bash(git status)`); `prefix` = word-boundary prefix (`Bash(git status:*)`). Closed vocabulary — an unknown value is not a candidate this contract describes; do not render it as redeemable.'
         command: { type: string, maxLength: 512, description: 'The command pattern inside the rule, for a shell that would rather not re-parse `rule`.' }
 
+    # ─── S-139(sdk 8.3.0):对 server 7.60.0 整体重对账带进来的四张型面 ───────────────────────
+    AskOrigin:
+      type: string
+      enum: [content_question, unresolvable, org_unavailable, org_rule, hook, ask_rule, denial_limit_fallback, policy]
+      description: >
+        WHO raised an ask (`ToolApprovalFrame.origin`; server >= 7.57.0 / core 7.5.0, S-125③/#564) — core's
+        `ASK_ORIGINS`, ENGINE-STAMPED at the gate (core's words: "engine-stamped at the gate, never a policy's
+        claim"), transcribed verbatim by the server, which deliberately mints no second eligibility table of
+        its own.
+
+        🔴 READ AS AN OPEN SET. The vocabulary's sole owner is core and it has grown before; branch with a
+        default arm and treat an unknown word as "unknown origin", never as "no origin".
+        🔴 NOT interchangeable with `governanceForced`: this says which KIND of authority asked, that one says
+        whether THIS DEPLOYMENT's ops governance layer is the gate — `origin: policy` covers any deployment
+        ToolPolicy's ask, so a governance-produced ask and an ordinary one look identical in this one word.
+
+    RuleOffersAbsence:
+      type: string
+      enum: [mandated, shadowed, lane_cannot_speak]
+      description: >
+        WHY `ruleOffers` is absent while the rule lane IS present (`ToolApprovalFrame.ruleOffersAbsence` and
+        `ApprovalCard.ruleOffersAbsence`; server >= 7.55.0 / core #490 fix ②, S-15). The engine names which
+        door is shut: `mandated` = this ask must be confirmed every time (🔴 this arm must NOT point the user
+        at writing a rule — a rule would not silence it, and saying so sends them into a loop); `shadowed` = a
+        rule matched but could not clear it (the machine-readable twin of `persistedRuleShadowed`);
+        `lane_cannot_speak` = the engine could mint no coverable form for this command.
+
+        Engine-side MUTUALLY EXCLUSIVE with `ruleOffers`. 🔴 ABSENCE IS NOT AN ASSERTION — it covers both
+        "there are offers" and the three structural doors, and one frame cannot tell them apart. ADVISORY
+        display metadata, NEVER adjudication input. The frame and the stored `card_json` go through the SAME
+        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).
+
+    DenialLimitKind:
+      type: string
+      enum: [consecutive, total]
+      description: 'Which bound tripped in a `DenialLimitFallback` — the consecutive-refusal limit or the cumulative one.'
+
+    DenialLimitFallback:
+      type: object
+      additionalProperties: false
+      required: [consecutive, total, limit, autoDenyAfterMs]
+      description: >
+        The auto-mode classifier's DENIAL-LIMIT FALLBACK card (`ToolApprovalFrame.denialLimitFallback` and
+        `ApprovalCard.denialLimitFallback`; server >= 7.57.0 / core 7.4.0 #548, S-114): the call that hit the
+        consecutive (default 3) or cumulative (default 20) refusal limit is no longer silently denied — it
+        becomes a card a HUMAN must decide. The same mint also stamps `requiresRealApproval`; the two are twins.
+
+        🔴 ALL FOUR MEMBERS ARE REQUIRED: core's shape has no optional member, so "one missing" is a bad value
+        rather than an older core, and the server drops the whole key instead of half-minting a card whose
+        counts would be misread.
+        🔴 `autoDenyAfterMs` (ms; `0` = not armed — the deployment turned the knob off, or a TOTAL-tier card
+        waits for a person) is for RENDERING THE COUNTDOWN ONLY. Never start a second timer from it: the window
+        is executed by the ENGINE, and two overlapping windows are worse than the original defect and silent.
+        🔴 ABSENCE IS NOT AN ASSERTION — the vast majority of asks are not fallback cards.
+        ⚠️ The durable (parked) leg does NOT carry this key today; the card's copy rides `card_json`, which is
+        a different leg from the parked row's `pendingAction`.
+      properties:
+        consecutive: { type: integer, description: 'Consecutive refusals at the moment the limit tripped.' }
+        total: { type: integer, description: 'Cumulative refusals at the moment the limit tripped.' }
+        limit: { $ref: '#/components/schemas/DenialLimitKind' }
+        autoDenyAfterMs: { type: integer, description: 'This card''s own auto-deny window in ms; 0 = not armed. Countdown rendering only.' }
+
+    RuleOfferMatch:
+      type: string
+      description: >
+        The MATCH FORM of a persisted rule — the server's `PERSISTED_RULE_MATCHES`, verbatim (the vocabulary
+        is OWNED BY CORE; the server only transcribes it and pins set equality, so core adding a member turns
+        the server red at compile time).
+
+        `exact` = this one command only (`Bash(git status)`). `prefix` = the historical colon-star
+        word-boundary prefix (`Bash(git status:*)`) and the ONLY spelling for a compound prefix form; it stays
+        a permanent compatibility read. `wildcard` = the trailing space-star form (`Bash(npm run *)`), the
+        same predicate as `prefix` on a single command body, minted by core's suggestion face since
+        design/382 / #510. `subpath` = the `Read(//abs-dir/**)` directory form, which never holds a command.
+
+        🔴 FOUR MEMBERS, not "the three today's miner emits": this type describes what a consumer may RECEIVE,
+        and the server's wire validator accepts all four. A consumer type narrower than the mint point is a
+        lie — it lets a `switch` claim exhaustiveness the wire does not honour. (The retired `RuleSuggestion`
+        declared only two, which is exactly why a legal `wildcard` candidate used to be dropped as malformed.)
+      enum: [exact, prefix, wildcard, subpath]
+
+    RuleOfferUncoveredReason:
+      type: string
+      description: >
+        Why one segment of a compound command is STILL not covered after redeeming the batch (design/382
+        §3.5; the server's `UNCOVERED_SEGMENT_REASONS`, core-owned). `redirection` = a redirection is asked
+        every time, permanently. `no_rule_form` = there is no rule form that could cover this segment.
+        `cap_overflow` = deduplication plus the batch cap pushed it out.
+      enum: [redirection, no_rule_form, cap_overflow]
+
+    RuleOfferUncoveredDetail:
+      type: object
+      description: >
+        design/382 §3.5, ADDITIVE — one "why is this segment still uncovered" row. `segment` is the folded
+        segment's ORIGINAL BYTES (command family: UNTRUSTED for display, and subject to the same redaction /
+        truncation discipline as a member's `segment`).
+      additionalProperties: false
+      required: [segment, reason]
+      properties:
+        segment: { type: string, maxLength: 512 }
+        reason: { $ref: '#/components/schemas/RuleOfferUncoveredReason' }
+
+    RuleOfferBatchMember:
+      description: >
+        ONE MEMBER of a `batch` offer — the rule folded out of one segment of a compound command
+        (design/382 §2.3 B3; discriminated on `kind`, core-owned closed vocabulary).
+
+        `segment` records WHICH folded segment this member came from. Core states it explicitly as a RENDERING
+        SEAT that never participates in adjudication, and it is UNTRUSTED for display exactly like
+        `rule` / `command` / `directory`. ⚠️ Only `segment` may be TRUNCATED by the server (an honest
+        elision); `rule` / `command` / `directory` sit on the left-hand side of the redemption equality and
+        are NEVER truncated.
+
+        🔴 AN UNRECOGNISED MEMBER `kind` DROPS THE WHOLE BATCH, never the single member (core's normative
+        degradation clause): a batch missing one member renders "yes to N" as "yes to N-1", which is worse
+        than not rendering it. Any `single` offers beside it are complete and honest, so they stay.
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [kind, rule, match, command, segment]
+          properties:
+            kind: { type: string, enum: [command] }
+            rule: { type: string, maxLength: 512 }
+            match: { $ref: '#/components/schemas/RuleOfferMatch' }
+            command: { type: string, maxLength: 512 }
+            segment: { type: string, maxLength: 512 }
+        - type: object
+          additionalProperties: false
+          required: [kind, rule, directory, segment]
+          properties:
+            kind: { type: string, enum: [directoryRead] }
+            rule: { type: string, maxLength: 512, description: 'The `Read(//abs-dir/**)` directory-read grant minted from a `cd` segment.' }
+            directory: { type: string, maxLength: 512, description: 'Lexically normalised absolute directory — a rendering seat, so the shell need not re-parse `rule`. This arm carries NO `match` / `command`.' }
+            segment: { type: string, maxLength: 512 }
+      discriminator:
+        propertyName: kind
+
+    RuleOffer:
+      description: >
+        ONE "don't ask again" OPTION on an approval card (core 5.58.0 design/375 §3.1; server >= 7.46.0 emits
+        the same shape on THREE legs — the live `tool_approval` frame, the stored `card_json`, and the durable
+        park row). It is the BREAKING replacement of `RuleSuggestion`, with no alias.
+
+        🔴 READ `kind`. ORDER IS CONTRACT: a whole-string exact `single` is index 0 when present, a `batch` is
+        always last, core's cardinality is <= 2 and the server's enforcement cap is 4.
+
+        🔴 TWO ARMS, TWO SELECTION KEYS (see PersistRuleSelection). The `single` arm is redeemed by echoing its
+        `rule` text VERBATIM — the server locates it BY TEXT, so a hand-built string is refused
+        (`rule_not_offered`) by construction. The `batch` arm has no single text to copy (it is ONE yes for
+        every member, with no per-member ticking), so it is redeemed BY INDEX, and the server additionally
+        checks an anti-drift equality before honouring it: the batch re-minted from the adjudicated command
+        must have the SAME member text set as the one the person saw, or the redemption is refused and the way
+        forward is to re-trigger the command for a fresh card.
+
+        🔴 INDEX SEMANTICS DIFFER PER LEG — the live card leg's index is a legal selection key, the durable
+        queue row's is not (that projection compacts). Both statements are on the two `ruleOffers` properties.
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [kind, rule, match, command]
+          properties:
+            kind: { type: string, enum: [single] }
+            rule: { type: string, maxLength: 512, description: 'The canonical rule text to echo back verbatim on redemption (server MAX_RULE_TEXT_CHARS = 512).' }
+            match: { $ref: '#/components/schemas/RuleOfferMatch' }
+            command: { type: string, maxLength: 512, description: 'The command pattern inside the rule, for a shell that would rather not re-parse `rule`.' }
+        - type: object
+          additionalProperties: false
+          required: [kind, rules, uncoveredSegments]
+          properties:
+            kind: { type: string, enum: [batch] }
+            rules:
+              type: array
+              minItems: 1
+              items: { $ref: '#/components/schemas/RuleOfferBatchMember' }
+              description: 'The per-segment members (segment order, deduplicated by rule text). Core contract 1..5; the server tolerates up to 8.'
+            uncoveredSegments:
+              type: integer
+              minimum: 0
+              description: >
+                The HONEST SURPLUS at mint time: how many segments of this compound command would still not be
+                allowed by any rule after redeeming this batch, under the coverage snapshot taken then. `0`
+                means "redeem this and the whole command is covered, as of that snapshot" — a statement about
+                the snapshot, not a lasting guarantee (a concurrent rule revocation makes it stale).
+            uncoveredDetail:
+              type: array
+              items: { $ref: '#/components/schemas/RuleOfferUncoveredDetail' }
+              description: >
+                design/382 §3.5, ADDITIVE — the per-segment reason behind `uncoveredSegments`. When present the
+                row count equals `uncoveredSegments`, but THE COUNT IS THE SOURCE OF TRUTH: the server drops a
+                malformed detail seat without dropping the batch, so an absent `uncoveredDetail` is NOT an
+                assertion that nothing is uncovered.
+      discriminator:
+        propertyName: kind
+
+    PersistedRuleAnchor:
+      type: object
+      description: >
+        server >= 7.48.0 (P-39), ADDITIVE — one self-describing attribution anchor for
+        `ToolApprovalRespondAck.persistedRules`, index-aligned with it.
+
+        The disease it closes: per-entry attribution of `persistedRules` used to be inferable only from
+        POSITION, and position was not provable on the wire (the ack order came from the server's RE-MINTED
+        batch walk, matching the documented display order only by coincidence — the anti-drift check is a SET
+        equality, order is not in it).
+
+        🔴 BOTH INDEXES LIVE IN THE OFFER SPACE, so a consumer needs no mapping: `offerIndex` echoes the
+        request's `persistRule.batchOfferIndex` VERBATIM (correlation: "this ack really is for the redemption
+        I sent"), and `memberIndex` is the position inside that batch's `rules[]` on the frame. Core's
+        candidate space is deliberately kept off the wire.
+      additionalProperties: false
+      required: [offerIndex, memberIndex, rule]
+      properties:
+        offerIndex: { type: integer, minimum: 0 }
+        memberIndex: { type: integer, minimum: 0 }
+        rule: { type: string, maxLength: 512, description: 'The canonical text this member actually landed as (equal to the same-index entry of `persistedRules`).' }
+
+    PersistRuleSelection:
+      description: >
+        The body field `persistRule` of POST /v1/tool-approvals/{id}/respond — TWO MUTUALLY EXCLUSIVE ARMS,
+        matching the server's `ParsedPersistRule` one for one.
+
+        🔴 THERE IS NO `kind` ON THE WIRE: that is the server's own post-parse discriminator. The arms are told
+        apart by WHICH FIELD IS PRESENT.
+
+        🔴 MUTUAL EXCLUSION IS A LOUD 400, not "pick one silently" (server constant
+        PERSIST_RULE_BATCH_EXCLUSIVE_ERROR, verbatim): "persistRule.batchOfferIndex is mutually exclusive with
+        persistRule.rule / persistRule.edited — send exactly one arm". Two arms are two DIFFERENT
+        authorisations; guessing between them is deciding for the person.
+
+        🔴 MALFORMED IS ALSO A 400, never folded (PERSIST_RULE_BATCH_INDEX_ERROR, verbatim):
+        "persistRule.batchOfferIndex must be a non-negative integer when present" — a negative, fractional or
+        non-numeric index that got coerced points at ANOTHER offer. Likewise
+        PERSIST_RULE_EDITED_FLAG_ERROR: "persistRule.edited must be a boolean when present" — a non-boolean is
+        NEVER silently treated as false, because that would quietly fold a "I want to store free text" back
+        into the candidate arm and answer `rule_not_offered`, leaving the person to think their own rule was
+        rejected. And `rule` must be a non-empty string of at most 512 characters.
+
+        🔴 NO SCOPE IN THE BODY: a top-level `scope` and a `persistRule.scope` are both loud 400s
+        ("this endpoint does not accept a rule scope — the server mints it from where the approval happened").
+        Letting the caller name a scope is letting a consent given inside project A be written as a standing
+        allow over project B (or globally) — the most expensive widening available on this axis.
+
+        ⚠️ ON `decision: "deny"` THE WHOLE FIELD IS NOT PARSED AT ALL (tolerated, ignored, no 400 — same
+        posture as `updatedInput`): having refused the operation, consenting to it persistently is meaningless.
+        So the refusals above apply to the allow family; only the TOP-LEVEL `scope` 400 is decision-independent.
+      oneOf:
+        - type: object
+          title: candidate-or-edited-arm
+          required: [rule]
+          # 🔴 互斥必须 EXPLICIT(codex R2-F1,验真后修):两臂都是开集,所以每一臂都能把对面臂的键
+          #    当「多余键」收下 —— `oneOf` 数的是「几臂命中」,于是 `{rule, batchOfferIndex:-1}` 会因为
+          #    批臂被 `minimum:0` 判假而**恰好命中一臂**,schema 放行、server 报互斥 400。靠「另一臂恰好
+          #    判假」表达互斥是间接后果,不是约束。
+          not: { required: [batchOfferIndex] }
+          properties:
+            rule:
+              type: string
+              minLength: 1
+              maxLength: 512
+              description: >
+                With `edited` absent or false this is the CANDIDATE ARM: echo back, VERBATIM, the `rule` of the
+                chosen `kind: "single"` entry of the frame's `ruleOffers` (or, against a <= 7.45 server, of
+                `ruleSuggestions`). Do not hand-build it, re-case it or append `:*` — the server locates it by
+                text and refuses otherwise (`rule_not_offered`). With `edited: true` this is the FREE-TEXT ARM
+                and the string is whatever the person typed.
+            edited:
+              type: boolean
+              description: >
+                server >= 7.44.0 (#340), ADDITIVE — capability bit `respondFreeFormRules`, PROBE IT FIRST.
+                `true` says the text above was hand-edited on the card, so the candidate-table equality is not
+                applied; the engine judges it instead through three gates (the shared validator, a COVERAGE
+                gate requiring the edited rule to still hold the command being adjudicated, and scope
+                inherited from this card). On success the ack carries `persistedRule` = the canonical spelling
+                that really landed. An older worker drops the unknown key and judges the text AS A CANDIDATE,
+                answering `rule_not_offered` — honest, but easily misread as "I wrote it wrong".
+
+                ⚠️ Together with `updatedInput` the persistence is refused (`rule_input_edited`): the call that
+                takes effect is the edited one while the candidates came from the ORIGINAL command. The
+                decision itself still stands.
+          # 🔴 刻意**不封闭**(codex R1-F2,验真后修;main 的同一格早有同款注释,换形时别把它丢了):
+          #    server 的 `parseToolApprovalResponse` 是手写 parser,只读它认识的键,对象里多给的键**忽略**
+          #    (与 `updatedInput` 同一条宽收姿势)。写 `additionalProperties:false` 会让照 spec 生成的客户端
+          #    拒发一个 server 其实会受理的请求 —— 例如一个把整只候选对象 `{rule, match, command}` 原样转发的
+          #    存量壳,重新 codegen 之后就发不出去了。那是我们自己造的漂移,不是上游的约束。
+          #    互斥**不靠封闭表达**:`oneOf` 的语义是「恰好命中一臂」,两臂各自 `required` 不同 ⇒
+          #    `{rule, batchOfferIndex}` 同时命中两臂 ⇒ 判假。开集与互斥两件事各自成立。
+        - type: object
+          title: batch-arm
+          required: [batchOfferIndex]
+          # 同上一臂:`{batchOfferIndex:0, edited:false}` 曾因为文本臂缺 `rule` 判假而恰好命中本臂。
+          not: { anyOf: [{ required: [rule] }, { required: [edited] }] }
+          properties:
+            batchOfferIndex:
+              type: integer
+              minimum: 0
+              description: >
+                server >= 7.46.0 (design/377), ADDITIVE — capability bit `respondBatchRuleOffers`, PROBE IT
+                FIRST. The person ticked a `kind: "batch"` offer; the value is that offer's INDEX in the
+                frame's `ruleOffers`. A conjunctive batch has no single text to copy, so the index is the only
+                possible selection key.
+
+                🔴 NARROWLY OPENED TO BATCH ONLY: an index that points nowhere, or points at a `single`, yields
+                `rulePersisted:false` + `rule_not_offered` — what was never rendered can never be redeemed, and
+                the `single` arm's anti-forgery anchor is its TEXT equality, which an index may not bypass.
+                🔴 An older worker drops the unknown key and then fails the `rule` shape check with a 400
+                — honest, but it cannot tell that a batch was ticked. If the capability bit is absent, do not
+                render a redeemable batch affordance.
+          # 同上一臂:刻意不封闭(理由逐字见那一段)。
+
     RuleRefusalReason:
       type: string
       description: >
         Why a "don't ask again" did NOT get persisted (#154 车二; the server's `RuleRefusalReason`, verbatim).
         A CLOSED set so a shell can branch instead of matching prose. The two naming styles are NOT a typo:
-        the four hyphenated members are derived from the consent lane's own refusal reasons, the four
-        underscored ones are minted by the server's gates.
+        the SEVEN hyphenated members are derived from the consent lane's own refusal reasons
+        (server `CardRulePersisted`), the SIX underscored ones are minted by the server's gates.
+
+        `edit-unsupported` and `edit-rejected` (server >=7.44.0, #340) belong to the FREE-TEXT arm and ask the
+        shell for OPPOSITE things: the first means the edit affordance does not work on this card (no binding
+        anchor, or the deployment has it off) so STOP RENDERING THE INPUT BOX; the second means the engine's
+        gates refused this particular text, so "fix it and try again" — and since #345 (server >=7.51.0) the
+        independently decidable half of that judgement happens BEFORE the decision settles (a 400 with the card
+        still alive), so trying again really works. `scope-unresolved` (core 7.0.0 #490②) is the death of the
+        silent global: with neither an explicit scope nor a cwd the lane refuses loudly instead of defaulting to
+        global, which makes it a ROUTINE answer on a deployment that has not wired `ruleScopeRootFor`.
 
         🔴 A refusal NEVER flips the decision. The person's "allow this once" has already taken effect and
         reached the engine; turning the whole respond into a 4xx would make a real allow vanish. The honest
@@ -10200,16 +10866,30 @@ components:
         note on `rule_lane_unavailable` above already says never to disable the feature globally on it, and
         the same holds here. The one correct source for "does this worker serve rules at all" is
         `capabilities.permissionRules`. Keep offering "don't ask again" on the next ask; just not on this one.
+        `rule_material_absent` (server >=7.48.0, #363) — DURABLE (PARKED) LATE-DECISION LEG ONLY: THIS ROW
+        carries no material to mint a rule from. Three causes, one handling: the ask never entered the rule
+        lane (governance-forced / no owner / the engine minted no candidate / the command bytes are not
+        readable out of the args), the row predates those columns, or the card on the row will not parse.
+        🔴 ALSO SPLIT FROM `rule_lane_unavailable` ON PURPOSE, for the same reason as the previous member:
+        that word says "this deployment serves no rules at all" and a shell may stop rendering the affordance
+        on it, whereas the truth here is "the lane is fine, only THIS ROW has no material". Folding them lets
+        one late park answer condemn a healthy deployment's whole lane. Silently ignoring it is worse still
+        (no silent fail-open on the approval axis): a person who ticked "don't ask again" and saw nothing
+        happen will not tick it twice.
       enum:
         - no-candidates
         - unknown-candidate
         - confirm-refused
         - redeem-refused
+        - edit-unsupported
+        - edit-rejected
+        - scope-unresolved
         - rule_lane_unavailable
         - rule_input_edited
         - rule_not_offered
         - rule_store_error
         - rule_governance_forced
+        - rule_material_absent
 
     ApprovalRiskAxes:
       type: object
@@ -11864,6 +12544,44 @@ components:
             next ask" (`rule_input_edited`) from "there was nothing redeemable on this card"
             (`rule_lane_unavailable`). 🔴 `rule_lane_unavailable` covers four causes, two of them per-card — do
             NOT read it as "this deployment has no rule lane" (see the RuleRefusalReason schema).
+        persistedRule:
+          type: string
+          maxLength: 512
+          description: >
+            server >= 7.44.0 (#340), ADDITIVE — FREE-TEXT ARM ONLY: the CANONICAL SPELLING of the rule that
+            actually landed (core may normalise `Bash(adb *)` into `Bash(adb:*)`). Echo THIS back to the
+            person, not the bytes they typed into the box.
+
+            🔴 ABSENCE HAS THREE MEANINGS, none of them "the rule is gone": (1) this respond used the
+            CANDIDATE arm — the server's `editedArmEcho` is the single mint point for this key, so a candidate
+            respond's ack is byte-for-byte unchanged; (2) nothing landed (read `rulePersisted` / `ruleRefusal`);
+            (3) the respond carried no `persistRule` at all.
+        persistedRules:
+          type: array
+          items: { type: string, maxLength: 512 }
+          description: >
+            server >= 7.46.0 (design/377), ADDITIVE — BATCH ARM ONLY: the canonical text of EVERY member that
+            landed in this one redemption. A conjunctive batch is one yes for the whole set; if any member is
+            refused the ack is `rulePersisted:false` + `ruleRefusal:"redeem-refused"` and the members that DID
+            land are not rolled back (their dots are on record and a re-triggered card dedupes idempotently).
+
+            🔴 ORDER: from server 7.48.0 on, the DISPLAY order of the requested offer
+            (`ruleOffers[batchOfferIndex].rules`) is a PROMISE, not a coincidence; on 7.46-7.47 it inherited the
+            server's re-minted walk order instead. For per-entry attribution read `persistedRuleAnchors`
+            rather than inferring it from position.
+            🔴 Not the same thing as `persistedRule`: the singular key belongs to the single/edited arm, the
+            plural one to the batch arm, and the two never appear together.
+        persistedRuleAnchors:
+          type: array
+          items: { $ref: '#/components/schemas/PersistedRuleAnchor' }
+          description: >
+            server >= 7.48.0 (P-39), ADDITIVE and with NO capability bit — the per-entry, self-describing
+            attribution anchors for `persistedRules`, INDEX-ALIGNED with it.
+
+            Minted ONLY on the batch arm (the single/edited arm has no member coordinates to speak of), and
+            omitted WHOLESALE whenever the server cannot prove attribution — an honest absence, never a
+            fabricated index. A consumer that sees it absent knows this ack can only be read positionally, and
+            `persistedRules` itself is unchanged to the byte (older consumers ignore the unknown key).
         noteRecorded:
           type: boolean
           description: >