@sema-agent/sdk 7.2.0-rc.1 → 7.3.0

package/openapi.yaml

@@ -487,10 +487,12 @@ paths:
       # `steering.duplicate_input_id` 语义**完全依赖这个头** —— 不声明它,就是声明了一条谁也走不到的臂。
       # ⚠️ 与 submit-class(`/v1/tasks`、`/v1/runs`)不同,这里的键**不是重试许可证**:steer 是
       # AT-MOST-ONCE,SDK 不自动铸键也不因为有键就重试;它纯粹是服务端的去重令牌。
-      # ⚠️⚠️ **作用域只到 parked 两腿**(codex R2 复审报出,亲读 server 证实):只有
-      # `setPendingSteer(token, scope, steerInput())` 那两条腿把派生的 `inputId` 交给 core;live 腿走的是
-      # `live.steer(text, { trusted })`,**没传 inputId**,core 的 `TaskStream.steer()` 今天也不收 ——
-      # 所以 200 `applied` 腿**不去重**。这条限定写进下面 409 的描述里,别在别处把它说成整个 verb 的幂等。
+      # ⚠️⚠️ **作用域(A-075.78 doc-rot 修,2026-08-30 亲读 server runs.ts live 腿实证)**:自 server 7.23.0
+      # (core 5.35.0 #257)起,派生的 `inputId` **两腿都传** —— parked 腿经 `setPendingSteer`(7.3.0 起就有),
+      # live 腿经 `live.steer(text, { trusted, inputId })`。此前这里写「live 腿不传 inputId,200 applied 腿
+      # 不去重」——那句自 7.23.0 起过期(SDK `resources/runs.ts` 的 SCOPE 段早已翻面,本注迟到)。两腿判重
+      # 窗口强度不同(parked=durable 行;live=流对象生命周期,不跨重启/副本/resume);对 7.19.0–7.22.0 的
+      # 老 server 旧限定仍逐字成立 —— 细节见下面 409 描述的 SCOPE 段。
       - $ref: '#/components/parameters/IdempotencyKey'
     post:
       tags: [runs]
@@ -590,13 +592,19 @@ paths:
             sent is already parked with DIFFERENT steering content (same key + same content is an idempotent
             no-op and 202s). The engine refuses rather than silently picking a side. Reissue with a fresh
             key — this is a new instruction, not a retry.
-            🔴 SCOPE (#193 车8, codex R2 — read this before treating the key as verb-wide idempotency): this
-            code, and idempotency in general, exist ONLY on the PARKED legs (202 `queued` / `parked_for_wake`),
-            because only those thread the derived `inputId` into core via `setPendingSteer`. The 200 `applied`
-            leg calls core's `TaskStream.steer(text, {trusted})`, which takes NO inputId today — so it does
-            NOT dedupe: a lost 200 retried with the SAME key injects the instruction a SECOND time. Worse, the
-            receipt's `messageId` is derived from that key, so both receipts are byte-identical and the
-            duplicate looks like an idempotent hit. Treat a lost 200 as "outcome unknown", not "safe to retry".
+            🔴 SCOPE (#193 车8 → corrected A-075.78, 2026-08-30, server live leg re-read): since server
+            7.23.0 (core 5.35.0 #257) the key dedupes BOTH legs — the parked path threads the derived
+            `inputId` into core's `setPendingSteer` (as it has since 7.3.0), and the live path threads the
+            SAME id into `TaskStream.steer(text, {trusted, inputId})`, so a lost 200 retried with the same
+            key is an idempotent no-op (core injects nothing, no second `human_input` frame) and same-key+
+            different-text 409s `steering.duplicate_input_id` on the live leg exactly like the parked one.
+            ⚠️ The two dedup windows differ in STRENGTH (core contract, stated rather than papered over):
+            parked = DURABLE (the checkpoint row); live = the stream object's lifetime — one run leg in one
+            process, never spanning a restart/replica/resume; an id already delivered by the parked leg is
+            NOT in the live domain (cross-leg idempotency is the deployment's half).
+            ⚠️ Against a server 7.19.0–7.22.0 the OLD caveat applies verbatim: only the parked legs dedupe —
+            a lost 200 retried with the same key injects TWICE with byte-identical receipts; treat a lost 200
+            there as "outcome unknown", never "safe to retry".
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -640,6 +648,127 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
 
+  /v1/runs/{taskId}/interrupt:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      # server 收法与 steer 逐字同配方(scoped 口径 + sha256 定长 + `idem-` 前缀)收成 core `inputId`,
+      # 🔴 且 text 形 **202 回执的 `messageId` ≡ 这个 inputId** —— `task.turn_interrupted` 帧的
+      # `detail.inputId` 用同一个值,回执与帧对得上(并发两刀分得清哪刀是谁的)。与 steer 的缺席臂刻意
+      # 不同:本 op **无 key 也现铸 uuidv7 并下传**(每请求各是各的指令,零去重域,重试语义与旧形一致)。
+      # bare 形上本头是 no-op(没有输入帧可去重;halt 天然幂等,重复调用引擎自答 turnCut:false)。
+      # ⚠️ 键不是重试许可证(steer 同纪律):AT-MOST-ONCE,SDK 不自动铸也不因有键而重试。
+      - $ref: '#/components/parameters/IdempotencyKey'
+    post:
+      tags: [runs]
+      operationId: runsInterrupt
+      x-status: live             # core #504 / server 7.52.0 F1 全弧(A-075.78 SDK 半场,2026-08-30)。
+      summary: Interrupt the in-flight TURN of a durable run — cut (+ optionally steer); bare form = halt.
+      description: >
+        core #504 — the TURN-level verb that run-level cancel is not: finished tools keep their REAL results,
+        un-started ones settle as interrupted pairs, in-flight tools are NOT collateral. TWO shapes,
+        discriminated by `text` presence.
+        WITH text = cut + steer: the in-flight turn is cut and the text goes to the FRONT of the queue — the
+        `"now"` tier is the VERB's semantics, not a body field (the steer op's `priority` stays advisory) —
+        and the run CONTINUES. 202 `{taskId, status, delivery:"queued-immediate", messageId, note}`;
+        `messageId` ≡ the engine inputId, and a real cut is proven ONLY by a `task.turn_interrupted` event on
+        the run stream whose `detail.inputId` matches it (core: no false interrupt claims — every real cut
+        emits one, an idle cut emits none and the text lands at the next turn boundary).
+        BARE form (body `{}` / empty / literal null) = halt (the CC Esc semantic, cut + STOP): the same cut,
+        but the run CLOSES at this human-made boundary as `status:"completed"` with
+        `TaskResult.haltedByUser:true`; the session continues normally (submit the next objective on the same
+        session). 202 `{taskId, status, turnCut, note}` — deliberately NO `delivery`/`messageId` (no input
+        frame exists to correlate; the frame's `detail.cause:"user_halt"` arm carries no inputId). A bare body
+        with EXTRA keys is a 400 — a typo'd `{txt:…}` must not silently become a verb that stops the run.
+        LIVE-ONLY, no park fallback (the root difference from steer — a turn is an in-process concept, a
+        parked run has no in-flight turn to cut). Authorization = the cancel door (owner-or-explicit-operator:
+        whoever may collaterally cancel the whole run holds the strictly smaller power to cut one turn).
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              # text 形对多余键宽容(冻结契约,steer 同族);bare 形零键纪律由 400 执法(见下)。
+              additionalProperties: true
+              properties:
+                text:
+                  type: string
+                  description: >-
+                    Optional. Present ⇒ cut + steer (non-empty required; present-but-empty/non-string = 400).
+                    Absent ⇒ bare halt — the body must then be EXACTLY `{}` (zero keys), empty, or null.
+      responses:
+        '202':
+          description: >-
+            Accepted — two shapes share this code; branch on which arm's keys are present (`delivery` vs
+            `turnCut`), NOT on the status code. See InterruptReceipt.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/InterruptReceipt' }
+        '400':
+          description: >-
+            errorCode "request.invalid_json" — the body did not parse as JSON;
+            errorCode "request.body_shape" — a scalar/array body, a bare body with EXTRA keys, or `text`
+            present but empty/non-string (the message is the literal accepted shape: `{}` for bare halt, or
+            `{ text: string (non-empty) }` for cut + steer). Malformed is NEVER silently folded into halt —
+            that would swap the caller's verb for one that stops the run.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: >-
+            errorCode "interrupt.nothing_in_flight" — the run is PARKED on a pending decision: no in-flight
+            turn to cut, and deliberately NO park fallback — to deliver input to a parked run use
+            POST /v1/runs/{taskId}/steer (it parks onto the checkpoint and injects on resume).
+            errorCode "interrupt.not_held" — the run is running but THIS replica holds no live interruptible
+            turn face: live on ANOTHER replica (stated only when the row's instanceId PROVES it — the message
+            then says to resend there), or a verify/cascade execution lane which exposes no stream (those legs
+            return a result, not a live stream; the weakest-claim wording covers single-replica deployments).
+            Use POST /v1/runs/{taskId}/cancel for a run-level stop.
+            errorCode "steering.not_running" (reused verbatim) — terminal / not accepting, or the stream
+            settled in the race window ("run just finished on this replica — no in-flight turn to interrupt").
+            errorCode "steering.duplicate_input_id" — this Idempotency-Key was already accepted with DIFFERENT
+            content or at a DIFFERENT tier (core's replay identity includes the normalized tier: the same key
+            that once went through the steer door (default tier) then hits this door (now) is refused —
+            "idempotent success without the cut" would be a dispositive lie). Reissue with a fresh key.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '413':
+          description: >-
+            errorCode "request.payload_too_large" — the worker's global body cap (`MAX_BODY`, 8 MiB), raised
+            by the shared JSON reader (the steer op's 413 note applies verbatim; no separate text cap here).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: >-
+            TWO codes, text form only (the bare form skips content validation — no text reaches the model,
+            and core's userPromptSubmit gate has no jurisdiction over a halt):
+            errorCode "steering.invalid_content" — the text carried a control-plane escape (e.g.
+            </system-reminder>); validated BEFORE the row lookup, and core re-rejects on the live leg.
+            errorCode "steering.blocked_by_hook" (S-51 / core 5.62 design/373 §4.3) — the deployment's
+            userPromptSubmit hook refused this input; block / hook timeout / hook crash are ONE code,
+            FAIL-CLOSED. The input was NOT accepted (no human_input frame, the inputId is not spent) — a
+            retry with different content is legitimate. The hook's own bounded reason is passed through
+            verbatim (first-hand triage material). SDK: falls on the SteeringError base via the `steering.`
+            prefix family (`.errorCode` carries the discriminator; same registration as
+            steering.parked_input_blocked).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' } # rateLimited||quotaExceeded||leaseDenied — steer 同门(mutating + injects into a model run)
+        '501':
+          description: >-
+            errorCode "capability.run_store_required" — no durable run store wired
+            (DB_BACKEND=mysql|pg|local); the whole async-run family is off. Probe `capabilities.asyncRuns`,
+            don't trial-by-501.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/runs/{taskId}/subagents/{target}/steer:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -1523,14 +1652,20 @@ paths:
               schema:
                 type: object
                 additionalProperties: false
-                required: [sessionId, status]
+                # #354 spec-drift fix(2026-08-27,亲读 server 真码):两处铸造点都恒带 `bindingEnforced:true`
+                # (server.ts 受理点 `onAccepted` 与 driveResumeIntoRunLog 终局 return)——此前 additionalProperties:false
+                # 把真响应判成超集;并且 [3833] S-1 起 wake 腿恒声明受理语义(notify-wake.ts 调 resumeWake 第五参=true):
+                # durable 行在场时 200 是**受理形** `{taskId, sessionId, status:"resuming", bindingEnforced}`,腿在后台
+                # 跑到停点(终态跟 GET /v1/runs/:id / events tail);无 durable 行的部署保持同步形(status=终局枚举)。
+                required: [sessionId, status, bindingEnforced]
                 properties:
                   taskId: { type: string, description: 'The active run id; OMITTED when no active row.' }
                   sessionId: { type: string }
-                  status: { type: string, description: 'The run''s resulting status (completed/failed/suspended/needs_review/blocked — core TaskStatus is passed through verbatim; "timeout" retired in core 5.8.0: walltime exhaustion now lands as failed + errorCode limits.max_walltime_exceeded).' }
-                  errorCode: { type: string, description: 'Failure code when the resumed leg failed (e.g. `cancelled`).' }
-                  errorMessage: { type: string, description: 'Human-readable failure detail (server-side secret-redacted).' }
-                  retriable: { type: boolean, description: 'true = the park is STILL pending (re-parked); refetch and retry.' }
+                  status: { type: string, description: 'ACCEPTANCE form (durable row present, [3833] S-1): "resuming" — the leg keeps running server-side; follow GET /v1/runs/:id or the events tail for the outcome. SYNCHRONOUS form (no durable run row): the run''s resulting status (completed/failed/suspended/needs_review/blocked — core TaskStatus verbatim; "timeout" retired in core 5.8.0: walltime exhaustion now lands as failed + errorCode limits.max_walltime_exceeded).' }
+                  bindingEnforced: { type: boolean, description: '[2400] HITL-12 generation probe — this server enforces decision-action binding. Always true (present on BOTH 200 forms).' }
+                  errorCode: { type: string, description: 'Failure code when the resumed leg failed (e.g. `cancelled`). Synchronous form only — never on the acceptance form.' }
+                  errorMessage: { type: string, description: 'Human-readable failure detail (server-side secret-redacted). Synchronous form only.' }
+                  retriable: { type: boolean, description: 'true = the park is STILL pending (re-parked); refetch and retry. Synchronous form only.' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: 'No parked checkpoint for this session (nothing to wake), or session not visible to the caller.' }
@@ -1549,14 +1684,21 @@ paths:
     get:
       tags: [workspace]
       operationId: workspaceList
-      x-status: live             # #3 workspace browse (server >=1.299; design docs/DESIGN-workspace-browse.md, [1894]).
-      summary: List a session's workspace snapshots (newest first).
-      description: >
-        #3 — the read-only projection over the E19 snapshot store (a snapshot = the working tree at a turn
-        boundary; zero new storage). Rows carry `{key, files, bytes?}` — `bytes` only when the SQL size index
-        is available (a local file backend omits it honestly). `latest` = the newest snapshot key (absent when
-        the session has none). Owner-scoped (non-owner → 404, no oracle); 501 without the snapshot-store read
-        faces (probe `capabilities.workspace`).
+      x-status: retired          # S-15/design/381 (server 7.52.0): whole-tree snapshot epoch retired — every ≥7.52 deployment answers 501 capability.workspace_retired.
+      summary: 'RETIRED (server 7.52.0, S-15) — snapshot listing; ≥7.52 answers 501 capability.workspace_retired. Live on 1.299–7.51 only.'
+      description: >
+        🔴 RETIRED as of `@sema-agent/server` 7.52.0 (S-15/design/381): the E19 whole-tree snapshot store this
+        face projected was replaced by per-edited-file rewind HISTORY, which holds only files the agent edited
+        — structurally there is no "whole workspace" manifest to browse anymore. The route SHAPE is kept
+        server-side as a tombstone: every ≥7.52 deployment answers 501 `capability.workspace_retired` (a named
+        refusal, not a 404 that reads like a typo), and `capabilities.workspace` is always false (same
+        predicate). There is NO 1:1 replacement path — a future "rewind coverage" browse would be a NEW face
+        with tracked-set semantics, not this name wired back. Related live faces: rewind restore rides
+        `TaskRequest.restoreFiles` (probe `capabilities.restoreFiles`); per-file history blobs ride
+        `GET /v1/sessions/{sessionId}/sync/history/blobs/{hash}`.
+        Historical shape (servers 1.299–7.51): read-only projection over the E19 snapshot store. Rows carry
+        `{key, files, bytes?}`; `latest` = the newest snapshot key. Owner-scoped (non-owner → 404, no
+        oracle); 501 without the snapshot-store read faces (probe `capabilities.workspace`).
       parameters:
         - in: query
           name: limit
@@ -1591,12 +1733,14 @@ paths:
     get:
       tags: [workspace]
       operationId: workspaceTree
-      x-status: live
-      summary: One snapshot's file tree (stable path order, paginated).
-      description: >
-        Entries carry `{path, hash, size?}` — `hash` is the sha256 content-address (cross-snapshot change
-        highlighting, [1894]②); `size` only when the SQL size index is available. `limit` 1..2000 default 500,
-        `offset` cursor; `nextOffset` present = more pages.
+      x-status: retired          # S-15 (server 7.52.0): retired with the family — see workspaceList's retirement note.
+      summary: 'RETIRED (server 7.52.0, S-15) — snapshot file tree; ≥7.52 answers 501 capability.workspace_retired.'
+      description: >
+        🔴 RETIRED as of server 7.52.0 — same retirement (and same replacement pointers) as `workspaceList`
+        above: every ≥7.52 deployment answers 501 `capability.workspace_retired`; `capabilities.workspace` is
+        always false. Historical shape (1.299–7.51): entries carry `{path, hash, size?}` — `hash` is the
+        sha256 content-address (cross-snapshot change highlighting, [1894]②); `size` only when the SQL size
+        index is available. `limit` 1..2000 default 500, `offset` cursor; `nextOffset` present = more pages.
       parameters:
         - in: query
           name: limit
@@ -1633,16 +1777,19 @@ paths:
     get:
       tags: [workspace]
       operationId: workspaceFile
-      x-status: live
-      summary: Read ONE file's bytes from a snapshot (preview face; capped).
-      description: >
-        Raw bytes with a CONSERVATIVE content-type table (only unambiguous non-active types; html/svg etc.
-        deliberately serve as octet-stream — agent output is untrusted; `x-content-type-options: nosniff`
-        always set) + the `x-sema-content-binary` discriminator header (first-8KiB NUL sniff, [1894]③).
-        Capped at `capabilities.workspace.maxFileBytes` (default 8MiB, WORKSPACE_FILE_MAX_BYTES) — over-cap ⇒
-        413 STRUCTURED envelope `{errorCode: "workspace_file_too_large", sizeBytes, limit}` ([1894]①; the archive
-        endpoint is the escape hatch). When the SQL size index knows the size, the 413 fires BEFORE fetching
-        the bytes.
+      x-status: retired          # S-15 (server 7.52.0): retired with the family — ≥7.52 the tombstone rejects BEFORE any size check, so the 413 envelope below is unreachable there.
+      summary: 'RETIRED (server 7.52.0, S-15) — single-file read; ≥7.52 answers 501 capability.workspace_retired.'
+      description: >
+        🔴 RETIRED as of server 7.52.0 — same retirement (and replacement pointers) as `workspaceList` above.
+        On ≥7.52 the tombstone 501 fires BEFORE any size check, so the 413 `workspace_file_too_large`
+        envelope below is UNREACHABLE there (the SDK keeps its typed WorkspaceFileTooLargeError for
+        1.299–7.51 servers still inside the support range). Historical shape (1.299–7.51): raw bytes with a
+        CONSERVATIVE content-type table (html/svg etc. deliberately serve as octet-stream — agent output is
+        untrusted; `x-content-type-options: nosniff` always set) + the `x-sema-content-binary` discriminator
+        header (first-8KiB NUL sniff, [1894]③). Capped at `capabilities.workspace.maxFileBytes` (default
+        8MiB, WORKSPACE_FILE_MAX_BYTES) — over-cap ⇒ 413 STRUCTURED envelope
+        `{errorCode: "workspace_file_too_large", sizeBytes, limit}` ([1894]①; archive was the escape hatch).
+        With the SQL size index the 413 fired BEFORE fetching the bytes.
       parameters:
         - in: query
           name: path
@@ -1686,15 +1833,16 @@ paths:
     get:
       tags: [workspace]
       operationId: workspaceArchive
-      x-status: live
-      summary: Download one whole snapshot as a streamed tar (ustar).
-      description: >
-        Streamed ustar (`content-disposition: attachment`), entries in stable path order, blob-by-blob with
-        backpressure — server memory stays O(1 file). Pre-flight checks BEFORE the headers go out: paths not
-        representable in ustar (>255 bytes / unsplittable) ⇒ 422 naming the first offenders; missing blobs
-        (raced a reap / partial import) ⇒ 502 (retryable). A blob vanishing MID-stream destroys the connection
-        (honest truncation — the tar end blocks are missing, consumers can detect it) rather than faking a
-        complete archive.
+      x-status: retired          # S-15 (server 7.52.0): retired with the family — see workspaceList's retirement note.
+      summary: 'RETIRED (server 7.52.0, S-15) — whole-snapshot tar; ≥7.52 answers 501 capability.workspace_retired.'
+      description: >
+        🔴 RETIRED as of server 7.52.0 — same retirement (and replacement pointers) as `workspaceList` above:
+        every ≥7.52 deployment answers 501 `capability.workspace_retired`. Historical shape (1.299–7.51):
+        streamed ustar (`content-disposition: attachment`), entries in stable path order, blob-by-blob with
+        backpressure — server memory stays O(1 file). Pre-flight checks BEFORE the headers went out: paths
+        not representable in ustar ⇒ 422 naming the first offenders; missing blobs (raced a reap / partial
+        import) ⇒ 502 (retryable). A blob vanishing MID-stream destroyed the connection (honest truncation)
+        rather than faking a complete archive.
       responses:
         '200':
           description: The tar stream.
@@ -1916,12 +2064,18 @@ paths:
     get:
       tags: [sessions]
       operationId: sessionSyncGetBlob
-      x-status: live
-      summary: PULL one content-addressed blob's raw bytes (scope-checked).
-      description: >
-        2c session-sync PULL — one content-addressed blob's RAW bytes (`application/octet-stream`). 🔴 SCOPE BOUNDARY:
-        a content-addressed blob is shared across sessions, so the cloud serves a hash ONLY if THIS session's `:key`
-        manifest references it (a foreign / unreferenced hash → 404 `blob not found`, never a blind read). 400 on a
+      x-status: retired          # S-15 (server 7.52.0): the E19-era snapshot-scoped PULL arm was REPLACED by GET …/sync/history/blobs/{hash} — ≥7.52 this path 404s (not_found.route).
+      summary: 'RETIRED (server 7.52.0, S-15) — snapshot-scoped blob PULL; use GET …/sync/history/blobs/{hash}. Live on ≤7.51 only.'
+      description: >
+        🔴 RETIRED as of `@sema-agent/server` 7.52.0 (S-15/design/381): a blob is scoped by the session's
+        HISTORY GRAPH now, not by a per-snapshot manifest key, so this arm was replaced by
+        `GET /v1/sessions/{sessionId}/sync/history/blobs/{hash}` (sessionSyncGetHistoryBlob — same
+        octet-stream body, same no-oracle 404 posture, scope check = "referenced by this session's
+        exportHistory envelope"). On ≥7.52 this path no longer matches the sync route family and answers 404
+        `not_found.route`. SDK: `sessions.sync.getHistoryBlob` (the legacy `getBlob` verb stays, deprecated,
+        for ≤7.51 servers inside the support range).
+        Historical shape (≤7.51): one content-addressed blob's RAW bytes; the cloud served a hash ONLY if
+        THIS session's `:key` manifest referenced it (foreign/unreferenced → 404 `blob not found`). 400 on a
         non-64-hex hash or an undecodable key/hash. Owner-scoped (404).
       responses:
         '200':
@@ -1934,6 +2088,43 @@ paths:
         '404': { $ref: '#/components/responses/NotFound' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
+  /v1/sessions/{sessionId}/sync/history/blobs/{hash}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: hash
+        required: true
+        schema: { type: string, pattern: '^[0-9a-f]{64}$' }
+        description: The content-address (SHA-256, 64 lowercase-hex).
+    get:
+      tags: [sessions]
+      operationId: sessionSyncGetHistoryBlob
+      x-status: live             # S-15/design/381 (server 7.52.0): the history-graph-scoped successor of the retired snapshots/{key}/blobs PULL arm.
+      summary: PULL one content-addressed blob's raw bytes (history-graph-scoped; server ≥7.52).
+      description: >
+        2c session-sync PULL, S-15 epoch — one content-addressed blob's RAW bytes
+        (`application/octet-stream`). 🔴 SCOPE BOUNDARY (the security boundary — a content-addressed blob is
+        shared across sessions): the cloud serves a hash ONLY if THIS session's HISTORY GRAPH references it
+        (some tracked file version's `blobHash` in its exportHistory envelope). A foreign / unreferenced hash
+        → 404 `not_found.blob`, never a blind read; a server whose file-history store has no blob faces
+        (e.g. the local file backend) answers the SAME 404 shape (no oracle — "nothing servable" and "not
+        referenced" are deliberately indistinguishable). 400 `request.id_invalid` on a non-64-hex hash.
+        Owner-scoped (404). Replaces the retired `GET …/sync/snapshots/{key}/blobs/{hash}`.
+      responses:
+        '200':
+          description: The blob bytes.
+          content:
+            application/octet-stream:
+              schema: { type: string, format: binary }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
   /v1/sessions/{sessionId}/sync/blobs/{hash}:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -1955,7 +2146,12 @@ paths:
         body). The cloud verifies `sha256(body) === :hash` (the content-address integrity guard) BEFORE storing — a
         mismatch → 400 `blob hash mismatch`. own-or-FRESH gate. Per-blob cap 64 MiB → 413 mid-stream beyond it. A
         backend write failure (e.g. a MinIO non-2xx) → 502 `blob store write failed`. 204 on success (no body). The
-        PUSH path is the BARE `blobs/:hash` (the PULL is scoped under `snapshots/:key`).
+        PUSH path is the BARE `blobs/:hash` (the PULL is `history/blobs/:hash` since server 7.52,
+        `snapshots/:key/blobs/:hash` before). 🔴 server ≥7.52 (S-15 换店): the blob faces ride the
+        file-HISTORY store — a deployment whose store has no blob faces (the local file backend) answers 501
+        `capability.snapshot_store_required` ("blob upload requires a durable file-history store") while the
+        rest of the sync surface keeps working; on ≤7.51 the same code meant a missing snapshot store. Same
+        code, same operator disposition (wire a backend with blob faces).
       requestBody:
         required: true
         content:
@@ -2028,6 +2224,14 @@ paths:
         2c session-sync PUSH Phase A — a SMALL metadata body (`entryIds, snapshots, policy, anchors, resolution?`); the
         entries stream in Phase B. The cloud classifies (§7), pre-checks blob presence (a missing referenced hash →
         422 `missing_blob` — PUT it first), guards the import lease + any active run (409), then mints a stagingId.
+        ⚠️ S-15 EPOCH DEBT (registered 2026-08-30, codex adversarial review; migration is a SEPARATE batch):
+        server ≥7.52's Phase A actually consumes `{entryIds, fileHistory?, policy, anchors, resolution?,
+        logDigest?}` (routes/session-sync.ts) — the `snapshots` key below is SILENTLY IGNORED there (an
+        unknown body key), so on ≥7.52 a push lands entries/policy/anchors and the session itself but NO
+        file snapshots/history; the snapshot-epoch shape below is what ≤7.51 servers consume. The full
+        migration (SessionManifest/SessionBundle/push-pull orchestration + `fileHistory: FileHistoryExport |
+        null` + epoch negotiation) is tracked as its own debt — this op's schema deliberately stays the
+        ≤7.51 truth until that batch lands rather than half-changing.
         `identical` → `{ relation:"identical", basis, payloadVerified }` with NO stagingId (skip Phase B);
         `basis` is `"entry-ids+digest"` when the caller supplied a comparable digest and it matched, else
         `"entry-ids"` (id-set equality only) — see the `ImportStaged` schema, which has carried these two
@@ -2282,6 +2486,23 @@ paths:
             already terminal (someone resolved it / abandonment-TTL GC / SLA resolve-deny). Client action:
             refetch the inbox; this pending is gone. SDK → ApprovalStaleError. Note the bare CAS 409 has NO
             `errorCode`, which is exactly how the three are told apart.
+            S-02 (server ≥7.52, A-075.94③): the stale body may carry the ADDITIVE pointer key
+            `currentPending` ($ref ApprovalStaleCurrentPending — the SESSION'S current pending's D-1
+            coordinates `{toolName, boundCallId, boundInputHash?}`, same names/shapes as the §7b queue row) so
+            a shell relocates and re-decides in ONE hop instead of refetching the whole queue. NEVER carries a
+            checkpointToken. Absent when there is no pending / the gate is not a tool approval / the row read
+            failed (loud fail-open ledger arm) / an older server. Owner domain = the route's owner gate (no
+            new disclosure surface). SDK: `ApprovalStaleError.currentPending`, whole-or-absent guard.
+            REACHABILITY (codex 复审 R1-[medium] 采纳成文): the stale arm fires only for callers that ECHO a
+            `checkpointToken`; this SDK's ApprovalDecision deliberately has no such field (removed in 1.0.0 —
+            resume credentials never ride the compliant decide), so decides issued through this SDK never
+            trigger it. The key is documented for the wire contract's sake: legacy shells and non-SDK callers
+            that still echo tokens DO reach it, and the SDK's read side stays typed for whatever arrives.
+            ALSO an S-02 behavior NARROWING on this arm: an echoed `checkpointToken` that does NOT belong to
+            this session, when the session has NO pending, now folds into the byte-identical 404
+            `not_found.approval` (it used to 409 — a single-bit cross-tenant "who is parked on an approval"
+            oracle); a legitimately-owned old token (a shell retrying its own already-decided row) keeps the
+            attributable 409 + `terminal:"resolved"` verbatim.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -5024,6 +5245,27 @@ components:
             CC Rewind "code"-only (core 1.166.0 TaskSpec.rewindFilesTo). Restore the working tree to this user-message
             entryId's snapshot WITHOUT forking the conversation (no setLeafId). Use instead of resumeAt+rewindFiles when
             the user wants only files reverted. Target = a user-message SessionTreeEntry.id.
+        restoreFiles:
+          type: boolean
+          description: >-
+            S-15 epoch request key (design/381; server ≥7.52 validates boolean and passes through to core —
+            codex review R1-[medium]: `capabilities.restoreFiles` told clients to send this key while neither
+            this schema nor the SDK type could express it). With `resumeAt`: restore the TRACKED SET (files
+            this session edited) to that boundary on fork — S-15 narrowed restore whole-tree ⇒ tracked-set and
+            moved the request key off `rewindFiles` (the old `rewindFiles`+`resumeAt` spelling gets core's
+            typed migration rejection on ≥7.52). Probe `capabilities.restoreFiles` first: bit absent = older
+            server, send the old spelling; never send both spellings.
+        acceptPartialRestore:
+          type: boolean
+          description: >-
+            S-15 companion key (design/381 DV-15; server ≥7.52 validates boolean and passes through —
+            semantics owned by core's restore contract, dist typings verbatim): partial-restore consent.
+            Absent/false = when the convergence ends with ≥1 per-file refusal/failure the run fails loud
+            with the terminal `rewind.restore_failed` carrying the per-file ledger; true = the run keeps
+            going and the same ledger is disclosed as a `restore_partial` note on `TaskResult.rewindNotes`.
+            🔴 Applies to BOTH restore legs (codex R2 correction): `resumeAt`+`restoreFiles` AND the
+            code-only `rewindFilesTo` — a code-only caller omitting it gets the loud terminal too. Recovery
+            either way: re-run the same restore (per-file idempotent, converges).
         permissionMode:
           type: string
           enum: [default, plan, acceptEdits, bypassPermissions, auto]
@@ -5370,6 +5612,14 @@ components:
           description: >
             The gate kind that produced `checkpointToken` when the run suspended. Deliberately UNTYPED here —
             the shape is core's and still evolving; treat it as opaque and branch on `status`/`errorCode` instead.
+        toolCallId:
+          type: string
+          description: >
+            [4913] (server 7.41+) — the PENDING tool call's id when this result is a durable park
+            (`status` suspended/needs_review with a `tool_approval` pending action); same key and meaning as the
+            `tool_approval` frame's `toolCallId` (server >= 1.307). ABSENT (key omitted, never null) on a
+            tool-less park (resource_limit / plan_review / task_done), on every terminal result, and when the
+            server-side checkpoint read failed — consumers test presence.
         degraded:
           type: object
           description: >
@@ -6084,9 +6334,29 @@ components:
             the store but no membership authority deliberately reports false (and does not mount the routes).
         workflows: { type: boolean, description: "ENGINE-CAN: this worker's engine can orchestrate S8 self-orchestration workflows (server: `workflowsCapable ?? Boolean(workflowRunStore)`). The MOUNTING of the durable /v1/workflows read routes is the separate `workflowsList` bit below; the two coincide in today's wiring but are declared as orthogonal axes." }
         workflowsList: { type: boolean, description: "`GET /v1/workflows` list face (separate from the per-run reads)." }
+        workflowModels:
+          type: array
+          items: { type: string }
+          description: >-
+            [5673]③/[5697] (server ≥7.52): the model VOCABULARY for workflow-script `agent({modelName})` —
+            teaching face = pre-dispatch validation face, single-sourced (`workflowModelAllowlistFor`: an
+            explicit SELF_ORCHESTRATION_MODELS always wins / single-user = every catalog key / multi-tenant
+            fail-closed = []) ∩ the live per-prepare expanded catalog — every listed word passes BOTH gates,
+            and a configured-but-absent word is filtered (config mistakes surface as core rejections and ops
+            diagnostics, never as vocabulary). Empty array = honest "nothing usable here" (e.g. multi-tenant
+            with no explicit allowlist); ABSENT = an older server (degrade to not teaching, not validating).
         resumeAt: { type: boolean, description: "E18 resume-at-message anchors are resolvable." }
         rewindFiles: { type: boolean, description: "E19 working-tree snapshot/restore is wired." }
         rewindFilesTo: { type: boolean, description: "Restore to a SPECIFIC entry id (not just the latest snapshot)." }
+        restoreFiles:
+          type: boolean
+          description: >-
+            S-15 epoch discriminator (server ≥7.52, `Boolean(fileHistoryStore)`): this server understands the
+            `restoreFiles` REQUEST KEY / tracked-set restore semantics (design/381 — restore narrowed
+            whole-tree ⇒ tracked set; the retired `rewindFiles`+`resumeAt` spelling gets core's typed
+            migration rejection there). New clients negotiate on THIS bit and send `restoreFiles` (+
+            `resumeAt`); absent ⇒ an older server, send the old spelling. `rewindFiles` keeps its name (same
+            affordance — "rewind can move files"); this bit is what tells the two epochs apart.
         manualCompact: { type: boolean, description: "`POST /v1/runs/:id/compact` (needs a run store)." }
         sessions: { type: boolean, description: "Session read face (`GET /v1/sessions/:id`)." }
         sessionList: { type: boolean, description: "`GET /v1/sessions` list/picker face." }
@@ -6118,10 +6388,15 @@ components:
                 steerPriority: { type: string }
         workspace:
           description: >
-            #3 (server >=1.299): workspace-browse capability family — an OBJECT when the E19 snapshot-store
+            #3 (server 1.299–7.51): workspace-browse capability family — an OBJECT when the E19 snapshot-store
             read faces + a durable session store are wired ({browse, archive, maxFileBytes}); `false`/absent
             otherwise (same predicate as the routes' 501). `maxFileBytes` = the single-file read cap (over-cap
             ⇒ 413 workspace_file_too_large envelope; the archive endpoint is the escape hatch).
+            🔴 RETIRED (server ≥7.52, S-15/design/381): the whole-tree snapshot epoch this face projected was
+            replaced by per-edited-file rewind history, so this key is now ALWAYS false and the four
+            /v1/sessions/{sessionId}/workspace* routes answer 501 `capability.workspace_retired` (route shape
+            kept as a tombstone — a named refusal, not a 404 that reads like a typo). Consumption posture
+            unchanged: probe this bit, false ⇒ don't render the panel.
           oneOf:
             - type: boolean
               enum: [false]
@@ -6253,8 +6528,14 @@ components:
         sessionSync:
           type: boolean
           description: >
-            2c session-sync (P1d) — the `/v1/sessions/{sessionId}/sync/*` peer routes resolve (durable backend +
-            entry-export seam + a file-snapshot store wired; src/http/routes/capabilities.ts). Gate the whole sync surface off this.
+            2c session-sync (P1d) — the `/v1/sessions/{sessionId}/sync/*` peer routes resolve (server ≥7.52
+            predicate: durable backend + entry-export/import-staging seams + a file-HISTORY store wired —
+            S-15 换店; ≤7.51 the last conjunct was the file-snapshot store). Gate the whole sync surface off
+            this. ⚠️ The two BLOB faces (PUT …/sync/blobs/{hash}, GET …/sync/history/blobs/{hash})
+            additionally need the store's blob faces (`syncBlobFaces` — the SQL/cloud backends; the local
+            file backend has none): without them the PUT answers 501 `capability.snapshot_store_required`
+            and the history PULL answers the no-oracle 404 `not_found.blob`, while the REST of the sync
+            surface keeps working.
 
     SkillSpec:
       type: object
@@ -6691,6 +6972,21 @@ components:
         replayed: { type: boolean, description: 'set when this agent''s result was REPLAYED from a resume journal rather than freshly run.' }
         prompt: { type: string, description: 'what the worker was ASKED (core-redacted + bounded). UNTRUSTED display text.' }
         output: { type: string, description: 'the worker''s final OUTPUT (core-redacted + bounded). UNTRUSTED display text.' }
+        pendingApproval:
+          type: object
+          description: >-
+            S-43(案A)E 段(server ≥7.52,core 5.65 供给;[5454] 键形冻结)— the suspended approvals this leg
+            is CURRENTLY parked on. ABSENT = none pending. Three-state on purpose: absence ≠ empty array — an
+            empty array would make "this engine does not supply the seat" and "truly nothing pending" the same
+            shape. Server-side zod narrow-read projection: a drifted/half-written record omits the WHOLE key
+            rather than projecting "a pendingApproval with nothing decidable in it".
+          required: [askIds, oldestCreatedAtMs]
+          additionalProperties: false
+          properties:
+            askIds: { type: array, items: { type: string }, minItems: 1 }
+            oldestCreatedAtMs: { type: number }
+        approvalWaitedMs: { type: number, description: 'S-43(案A)same batch — CUMULATIVE ms this leg has waited on approvals (#485 timeout-typing consumer; server single-sourced, core does not self-estimate). Absent on engines predating the seat.' }
+        taskRunId: { type: string, description: '#499 (server ≥7.52, core 5.65) — the child ENGINE run identity (= the child TaskResult.runId; LAST-WINS across retries reusing the session). Named taskRunId NOT runId — in the workflow family `runId` already means the workflow run itself (core workflow-types 同名异形防撞段). Absent = stub leg / never reached prepare (additive, key not minted).' }
 
     WorkflowPhaseProgress:
       # 新(census 批2 四段):此前 `WorkflowRun.phases` 是 `items: {}`(零形状)。真形 = server
@@ -7167,12 +7463,18 @@ components:
       description: >
         FIRST frame — `{type, version, scoped, sessionScoped, bgNotifyFailClosed}` (all five UNCONDITIONAL on
         server >= 1.247). `scoped:true` ⇒ owner-scoped view; `false` ⇒ fleet-wide (operator/trace token).
+        `session` (server 7.31+, [4119] P-31 Q2): additive echo of THE session id in effect on THIS connection
+        — present iff the connection carried `?session=`. This is the connection-level zero-content
+        self-attestation bit client-core's P-31 residual family asks for ([5427]): a keyed host feeds a stream
+        into a ledger, compares this echo against the ledger's session anchor, and can trust
+        `sessionScoped`/`bgNotifyFailClosed` without content-based inference.
       required: [type, version, scoped, sessionScoped, bgNotifyFailClosed]
       properties:
         type: { const: meta }
         version: { type: integer }
         scoped: { type: boolean }
         sessionScoped: { type: boolean, description: 'true ⇒ this connection carried `?session=` (rows and notifications are filtered by the host session).' }
+        session: { type: string, description: 'server 7.31+ ([4119] P-31 Q2): the session id in effect on this connection — the verbatim `?session=` value. ABSENT when the connection is not session-bound (never minted empty). Compare against your ledger''s session anchor to close the misrouted-stream trust gap.' }
         bgNotifyFailClosed: { type: boolean, description: 'GENERATION marker — true ⇒ this server''s bg_notification injection path fails CLOSED for scoped subscribers, so a new-generation shell may drop its frame-level own/foreign checks entirely. ABSENT (older server) ⇒ keep them.' }
     FleetFrame_snapshot:
       type: object
@@ -7351,12 +7653,55 @@ components:
       description: Envelope for pending HITL checkpoints (key `pending`, NOT a bare array — the pinned wire contract).
       # 封闭(census 轴一,2026-07-30):三个铸造点(routes/approvals-assistant.ts)都只发
       # `{ pending }`。行本身(`PendingCheckpoint`)保持开集(TS 侧索引签名)。
+      # #315(server ≥7.43):第二顶层键 `livePending` = streamApproval 窗内的流内 ask(此前对轮询消费端
+      # 结构性不可见)。ADDITIVE / tolerate-absent:键缺席=「协调器未装配(本部署无 live 审批面)」或
+      # 旧 server;空数组=「有面、此刻无待批」——两义可判别,消费端测 presence。**分数组不混编**:
+      # live 行的决议口=POST /v1/tool-approvals/{approvalId}/respond,durable 行=decide 口;数组名即路由判据。
       additionalProperties: false
       required: [pending]
       properties:
         pending:
           type: array
           items: { $ref: '#/components/schemas/PendingCheckpoint' }
+        livePending:
+          type: array
+          items: { $ref: '#/components/schemas/LivePendingRow' }
+
+    LivePendingRow:
+      type: object
+      description: >-
+        A live (in-stream) pending ask inside its streamApproval window (#315, server ≥7.43). Decide it via
+        POST /v1/tool-approvals/{approvalId}/respond — NOT the /decide route (that is the durable rows' door).
+        Deliberately narrow: tool input/args are NOT listed (no second redaction surface — details ride the
+        SSE tool_approval frame). Optional flags are only-if-true (absent is NEVER encoded as false).
+      additionalProperties: false
+      required: [approvalId, toolName, ts, expiresAtMs]
+      properties:
+        approvalId: { type: string, description: 'The SAME id the respond endpoint takes (wire uuidv7).' }
+        toolName: { type: string }
+        ts: { type: number, description: 'Registration time (ms epoch).' }
+        expiresAtMs: { type: number, description: 'Absolute window deadline — the SAME number minted once for the tool_approval frame (never recomputed).' }
+        sessionId: { type: string }
+        requiresRealApproval: { type: boolean, enum: [true] }
+        governanceForced: { type: boolean, enum: [true] }
+        fromSubagent: { type: boolean, enum: [true], description: 'The ask originates from a delegated subagent.' }
+        originTaskId: { type: string, description: 'S-52 C2 (server ≥7.52, A-075.87): the delegated child taskId (= the child''s core runSourceTaskId, uuid) — correlates this live ask to the child run row. Minted by the SAME conditional spread as `fromSubagent`: the two keys are always both present or both absent (三键恒等亲证在案).' }
+
+    ApprovalStaleCurrentPending:
+      type: object
+      description: >-
+        S-02 (server ≥7.52) — the ADDITIVE pointer key `currentPending` on the decide 409 `approval_stale`
+        body: the session's CURRENT pending's three D-1 coordinates (same names/shapes as the §7b queue row),
+        so a shell relocates and re-decides in ONE hop instead of refetching the whole queue. 🔴 NEVER includes
+        a checkpointToken (resume credentials do not leave the server). Whole-or-absent: the server mints it
+        only from a pending, owner-checked tool-approval row (no pending / non-tool gate / row read failure —
+        a loud fail-open ledger arm — all omit the key).
+      required: [toolName, boundCallId]
+      additionalProperties: false
+      properties:
+        toolName: { type: string, description: 'The current pending''s gated tool (same source/value as the pending row''s toolName).' }
+        boundCallId: { type: string, description: 'The current pending''s pendingAction.toolCallId — the D-1 anchor to echo back on the relocated decide.' }
+        boundInputHash: { type: string, description: 'Server-minted; present only when the row has one. Echo verbatim, never recompute.' }
 
     ExemptionList:
       type: object
@@ -7374,14 +7719,25 @@ components:
       description: >
         The 200 body of `POST /v1/approvals/{sessionId}/decide` (census 批2 第二段, 2026-07-30 — this op's 200 was
         a bare `{type: object, additionalProperties: true}`, i.e. no field set at all for a generated consumer).
-        TWO real shapes share this envelope, discriminate on `status`:
-         · the RESUMED-TASK shape (`http/server.ts` driveResumeIntoRunLog return) — `{taskId?, sessionId, status,
+        THREE real shapes share this envelope (#316, server >= 7.37 — [4660] Inkglow: the task-level leg used to
+        drive the ENTIRE resume synchronously before responding, so its 200 took a full model round-trip with no
+        upper bound; it now answers at the ACCEPTANCE point instead):
+         · the TASK-LEVEL ACCEPTANCE shape (server >= 7.37, the DEFAULT on durable deployments;
+           `http/server.ts` driveResumeIntoRunLog acceptance point) — `{taskId, sessionId, status:"resuming",
+           bindingEnforced:true}`. Emitted AFTER every rejection-capable step has settled (lease 429, markResuming
+           CAS 409, core pre-CAS guards + atomic CAS — those still reject synchronously); only the model leg runs
+           on after the response. Follow the run via poll/SSE (`GET /v1/runs/:id` / `/events`) — `errorCode` /
+           `errorMessage` / `retriable` NEVER ride this shape, failures land on the run row and its stream.
+         · the RESUMED-TASK TERMINAL shape (pre-7.37 servers on every decide; >= 7.37 ONLY on deployments with no
+           durable run row to follow — there the leg honestly stays synchronous) — `{taskId?, sessionId, status,
            errorCode?, errorMessage?, retriable?}`, plus `rememberApplied` when the request carried
            `remember:"session"` AND the worker has an exemption store;
          · the PARKED-BACKGROUND-AGENT shape (`parked-decide.ts`, server >=1.267) — `{taskId, status:"resuming",
            decision}`, an ACCEPTED (not completed) receipt; the revive drives asynchronously.
-        `status` is the only key BOTH shapes guarantee: `taskId` rides `getActiveTaskId` on the resumed leg (omitted
-        when there is no active row) and `sessionId` is absent from the parked shape.
+        `status` is the only key ALL shapes guarantee. ⚠️ `status === "resuming"` alone no longer discriminates
+        the parked shape: branch on `decision` (parked receipt only) vs `sessionId`/`bindingEnforced` (task-level
+        acceptance only). `taskId` rides `getActiveTaskId` on the terminal leg (omitted when there is no active
+        row) and `sessionId` is absent from the parked shape.
       required: [status]
       additionalProperties: false
       properties:
@@ -7397,8 +7753,9 @@ components:
         status:
           type: string
           description: >
-            OPEN string — do NOT narrow. Resumed leg: the run's resulting status (`completed`/`failed`/`suspended`/
-            `needs_review`). Parked leg: the literal `resuming` (= accepted, revive in flight).
+            OPEN string — do NOT narrow. Task-level acceptance (server >= 7.37): the literal `resuming` (= accepted,
+            resume in flight — follow the run stream). Terminal leg: the run's resulting status (`completed`/`failed`/
+            `suspended`/`needs_review`). Parked leg: the literal `resuming` (= accepted, revive in flight).
         decision:
           type: string
           enum: [approve, deny]
@@ -8257,6 +8614,7 @@ components:
         - $ref: '#/components/schemas/Event_status'
         - $ref: '#/components/schemas/Event_task_progress'
         - $ref: '#/components/schemas/Event_workspace_changed'
+        - $ref: '#/components/schemas/Event_engine_notice'
         - $ref: '#/components/schemas/Event_suspended'
         # 🔴 以下 6 臂是 2026-07-25 补的:`events.ts` 的 `AgentEvent` 联合有 21 个 `type` 字面量,本文件此前只声明
         #   15 个 —— 照本文件生成客户端的消费方会把 6 种合法帧当成非法值(事件面是最吃重的 wire 面,这个缺口比
@@ -8313,6 +8671,7 @@ components:
           status: '#/components/schemas/Event_status'
           task_progress: '#/components/schemas/Event_task_progress'
           workspace_changed: '#/components/schemas/Event_workspace_changed'
+          engine_notice: '#/components/schemas/Event_engine_notice'
           suspended: '#/components/schemas/Event_suspended'
           file_link: '#/components/schemas/Event_file_link'
           prompt_assembled: '#/components/schemas/Event_prompt_assembled'
@@ -8619,9 +8978,18 @@ components:
       required: [type, phase]
       properties:
         type: { const: status }
-        phase: { type: string, description: "rate_limited | retrying | reconnecting | circuit_open (open set)" }
+        # 🔴 A-057.27:6 员(此前只列 4,漏 recovered/gave_up 两个**终局**值 —— 一段重试序列恒恰一终局帧,
+        # 两者对渲染方是同一句话「把重试行撤下来」)。闭集声明、开集读。
+        phase: { type: string, description: "rate_limited | retrying | reconnecting | circuit_open | recovered | gave_up (closed in core, read as open set)" }
         detail: { type: string, description: "neutral human hint (NO provider/HTTP detail)" }
         retryInSec: { type: number }
+        # 🔴 A-057.26:以下四键 server 真在发(builder brainStatusEventData,三腿共享),而本 schema 是
+        # `additionalProperties: false` ⇒ 不声明 = 一个**合法**的真帧会被严格校验器判违约(假红),正是本仓
+        # 元门(封闭 schema 必须镜像分支键)要防的那一形。缺席不铸键,故一律 optional。
+        attempt: { type: number, description: "1-based index of the attempt that just FAILED (this wait precedes attempt+1)" }
+        maxRetries: { type: number, description: "retry budget of the lane in force (refused-connect short lane = 2)" }
+        retryInMs: { type: number, description: "same number as retryInSec at ms precision (countdown rendering)" }
+        errClass: { type: string, description: "connect_refused | transport | rate_limit | server | http | output_cap — retry-wait frames ONLY; never inferred from phase" }
         eventId: { type: string }
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
@@ -8846,6 +9214,36 @@ components:
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
+    Event_engine_notice:
+      type: object
+      description: >
+        server >= 7.36 (#310, board [4630]) — an engine STRUCTURED NOTICE judged to be for THIS SESSION'S end user,
+        routed to the session's event projection by `sessionId`. Present on BOTH legs (live SSE and the durable
+        ledger replayed by `GET /v1/runs/:id/events`) — reconnect replay shows it again, so consume idempotently
+        (same discipline as `workspace_changed`).
+        RENDER BY `code` + `detail`; `message` is a FALLBACK ONLY (core states that `memory.session_polluted`'s
+        message varies with the memoryProvenance mode — matching on message text WILL break). `code` is an OPEN
+        set (the server whitelist grows with core's code register): render a known code specially, fall back to
+        `message` for an unknown one — never drop the frame.
+        Starter whitelist (server 7.36): `memory.session_polluted` `{reason, sessionId?}` ·
+        `memory.harvest_quarantined` `{count, moved, escalated, reason?}` — `moved` and `escalated` MUST NOT be
+        subtracted from each other (an in-place tombstone counts as both) · `memory.delegation_static_mark_waived`
+        `{reason, subagentType?, sessionId?}`.
+        A notice whose `detail.sessionId` is absent is HONESTLY NOT DELIVERED (the server never guesses a session),
+        so the frame's absence does NOT mean "did not happen" — the operator-facing structured log always has the
+        full family. `detail` is already redacted + size-bounded by the server; still treat it as external text.
+      additionalProperties: false
+      required: [type, code, message, detail, sessionId, ts]
+      properties:
+        type: { const: engine_notice }
+        code: { type: string, description: 'Stable dot-namespaced machine code. OPEN set — never drop an unknown one.' }
+        message: { type: string, description: 'Core-minted human line. FALLBACK DISPLAY ONLY, never a match key.' }
+        detail:
+          type: object
+          additionalProperties: true
+          description: 'Machine-readable facts (per code). Redacted + bounded server-side; open set of keys.'
+        sessionId: { type: string, description: 'Owning session — this frame only ever appears on that session stream.' }
+        ts: { type: integer, format: int64, description: 'SERVER observation time (ms epoch), NOT the engine mint time.' }
     Event_workspace_changed:
       type: object
       description: >
@@ -9508,6 +9906,12 @@ components:
         fromSubagent: { type: boolean, enum: [true], description: 'Present ⇔ the ask comes from a DELEGATED child — the explicit discriminator (a worker cannot forge it).' }
         sourceTaskId: { type: string, description: 'The child''s core session id — row-join value + fallback discriminator.' }
         sourceAgentName: { type: string, description: 'The child agent''s display name, redacted. UNTRUSTED.' }
+        # A-057.④(#314):三键 server 早已随卡投出(与 tool_approval 帧同一窄读函数 ⇒ 帧与 card 同值),
+        # 但本 schema 只在帧上公示过 —— 按 spec 生成的卡消费方拿不到。定义与帧上同构段逐字同源,
+        # 长 description 不复制(单一真源在 ToolApprovalFrame 的同名键)。
+        inputHasBidi: { type: boolean, enum: [true], description: 'server >= 7.45.0 (E-14): the TO-BE-EXECUTED input (redacted args, computed BEFORE the byte cap) contains Unicode bidi override characters — what the eye reads may not be the byte order that runs. DISCLOSURE bit, bytes unchanged; rendering (escape/highlight) is the shell''s. Present (true) or ABSENT; absence != "verified clean" (not detected / serialization failed / older server).' }
+        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' }
 
     RuleSuggestion:
@@ -9973,6 +10377,23 @@ components:
         activeTaskStatus:
           type: string
           description: '`running` | `suspended` | `needs_review` — best-effort (absent when the store lookup degraded).'
+        msSinceLastActivity:
+          type: number
+          description: >
+            (#245 S1, server >= 7.18 — 既存违例回填 2026-08-20: server has been emitting this on the done frame
+            since the key landed on the 409 body; the CLOSED schema here just never declared it, so every real
+            frame carrying it "violated" spec. Same key, same semantics as the 409 body.) Milliseconds since the
+            occupying run's last recorded activity — the ONLY liveness-evidence bit on this frame (same-replica
+            best-effort). Absent = no evidence, NOT "fresh"; never narrow absence to 0.
+        stale:
+          const: true
+          description: >
+            (#316(c), server >= 7.37; [4664]② hole (c)) The occupying run row looks DEAD by the same staleness
+            criterion the poll face (`GET /v1/runs/:id`) uses to fold a terminal status — heartbeat silence past
+            the reap window. This frame does NOT fold the status (`activeTaskStatus` stays verbatim, the reaper
+            owns the transition); the bit lets a shell reconcile "conflict says running / poll says failed"
+            inside the self-heal window. ADDITIVE, present ONLY as `true`; absent = no staleness evidence (parked
+            rows are out of reap scope and never carry it — absence is NOT "alive").
         pendingGate:
           allOf: [{ $ref: '#/components/schemas/PendingGateMaterial' }]
           description: >
@@ -10889,6 +11310,40 @@ components:
         priority: { $ref: '#/components/schemas/SteerPriority' }
         note: { type: string, description: 'Human-readable note on the two parked legs; absent on `applied`.' }
 
+    InterruptReceipt:
+      description: >
+        The POST /v1/runs/{taskId}/interrupt 202 receipt — TWO mutually exclusive shapes (oneOf, discriminated
+        by which arm's keys are present, NOT by status code; both are 202 — codex 复审 R1-[medium]:单对象全
+        可选形会让 `{taskId,status}` 与混臂形都合法,生成式消费方靠不住判别键). TEXT form (cut + steer):
+        `delivery:"queued-immediate"` + `messageId` (≡ the engine inputId — correlate with the run stream's
+        `task.turn_interrupted` `detail.inputId`; acceptance = enqueued, the cut itself is best-effort).
+        BARE (halt) form: `turnCut` and deliberately NO delivery/messageId (no input frame exists to correlate
+        — A-075.78 成文;halt's acceptance is NOT a queue insert, so the receipt can honestly answer whether
+        THIS call cut a live turn). `status` = the run row's word as the server read it at acceptance. Honest
+        window: a halt racing the run's natural last moments reports the natural completion, still carrying
+        the haltedByUser seat.
+      # 封闭两臂:两个铸造点都是逐字面量拼出的对象(server routes/runs.ts interrupt 段),不是引擎透传形。
+      oneOf:
+        - type: object
+          description: TEXT form (cut + steer) — the run continues.
+          required: [taskId, status, delivery, messageId]
+          additionalProperties: false
+          properties:
+            taskId: { type: string }
+            status: { type: string, description: 'The run status the server saw at acceptance time.' }
+            delivery: { type: string, enum: [queued-immediate] }
+            messageId: { type: string, description: '≡ the engine inputId (with an Idempotency-Key: `idem-<sha256[:32]>`; without one: a fresh uuidv7, minted and threaded down PER REQUEST — unlike steer''s absent arm, which lets core mint).' }
+            note: { type: string, description: 'Contract note (逐句照 core 契约,不多许诺一个字).' }
+        - type: object
+          description: BARE (halt) form (cut + stop) — the run closes at this boundary.
+          required: [taskId, status, turnCut]
+          additionalProperties: false
+          properties:
+            taskId: { type: string }
+            status: { type: string, description: 'The run status the server saw at acceptance time.' }
+            turnCut: { type: boolean, description: 'true ⇔ THIS call cut a live turn; repeat calls answer false once the stop is latched (halt is naturally idempotent).' }
+            note: { type: string, description: 'Contract note (逐句照 core 契约,不多许诺一个字).' }
+
     SubagentSteerReceipt:
       type: object
       description: >
@@ -11619,7 +12074,7 @@ components:
       required: [rule, scope]
       properties:
         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: 1088, 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.' }
+        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.' }
         principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant revoke. Absent (or your own principal) = revoke your own rule.' }
 
     RuleRevokeResult: