@sema-agent/sdk 19.0.0 → 20.0.0

package/openapi.yaml

@@ -87,7 +87,9 @@ info:
         browser guard refuses to hold this in a browser; the portal's browser talks to its own BFF) and
         `x-agent-principal: <principal>` (REQUIRED; opaque to the service; principal-first, CORE-PRINCIPLES §3).
       • Submit-class POSTs (`/v1/tasks`, `/v1/runs`) carry an `Idempotency-Key` (the SDK auto-generates one;
-        in-process dedupe window = 15 min; cross-replica hard-dedupe = the session-active 409, see §below).
+        server <= 7.124.x: in-process dedupe window = 15 min; cross-replica hard-dedupe = the session-active 409, see §below.
+        server >= 7.125.0: the key is a unique key on the RUN ROW — a same-key resubmit reads that row and answers from it, across
+        replicas and restarts; the process only merges concurrent in-flight duplicates. `GET /v1/runs?idempotencyKey=` reads what a key built).
       • New contract fields are OPTIONAL with no default (CORE-PRINCIPLES §6).
       • Async results are delivered by POLL (`GET /v1/runs/:id`) or SSE (`/v1/runs/:id/events`).
         There is NO generic webhook/callback and NO signing (SERVICE-CORE-CONTEXT §2.4).
@@ -427,6 +429,12 @@ paths:
         `verify` / `cascade` run's earlier tier already ran turns and only the last tier is refused, the SAME code arrives
         as 200 with a failed body (`terminal.code`; billed; a same-key resend replays). Multi-tier callers must read both
         forms. On a park the 200 body is the result itself plus the three poll-receipt keys (`SyncSubmitResult`, S-173).
+        🔴 IDEMPOTENT REPLAY (server >= 7.125.0, contract §0.7): a same-key resubmit that finds the run row the key already built (another process, another
+        replica, a restart, or an original request that has since settled) does NOT run again and does NOT answer the first answer's engine-result shape —
+        it answers `200` with that run's READ FACE (`GET /v1/runs/{taskId}`) plus `replay: true` (`RunReplayRecord`). Branch on `replay === true`; the outcome is
+        in `result` (a nested `TaskResult`), and `wiringManifest` / `notice` are absent. A same-key duplicate that is still IN FLIGHT in the same process is merged
+        instead and gets the first answer's bytes (no `replay` key). Only a submit that builds a row can be replayed this way (a run store AND a `sessionId`);
+        otherwise a settled key re-runs. A key whose row the caller cannot read answers 409 `conflict.run_exists`.
       parameters:
         - $ref: '#/components/parameters/IdempotencyKey'
       requestBody:
@@ -437,13 +445,17 @@ paths:
       responses:
         '200':
           description: >-
-            The task result (`SyncSubmitResult`): the sealed + redacted engine result; on a park (`terminal.kind:"paused"`)
+            One of two shapes, told apart by the `replay` key. (1) The task result (`SyncSubmitResult`): the sealed + redacted engine result; on a park (`terminal.kind:"paused"`)
             it additionally carries the poll receipt `{taskId, sessionId, status}` with `status` ∈ {suspended, needs_review}
             (server >= 7.104.0 / S-173 — before that a park answered ONLY those three keys). Terminal bodies carry no `status`
             on >= 7.64; a server <= 7.63 answers the flat form instead (terminal word in `status`, no `terminal`) — see SyncSubmitResult.
+            (2) server >= 7.125.0, same-key replay: the existing run's read face with `replay: true` (`RunReplayRecord`) — NOT an engine result.
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/SyncSubmitResult' }
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/SyncSubmitResult'
+                  - $ref: '#/components/schemas/RunReplayRecord'
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403': { $ref: '#/components/responses/Forbidden' } # (declared 2026-08-01) 带 `sessionId` 复用他人会话:归属不匹配 ⇒ 403(自公开快照起点即有,spec 此前漏登记)。server 3.15.0 起多一个触发条件:多租部署上 session store 无归属判别能力时,复用**任何** caller 自报的 sessionId 都 403(含本 worker 自己刚铸的 —— 无 register seam 时归属从未被记下)。core 2.11.0 起默认内存店自带该能力 ⇒ 该触发条件在默认部署上不再出现。 ⚠️ (declared 2026-08-05,server >=7.0.0)`memory.admission_denied` 也走本状态 —— 本状态的 producer 全清单与分支判据写在 `Forbidden` 组件的 description 里(**那段是被解析的**,本行注释只是指路,不复述以免两处漂移)。
@@ -467,6 +479,10 @@ paths:
             deployment has NO file-history store but the request asks to restore files; the request is well-formed, the
             deployment shape conflicts with it (change the deployment, not the request; `capabilities.rewindFiles` is false
             there). Before 7.104.0 it arrived as 200 with a failed body.
+            `conflict.run_exists` (server >= 7.125.0, contract §0.7): the submit's `Idempotency-Key` (or `body.taskId`) already points at a run row you cannot read,
+            or at a row that is not the one this submit's `taskId` names. The sentence is `a run already exists for this submission's taskId or Idempotency-Key`
+            (the code is unchanged; only the sentence moved); nothing about the row is echoed (no cross-tenant oracle). Submit under a NEW key. On
+            `POST /v1/tasks/stream`, once the stream is open the same refusal arrives as the `done` frame's `{status:"failed", errorCode, errorMessage}`.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -653,6 +669,53 @@ paths:
         '429': { $ref: '#/components/responses/RateLimited' }
         '501': { $ref: '#/components/responses/NotImplemented' }
         '503': { $ref: '#/components/responses/Unauthorized' }
+    get:
+      tags: [runs]
+      operationId: runsGetByIdempotencyKey
+      x-status: live
+      summary: Read the run an `Idempotency-Key` built (look before you re-submit).
+      description: >
+        server >= 7.125.0 (contract §0.7). Answers "which run did this submit key build?" for a client that crashed or lost the connection
+        after a submit and must decide whether to submit again. `idempotencyKey` is the RAW value the submit was sent with; the server scopes
+        it exactly as the submit did (your verified identity × resource family `run` — `POST /v1/tasks`, `/v1/tasks/stream`, `/v1/runs` and A2A
+        `message/send` all share family `run`, so a key used on any of them is found here). Another caller's key resolves to a different key and
+        reads as the same 404, byte-for-byte (no existence oracle). 200 = the same read face as `GET /v1/runs/{taskId}` (`RunRecord`), and the gates
+        run in the same order: 501 no run store → 401 → read row → owner gate → `?session=` assertion. A submit that never built a row leaves
+        nothing to find (404): no run store, or a `POST /v1/tasks` / `/v1/tasks/stream` submit without `sessionId` (those legs build a row only
+        with both), and a zero-work refusal (the key is released). NOT a submit: no billing, no admission gates.
+      parameters:
+        - in: query
+          name: idempotencyKey
+          required: true
+          schema: { type: string, minLength: 1 }
+          description: 'The RAW `Idempotency-Key` the submit carried (the server applies the scope; send it unhashed and unmodified). Missing or empty ⇒ 400 `request.query_invalid`.'
+        - in: query
+          name: session
+          required: false
+          schema: { type: string }
+          description: >-
+            The session assertion `GET /v1/runs/{taskId}` honors: for a session-bound run a non-operator caller sends the conversation's `sessionId` here;
+            a mismatch answers the same 404 as an unknown key.
+      responses:
+        '200':
+          description: The run row's read face — byte-for-byte what `GET /v1/runs/{taskId}` returns for that run. NO `replay` marker (that is only on a submit's replay body).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RunRecord' }
+        '400':
+          description: 'errorCode `request.query_invalid` — `idempotencyKey` is missing or empty. (Unlike `GET /v1/leader?idempotencyKey=`, no key-shape check: the key is only hashed here.)'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          description: >-
+            errorCode `not_found.run` — this key (under your identity) built no run row, or the row is not yours, or `?session=` mismatched. One
+            code, one sentence, for every cause: absence of the key is not distinguishable from another caller's run.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
 
   /v1/runs/{taskId}:
     parameters:
@@ -1777,6 +1840,48 @@ paths:
                 properties:
                   error: { type: string }
                   total: { type: integer, description: 'present on the out-of-range `?message=` 404 — the message count available.' }
+    patch:
+      tags: [sessions]
+      operationId: sessionsPatch
+      x-status: live             # server >= 7.125.0 (contract section 20).
+      summary: Rename and/or pin a session (the session row's two writable bits).
+      description: >
+        server >= 7.125.0 (contract section 20) — write the session row's two writable bits: `title` (rename, or `null` = clear back to the
+        automatic title) and `pinned`. ONE COLUMN, ONE FACT: `title` is a single column with two writers under one law — the user writes it through
+        this verb UNCONDITIONALLY (a string renames; `null` clears the column back to NULL); the service's auto-titler fills it ONLY when it is
+        NULL (read once per submit). So a session the user named is never overwritten by the auto-titler, and after a clear the next submit has
+        the auto-titler fill it again. There is no second column. `pinned` is one boolean column (default `false`).
+        `200` is the session's LIST ROW — the same projection as the matching row of `GET /v1/sessions`, key for key (including the derivation of
+        `tempo` and the always-present `pinned`). Renaming / pinning does NOT move `lastActivityAt` (the list's recency order is unchanged).
+        PROBE: there is no capability bit; probe by status code — `405` (`Allow` without `PATCH`, `errorCode: method_not_allowed`) = an older server (<= 7.124.x);
+        `501 capability.session_store_required` = this deployment has no durable session store (the in-memory dev store has no row read / write face).
+        Same gate as `GET /v1/sessions/{sessionId}`, same order: store fact (501) -> ownership (the SAME predicate as the session-view read — whoever can read
+        the row can write it, never wider; an operator / service token gets no extra reach; a stranger and "no such session" answer byte-identical
+        `404 not_found.session`, no existence oracle) -> body (400) -> the store's one write door -> read back and answer with the list row.
+        Only rows on the LIST face are writable: a placed (delegation-transcript) session is not in the list, so a PATCH on it answers 404.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SessionPatchBody' }
+      responses:
+        '200':
+          description: The session's list row (same projection as the matching `GET /v1/sessions` row, key for key).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionSummary' }
+        '400':
+          description: >-
+            Malformed body, told apart by `errorCode` (branch on the code, never the sentence). `request.body_shape` — not a JSON object / empty body /
+            a key outside the closed set `{ title, pinned }` / `title: ""` (the only spelling of "clear" is `null`). `request.field_invalid` — `title`
+            neither a string nor `null`, longer than 120 characters, or with leading / trailing whitespace; `pinned` not a boolean. Invalid JSON answers
+            like every other JSON-body route (`request.invalid_json`). The row is untouched on any 400.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
     delete:
       tags: [sessions]
       operationId: sessionsDelete
@@ -1810,7 +1915,9 @@ paths:
                   deleted: { type: boolean }
         '400':
           # (declared 2026-07-31) errorCode "request.id_invalid" — the path sessionId must decode to a
-          # well-formed uuidv7 (`routes/sessions.ts`); a malformed id never reaches the store.
+          # canonical uuid of ANY version (`routes/sessions.ts`; server >= 7.125.0 — the ONE shape gate shared with sync / fork / policy;
+          # <= 7.124.x accepted only uuidv7 here); a malformed id never reaches the store. Branch on the code, never the sentence
+          # (the sentence changed with the gate: "invalid session id (must be a canonical uuid)").
           $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -1845,8 +1952,9 @@ paths:
       summary: Branch a NEW session off this one's whole history.
       description: >
         E17 (shell-host) — branch a fresh session off the source's WHOLE history (a "branch this conversation" /
-        regenerate-from-here). Owner-scoped (non-owner → 404; the fork is owned by the caller). 400 on a non-uuidv7
-        id. 501 without a durable session store.
+        regenerate-from-here). Owner-scoped (non-owner → 404; the fork is owned by the caller). 400 `request.id_invalid` on an id that is not
+        a canonical uuid — ANY uuid version passes since server >= 7.125.0 (the ONE shape gate shared with sync / policy / delete; <= 7.124.x accepted only
+        uuidv7 here, so a shell-preset v4 id was creatable and syncable but not forkable). 501 without a durable session store.
       responses:
         '200':
           description: The new branched session id.
@@ -2364,7 +2472,7 @@ paths:
                   rules: { $ref: '#/components/schemas/StoredSessionRules' }
         '400':
           # (declared 2026-07-31) errorCode "request.id_invalid" — GET and PUT share the SAME id-shape check
-          # in `routes/sessions.ts` (uuidv7 required) ahead of the method branch; only PUT had this declared.
+          # in `routes/sessions.ts` (a canonical uuid of any version since server >= 7.125.0; uuidv7 only on <= 7.124.x) ahead of the method branch; only PUT had this declared.
           $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -2845,8 +2953,8 @@ paths:
         lacks. Owner-scoped (non-owner → 404, no oracle); 400 on an id that is not uuid-SHAPED — 🔴 the sync family's
         gate is `isUuidShape` (ANY uuid version), NOT `isUuidV7`: server `routes/session-sync.ts` deliberately
         keeps a v4-keyed legacy shell session pushable (it was creatable via the lenient submit face), while
-        crafted-id classes stay shut out. `fork`/`delete`/`policy` DO use `isUuidV7` — only this family is lenient;
-        501 without a durable session store.
+        crafted-id classes stay shut out. Since server >= 7.125.0 `fork` / `delete` / `policy` read the SAME one gate (any canonical uuid version);
+        <= 7.124.x those three used `isUuidV7` and only this family was lenient. 501 without a durable session store.
       responses:
         '200':
           description: The manifest, wrapped as `{ manifest }`.
@@ -3111,6 +3219,14 @@ paths:
                   description: 'server >= 7.52: the file-history envelope (replaces `snapshots`); `null` / absent = none. Every blob it references must already be PUT.'
                 policy: { type: array, items: { $ref: '#/components/schemas/SessionRulesRecord' } }
                 anchors: { type: array, items: { $ref: '#/components/schemas/SyncAnchor' } }
+                title:
+                  type: [string, 'null']
+                  description: >
+                    server >= 7.125.0 (contract section 20): the session row's title from the manifest. Judged by the SAME reader as `PATCH /v1/sessions/{sessionId}` cell by cell
+                    (a string 1..120 characters with no leading / trailing whitespace; `""` is `400 request.body_shape`; a non-string-non-null / too long / whitespace-edged value is
+                    `400 request.field_invalid`) BEFORE any staging is opened, so a refused push leaves nothing behind. `null` CLEARS the destination back to the automatic title. After the
+                    commit (and on the `identical` short-circuit arm) the keys that were sent are replayed through the store's one write door. KEY NOT SENT = the destination's two bits stay (older callers).
+                pinned: { type: boolean, description: 'server >= 7.125.0 (contract section 20): the session row''s pin from the manifest; judged by the PATCH reader (non-boolean is `400 request.field_invalid`); not sent = the destination''s pin stays.' }
                 resolution: { type: string, enum: [overwrite-dst], description: Override a fork/stale loss-of-history conflict. }
                 logDigest:
                   type: string
@@ -4779,6 +4895,45 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+    get:
+      tags: [leader]
+      operationId: leaderGetByIdempotencyKey
+      x-status: gated
+      summary: Read the leader run an `Idempotency-Key` built (look before you re-submit).
+      description: >
+        server >= 7.125.0 (contract §0.7). Same shape as `GET /v1/runs?idempotencyKey=` for family `leader`: `idempotencyKey` is the RAW key the
+        `POST /v1/leader` carried; the server scopes it by your verified identity exactly as the submit did. 200 = the same read face as
+        `GET /v1/leader/{leaderRunId}` (`LeaderRecord`). A key that built no leader run, and a run that is not yours, are the SAME 404 (no existence
+        oracle). A leader key is a different key from a run key even with the same raw text (resource families do not cross). Not a submit: no billing, no admission gates.
+        The leader face being absent on the deployment is the same 501 `capability.leader_endpoint_required` as the other leader verbs.
+      parameters:
+        - in: query
+          name: idempotencyKey
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 255 }
+          description: 'The RAW `Idempotency-Key` the `POST /v1/leader` carried (1–255 characters, no leading or trailing whitespace — the submit-header rule). Missing, or a malformed shape ⇒ 400 `request.query_invalid`.'
+      responses:
+        '200':
+          description: The leader run's read face — what `GET /v1/leader/{leaderRunId}` returns for that run.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/LeaderRecord' }
+        '400':
+          description: 'errorCode `request.query_invalid` — `idempotencyKey` is missing, or not a well-formed key (empty / over 255 characters / leading or trailing whitespace).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          description: 'errorCode `not_found.leader_run` — this key (under your identity) built no leader run, or the run is not yours. Same code and sentence for both.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501':
+          description: 'errorCode `capability.leader_endpoint_required` — no leader face on this deployment (the same refusal the other leader verbs give).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/leader/{leaderRunId}:
     parameters:
@@ -6669,8 +6824,11 @@ components:
       required: false
       schema: { type: string }
       description: >
-        Submit-class dedupe key (the SDK auto-generates a UUID → retries are safe by default). In-process window
-        = 15 min (per-instance). A submit is retried by the SDK ONLY when a key exists.
+        Submit-class dedupe key (the SDK auto-generates a UUID → retries are safe by default). server <= 7.124.x: in-process window
+        = 15 min (per-instance). server >= 7.125.0: the key is a unique key on the run row (scope = identity bit (the verified principal, else the credential family) × resource family × raw key,
+        families `run` / `leader` / `bake`; the endpoint is NOT part of the scope, so `POST /v1/tasks`, `/v1/tasks/stream`, `/v1/runs` and A2A
+        `message/send` share family `run`), valid across replicas and restarts for the run's retention; only concurrent in-flight duplicates are
+        merged in process. A submit is retried by the SDK ONLY when a key exists.
     LastEventId:
       in: header
       name: Last-Event-ID
@@ -6772,6 +6930,9 @@ components:
         does NOT silently resolve it to that run: `activeTaskId` may be the caller's own first attempt OR an
         unrelated concurrent run on the same session — 409 alone cannot tell (the pinned wire contract Q6). Only triggers when
         a `sessionId` is present.
+        server >= 7.125.0 also: `conflict.run_exists` — on a submit (`POST /v1/runs`, `/v1/tasks`, `/v1/tasks/stream`), the `Idempotency-Key` /
+        `body.taskId` points at a run the caller cannot read, or the two keys of one submit point at different rows. The sentence is
+        `a run already exists for this submission's taskId or Idempotency-Key` (code unchanged, sentence new; nothing echoed). Submit again under a new key.
       content:
         application/json:
           schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -7027,13 +7188,15 @@ components:
           type: string
           description: >-
             [2400] TR-16 (declared 2026-08-02) — CALLER-MINTED uuidv7 task id: the DURABLE second tier of
-            idempotency on POST /v1/runs (`src/http/routes/runs.ts`). The `Idempotency-Key` header's
+            idempotency on POST /v1/runs (`src/http/routes/runs.ts`). On server <= 7.124.x the `Idempotency-Key` header's
             cache is in-memory and PER-POD, so a dispatch gateway that re-routes a retry to ANOTHER instance
             after a network error would start a SECOND run; THIS replay reads the durable run store, so it
             survives the re-route and a restart — it is the prerequisite for gateway failover. A hit replays the
             original 202 receipt (`{taskId, sessionId, status}`); nothing re-runs, nothing re-bills.
             Shape-gated: a non-uuidv7 value is 400 `request.id_invalid`. Owner-gated: a taskId owned by another
             principal answers 409 `conflict.run_exists` (no cross-tenant id oracle). Omit ⇒ the server mints one.
+            server >= 7.125.0: `Idempotency-Key` is ALSO a unique key on the run row (contract §0.7), so the two are two keys to one row. Sent together
+            they must point at the same row; a key that points at a row this `taskId` does not name is 409 `conflict.run_exists`.
         scenario: { $ref: '#/components/schemas/Scenario' }
         sessionId:
           type: string
@@ -8221,6 +8384,37 @@ components:
         toolCallId: { type: string }
         retryAfterMs: { type: integer }
 
+    RunReplayRecord:
+      description: >
+        server >= 7.125.0 (contract §0.7). The idempotent-REPLAY body of a submit whose `Idempotency-Key` had already built a run row: `RunRecord` (the
+        `GET /v1/runs/{taskId}` read face, same projection) plus `replay: true`. It answers `POST /v1/tasks` (200) and is the `done.result` of
+        `POST /v1/tasks/stream`. 🔴 IT IS NOT A `TaskResult`: a synchronous first answer carries the engine result at the top level (`terminal`, `stats`, `result` as a
+        string); a replay has only the row, so `result` is the NESTED `TaskResult` (or absent while the run has no result), there is no top-level `terminal` / `stats`, and
+        `wiringManifest` / `notice` are absent (the wiring receipt is a live capture that is not stored on the row). `taskId` is the row's id — on the stream leg, when the
+        replay is discovered only after the stream opened (another replica created the row first), the `x-task-id` header and `meta` frame carried an id this leg minted
+        and never created: the id in this body is the real one. Narrow on `replay === true` (the two shapes cannot both match). A same-key duplicate still IN FLIGHT in the same
+        process is merged instead and gets the first answer's bytes with no `replay` key.
+      allOf:
+        - $ref: '#/components/schemas/RunRecord'
+        - type: object
+          required: [replay]
+
+    SubmitRefusalDoneResult:
+      type: object
+      description: >
+        The `done.result` of a submit REFUSED after the SSE stream was already open (`POST /v1/tasks/stream`): the status line is gone, so the refusal travels as the
+        stream's terminal frame in the triple `{status:"failed", errorCode, errorMessage}` — the same code and sentence the JSON refusal body would have carried
+        (server `src/http/routes/tasks.ts`). Two producers: (1) server >= 7.125.0 — the submit's key (or `body.taskId`) turned out, only at row-creation time, to point at a run row
+        the caller cannot read or that is not the one this submit names: `errorCode: "conflict.run_exists"` (contract §0.7; the frame carries `replay: true`); (2) a device-placement
+        refusal (the placement error body's code and sentence). It is NOT an engine result and NOT `ActiveRunConflictDoneResult` (that one is `conflict.session_active_run` and requires
+        `activeTaskId`). Branch on `errorCode`; the sentence is for people.
+      additionalProperties: false
+      required: [status, errorCode, errorMessage]
+      properties:
+        status: { const: failed }
+        errorCode: { type: string, description: 'Open string: `conflict.run_exists` (server >= 7.125.0) or the device-placement refusal code.' }
+        errorMessage: { type: string, description: 'The refusal sentence (display only — never match on it).' }
+
     RunReceipt:
       type: object
       # 封闭(census 轴一,2026-07-30):producer 铸造点 routes/runs.ts 与 idem 重放臂各自逐字写死
@@ -8249,6 +8443,25 @@ components:
           description: 'v1 sole value, the same word as settings-schema `SEALED_BOX_ALG`; another alg is a loud per-model refusal.'
         publicKeyId: { type: string, description: 'Goes into `sealedApiKey.publicKeyId` (server default mint `exec-<first 12 hex of sha256(raw public key)>`; treat as opaque); the engine opens with EXACTLY this key.' }
         publicKey: { type: string, description: 'STANDARD base64 of the 32-byte X25519 public key (44 chars). Public — safe to log.' }
+    WorkspaceSyncCapability:
+      type: object
+      description: >
+        server >= 7.125.0 (contract appendix B.1 / B.1a) — the `GET /v1/capabilities` `workspaceSync` segment: EXACTLY two keys, key-for-key the server's `src/workspace-space.ts`
+        `WorkspaceSyncCapability`. Both are ALWAYS-PRESENT members of the object (B.1a); the object itself is present-iff (see `Capabilities.workspaceSync`).
+      additionalProperties: false
+      required: [persist, keep]
+      properties:
+        persist:
+          type: string
+          enum: [space, off]
+          description: >
+            The operator knob `WORKSPACE_PERSIST` (default `off` — persistence is opt-in), a TWO-WORD closed set. `space` = the operator switched it on: the k8s `/workspace` persists across runs per session occupant. `off` = the snapshot
+            store IS wired but persistence is not switched on (the default, or the operator switched it off): a fresh workspace every run — NOT the same as the whole object being absent (absent = no such facility on this deployment).
+        keep:
+          type: integer
+          minimum: 1
+          maximum: 50
+          description: 'Snapshots kept per space (the session occupant) (`WORKSPACE_SNAPSHOT_KEEP`, an integer in [1, 50], default 3); older ones are deleted after each successful save.'
     StoreCapability:
       type: object
       description: >
@@ -8413,6 +8626,13 @@ components:
         taskId: { type: string }
         sessionId: { type: string }
         status: { $ref: '#/components/schemas/RunStatus' }
+        replay:
+          const: true
+          description: >
+            server >= 7.125.0 (additive; contract §0.7). Present ONLY on the IDEMPOTENT-REPLAY body of a submit — `POST /v1/tasks` 200, and the same body as
+            `done.result` on `POST /v1/tasks/stream` (see `RunReplayRecord`) — where it is always `true`: the submit's key had already built this run row, so the
+            answer is the row's read face plus this marker, NOT the first answer's engine result. ABSENT on `GET /v1/runs/{taskId}` and
+            `GET /v1/runs?idempotencyKey=` (those are the read face itself) and never `false`. Branch on `replay === true`; the outcome is in `result`.
         msSinceLastActivity:
           type: integer
           description: >
@@ -8741,6 +8961,13 @@ components:
         usedMicroUsd: { type: integer }
         limitMicroUsd: { type: integer }
         retryAfterSec: { type: integer }
+        windowResetsAt:
+          type: string
+          format: date-time
+          description: >
+            server >= 7.125.0 (additive). The end of the current quota window (ISO 8601) — the same instant `GET /v1/usage` reports as
+            `UsageInfo.windowResetsAt`. `retryAfterSec` and the `Retry-After` header stay as they were and share its clock read.
+            Absent = an older server.
 
     TraceTurn:
       type: object
@@ -9909,6 +10136,10 @@ components:
             (`DB_BACKEND=memory`, multi-tenant bare boot) this bit is now false and the card and the RPC both answer 404 (7.115.x:
             true, card 200, every `message/send` / `tasks/get` a JSON-RPC `-32004`); the startup log carries a warn
             `a2a_serve_not_served`. The old "the server deliberately does not fold the run store into this bit" note is retired.
+            server >= 7.125.0 (contract §0.7): an A2A `message/send` shares the submit idempotency scope with the HTTP submits (family `run`; the key is derived from the
+            message's `messageId`, its content, `contextId` and skill id, and scoped by the caller identity) — a repeat that finds the existing run answers that task's protocol object immediately (it never enters the
+            `blocking` wait), and a hit the caller cannot read, or that names a different run, is a JSON-RPC `-32602` (Invalid params) error, the same refusal the HTTP
+            faces give as 409 `conflict.run_exists`.
         agentRoster:
           type: boolean
           description: >
@@ -10075,6 +10306,20 @@ components:
             do NOT seal — use `apiKeyEnv`, or fix the custody directory and restart. Absent is a missing key, never `null`.
             🔴 ONE STORE PER HOST (`<data root>/sealed-key/`): replicas that do not share that directory answer different
             keys, and a ciphertext sealed against replica A's key is `stale_ciphertext` on replica B.
+        workspaceSync:
+          allOf: [{ $ref: '#/components/schemas/WorkspaceSyncCapability' }]
+          description: >
+            server >= 7.125.0 (contract appendix B.1 / B.1a) — WORKSPACE KEPT ACROSS RUNS: the k8s lane's `/workspace` is stored in object storage per session OCCUPANT (the session incarnation: delete the session and re-register the same id = a NEW space, starting from an empty directory). Each run's end
+            snapshots the workspace into `<prefix>/<incarnation>/space/` (a sub-prefix this lane owns; the park-suspend snapshots live outside it and are never pruned), moves the `space/latest` pointer and keeps only
+            the newest `keep`; the next run's start (when it connects the sandbox) restores from `latest`. A replica that cannot read the session occupant neither restores nor saves for that run (an operator line) and does NOT fall back to the session id.
+            A shell / center renders "work files kept across turns" only when `persist` is `"space"` (the default is `off`; persistence is opt-in).
+            🔴 PRESENT-IFF — one of the three per-key exceptions on this surface (with `sealedKey` and `centerWiring`, contract appendix B.1): the facility = the k8s lane AND a snapshot store (the three
+            `MINIO_*` keys). ABSENT is a missing key, never `false` / `null` / `{}`, and means one of TWO things with the SAME action: an older server (< 7.125.0, does not know this bit), or a deployment that
+            is not the k8s lane / has no snapshot store (the same body's `version` tells them apart) — either way do NOT promise "last run's files are still there"; treat each run's workspace as an empty directory.
+            `persist: "off"` means the store is present and the capability is present but nothing is retained today (the default, or the operator switched it off) — different from absent. Covers `/workspace` only (process / memory state does not cross runs).
+            FAILURE IS LOUD: failing to read `latest` or the commit marker, a `latest` that points at a missing snapshot object, or a restore that fails midway fails THAT run's sandbox connect (never a silent empty
+            directory; a partial directory is not handed to tools and is not snapshotted back); a failed end-of-run snapshot puts the residual key `workspaceSnapshot: "failed"` on the fleet terminal `task` frame
+            (`FleetTaskRow.workspaceSnapshot`), and the next run restores the PREVIOUS `latest`.
         background:
           type: object
           additionalProperties: true
@@ -11322,15 +11567,23 @@ components:
         Per-principal cost/quota snapshot (GET /v1/usage; shape audited from source). Computed from
         the REQUEST principal. When no quota window is configured → enabled=false + ONLY windowSec/maxTask*
         (the amount/limit fields are ABSENT) — render must tolerate the gap.
+        server >= 7.125.0: an `enabled:true` body ALWAYS carries `windowResetsAt` (the end of the current quota window),
+        zero spend and the limit-0 switched-off sentinel included; an `enabled:false` body is unchanged and has no such key.
       # 🔴 封闭 + required 补铸造点(census 批2 第二段,2026-07-30)。两条腿都是逐字字面量
       # (`routes/observability.ts` —— 无配额臂 4 键 / 有配额臂 11 键),11 个属性就是并集。
+      # server 7.125.0:有配额臂 +`windowResetsAt` = 12 键,并集 12 个属性(无配额臂 4 键不变)。
       # required 从 `[enabled]` 抬到四键:`windowSec`/`maxTaskCostUsd`/`maxTaskTokens` 在**两条腿上都**
       # 无条件发送(config 直读),只列 `enabled` 是把恒在键写成了可缺 —— 消费方因此得写永远为真的判空。
       required: [enabled, windowSec, maxTaskCostUsd, maxTaskTokens]
       additionalProperties: false
       properties:
         enabled: { type: boolean, description: 'A cost-quota WINDOW is configured (false ⇒ single-task ceilings only).' }
-        windowSec: { type: integer, description: 'Rolling quota window seconds (e.g. 86400 = daily).' }
+        windowSec:
+          type: integer
+          description: >
+            Quota window length in seconds (e.g. 86400 = daily). server >= 7.125.0: on EVERY deployment the window is a
+            clock-aligned bucket (bucket number = `floor(now / windowSec)`, a daily window rolls at UTC midnight) — not a window that
+            starts at the principal's first spend and not a sliding one; read the roll instant from `windowResetsAt`.
         usedMicroUsd: { type: integer, description: 'Spent in the current window (micro-USD = 1e-6 USD).' }
         usedUsd: { type: number, description: 'Spent in the current window (USD; convenience projection).' }
         limitMicroUsd: { type: integer, description: 'Window quota ceiling (micro-USD).' }
@@ -11338,6 +11591,15 @@ components:
         remainingMicroUsd: { type: integer, description: 'Window remaining (limit - used, floored at 0).' }
         overLimit: { type: boolean, description: 'Window quota exceeded (new tasks blocked until retryAfterSec).' }
         retryAfterSec: { type: integer, description: 'Suggested wait when overLimit.' }
+        windowResetsAt:
+          type: string
+          format: date-time
+          description: >
+            server >= 7.125.0 (additive). The END of the current quota window (ISO 8601) — the instant the clock-aligned bucket rolls
+            over and `usedMicroUsd` starts again from zero. ALWAYS present when `enabled` is true (the window is a clock-aligned bucket,
+            so a zero-spend principal and the limit-0 switched-off sentinel report it too — the window length is a configured fact); ABSENT
+            when `enabled` is false. ABSENT on an `enabled:true` body = an older server, NOT "the window does not roll". The same instant rides
+            the 429 `limit.cost_quota_exceeded` body (`QuotaError.windowResetsAt`), derived from the same clock read as `retryAfterSec`.
         maxTaskCostUsd: { type: number, description: 'Single-task cost hard ceiling (USD; independent of the window, always present).' }
         maxTaskTokens: { type: integer, description: 'Single-task token hard ceiling (independent of the window).' }
 
@@ -12007,6 +12269,17 @@ components:
             workflow `wa*` agent, and the TOP-LEVEL run row — has no generation concept at all. Absent means "no
             such concept", NOT "generation 1"; a consumer that reads absence as 1 will misread a late first frame
             as a revive.
+        workspaceSnapshot:
+          type: string
+          enum: [failed]
+          description: >
+            server >= 7.125.0 (contract appendix H.3b), ADDITIVE / tolerate-absent, a TERMINAL top-level run frame's residual key (`completed` / `failed` / `killed`; a parked frame NEVER carries it).
+            Has a source only while the k8s lane keeps the workspace across runs (`capabilities.workspaceSync.persist: "space"`). A SINGLE-MEMBER CLOSED SET, the one word `failed`:
+            the workspace snapshot at the end of THIS run was NOT saved (the upload failed, or the `latest` pointer write failed). The pod is deleted anyway; `latest` still points at the previous snapshot, so the next
+            run of the same session restores the PREVIOUS one and this run's changes to `/workspace` are lost. Render "this turn's work files were not saved" — NOT as a run failure (`status` is still the run's own
+            terminal state). ABSENT = saved / persistence off / not the k8s lane / the run never touched a sandbox / an older server / OR the save took longer than the engine's 15-second teardown bound and its outcome
+            arrived after the terminal frame — so absence must NEVER be read as "definitely saved": it only says "no failure to report". Source: the save outcome the server notes before the engine hands back its result
+            (keyed by the run's session id), reported once. ONLY the outcome that settled before THIS run's terminal frame is carried: one that settles after the teardown bound stays an operator log line and is never attached to the NEXT run's terminal frame of the same session. The `?session=` scoped (unattributed-row) projection keeps this key (a structural fact, zero conversation content).
         retiredBy:
           # 🔴 NO `enum` (codex R1-F3, verified): the description below REQUIRES open-on-read, and the SDK type is
           # open (`"reconcile" | (string & {})`). A closed enum would make a strict generated client reject a
@@ -13154,8 +13427,36 @@ components:
                   taskId: { type: string, description: The later run on whose first beat the notice was emitted. }
         messages:
           type: array
+          description: >
+            The engine's message rows (opaque here; their shapes are the engine's). server >= 7.125.0 (contract section 20): the ONE key the server adds itself is the
+            rewind handle `taskId` on a `role: "user"` row — the `taskId` of the run that submitted that prompt, to be handed to `resumeAt` (rewind =
+            the existing `POST /v1/runs` / `POST /v1/tasks` with `{ sessionId, resumeAt: <taskId> }`, no new verb). It rides EVERY way of fetching the rows (whole read /
+            `tail` / `before` / `blobCap` / `?message=N`). PRESENT-IFF the anchor store holds EXACTLY ONE row for that user entry whose owner is the reader (the same
+            predicate `resumeAt` resolves with, so a handle on a row always resolves). ABSENT = no such anchor: an older entry (anchors are written only from the point
+            they were introduced; no backfill), an anchor owned by someone else (mixed-owner session), the same entry named by two anchor rows (not picked), or a prompt
+            submitted through the non-streaming `POST /v1/tasks` (only the durable legs — `POST /v1/runs`, `POST /v1/tasks/stream`, the resume leg — write user-message
+            anchors; resuming at that run's `taskId` is 404 `resume_at.unknown_event`, the same fact as the key being absent). A later user message (steer) inside one run
+            moves that run's anchor to the last-submitted one, so the handle appears on that row. assistant / toolResult / other-role rows never carry it. The value is a
+            server-minted identifier, verbatim (not redacted). Older servers (<= 7.124.x) never emit it.
           items: {}
 
+    SessionUserMessageRow:
+      type: object
+      description: >
+        The `role: "user"` arm of a `SessionRecord.messages` row — the NARROWING TARGET for reading the rewind handle (server >= 7.125.0, contract section 20). `messages` rows are the
+        engine's own shapes and stay open/opaque; the only key the server itself adds is `taskId` on a user row. OPEN object: every other key is the engine's.
+      required: [role]
+      additionalProperties: true
+      properties:
+        role: { const: user }
+        taskId:
+          type: string
+          description: >
+            The rewind handle: the `taskId` of the run that submitted this prompt, handed to `resumeAt` (`POST /v1/runs` / `POST /v1/tasks` with `{ sessionId, resumeAt: <taskId> }`).
+            PRESENT-IFF the anchor store holds EXACTLY ONE row for this user entry owned by the reader — the same predicate `resumeAt` resolves with, so a handle on a row always
+            resolves. ABSENT = an older entry (no backfill) / an anchor owned by someone else / the same entry named by two anchor rows / a prompt submitted through the non-streaming
+            `POST /v1/tasks` (no anchor is written there; resuming at that run's `taskId` is 404 `resume_at.unknown_event`) / an older server (<= 7.124.x). A server-minted identifier, verbatim.
+
     SessionSummary:
       type: object
       description: >
@@ -13186,6 +13487,9 @@ components:
             Auto-generated session summary title (service-side `session-titler`: one cheap model call kicked off in
             the background after the first submit, idempotent via an IS-NULL gate). Genuinely `null` until it lands,
             so render a fallback rather than waiting on it.
+            server >= 7.125.0 (contract section 20): ONE column with TWO writers — the user's string (`PATCH /v1/sessions/{sessionId}`, unconditional;
+            `null` clears it back) wins, otherwise the auto-titler's (fills ONLY a NULL column), otherwise `null`. So read it as "the user's title, else the
+            automatic one, else null" — a reader that took it as "always the automatic title" must change. <= 7.124.x: only the auto-titler writes it.
         tempo:
           type: string
           enum: [active, idle, blocked]
@@ -13193,6 +13497,32 @@ components:
             server ≥7.91.0 (additive, absent on older servers): the session's activity word, derived from its most
             recent run's status by the ONE mapping table the peer directory also reads (running → active;
             suspended / needs_review → blocked; no non-terminal run → idle).
+        pinned:
+          type: boolean
+          description: >
+            server >= 7.125.0 (contract section 20): the user's pin (written by `PATCH /v1/sessions/{sessionId}`), default `false`. ALWAYS present on
+            >= 7.125.0 (a session's state, not a capability — NOT present-iff); a lister face with no session metadata (the in-memory run-store
+            aggregate) always answers `false`. ABSENT = an older server (<= 7.124.x) — read as "not pinned". Not in `required` for that reason only.
+            The list order is unchanged (recency by `lastActivityAt`); the client groups the pinned section. Renaming / pinning does not move `lastActivityAt`.
+
+    SessionPatchBody:
+      type: object
+      description: >
+        `PATCH /v1/sessions/{sessionId}` body (server >= 7.125.0, contract section 20) — a CLOSED set of two keys, at least one: any other key, an empty body or a
+        non-object is `400 request.body_shape`. `title`: a string renames (1..120 CHARACTERS counted as Unicode characters = the storage column width, no leading /
+        trailing whitespace, stored verbatim — not rewritten, not redacted); `null` CLEARS it back to the automatic title (the next submit lets the auto-titler fill
+        it again). `""` is NOT a clear — it is `400 request.body_shape`. A string of the wrong form / a non-string-non-null `title` / a non-boolean `pinned` is
+        `400 request.field_invalid`.
+      additionalProperties: false
+      minProperties: 1
+      properties:
+        title:
+          type: [string, 'null']
+          minLength: 1
+          maxLength: 120
+          pattern: '^\S([\s\S]*\S)?$'
+          description: 'A string = rename (1..120 characters, no leading / trailing whitespace); `null` = clear back to the automatic title; `""` is a 400 (the only spelling of "clear" is `null`).'
+        pinned: { type: boolean, description: 'The pin (default `false` on a row that never set it).' }
 
     SessionWindow:
       type: object
@@ -13220,7 +13550,7 @@ components:
           type: ['string', 'null']
           description: 'the compaction floor this index is relative to, when one applies.'
         index: { type: integer, description: 'the requested message index (echoed).' }
-        message: { description: 'OPEN — the message payload as stored; shape belongs to the transcript format, not to this envelope.' }
+        message: { description: 'OPEN — the message payload as stored; shape belongs to the transcript format, not to this envelope. server >= 7.125.0: a `role: "user"` message carries the same present-iff rewind handle `taskId` as on the whole-record read (see `SessionRecord.messages`).' }
 
     PromptEpoch:
       type: object
@@ -13645,13 +13975,15 @@ components:
         snapshot: entry IDS (oldest-first, NOT payloads) + the file-history envelope + policy + anchors + leaf.
         🔴 server >= 7.52 (S-15, design/381; re-read byte for byte against 7.116.0): the key `snapshots` (per-snapshot
         relPath→blobHash, the retired E19 whole-tree snapshot epoch) is NO LONGER SENT — the server's `exportSessionManifest` mints
-        `{ sessionId, entryIds, entryCount, leafId, fileHistory, policy, anchors }` and `fileHistory` (core's versioned
+        `{ sessionId, entryIds, entryCount, leafId, fileHistory, policy, anchors }` (server >= 7.125.0 adds the session row's two writable bits `title` / `pinned`,
+        present-iff the session is a row of the list face — see the two properties) and `fileHistory` (core's versioned
         `FileHistoryExport` envelope; `null` = no history / the source store cannot export) replaces it. <= 7.51 servers still send
         `snapshots` and no `fileHistory`. The blob BYTES never ride the manifest: content-addressed, via the history blob faces
         (`GET …/sync/history/blobs/{hash}` / `PUT …/sync/blobs/{hash}`; probe `capabilities.sessionSyncFileHistory` on BOTH ends).
         The SDK's `manifest()` fills `snapshots: []` when the wire omits it.
       # 封闭(census 批2 第三段,2026-07-30;16.2.0 按 7.116.0 发布字节重核):铸造点 `session-sync.ts`(exportSessionManifest 尾部
       # 字面量)恰是 `{ sessionId, entryIds, entryCount, leafId, fileHistory, policy, anchors }` 7 键(≥7.52),无 `snapshots`;
+      # server ≥7.125.0 另有 `title` / `pinned` 两键(会话行可写位,present-iff 会话是列表面上的行;条件展开,不进 required);
       # ≤7.51 老 server 发 `snapshots`、无 `fileHistory` ⇒ 两键都不进 required(支持底线 3.0.0)。
       additionalProperties: false
       required: [sessionId, entryIds, entryCount, leafId, policy, anchors]
@@ -13668,6 +14000,15 @@ components:
           description: 'server >= 7.52: the per-edited-file rewind history envelope; `null` = no history / the source store cannot export; key ABSENT = a <= 7.51 server (that generation sends `snapshots`).'
         policy: { type: array, items: { $ref: '#/components/schemas/SessionRulesRecord' } }
         anchors: { type: array, items: { $ref: '#/components/schemas/SyncAnchor' } }
+        title:
+          type: [string, 'null']
+          description: >
+            server >= 7.125.0 (contract section 20): the session row's title, read through the LIST ROW's one projection (the same value as `SessionSummary.title`: the
+            user's string, else the auto-titler's). `null` = no title — and a PUSH that replays it (`sync/import` Phase A `title: null`) CLEARS the destination back to the
+            automatic title, the same law as `PATCH`. PRESENT-IFF the session is a row of the list face (every ordinary session; a placed delegation-transcript
+            session has no writable row bits, so BOTH keys are absent there). ABSENT also = an older server (<= 7.124.x). Not part of the `basis` / `payloadVerified` judgement
+            (those two speak only for the conversation log).
+        pinned: { type: boolean, description: 'server >= 7.125.0 (contract section 20): the session row''s pin (same value as `SessionSummary.pinned`; present-iff exactly as `title` above).' }
 
     FileHistoryExport:
       type: object
@@ -17892,12 +18233,18 @@ components:
     Event_done:
       type: object
       description: >
-        The stream's terminal frame. `result` is a DISCRIMINATED UNION of TWO real shapes (契约调和车1 E,
+        The stream's terminal frame. `result` is a DISCRIMINATED UNION of real shapes (契约调和车1 E,
         2026-08-02) — do NOT assume the full TaskResult:
          · `TaskResult` — the normal terminal (output string at `.result`, stats at `.stats`), service Drift 4;
          · `ActiveRunConflictDoneResult` — the SSE lane's REJECTION terminal: when the session already has an
            active run, the submit's 409 is encoded as this done frame (`src/http/routes/tasks.ts`), and it
-           carries NO `taskId` / `sessionId` / `stats`.
+           carries NO `taskId` / `sessionId` / `stats`;
+         · `RunReplayRecord` (server >= 7.125.0, contract §0.7) — the IDEMPOTENT-REPLAY terminal of `POST /v1/tasks/stream`: the submit's key had already built a run row, so
+           `result` is that row's read face plus `replay: true` — NOT an engine result (no top-level `terminal` / `stats`; the outcome is the nested `result`). The frame carries
+           `replay: true` as well. (A same-key duplicate still in flight in the same process is merged instead: the frame has `replay: true` but `result` is the first answer's
+           `TaskResult` verbatim — so the FRAME's `replay` does not tell the shapes apart; `result.replay` does.)
+         · `SubmitRefusalDoneResult` — a submit refused after the stream was already open, as `{status:"failed", errorCode, errorMessage}` (server >= 7.125.0: `conflict.run_exists` when
+           the replay is discovered at row-creation time and the caller cannot read that row; also the device-placement refusal). Not an engine result; carries no `taskId` / `stats`.
         Narrow in TWO steps: `stats` present (an engine result) vs absent (the conflict envelope) — or match
         `errorCode === "conflict.session_active_run"` — and then, among the engine results, `"terminal" in result`
         (the current cause form) vs absent (`LegacyPlaneTaskResult`, the flat bytes an older generation left in
@@ -17916,14 +18263,17 @@ components:
             - $ref: '#/components/schemas/TaskResult'
             - $ref: '#/components/schemas/ActiveRunConflictDoneResult'
             - $ref: '#/components/schemas/LegacyPlaneTaskResult'
+            - $ref: '#/components/schemas/RunReplayRecord'
+            - $ref: '#/components/schemas/SubmitRefusalDoneResult'
         replay:
           type: boolean
           description: >
             契约调和车1 F(2026-08-02;server `src/http/routes/tasks.ts` 的两处铸造点)— `true`
             marks the IDEMPOTENT-REPLAY leg: this terminal was NOT produced by a live run of your submit. Either
-            the `Idempotency-Key` hit the in-flight/settled cache, or your call was deduplicated into a
-            concurrent identical submit and received no live events at all. The `result` is the original
-            run's terminal, verbatim. ABSENT on every live leg (never `false`) — a UI can use it to say "replayed"
+            your call was deduplicated into a concurrent identical submit still in flight in the same process (then `result` is the original
+            run's terminal, verbatim, and you received no live events at all), or — server >= 7.125.0 — the `Idempotency-Key` had already built a run
+            row and `result` is that row's read face plus `replay: true` (`RunReplayRecord`; NOT an engine result). The frame's flag does not
+            tell the two apart; `result.replay === true` does. ABSENT on every live leg (never `false`) — a UI can use it to say "replayed"
             instead of implying the work just ran twice.
 
     ActiveRunConflictDoneResult: