@sema-agent/sdk 4.2.0 → 5.0.0

package/openapi.yaml

@@ -1286,9 +1286,10 @@ paths:
           description: Delivered onto the live stream.
           content:
             application/json:
+              # 封闭(census 批2 第三段,2026-07-30):live 臂铸造点 `routes/notify-wake.ts:98` 是两键字面量。
+              # 4.3.0:形提成具名 `SessionNotifyResult` 的 live 臂(SDK 同批给了判别联合返回型)。
               schema:
                 type: object
-                # 封闭(census 批2 第三段,2026-07-30):live 臂铸造点 `routes/notify-wake.ts:86` 是两键字面量。
                 additionalProperties: false
                 required: [sessionId, delivery]
                 properties:
@@ -1298,9 +1299,9 @@ paths:
           description: No live stream — parked in the session inbox, drained on the next stream open.
           content:
             application/json:
+              # 封闭 + note 补 required:parked 臂铸造点 `routes/notify-wake.ts:116` 是三键字面量,note 无条件。
               schema:
                 type: object
-                # 封闭 + note 补 required:parked 臂铸造点 `routes/notify-wake.ts:104` 是三键字面量,note 无条件。
                 additionalProperties: false
                 required: [sessionId, delivery, note]
                 properties:
@@ -1395,26 +1396,11 @@ paths:
           description: The snapshot listing.
           content:
             application/json:
-              schema:
-                type: object
-                # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:621-626`(信封)与
-                # `:616`(行)。条件键=信封 `latest`(零快照即省略)、行 `bytes`(blobSizes 面缺席=诚实省略)。
-                additionalProperties: false
-                required: [sessionId, snapshots, total]
-                properties:
-                  sessionId: { type: string }
-                  snapshots:
-                    type: array
-                    items:
-                      type: object
-                      additionalProperties: false
-                      required: [key, files]
-                      properties:
-                        key: { type: string }
-                        files: { type: integer }
-                        bytes: { type: integer }
-                  latest: { type: string }
-                  total: { type: integer }
+              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:624-629`(信封)与
+              # `:620`(行)。条件键=信封 `latest`(零快照即省略)、行 `bytes`(blobSizes 面缺席=诚实省略)。
+              # 4.3.0:形提成具名 `WorkspaceSnapshotPage`(SDK 同批把返回位的内联字面量也提成了 exported type,
+              # 让 spec-resource-schema-gate 罩得住 —— CAPS-OPS-8)。
+              schema: { $ref: '#/components/schemas/WorkspaceSnapshotPage' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -1455,27 +1441,10 @@ paths:
           description: One page of the tree.
           content:
             application/json:
-              schema:
-                type: object
-                # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:648-654`(信封)与
-                # `:651`(行)。条件键=信封 `nextOffset`(尾页省略)、行 `size`(blobSizes 面缺席省略)。
-                additionalProperties: false
-                required: [sessionId, key, entries, total]
-                properties:
-                  sessionId: { type: string }
-                  key: { type: string }
-                  entries:
-                    type: array
-                    items:
-                      type: object
-                      additionalProperties: false
-                      required: [path, hash]
-                      properties:
-                        path: { type: string }
-                        hash: { type: string }
-                        size: { type: integer }
-                  total: { type: integer }
-                  nextOffset: { type: integer }
+              # 封闭两层(census 批2 第三段,2026-07-30):铸造点 `routes/sessions.ts:651-657`(信封)与
+              # `:654`(行)。条件键=信封 `nextOffset`(尾页省略)、行 `size`(blobSizes 面缺席省略)。
+              # 4.3.0:形提成具名 `WorkspaceTreePage`(理由同 list 腿 —— CAPS-OPS-8)。
+              schema: { $ref: '#/components/schemas/WorkspaceTreePage' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -1696,7 +1665,11 @@ paths:
         2c session-sync PULL — the THIN snapshot: entry IDS (oldest-first, NOT payloads — those stream via
         `/sync/entries`) + per-snapshot relPath→blobHash + policy + anchors + leaf. The local peer feeds `entryIds`
         to the §7 classifier to decide fast-forward/fork BEFORE pulling the entry stream + only the blob hashes it
-        lacks. Owner-scoped (non-owner → 404, no oracle); 400 on a non-uuidv7 id; 501 without a durable session store.
+        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:135-138` 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.
       responses:
         '200':
           description: The manifest, wrapped as `{ manifest }`.
@@ -1739,7 +1712,7 @@ paths:
         at 200 BEFORE the first line, so a mid-stream failure ends the body WITHOUT the trailer — the trailer's
         ABSENCE (or a count mismatch) is the SOLE truncation signal (NO 5xx mid-stream). The SDK reader throws
         `SyncTruncatedError` on a missing trailer / count mismatch. Owner-scoped (404); 400 on a bad afterSeq /
-        non-uuidv7 id; 501 without a durable entry-streaming store.
+        non-uuid-SHAPED id (ANY uuid version passes — see the manifest leg); 501 without a durable entry-streaming store.
       responses:
         '200':
           description: The NDJSON entry stream (begin / entry× N / end-trailer).
@@ -1844,7 +1817,8 @@ paths:
       description: >
         2c session-sync PLAN — classify the §7 relation between the LOCAL peer's `entryIds` (oldest-first, the SOURCE)
         and the cloud's current log (the DST), WITHOUT writing. Returns the `SyncRelation` (`fresh` for a fresh cloud
-        session). own-or-FRESH gate; 400 on a non-string-array body / non-uuidv7 id. Unlike import, plan NEVER 409s —
+        session). own-or-FRESH gate; 400 on a non-string-array body / a non-uuid-SHAPED id (ANY uuid version passes —
+        see the manifest leg). Unlike import, plan NEVER 409s —
         a fork/stale is REPORTED in the relation, not raised.
       requestBody:
         required: true
@@ -1901,6 +1875,20 @@ paths:
                 policy: { type: array, items: { $ref: '#/components/schemas/SessionRulesRecord' } }
                 anchors: { type: array, items: { $ref: '#/components/schemas/SyncAnchor' } }
                 resolution: { type: string, enum: [overwrite-dst], description: Override a fork/stale loss-of-history conflict. }
+                logDigest:
+                  type: string
+                  description: >
+                    🔴 OPTIONAL content digest of the SOURCE's whole entry log (core `sessionLogDigest`, scheme
+                    `sema-log-v3`; this leg's core floor is ^1.416.0). Server producer/consumer:
+                    `routes/session-sync.ts:295,310,357-366`. This is THE key that makes `ImportStaged.payloadVerified:true`
+                    reachable — until 4.3.0 the response schema promised a `payloadVerified`/`entry-ids+digest` pair
+                    that the request side had no way to trigger. Rationale: `identical` is classified from entry-id
+                    SETS only, and an entry id is a uuidv7 (NOT content-addressed), so "same ids, different payloads"
+                    is structurally possible and would be reported as already-synced. Supply this and the server
+                    recomputes the digest over its own log: equal ⇒ `basis:"entry-ids+digest"` + `payloadVerified:true`;
+                    different or not comparable ⇒ it does NOT short-circuit and stages a full sync (safe direction).
+                    A malformed value is NOT rejected — it is treated as absent (a digest mismatch must never become
+                    an error, a 409, or a refusal to sync).
       responses:
         '200':
           description: Staged (or `identical` no-op).
@@ -3013,7 +3001,12 @@ paths:
         per-row delta for every transition. Frame order: `event: meta` `{version, scoped}` → `event: snapshot`
         `{tasks, workflows, ts}` → then `event: task`/`event: workflow` UPSERTS (each `data: {row, ts}` is the
         POST-MERGE FULL row — replace by `row.id`, NOT a sparse patch) + `event: task_remove`/`event:
-        workflow_remove` `{id, ts}` departures. Heartbeat `: hb` comment frames keep the connection alive.
+        workflow_remove` `{id, ts}` departures.
+        🔴 Keep-alive is a REAL NAMED FRAME — `event: heartbeat` + `data: {}` every 15 s
+        (`src/http/routes/fleet.ts:223`), NOT an SSE `: hb` comment (the旁注 says why: a per-frame-parsing BFF
+        drops comments, so downstream saw a zero-frame window). Do NOT implement the reader as "skip lines
+        starting with `:`" — swallow the heartbeat BY NAME. (Corrected 2026-08-02; the `: hb` shape belongs to
+        `GET /v1/sessions/{sessionId}/events` alone, and beats at a tunable ~25 s.)
         🔴 OWNER-SCOPED by the credential-derived principal (NOT a spoofable header) UNLESS fleet-wide (an operator
         / deployment trace token sees every tenant's rows). The row `scope` is WIRE-STRIPPED after the owner-gate —
         it never appears on a row; the `meta.scoped` flag tells the consumer which view this is (true = owner-scoped).
@@ -4244,6 +4237,30 @@ components:
           description: Per-task sub-agent definitions (roster additions scoped to this task only).
         interactiveTools: { type: boolean, description: Mount interactive (prompting) tools. }
         retainBackgroundProcesses: { type: boolean, description: Keep background processes alive past the turn. }
+        forwardSubagentEvents:
+          type: boolean
+          description: >
+            🔴 PER-TASK opt-in for forwarding subagent CONTENT onto the parent's event stream (server
+            `src/http/wire-types.ts:157`, consumed at `boot/resolve-spec.ts:557` — read STRICTLY as `=== true`).
+            ⚠️ The capability bit of the same name says "this body key is ACCEPTED", NOT "forwarding is on":
+            it is hard-coded true, while forwarding itself is OFF unless this key is sent. Without it the parent
+            stream carries progress-only frames and a subagent-transcript view stays empty forever.
+            (Declared 2026-08-02 — the capability bit had been registered here since 3.x, the request key never was.)
+        retainSubagentSessions:
+          oneOf:
+            - type: boolean
+            - type: object
+              additionalProperties: false
+              properties:
+                ttlMs: { type: integer, description: 'Retention window; server CLAMPS to ≤ 24 h (task-workflow.ts:77-83).' }
+                max: { type: integer, description: 'Retained session count; server CLAMPS to ≤ 64.' }
+          description: >
+            🔴 PER-TASK opt-in to RETAIN finished subagent sessions so they can be resumed (server
+            `src/http/wire-types.ts:169`, normalized at `boot/resolve-spec.ts:564`). This is the OTHER HALF of
+            `POST /v1/runs/{runId}/subagents/{handle}/resume`: the capability bit `subagentResume` can be true and
+            the route mounted, and the call still 409s `resume.retain_off` — retention is per-run and OFF by default.
+            An over-large ask is CLAMPED, not rejected. (Declared 2026-08-02; the error code and the capability bit
+            were both already documented, only the knob that turns retention on was missing.)
         excludeTools:
           type: array
           items: { type: string }
@@ -4990,25 +5007,8 @@ components:
         scheduler: { type: boolean, description: "Assistant-scheduler face is mounted." }
         sendUserFile: { type: boolean, description: "Outbound user-file delivery is wired." }
         sendUserFileLedger: { type: boolean, description: "The send-file ledger (audit of deliveries) is available." }
-        excludeTools:
-          type: array
-          items: { type: string }
-          description: >
-            ⚠️ PHANTOM KEY — NEVER emitted by any server version (契约调和车1 H①, 2026-08-02: verified against
-            every casting site in `src/http/routes/capabilities.ts`). It is a **TaskRequest** field (submit-body
-            validation `src/http/server.ts:1358`, TaskSpec mapping `src/boot/resolve-spec.ts:588`) that was
-            mis-registered on the capability face. Reading it always yields absent. Kept (removing it is a
-            breaking change) — SCHEDULED FOR REMOVAL IN THE NEXT MAJOR.
-            Semantics, for the archive: roster TRUE-UNMOUNT — the named tools' schema bytes never reach the
-            model and the assembly manifest narrows honestly; tighten-only, unioned into every child spawn.
-        deferTools:
-          type: array
-          items: { type: string }
-          description: >
-            ⚠️ PHANTOM KEY — NEVER emitted by any server version; same mis-registration as `excludeTools`, and
-            the real thing is the **TaskRequest** field of this name. SCHEDULED FOR REMOVAL IN THE NEXT MAJOR.
-            Semantics, for the archive: DEFERRED DISCLOSURE — the named MOUNTED tools ride the wire as a
-            placeholder (schema bytes out of the cache prefix) and materialize via ToolSearch on demand.
+        # [2400] CAPS-OPS-1(5.0.0):excludeTools/deferTools 两幻影属性已删——server 从不在能力面发;
+        # 真身=TaskRequest 同名字段(本 spec TaskRequest 节登记的那两条是对的)。
         s3PublicEndpoint:
           type: ["string", "null"]
           description: >
@@ -5654,6 +5654,42 @@ components:
         result: { type: string }
         seq: { type: integer, minimum: 1 }
         source: { type: string, maxLength: 190 }
+    SessionNotifyResult:
+      # 4.3.0(SM-9):把 notify 的两态提成**具名** schema —— 此前只有 path 内联的两个匿名 200/202 形,
+      # SDK 侧的返回型则是裸 `Record<string, unknown>`,`delivery` 这条承重语义(已送达 vs 排队)在类型面
+      # 整个丢失。铸造点 `routes/notify-wake.ts:98`(live)/ `:116`(parked),两臂都是字面量。
+      description: >
+        POST /v1/sessions/{sessionId}/notify 的判别联合。分支 `delivery`:`live` = 会话有活流、通知已送达
+        (HTTP 200);`parked` = 无活流,排队到下次开流才 drain(HTTP 202)。消费方不得把两者都渲染成"已通知"。
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [sessionId, delivery]
+          properties:
+            sessionId: { type: string }
+            delivery: { type: string, enum: [live] }
+        - type: object
+          additionalProperties: false
+          required: [sessionId, delivery, note]
+          properties:
+            sessionId: { type: string }
+            delivery: { type: string, enum: [parked] }
+            note: { type: string }
+    SessionWakeResult:
+      # 4.3.0(SM-9):wake 200 形提成具名 schema(形与下面 /wake 路径的 200 逐字同源)。
+      type: object
+      description: >
+        POST /v1/sessions/{sessionId}/wake 的 200 形。⚠️ 200 也可能带 `errorCode`(core 侧 `wake.*` 拒了) ——
+        按机器码分支,别只看 HTTP 状态码。
+      additionalProperties: false
+      required: [sessionId, status]
+      properties:
+        sessionId: { type: string }
+        status: { type: string, description: 'The run''s resulting status (core TaskStatus verbatim).' }
+        taskId: { type: string, description: 'The active run id; OMITTED when no active row.' }
+        errorCode: { type: string, description: 'Failure code when the resumed leg failed / was refused.' }
+        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.' }
     WorkflowJournalRow:
       # 🔴 census 批2 四段:CLOSED against server's real projected/truncated row shapes — a row is EITHER the
       # projected result OR an honest truncated stub(超 64KiB 的行从不进程内存,投影为 truncated stub)。
@@ -5703,9 +5739,18 @@ components:
     WorkflowStreamEvent:
       type: object
       description: >
-        One frame of GET /v1/workflows/:id/stream (streamWorkflowRun). FIRST frame is `event:meta`
-        `{version, runId}`; subsequent frames carry a core WorkflowEvent (its `type` is the SSE event name). NOT
-        resumable (replica-local, in-process; no id/Last-Event-ID). `data` is permissive (core-internal, evolves).
+        One frame of GET /v1/workflows/:id/stream (streamWorkflowRun). FIRST frame is `event:meta` with
+        `data: {type:"meta", version, runId}` (`src/http/routes/workflows.ts:487` — the `type` is double-emitted
+        on purpose: a proxy that forwards only `data:` lines would otherwise leave a `data.type`-dispatching
+        consumer unable to recognise the opener). Subsequent frames carry a core WorkflowEvent verbatim (its
+        `type` is the SSE event name). NOT resumable (replica-local, in-process; no id/Last-Event-ID).
+        `data` is permissive (core-internal, evolves).
+        🔴 There IS exactly one TERMINAL frame and it means FAILURE: `event: error` with
+        `data: {type:"error", errorCode:"workflow.stream_error", message:"workflow stream error"}`
+        (`routes/workflows.ts:517`). Branch on `errorCode` — NEVER anchor on `message`; the errorCode was added
+        precisely because consumers were otherwise forced to anchor prose or to conflate "the stream broke" with
+        "the stream ended normally", i.e. to report a FAILED workflow as finished. (Declared 2026-08-02.)
+        Keep-alive is a REAL NAMED FRAME `event: heartbeat` / `data: {}` @15 s (`:496`), not an SSE comment.
         NOTE: on the wire this is SSE framing (event name + JSON data), not a JSON body — schema describes one
         decoded frame.
       required: [event, data]
@@ -5809,12 +5854,19 @@ components:
       required: [id, name, status]
       additionalProperties: true
       properties:
+        # 🔴 FW-6(2026-08-02):这里此前有一个 `sourceLane` —— **幻影键,已删**。`sourceLane` 只在
+        # `FleetTaskRow`(`src/fleet/fleet-bus.ts:146`)上,`FleetWorkflowRow`(`:150-170`)全文没有它,
+        # `publishWorkflow`(`:338-342`)也从不写它;SDK 侧同样没有(SDK 是对的那一边)。
+        # 按它 codegen 的第三方会得到一个永远 undefined 的 `workflowRow.sourceLane`,并照 FleetTaskRow 那条
+        # 「run-leg composite rows only」的描述写出一个**永不触发**的 workflow 行去重分支。
         id: { type: string }
-        sourceLane: { type: string, description: 'run-leg composite rows only (server >=3.6.0, [2070]-1 yield half); BCE-lane rows omit it.' }
         name: { type: string }
         description: { type: string }
         status: { type: string, description: 'Neutral workflow run status (running|completed|failed; open).' }
         doneCount: { type: integer }
+        # 🔴 FW-6(2026-08-02):补上一个 server 真发、SDK 真声明、只有 spec 漏了的键。
+        # `src/fleet/fleet-bus.ts:167` 声明,`src/orchestration/workflow-notify-journal.ts:511` 真发。
+        startedCount: { type: integer, description: 'Agents actually STARTED (vs `totalCount` = planned, queued included). CC 2.1.220 的 `⚠ Large workflow` 规模告警用它当分母 —— 漏了它那条告警根本渲染不出来。' }
         totalCount: { type: integer }
         failedCount: { type: integer }
         elapsedMs: { type: integer }
@@ -5825,7 +5877,9 @@ components:
         wire this is SSE framing (the `type` here = the SSE `event` name; the object = the decoded `data:` JSON).
         Emit order: `meta` (FIRST) → `snapshot` (connect-time full set) → per-row `task`/`workflow` upserts +
         `task_remove`/`workflow_remove` departures. The SDK PRODUCES these frames; the consumer maintains the
-        active-set state (update-in-place by `row.id`, remove by `id`). Heartbeat `: hb` comments are not frames.
+        active-set state (update-in-place by `row.id`, remove by `id`).
+        🔴 The keep-alive IS a frame: `event: heartbeat` / `data: {}` @15 s (corrected 2026-08-02 — this line
+        previously said "`: hb` comments are not frames", which described a superseded shape). Swallow it by NAME.
         OPEN set — branch on `type`, ignore an unknown future frame.
       oneOf:
         - $ref: '#/components/schemas/FleetFrame_meta'
@@ -5849,12 +5903,22 @@ components:
           hook_notice: '#/components/schemas/FleetFrame_hook_notice'
     FleetFrame_meta:
       type: object
-      description: 'FIRST frame — `{version, scoped}`. `scoped:true` ⇒ owner-scoped view; `false` ⇒ fleet-wide (operator/trace token).'
-      required: [type, version, scoped]
+      # 🔴 FW-10(2026-08-02):此前只声明三键,而铸造点 `src/http/routes/fleet.ts:79` **无条件**发五键 ——
+      # `sessionScoped` / `bgNotifyFailClosed` 不在任何条件分支里。这两个键正是「server 契约方复审 F1
+      # (行为错·最高)」的当事键:它们曾被一次白名单重构静默剥掉,导致 cli 的让位臂全程死代码。
+      # SDK 侧已上锁(`test/fleet.test.ts` 有专门的透传回归钉),spec 侧一直空白 —— 按 spec 生成的客户端
+      # 拿不到 `bgNotifyFailClosed`,只能保留帧级 own/foreign 判别(或更糟:以为拿不到就是老 server),
+      # 代际让位机制对这类消费方永远不生效。
+      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).
+      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).' }
+        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
       description: 'Connect-time FULL state (the visible, scope-stripped rows). Seed the active-set Map from this.'
@@ -8603,6 +8667,43 @@ components:
         delivery: { type: string, const: applied, description: 'Literal "applied" on today''s server.' }
         marker: { type: string, description: 'Engine-minted delivery marker.' }
 
+    WorkspaceSnapshotPage:
+      # 4.3.0(CAPS-OPS-8):把 GET …/workspace 的 200 信封提成具名 schema。SDK 侧此前是 `list()` 返回位上的
+      # **内联闭合字面量**,两道 spec 门(field-drift 只扫 types.ts / resource-schema 只扫 resources 的 exported
+      # type)对方法返回位的内联形都是盲的 —— 于是它漏了这里一直标为 required 的 `sessionId`,CI 全绿。
+      type: object
+      description: >
+        GET /v1/sessions/{sessionId}/workspace 的 200 信封(server src/http/routes/sessions.ts:624-629)。
+        ⚠️ `total` = **本页行数**(`snapshots.length`),不是快照总数,且这条腿没有任何分页游标 —— 与同族
+        `WorkspaceTreePage.total`(真·全量)**同名反义**。`latest` 与展示行同源(防 ghost key)。
+      additionalProperties: false
+      required: [sessionId, snapshots, total]
+      properties:
+        sessionId: { type: string }
+        snapshots:
+          type: array
+          items: { $ref: '#/components/schemas/WorkspaceSnapshotRow' }
+        latest: { type: string, description: 'Newest snapshot key; absent when the session has none.' }
+        total: { type: integer, description: 'ROWS ON THIS PAGE — not the snapshot count.' }
+
+    WorkspaceTreePage:
+      # 4.3.0(CAPS-OPS-8):同上,tree 腿的 200 信封。
+      type: object
+      description: >
+        GET /v1/sessions/{sessionId}/workspace/{key}/tree 的 200 信封(server src/http/routes/sessions.ts:651-657)。
+        `total` 在这条腿上是**全量**(`all.length`)—— 与 `WorkspaceSnapshotPage.total` 语义相反。
+        `key` 回的是解析后的真实键(请求可传 `latest` 别名)。
+      additionalProperties: false
+      required: [sessionId, key, entries, total]
+      properties:
+        sessionId: { type: string }
+        key: { type: string, description: 'The RESOLVED snapshot key (a `latest` alias in the request comes back resolved).' }
+        entries:
+          type: array
+          items: { $ref: '#/components/schemas/WorkspaceTreeEntry' }
+        total: { type: integer, description: 'FULL entry count (not the page size).' }
+        nextOffset: { type: integer, description: 'Present ⇒ more pages; send it back as ?offset=.' }
+
     WorkspaceSnapshotRow:
       type: object
       description: >

package/package.json

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

package/registry-openapi.yaml

@@ -153,8 +153,21 @@ paths:
       - { in: path, name: domain, required: true, schema: { type: string } }
     get:
       operationId: registryScopeConfigDraftGet
-      summary: Read a scope's config DRAFT (getScopeConfigDraft).
-      responses: { '200': { description: '{value, version, …}.' } }
+      summary: Read a scope's config — DRAFT by default, or the PUBLISHED snapshot with `?source=published`.
+      # 🔴 RC-6(2026-08-02):`?source=published` 此前完全未成文,而 SDK 的 `getScopeConfigPublished`
+      # (`scope-config-feedback.ts:46`)一直在打它 —— 两个响应形不同(draft 是 `{value, version}`,
+      # published 是 `{value, published, publishedAt?}`),按 spec codegen 的人只知道 draft 那一个。
+      parameters:
+        - in: query
+          name: source
+          required: false
+          schema: { type: string, enum: [published] }
+          description: 'Omit ⇒ the DRAFT (workspace) read. `published` ⇒ the PUBLISHED snapshot — what members actually receive.'
+      responses:
+        '200':
+          description: >
+            Without `?source=`: the draft, `{value, version, …}` — `version` is the CAS baseline for the PUT.
+            With `?source=published`: `{value, published, publishedAt?, …}`.
     put:
       operationId: registryScopeConfigDraftPut
       summary: CAS-write the draft (putScopeConfigDraft; version NUMBER axis — not updatedAt).
@@ -164,10 +177,28 @@ paths:
   /api/v1/scopes/{s}/publish:
     parameters:
       - { in: path, name: s, required: true, schema: { type: string } }
+    # 🔴 RC-6(2026-08-02):此前这条路径**只有 post、只有 '200'**。两个后果,都命中同一个设计的核心:
+    #  ① 缺 `get` ⇒ 按本 spec(随 npm 包发布,package.json exports `./registry-openapi.yaml`)生成客户端的人
+    #     拿不到状态查询 verb —— 而 SDK 的 `getPublishState` 一直在打它。
+    #  ② 缺 `'202'` ⇒ 拿不到 pending 分支,他会把 202 当成一个未处理的异常状态。而 200/202 的判别**就是**
+    #     这条设计的核心(`scope-config-feedback.ts:85-86` 明写「消费方绝不许把 202 渲染成已发布」)。
+    # 现有的 registry path 门是双向零基线的、很强 —— 但它比对的是**路径集合**,method/responses 全不参与,
+    # 所以这两类问题结构上红不了。同批把那道门升到了 path × method(见 test/registry-spec-path-gate.test.ts)。
+    get:
+      operationId: registryScopePublishState
+      summary: Read the publish state (getPublishState) — is a request already pending, and how many approvals does it need?
+      responses:
+        '200':
+          description: >
+            `{published?, pending?, approvalsRequired}`. `pending` present ⇒ a request is already outstanding and a
+            new one cannot be opened. ⚠️ `approvalsRequired` gates a PROTECTION; if it is ever absent, treat that as
+            unknown and fail CLOSED — never render "no approval needed".
     post:
       operationId: registryScopePublishRequest
       summary: Request publish of the draft (requestPublish; goes through the approval gate).
-      responses: { '200': { description: 'Publish requested/pending.' } }
+      responses:
+        '200': { description: 'PUBLISHED — the draft took effect immediately (no approval gate, or already satisfied).' }
+        '202': { description: 'PENDING — the approval gate is open and the draft is NOT in effect. Approvers act via …/publish/approve. A consumer MUST NOT render this as published.' }
 
   # ── feedback ──────────────────────────────────────────────────────────────────────────────────
   /api/v1/feedback: