@sema-agent/sdk 0.0.46

package/openapi.yaml

@@ -0,0 +1,3434 @@
+openapi: 3.1.0
+
+# ─────────────────────────────────────────────────────────────────────────────
+# M0 wire contract — the SINGLE SOURCE OF TRUTH for the usage plane.
+# Consumed by @sema-agent/sdk (→ both doors: the CC/Codex MCP façade and the
+# portal BFF). Producer = the service. BOTH sides anchor contract tests to THIS
+# file; drift fails in CI, not in prod (CORE-PRINCIPLES §5).
+#
+# Authoritative producer input: ../docs/SERVICE-CORE-CONTEXT.md §2/§4.
+# packages/sdk/src/types.ts + events.ts + errors.ts MIRROR these schemas (kept in sync by hand;
+# the contract test guards the drift). Where types.ts intentionally leaves an M2 surface as
+# `unknown`, this spec may be slightly ahead — those are marked `x-status: draft`.
+#
+# x-status legend:
+#   live    — implemented & verified server-side; in the contract-test assertion set.
+#   draft   — verb exists but the response shape is not fully pinned; co-design pending (do not over-assert).
+#   planned — NOT yet implemented server-side; documented for SDK/producer alignment; EXCLUDED from
+#             contract-test assertions until it ships.
+#   gated   — implemented but off by a server deploy flag (e.g. leader); not on the default product path.
+# ─────────────────────────────────────────────────────────────────────────────
+
+info:
+  title: AI Agent Fleet — Usage-Plane Wire Contract
+  version: 0.1.0
+  description: >
+    M0 contract for the agent-service worker as consumed by the usage plane.
+    Conventions (enforced by the SDK + this contract):
+      • Every request carries `Authorization: Bearer <SERVICE_AUTH_TOKEN>` (SERVER-SIDE ONLY — the SDK's
+        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).
+      • 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).
+  x-sources:
+    - ../docs/SERVICE-CORE-CONTEXT.md   # §2 wire answers, §4 verb surface (authoritative producer input)
+    - ../docs/CORE-PRINCIPLES.md        # §2 secret discipline, §3 principal-first, §5 contract-as-anchor, §6 optional-no-default
+  x-contract-test:
+    producer: the service
+    consumer: '@sema-agent/sdk (packages/sdk)'
+    note: 'Both sides assert against this file. `x-status` planned|draft operations are excluded until live/pinned.'
+
+servers:
+  - url: '{baseUrl}'
+    description: >
+      Worker base URL — injected from deploy env, NEVER hardcoded (secret/config discipline, CORE-PRINCIPLES §2:
+      config stores env-NAME, not values). e.g. a Traefik route prefix in front of a worker pod.
+    variables:
+      baseUrl:
+        default: http://worker.invalid
+        description: Placeholder. Real value comes from the integrator's env (e.g. SERVICE_BASE_URL).
+
+security:
+  - bearerAuth: []
+
+tags:
+  - name: tasks
+    description: Synchronous tasks (run-to-completion + live token stream).
+  - name: runs
+    description: Asynchronous, durable, resumable runs (the door-B / HITL path).
+  - name: sessions
+    description: Conversation continuity (the "对话框") audit reads.
+  - name: approvals
+    description: HITL — approve/deny a policy gate or answer an AskUserQuestion (SERVICE-CORE-CONTEXT §3.4).
+  - name: assistant
+    description: >
+      Assistant-scheduler + HITL decision surface (ASSISTANT-WIRE-CONTRACT.md, service main 6cd0164 /
+      core 1.110.0, LIVE on worker): severity-sorted inbox, N-task overview, and the 3 DISTINCT decision
+      wires (resume / plan_review / preempt). Owner-gated via the principal header (NOT D-G crypto-bound —
+      only /decide is, §6); a non-owner non-operator gets 404 (no existence oracle), never 403.
+  - name: trace
+    description: Workspace data source — list/turns/stream + jobId grouping (the anti-fragmentation substrate).
+  - name: usage
+    description: Read-only per-principal cost/quota snapshot (the CLI `/cost` panel's real data).
+  - name: policy
+    description: Read-only effective-governance snapshot (the CLI `/permissions` panel's real data; inspect-only).
+  - name: workflows
+    description: >
+      S8 self-orchestration run observability (design/97/98) — owner-scoped list / detail / live SSE.
+      Gated server-side (SELF_ORCHESTRATION_ENABLED, default OFF → 501); replica-local (list/stream see this
+      replica's runs). NOT resumable on the stream (in-process subscription; a drop is a full restart).
+  - name: fleet
+    description: >
+      MF-Fleet (shell-host data contract) — the LIVE multi-row fleet view SSE (active task + workflow rows,
+      transitioning over time). Owner-scoped by the credential principal (scope wire-stripped) unless fleet-wide;
+      in-process bus, NOT resumable (a drop is a full restart). No fleet wiring → 501.
+  - name: leader
+    description: v2 leader pipeline (gated; E2B + git push). NOT the default door-B brain.
+  - name: metrics
+    description: Worker health/cost (ops; uses metricsToken, not a principal).
+
+paths:
+
+  /v1/capabilities:
+    get:
+      tags: [metrics]
+      operationId: capabilities
+      x-status: live             # service 7aa0f3d. Booleans share deps with the route gates.
+      summary: Worker capability discovery (what surfaces are enabled).
+      description: >
+        One call replaces probe-by-501. Booleans are computed from the SAME deps as the route gates —
+        "capabilities says yes but the route 501s" is structurally impossible (producer-tested). Auth = same
+        as config surfaces (Bearer authToken; NO principal header). Open set: ignore unknown keys.
+        `pricingConfigured` disambiguates stats.costMicroUsd=0 (true zero vs MODEL_COST_* unset) — it is
+        worker-level, deliberately NOT on per-result stats (the pinned wire contract ②).
+      responses:
+        '200':
+          description: Capability map.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Capabilities' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/memory:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [sessions]
+      operationId: memoryGet
+      x-status: live             # service 170c384. Owner-scoped by construction.
+      summary: Read your own <user_memory> (transparency surface).
+      description: >
+        Scope derives from the request principal (same rule as task execution) — a caller CANNOT address
+        anyone else's memory. No principal header → 401. Discover via capabilities().memory.
+      responses:
+        '200':
+          description: The memory record (content null = empty).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MemoryRecord' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+    delete:
+      tags: [sessions]
+      operationId: memoryClear
+      x-status: live
+      summary: Clear your WHOLE memory scope (per-entry deletion is a future additive).
+      responses:
+        '200':
+          description: Cleared.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, scope]
+                properties:
+                  ok: { type: boolean }
+                  scope: { type: string }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/tasks:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [tasks]
+      operationId: tasksSubmit
+      x-status: live
+      summary: Run a short task to completion (synchronous).
+      description: >
+        Synchronous run-to-completion. Auto `Idempotency-Key` (→ retry-safe). Supports `verify`/`cascade`.
+        For anything that may take minutes or hit a HITL gate, use `/v1/runs` instead (this call blocks).
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/TaskRequest' }
+      responses:
+        '200':
+          description: Task result.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TaskResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '503': { $ref: '#/components/responses/Unauthorized' }
+    get:
+      tags: [trace]
+      operationId: traceList
+      x-status: live
+      summary: List runs, optionally filtered by jobId (the work-view grouping).
+      description: >
+        Lists runs (keyset pagination). `?jobId=<id>` returns all runs of one logical job — the substrate the
+        workspace uses to group a job's scattered runs across BOTH doors (jobId LIVE, service 63b8696).
+        Summary items carry `jobId` when present. Full per-task shape beyond the summary is draft (see traceTurns).
+      parameters:
+        - in: query
+          name: jobId
+          required: false
+          schema: { type: string, minLength: 1, maxLength: 64 }
+          description: Filter to one logical job's runs (idx_job, keyset).
+        - in: query
+          name: status
+          required: false
+          schema: { $ref: '#/components/schemas/RunStatus' }
+          description: Filter by run status.
+        - in: query
+          name: source
+          required: false
+          schema: { type: string }
+          description: Filter by credential-derived system (oa | cc-mcp | portal …). the pinned wire contract.
+        - in: query
+          name: owner
+          required: false
+          schema: { type: string }
+          description: >
+            Filter to one principal's runs. AUTHZ IS THE BFF'S RESPONSIBILITY (trace surface trusts the
+            system token): ordinary users MUST be forced to owner=<their principal>; operator role may omit.
+            the pinned wire contract.
+        - in: query
+          name: limit
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
+        - in: query
+          name: cursor
+          required: false
+          schema: { type: string }
+          description: Keyset pagination cursor (opaque).
+      responses:
+        '200':
+          description: Run summaries.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TaskList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+
+  /v1/tasks/stream:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [tasks]
+      operationId: tasksStream
+      x-status: live
+      summary: Live token stream (synchronous, per-token).
+      description: >
+        Same instance, transient, per-token SSE. `verify`/`cascade` are REJECTED here with 400 (multi-attempt,
+        not a stream). NOT a resumable surface — a client disconnect ABORTS the run (kills token burn). HITL can
+        still checkpoint mid-stream, but RESUME is only via a durable `/v1/runs` + `/v1/approvals` (the pinned wire contract/[5]
+        Q3). Use this only for fast, single-connection, no-HITL interactions; the portal standardizes on `/v1/runs`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/TaskRequest' }
+      responses:
+        '200':
+          description: SSE stream of AgentEvents (per-token text/reasoning carry the `delta` flag).
+          content:
+            text/event-stream:
+              schema: { $ref: '#/components/schemas/AgentEvent' }
+        '400':
+          description: Bad request — e.g. `verify`/`cascade` not supported on the stream, or invalid `jobId`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+
+  /v1/runs:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [runs]
+      operationId: runsCreate
+      x-status: live
+      summary: Start an async run (202).
+      description: >
+        Async; runs in the background. Requires a TiDB run store (absent → 501). Auto `Idempotency-Key`.
+        Poll `GET /v1/runs/:id` or stream `GET /v1/runs/:id/events`. A client disconnect does NOT stop the run.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/TaskRequest' }
+      responses:
+        '202':
+          description: Run accepted (the capability token is NEVER on the wire — server-internal).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RunReceipt' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+        '503': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/runs/{taskId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    get:
+      tags: [runs]
+      operationId: runsGet
+      x-status: live
+      summary: Read run state (poll).
+      description: Owner-scoped read. Response includes `jobId` when the run has one.
+      responses:
+        '200':
+          description: Run state.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RunRecord' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /v1/runs/{taskId}/events:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    get:
+      tags: [runs]
+      operationId: runsEvents
+      x-status: live
+      summary: Resumable SSE event stream (durable log).
+      description: >
+        Replays durable events from after `Last-Event-ID` (each event's `id:` = the TiDB `task_event.seq`,
+        monotonic; events are NOT rolling-deleted, so the normal path never evicts), then tails to a terminal
+        state. Durable `text`/`reasoning` are turn-AGGREGATED (no per-token deltas — those are only on
+        `/v1/tasks/stream`). Heartbeat = 30s (`:` comment lines); the SDK declares a drop at ≥~45s and re-enters
+        the resume loop without consuming a retry. On a rare window eviction the server returns `416` with
+        `{ error, retainedFrom }` (NO machine code field — match the STATUS, not a body code); the SDK then
+        full-syncs via `GET /v1/tasks/:id/turns` and resumes events from `retainedFrom` (no event lost;
+        consumer is event-id idempotent).
+      parameters:
+        - $ref: '#/components/parameters/LastEventId'
+      responses:
+        '200':
+          description: SSE stream of AgentEvents (turn-aggregated; resumable).
+          content:
+            text/event-stream:
+              schema: { $ref: '#/components/schemas/AgentEvent' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '416':
+          description: >
+            Resume point evicted past retention. Match the STATUS 416 (there is NO `code` field); read
+            `retainedFrom`, full-sync via `GET /v1/tasks/:id/turns`, then resume from `retainedFrom`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ResumeEvicted' }
+
+  /v1/runs/{taskId}/cancel:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [runs]
+      operationId: runsCancel
+      x-status: live             # LIVE (service ced3d88). SDK verb runs.cancel(id) = M1.5.
+      summary: Cancel a durable async run (LIVE).
+      description: >
+        Cancels a durable async run (one created by `POST /v1/runs`). Auth = same as `runs.get`: owner-checked
+        (non-owner → 404, no existence leak; missing principal → 401). All responses are synchronous ACKs; actual
+        termination is async (same-replica immediate; cross-replica ≈30s via the heartbeat tick). A cancelled run
+        settles to `status` failed + `errorCode` "cancelled" (NO new status — distinguish via errorCode; the UI
+        shows "cancelled", not an error). A SUSPENDED run has no running stream to abort → 409; cancel it by
+        DENYING its approval instead. LIVE (service ced3d88).
+      responses:
+        '202':
+          description: >
+            Ack. A running run returns status "cancelling"; an already-terminal run is an idempotent no-op
+            (returns the terminal status + a note).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CancelAck' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: Run is suspended (HITL) — cancel by denying its approval (`/v1/approvals/:sessionId/decide`), not here.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/runs/{taskId}/steer:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [runs]
+      operationId: runsSteer
+      x-status: draft            # design/80 D-A; core landing the slice (pendingSteer freeze/close-tag). Skeleton per the pinned wire contract.
+      summary: Steer a RUNNING durable run — inject mid-flight direction (supervision).
+      description: >
+        design/80 D-A. The core of *supervision* (vs mere approve/deny): inject direction into a running run.
+        AT-MOST-ONCE — steer is NOT idempotent (no retry). `trusted` is NOT a body field — the server derives it
+        from the authenticated operator (the BFF's operator role); a network steer defaults to untrusted. A
+        durable-`suspended` run → 409 `errorCode` "steering.not_running" (steer is not queued; resolve its
+        approval instead). The pendingSteer freeze / close-tag guard is server-side; the client only sends text.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [text]
+              properties:
+                text: { type: string, description: 'The steering direction (untrusted DATA; the server fences it).' }
+                mode:
+                  type: string
+                  enum: [all, one-at-a-time]
+                  description: >
+                    Engine QueueMode (default one-at-a-time) — how many queued steers drain per TURN BOUNDARY:
+                    "all" = inject ALL queued steers together at the next turn; "one-at-a-time" = inject ONE per
+                    turn (FIFO), spread across turns. FORWARD-DRAFT: core's steer is harness-level today, not
+                    per-call; the per-call mapping is pending D-A core.
+      responses:
+        '200': { description: Steer accepted and applied. }
+        '202': { description: Steer accepted (queued to the next turn-boundary drain). }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'errorCode "steering.not_running" — the run is suspended/terminal, not running (steer is not queued).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: 'errorCode "steering.invalid_content" — the steer text carried a control-plane escape (e.g. </system-reminder>); core rejected it.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/runs/{taskId}/subagents/{target}/steer:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - name: target
+        in: path
+        required: true
+        schema: { type: string }
+        description: >
+          The delegating tool call's id (`parentToolCallId`, stamped on every forwarded subagent content
+          event when `forwardSubagentEvents` is on) or the subagent's agentName (an ambiguous name → 409).
+    post:
+      tags: [runs]
+      operationId: runsSteerSubagent
+      x-status: live             # core 1.219 C2 (onSubagentSpawn steer handles) / server 1.89 SubagentSteerRegistry; wire-verified 2026-07-04 (subagent-wire C1C2).
+      summary: Steer a RUNNING SUBAGENT of this run (drains at the subagent's next tool round).
+      description: >
+        core 1.219 C2 / server 1.89. The CC "enter the agent's view and type to it" semantic (AGe
+        pendingMessages): the message is queued and drains at the subagent's NEXT TOOL ROUND. BODY SHAPE
+        differs from the main-run steer — `{ content }`, NOT `{ text }`. AT-MOST-ONCE (no retry). A
+        settled/unknown subagent → 409 `errorCode` "steering.not_running".
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [content]
+              properties:
+                content: { type: string, description: 'The message for the subagent (untrusted DATA; the server fences it — same framing as the workflow-agent steer).' }
+      responses:
+        '200':
+          description: >
+            Queued/applied. Body `{ taskId, target, status, delivery, note }` — `note` carries the
+            CC-verbatim "Message queued for delivery to <name> at its next tool round." receipt copy.
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 'errorCode "steering.not_running" — the run/subagent is settled or unknown (also: ambiguous agentName).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/sessions:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [sessions]
+      operationId: sessionsList
+      x-status: live             # E16, service 6cbf61e (durable session store).
+      summary: List the caller's sessions (keyset page).
+      description: >
+        E16 (shell-host sessionPicker) — owner-scoped keyset page of the caller's sessions; each row aggregates a
+        session's run ledger (last activity + most-recent objective preview + status). `owner` is honored only for
+        a fleet-wide credential (a principal caller is force-scoped to itself). 501 without a durable session store
+        (SESSION_BACKEND=tidb) — gate the picker off `capabilities()` instead of trial-by-501.
+      parameters:
+        - in: query
+          name: limit
+          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
+        - in: query
+          name: cursor
+          schema: { type: string }
+          description: Opaque keyset cursor from a previous page's `nextCursor` (echo verbatim). Absent = first page.
+        - in: query
+          name: owner
+          schema: { type: string }
+          description: Fleet-wide credential only — scope the page to a tenant. Ignored for a principal caller.
+      responses:
+        '200':
+          description: Keyset page of session summaries.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionListPage' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsGet
+      x-status: live             # true shape from source.
+      summary: Session audit (current context + owner + compaction state).
+      description: >
+        Owner-checked read of a durable session (same semantics as runs: non-owner → 404). `messages` is the
+        CURRENT model context (older history already folded into a summary message) — can be LARGE, the portal
+        should lazy-expand. Absent entirely on workers without the TiDB pool (capabilities.asyncRuns is the
+        practical same-prereq signal).
+      responses:
+        '200':
+          description: Session record.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionRecord' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+    delete:
+      tags: [sessions]
+      operationId: sessionsDelete
+      x-status: live             # E21, service durable session store.
+      summary: Purge a session's history + run ledger (idempotent).
+      description: >
+        E21 (shell-host) — purge the session's conversation history + service-owned run-ledger/checkpoint/tool-result
+        rows. Owner-scoped (non-owner → 404). Idempotent (`{deleted:false}` when nothing existed). 🔴 409 while a run
+        is LIVE on the session (`activeTaskId` in the body) — cancel it first so the session lock isn't orphaned.
+        501 without a durable session store.
+      responses:
+        '200':
+          description: Delete result (idempotent).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [deleted]
+                properties:
+                  deleted: { type: boolean }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/fork:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: sessionsFork
+      x-status: live             # E17, service durable session store.
+      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.
+      responses:
+        '200':
+          description: The new branched session id.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [sessionId]
+                properties:
+                  sessionId: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/policy:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsGetPolicy
+      x-status: live             # E6, service + core session-policy store.
+      summary: Read the per-session tool-permission rules (permissionMode).
+      description: >
+        E6 (shell-host permissionMode) — the operator-tightened per-session tool-permission rules core reads at
+        prepare-time (SUBTRACT-only). Owner-scoped (non-owner → 404); ownerless session → 409. Read-only snapshot
+        (enforcement is 100% core-side). 501 without a session-policy store.
+      responses:
+        '200':
+          description: The stored rules (incl. the OCC `rev`).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rules]
+                properties:
+                  rules: { $ref: '#/components/schemas/StoredSessionRules' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+    put:
+      tags: [sessions]
+      operationId: sessionsPutPolicy
+      x-status: live
+      summary: Write the per-session tool-permission rules (tighten-only).
+      description: >
+        E6 — write the per-session rules. 🔴 TIGHTEN-ONLY for a normal principal: a loosen (remove a deny / widen
+        an allowlist or allowDirs) → 403 `loosen_forbidden` (operator-only). `expectedRev` = optimistic-concurrency
+        CAS; a stale rev → 409 `conflict`. Each rule field must be `string[]` → malformed body 400. ownerless
+        session → 409; non-owner → 404. 501 without a session-policy store.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [rules]
+              properties:
+                rules: { $ref: '#/components/schemas/SessionPermissionRules' }
+                expectedRev: { type: integer, minimum: 0, description: CAS — reject if the stored rev differs. }
+      responses:
+        '200':
+          description: The stored rules with the new `rev`.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rules]
+                properties:
+                  rules: { $ref: '#/components/schemas/StoredSessionRules' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: 403 `loosen_forbidden` — a non-operator write tried to relax the rules (tighten-only).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409': { $ref: '#/components/responses/Conflict' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/mcp:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionsMcp
+      x-status: live             # E9, service + core 1.124.
+      summary: Per-server MCP status (materialization-time projection).
+      description: >
+        E9 (shell-host mcpStatus) — per-server MCP status for the `/mcp` panel. 🔴 MATERIALIZATION-TIME, not live
+        session health: core never persists MCP connections, so the service fresh-connects→lists→disposes the
+        worker's configured MCP servers on demand and projects their status (`asOf` = that moment; render "as of
+        <asOf>"). `degraded:true` (servers empty) ⇒ materialize timed out/failed (NOT "no MCP"). No MCP configured
+        ⇒ `servers:[]` without `degraded`.
+      responses:
+        '200':
+          description: The MCP status panel.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/McpStatusPanel' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/sessions/{sessionId}/memory:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: memoryAppend
+      x-status: live             # MF-30, service @sema-agent/server 1.3.0 (server.ts:2880).
+      summary: Append a memory note (MF-30 — the /memory write verb).
+      description: >
+        🔴 Memory is PER-PRINCIPAL, not per-session — {sessionId} is only the shell's addressing context (the
+        /memory command runs inside some session); a note appended for a principal is visible from ALL that
+        principal's sessions. Note stored VERBATIM (≤8 KiB, user-authored = intentional, NOT redacted).
+        Empty/oversized → 400. Always available when capabilities().memoryWrite.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [content]
+              properties: { content: { type: string } }
+      responses:
+        '200':
+          description: Append ack — unified { ok, id, scope } (service; handler always returns ok).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MemoryWriteAck' }
+        '400': { description: "Empty / oversized / missing content." }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/sessions/{sessionId}/memory/{noteId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: noteId
+        required: true
+        schema: { type: string }
+    patch:
+      tags: [sessions]
+      operationId: memoryEdit
+      x-status: live             # MF-30 (server.ts:2881).
+      summary: Edit one memory note by id (id unchanged).
+      description: >
+        🔴 501 when the backend lacks id-addressable update (honest degrade, never a fake 200). Per-PRINCIPAL.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [content]
+              properties: { content: { type: string } }
+      responses:
+        '200':
+          description: Edited note ack.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MemoryWriteAck' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { description: "Backend lacks id-addressable update." }
+    delete:
+      tags: [sessions]
+      operationId: memoryForget
+      x-status: live             # MF-30 (server.ts:2882).
+      summary: Forget one memory note by id.
+      description: >
+        🔴 501 when the backend lacks id-addressable delete (honest degrade). Per-PRINCIPAL.
+      responses:
+        '200':
+          description: Forgotten note ack.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MemoryWriteAck' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { description: "Backend lacks id-addressable delete." }
+
+  # ── 2c session-sync (P1d) — the cloud as a SYNC PEER ──────────────────────────────────────────────────────────
+  # The local shell's local backend ⇄ this cloud service. PULL a session's whole state out, or PUSH the local
+  # peer's in. Gate the whole surface off `capabilities.sessionSync` (= durable backend + entry export + a
+  # file-snapshot store). Owner-gated like fork/delete (§9): a PULL 404s a non-owner; a PUSH is own-or-FRESH.
+  /v1/sessions/{sessionId}/sync/manifest:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [sessions]
+      operationId: sessionSyncManifest
+      x-status: live             # 2c P1d, service @sema-agent/server@1.2.0 (LIVE pending worker 1.2.0 deploy).
+      summary: PULL the session manifest (thin cross-backend snapshot).
+      description: >
+        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.
+      responses:
+        '200':
+          description: The manifest, wrapped as `{ manifest }`.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [manifest]
+                properties:
+                  manifest: { $ref: '#/components/schemas/SessionManifest' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/sync/entries:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: query
+        name: afterSeq
+        required: false
+        schema: { type: integer, minimum: 0 }
+        description: >
+          Resume cursor = the backend-native durable `seq` (yield entries whose seq > afterSeq). SAME-BACKEND only.
+          A non-integer / negative value → 400.
+    get:
+      tags: [sessions]
+      operationId: sessionSyncEntries
+      x-status: live
+      summary: PULL the entry payloads as an NDJSON stream.
+      description: >
+        2c session-sync PULL — the entry PAYLOADS as `application/x-ndjson`: a `{"__sync":"begin",sessionId}` header
+        line, then ONE entry JSON per line, then a `{"__sync":"end",count}` TRAILER line. 🔴 The status is committed
+        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.
+      responses:
+        '200':
+          description: The NDJSON entry stream (begin / entry× N / end-trailer).
+          content:
+            application/x-ndjson:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/sync/snapshots/{key}/blobs/{hash}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: key
+        required: true
+        schema: { type: string }
+        description: The snapshot key (= a `SessionTreeEntry.id`).
+      - 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: 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
+        non-64-hex hash or an undecodable key/hash. Owner-scoped (404).
+      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'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: hash
+        required: true
+        schema: { type: string, pattern: '^[0-9a-f]{64}$' }
+    put:
+      tags: [sessions]
+      operationId: sessionSyncPutBlob
+      x-status: live
+      summary: PUSH one content-addressed blob (own-or-fresh, integrity-checked).
+      description: >
+        2c session-sync PUSH — store one content-addressed blob's RAW bytes ahead of import (`application/octet-stream`
+        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`).
+      requestBody:
+        required: true
+        content:
+          application/octet-stream:
+            schema: { type: string, format: binary }
+      responses:
+        '204': { description: Stored (no body). }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+        '502':
+          description: 502 `blob store write failed` — the backend (MinIO/…) rejected the write. Re-PUT (idempotent).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/sessions/{sessionId}/sync/plan:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: sessionSyncPlan
+      x-status: live
+      summary: DRY-RUN — classify what a PUSH would do (no write).
+      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 —
+        a fork/stale is REPORTED in the relation, not raised.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [entryIds]
+              properties:
+                entryIds: { type: array, items: { type: string } }
+      responses:
+        '200':
+          description: The classified relation.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SyncRelation' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/sync/import:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [sessions]
+      operationId: sessionSyncImport
+      x-status: live
+      summary: PUSH Phase A — classify + stage (mint a stagingId).
+      description: >
+        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.
+        `identical` → `{ relation:"identical" }` with NO stagingId (skip Phase B); `fresh`/`fast_forward` →
+        `{ stagingId, relation }`. 🔴 a `fork`/`stale` without `resolution:"overwrite-dst"` → 409
+        `conflict` carrying the `relation` (the SDK surfaces SyncConflictError).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [entryIds, snapshots, policy, anchors]
+              properties:
+                entryIds: { type: array, items: { type: string } }
+                snapshots: { type: array, items: { $ref: '#/components/schemas/SyncSnapshot' } }
+                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. }
+      responses:
+        '200':
+          description: Staged (or `identical` no-op).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ImportStaged' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: >
+            409 `conflict` — a `fork`/`stale` PUSH without `resolution:"overwrite-dst"` (carries `relation`; the SDK
+            surfaces SyncConflictError), OR an active run (`session_active`, `activeTaskId`) / an in-flight import
+            (`import_in_flight`) on the session (ConflictError).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SyncConflict' }
+        '422': { $ref: '#/components/responses/UnprocessableEntity' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/sessions/{sessionId}/sync/import/{stagingId}/entries:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: stagingId
+        required: true
+        schema: { type: string }
+        description: The token minted by Phase A.
+    post:
+      tags: [sessions]
+      operationId: sessionSyncImportEntries
+      x-status: live
+      summary: PUSH Phase B — stream the entry log (NDJSON) → commit.
+      description: >
+        2c session-sync PUSH Phase B — stream the entry log as an NDJSON REQUEST body into the staged shadow id; the
+        cloud validates per-line (the streaming invariant gate) then `finish()` (exactly-one-root + leaf-resolvable) →
+        commits (the atomic swap) → replays snapshots/policy/anchors. Returns `{ relation }` (the AUTHORITATIVE in-txn
+        re-classify). Re-POSTing the same stagingId is idempotent. Typed errors: a per-entry / structural violation →
+        422 `invalid_entries`; a line too large → 413; a commit-time TOCTOU flip to fork/stale → 409 `conflict`
+        (SyncConflictError); a refused policy loosen → 403 `loosen_forbidden`; a wrong/foreign stagingId → 404.
+      requestBody:
+        required: true
+        content:
+          application/x-ndjson:
+            schema: { type: string, description: One entry JSON per line. }
+      responses:
+        '200':
+          description: Committed.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ImportCommitted' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: 403 `loosen_forbidden` — a post-commit policy replay tried to relax the rules (tighten-only).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: 409 `conflict` — a commit-time TOCTOU re-classify flipped to fork/stale (carries `relation`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SyncConflict' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }
+        '422': { $ref: '#/components/responses/UnprocessableEntity' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/approvals:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [approvals]
+      operationId: approvalsList
+      x-status: live             # true shape from source. NEVER returns a capability token.
+      summary: List pending HITL checkpoints (operator-scoped).
+      description: >
+        Pending approvals/questions for runs that went `suspended` (an F4 policy gate or an AskUserQuestion;
+        AskUserQuestion appears as the question gate's toolName). Envelope key = `pending` (NOT a bare array),
+        ordered by created_at asc. Operator view sees all tenants; `scope` is enforced in the decide CAS.
+        NEVER returns the capability token (secret discipline).
+      responses:
+        '200':
+          description: Pending checkpoints.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/PendingList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/approvals/{sessionId}/decide:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [approvals]
+      operationId: approvalsDecide
+      x-status: live
+      summary: Resolve a suspend — approve/deny or answer.
+      description: >
+        Resolves a `suspended` run: an F4 approve/deny, or an answer to an AskUserQuestion. The resumed run
+        continues its durable stream (`/v1/runs/:id/events`). design/80 D-1: the decision SHOULD carry the
+        action binding (checkpointToken/boundCallId/boundInputHash read off the PendingCheckpoint) — the server
+        resolves THAT exact checkpoint, fail-closed on mismatch. (Path param stays `sessionId` until service
+        finalizes a checkpointToken-keyed route; the binding travels in the body regardless.)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ApprovalDecision' }
+      responses:
+        '200':
+          description: Decision accepted; the run resumes.
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: >
+            Either a session-CAS conflict (`ErrorResponse.activeTaskId`), OR a design/80 D-1
+            `approval_binding_mismatch` (`errorCode`, `field`: boundCallId|boundInputHash) — your binding does
+            NOT match the current pending action (TOCTOU/swap). The SDK splits these by `errorCode` into
+            ConflictError vs ApprovalBindingMismatchError. binding_mismatch = SAFETY signal: refetch + re-present
+            to the human, NEVER auto-retry.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '410':
+          description: >
+            design/80 D-1 `approval_stale` (`errorCode`, `terminal`: resolved|expired_abort|expired_sla) — the
+            checkpoint is already terminal (someone resolved it / abandonment-TTL GC / SLA resolve-deny). Client
+            action: refetch the inbox; this pending is gone. SDK → ApprovalStaleError.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/approvals/{sessionId}/exemptions:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [approvals]
+      operationId: approvalsListExemptions
+      x-status: live             # service exemptions ruling — server.ts exemptions surface; 501 without a store backend.
+      summary: List the session's approval exemptions ("don't ask again").
+      description: >
+        The session's granted per-tool approval exemptions () — an APPROVAL MEMORY, not a policy loosen
+        (deny/neverAuto always outrank a grant). Envelope key = `exemptions`. OWNER-GATED with a 404 (no
+        existence oracle): a non-owner and an unknown session are indistinguishable. Explicit operators may
+        inspect any session. `toolName` is in CANONICAL tool-name space. GET is list-only (a per-tool GET
+        `/exemptions/:toolName` is 404).
+      responses:
+        '200':
+          description: The session's exemptions.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ExemptionList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501':
+          description: Worker has no exemption store backend (DB_BACKEND / LOCAL lane required).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/approvals/{sessionId}/exemptions/{toolName}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: sessionId
+        required: true
+        schema: { type: string }
+      - in: path
+        name: toolName
+        required: true
+        schema: { type: string }
+        description: Canonical tool name (echo `toolName` off the list row; the service canonicalizes).
+    delete:
+      tags: [approvals]
+      operationId: approvalsRevokeExemption
+      x-status: live             # service exemptions ruling; 501 without a store backend.
+      summary: Revoke one approval exemption (the tool asks again).
+      description: >
+        Revokes a single (sessionId, toolName) exemption. 200 `{revoked: true}` on success; 404 when
+        there is nothing to revoke OR the caller is not the owner / the session is unknown (deliberately
+        indistinguishable — no existence oracle). The SDK surfaces this as a boolean
+        (`approvals.revokeExemption` → false on 404), matching the store's idempotent revoke.
+      responses:
+        '200':
+          description: Revoked.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [revoked]
+                properties:
+                  revoked: { const: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501':
+          description: Worker has no exemption store backend.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/assistant/inbox:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: query
+        name: owner
+        required: false
+        schema: { type: string }
+        description: >
+          Operator-only — inspect ONE owner's inbox. An ordinary user OMITS it → own scope. Non-owner
+          non-operator → 404 (owner gate, no existence oracle).
+    get:
+      tags: [assistant]
+      operationId: inboxList
+      x-status: live             # ASSISTANT-WIRE-CONTRACT §2 (server.ts ~1388), LIVE on worker.
+      summary: The single severity-sorted HITL inbox (per-user).
+      description: >
+        ASSISTANT-WIRE-CONTRACT §2 — a PER-USER view of pending checkpoints. Each row = a CheckpointSummary
+        (§1) + an `objective` (enriched from task ctx; `null` if unavailable). ALREADY severity-sorted by
+        core's `listPending` — the consumer MUST NOT re-sort, and must tolerate `undefined` severity
+        (present only on human/irreversible_ask gates).
+      responses:
+        '200':
+          description: Severity-sorted inbox rows.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/InboxList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/assistant/tasks:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [assistant]
+      operationId: assistantTasks
+      x-status: live             # ASSISTANT-WIRE-CONTRACT §3 (server.ts ~1410), LIVE on worker.
+      summary: The N-task scheduler overview (per-user cross-task).
+      description: >
+        ASSISTANT-WIRE-CONTRACT §3 — a PER-USER cross-task view = run-store `listRuns(owner)` joined with the
+        core scheduler seam `listByScope`. Triage-ordered server-side (needs-attention first, then severity
+        DESC, then spend DESC) — DO NOT re-sort. Requires the TiDB run store, else `{ "tasks": [] }` (no 501).
+        ⚠️ `createdAt`/`updatedAt` are ISO date-time strings here (unlike inbox/§1 epoch-ms).
+      responses:
+        '200':
+          description: Triage-ordered task rows (empty `{tasks:[]}` when no TiDB run store).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AssistantTaskList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/assistant/tasks/{taskId}/resume:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [assistant]
+      operationId: assistantResume
+      x-status: live             # ASSISTANT-WIRE-CONTRACT §4b (server.ts ~1490), LIVE on worker.
+      summary: Resume a resource_limit-suspended task (CONTINUE).
+      description: >
+        ASSISTANT-WIRE-CONTRACT §4b — resumes a task durably SUSPENDED on a `resource_limit` gate (scheduler
+        preempt OR a budget/turns/walltime slice). NO request body. 🔴 GATE-KIND GUARD: a `human`/`policy_ask`
+        gate → 409 `gate_not_resumable` (a "continue" must NEVER bypass a human approval — use `/decide`).
+        Owner-gated (NOT D-G); non-owner → 404. SDK → GateNotResumableError on the 409.
+      responses:
+        '200':
+          description: Resumed; `{status}` (e.g. "completed").
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status]
+                additionalProperties: true
+                properties:
+                  status: { type: string }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: >
+            `errorCode:"gate_not_resumable"` — the gate is `human`/`policy_ask`, NOT `resource_limit`. A
+            "continue" must NEVER bypass a human approval — resolve via `/v1/approvals/:sessionId/decide`.
+            SEMANTIC (wrong-gate), NOT a session-CAS conflict. SDK → GateNotResumableError.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/assistant/tasks/{taskId}/plan_review:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [assistant]
+      operationId: assistantPlanReview
+      x-status: live             # ASSISTANT-WIRE-CONTRACT §4c (server.ts ~1505), LIVE on worker.
+      summary: Resolve a plan_review gate (3-state approve/edit/reject).
+      description: >
+        ASSISTANT-WIRE-CONTRACT §4c (design/80 D-B) — resolves a PRE-ACTION `plan_review` gate: the human
+        reviews the PLAN (no bound tool action). A SIBLING of `/resume` (owner-gated via the run store), a
+        DISTINCT wire from `/decide` and from the `needs_review` wire. `approve` → resume with the original
+        plan; `edit` → resume with `editedPlan`; `reject` → resume to handle the rejection. approve/edit/reject
+        all run the model → BILLABLE.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PlanReviewRequest' }
+      responses:
+        '200':
+          description: Resolved; `{status}` (e.g. "completed").
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status]
+                additionalProperties: true
+                properties:
+                  status: { type: string }
+        '400':
+          description: >
+            Bad/missing `decision`; `edit` without a non-empty `editedPlan`; `editedPlan` present on
+            approve/reject (FORBIDDEN); non-string `reason`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: >
+            `errorCode:"gate_not_plan_review"` — a non-`plan_review` gate. A plan decision must NEVER resolve a
+            tool approval / resource_limit suspend (the checkpoint is never consumed). SEMANTIC (wrong-gate),
+            NOT a session-CAS conflict. SDK → GateNotPlanReviewError.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/assistant/tasks/{taskId}/preempt:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [assistant]
+      operationId: assistantPreempt
+      x-status: live             # ASSISTANT-WIRE-CONTRACT §4d (server.ts ~1434), LIVE on worker.
+      summary: Gracefully preempt (YIELD) a task.
+      description: >
+        ASSISTANT-WIRE-CONTRACT §4d — durable cross-replica "yield this task" (the OPPOSITE of
+        `/v1/runs/:id/cancel`'s kill). NO body. NOT billable. `202 {status:"preempting"|…}`; a terminal task →
+        `202` no-op; an already-`suspended` task → 409; `RESOURCE_SUSPEND` off → 501. Owner-gated; non-owner → 404.
+      responses:
+        '202':
+          description: Preempting (or 202 no-op on a terminal task); `{status}`.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status]
+                additionalProperties: true
+                properties:
+                  status: { type: string }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: The task is already `suspended` — there is nothing running to yield.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/tasks/{taskId}/turns:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    get:
+      tags: [trace]
+      operationId: traceTurns
+      x-status: live             # shape confirmed the pinned wire contract.
+      summary: Full per-task turn trace (the workspace action timeline).
+      description: >
+        The full turn-by-turn trace that the workspace renders as the action timeline (tool cards, etc.).
+        Requires a `SESSION_BACKEND=tidb` worker. Turn shape is draft (co-design with the artifacts shape, Q7).
+      responses:
+        '200':
+          description: Turn trace — envelope `{ turns, nextCursor?, retainedFrom }` (key `turns`; item shape draft).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/TurnList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /v1/tasks/source-summary:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [trace]
+      operationId: traceSourceSummary
+      x-status: live             # the pinned wire contract — per-door usage rollup (prove-before-scale data spine).
+      summary: Per-source run counts (door-level usage).
+      parameters:
+        - in: query
+          name: sinceSec
+          required: false
+          schema: { type: integer }
+      responses:
+        '200':
+          description: Rollup rows.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rows]
+                properties:
+                  rows:
+                    type: array
+                    items:
+                      type: object
+                      required: [source, status, count]
+                      properties:
+                        source: { type: string }
+                        status: { type: string }
+                        count: { type: integer }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/tasks/{taskId}/artifacts:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    get:
+      tags: [trace]
+      operationId: traceArtifacts
+      x-status: live             # producer shipped (service 2779155 co-signed).
+      summary: Workspace artifacts for a run (projection of the persisted trace).
+      description: >
+        Deterministic projection from persisted tool events — works for ALL historical runs, never drifts from
+        real execution. Job-level aggregation is client-side: `GET /v1/tasks?jobId=X` then fetch per-run
+        artifacts (each carries taskId+jobId). Failed calls / unpaired starts emit nothing.
+      responses:
+        '200':
+          description: Artifacts (possibly empty).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ArtifactList' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/tasks/{taskId}/stream:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    get:
+      tags: [trace]
+      operationId: traceStream
+      x-status: draft            # trace relay (same source/semantics as runs.events); kept for the workspace live view.
+      summary: Trace relay SSE (same source/semantics as runs.events).
+      parameters:
+        - $ref: '#/components/parameters/LastEventId'
+      responses:
+        '200':
+          description: SSE stream of AgentEvents (resumable; same durable source as runs.events).
+          content:
+            text/event-stream:
+              schema: { $ref: '#/components/schemas/AgentEvent' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /v1/usage:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [usage]
+      operationId: usageGet
+      x-status: live             # service GET /v1/usage (shape audited from source). SDK usage.get().
+      summary: Per-principal cost/quota snapshot (the CLI `/cost` panel's real data).
+      description: >
+        READ-ONLY. Worker computes this from the REQUEST principal (crypto-verified on a direct door — never the
+        spoofable header); the client never sends a scope. When no cost-quota window is configured →
+        `{ enabled:false, windowSec, maxTaskCostUsd?, maxTaskTokens? }` (only the single-task ceilings); the caller
+        renders "no quota data" and NEVER blocks on it (enforcement is 100% server-side; this only displays).
+      responses:
+        '200':
+          description: Usage/quota snapshot (enabled=false when no window is configured).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/UsageInfo' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/policy:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [policy]
+      operationId: policyGet
+      x-status: live             # service GET /v1/policy (shape audited from source). SDK policy.get().
+      summary: Effective-governance snapshot (the CLI `/permissions` panel's real data; inspect-only).
+      description: >
+        READ-ONLY snapshot of the worker's effective autonomy band + command policy + approval conditions + limits
+        (worker-GLOBAL config, same for every principal — a principal is OPTIONAL, only enforced under
+        REQUIRE_PRINCIPAL). The CLI renders "what can run automatically, what needs approval, what the ceilings
+        are" from this. 🔴 The client NEVER re-decides/admits commands from this — command admission + approval
+        enforcement is 100% server-side (in resolveSpec); this is pure inspect. The CLI's "permission modes" are
+        TIGHTEN-ONLY client cosmetics and cannot loosen server gating.
+      responses:
+        '200':
+          description: Effective policy snapshot.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/PolicyInfo' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/models:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [models]
+      operationId: modelsList
+      x-status: live             # service GET /v1/models (server.ts:859-882). SDK models.list().
+      summary: Non-secret model catalog (the `@model` picker / autocomplete data source).
+      description: >
+        READ-ONLY catalog of `@mention`-pickable models. The user selects a model PER-TASK by typing `@<name>` in
+        the objective body (the service allowlist-parses it; the client never re-decides). Envelope `{ models, default }`
+        (`default` = the deployment default model id, display-only — the internal `default` alias is hidden).
+        🔴 NON-SECRET: only name/id/provider/reasoning/vision + the E4/E7 capability fields — NEVER baseUrl/apiKey/
+        headers (the service strips them). Fail-safe: on error, render an empty picker (never block).
+      responses:
+        '200':
+          description: Model catalog (possibly empty).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [models, default]
+                properties:
+                  models:
+                    type: array
+                    items: { $ref: '#/components/schemas/ModelInfo' }
+                  default: { type: string, description: "deployment default model id (display-only)" }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+  /v1/elicitations/{id}/respond:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - name: id
+        in: path
+        required: true
+        schema: { type: string }
+        description: the elicitationId from the live `elicitation` SSE frame.
+    post:
+      tags: [elicitations]
+      operationId: elicitationRespond
+      x-status: gated            # service POST /v1/elicitations/:id/respond — present only under MCP_ELICITATION_ENABLED (else 501).
+      summary: Answer an inbound-MCP elicitation (design/99 §E23, LIVE-only HITL).
+      description: >
+        Resolve a parked inbound-MCP elicitation with the user's form answer; the value flows back to the MCP server
+        on the still-open task connection. 🔴 LIVE-ONLY + SAME-REPLICA (the parked promise is in-memory): a respond
+        on another replica / after answer / after the TTL finds nothing → 404. 🔴 OWNER-GATED with a 404 (NO existence
+        oracle): a non-owner AND an unknown id both get 404 — never an existence leak. A malformed body → 400
+        (existence-independent). Not a submit / not idempotent → no client retry.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ElicitResponse' }
+      responses:
+        '200':
+          description: Answer applied (the promise resolved).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ElicitRespondAck' }
+        '400': { description: malformed body (action not accept/decline/cancel, or non-scalar content). }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: no pending elicitation for this id (non-owner, answered, expired, or wrong replica) — no existence oracle. }
+        '501': { description: inbound MCP elicitation is not enabled on this worker (MCP_ELICITATION_ENABLED). }
+
+  /v1/questions/{id}/respond:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - name: id
+        in: path
+        required: true
+        schema: { type: string }
+        description: the questionId from the live `question` SSE frame.
+    post:
+      tags: [questions]
+      operationId: questionRespond
+      x-status: gated            # service POST /v1/questions/:id/respond — present only under ASK_QUESTION_ENABLED (else 501).
+      summary: Answer the agent's own AskUserQuestion (§4④ tool-panorama, LIVE-only HITL).
+      description: >
+        Resolve a parked LIVE AskUserQuestion with the end user's selection; the value flows back to the model on the
+        still-open task connection (the model's AskUserQuestion tool call returns it). The SIBLING of elicitationRespond
+        (that is an inbound-MCP-server ask; this is the AGENT's OWN structured multiple-choice question to the user).
+        🔴 LIVE-ONLY + SAME-REPLICA (the parked promise is in-memory): a respond on another replica / after answer /
+        after the TTL (5 min) finds nothing → 404. 🔴 OWNER-GATED with a 404 (NO existence oracle): a non-owner AND an
+        unknown id both get 404 — never an existence leak. A malformed body → 400 (existence-independent). Not a submit /
+        not idempotent (it resolves an in-flight promise exactly once) → no client retry.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/QuestionAnswer' }
+      responses:
+        '200':
+          description: Answer applied (the parked question promise resolved).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/QuestionRespondAck' }
+        '400': { description: 'malformed body (answers not an array of {header, selected:string[], note?}).' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: no pending question for this id (non-owner, answered, expired, or wrong replica) — no existence oracle. }
+        '501': { description: AskUserQuestion is not enabled on this worker (ASK_QUESTION_ENABLED). }
+
+  /v1/workflows:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [workflows]
+      operationId: workflowsList
+      x-status: gated            # design/97/98; SELF_ORCHESTRATION_ENABLED (default OFF → 501). Owner-scoped (scope = creating principal).
+      summary: List S8 self-orchestration runs (owner-scoped summaries).
+      description: >
+        OWNER-SCOPED — returns ONLY the calling principal's own runs (scope = the run's creating principal,
+        `default` when none). Envelope key = `workflows` (NOT a bare array). REPLICA-LOCAL: this lists the runs the
+        run store on THIS replica knows (durable cross-replica history is a service follow-on). Gated off
+        (SELF_ORCHESTRATION_ENABLED) → 501; the caller fail-safes to empty.
+      parameters:
+        - in: query
+          name: status
+          required: false
+          schema: { $ref: '#/components/schemas/WorkflowRunStatus' }
+          description: Filter by lifecycle status.
+        - in: query
+          name: limit
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
+          description: Max rows (server clamps to 1..100; default 50).
+      responses:
+        '200':
+          description: Owner's workflow-run summaries.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [workflows]
+                properties:
+                  workflows:
+                    type: array
+                    items: { $ref: '#/components/schemas/WorkflowRunSummary' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/workflows/{workflowRunId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/WorkflowRunIdPath'
+    get:
+      tags: [workflows]
+      operationId: workflowsGet
+      x-status: gated            # design/97/98; SELF_ORCHESTRATION_ENABLED (default OFF → 501). Per-id owner gate (non-owner → 404).
+      summary: Full S8 self-orchestration run (phases/agents/stats).
+      description: >
+        Full run detail. OWNER-GATED via the persisted run's scope — a non-owner or unknown id → 404 (NO existence
+        oracle, parity with runs). Gated off → 501.
+      responses:
+        '200':
+          description: Full workflow run.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/WorkflowRun' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/workflows/{workflowRunId}/stream:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/WorkflowRunIdPath'
+    get:
+      tags: [workflows]
+      operationId: workflowsStream
+      x-status: gated            # design/97/98; SELF_ORCHESTRATION_ENABLED (default OFF → 501). In-process subscribeWorkflow; NOT resumable.
+      summary: Live S8 run progress SSE (NON-resumable).
+      description: >
+        LIVE progress. FIRST frame is `event: meta` `{version, runId}`; each subsequent frame carries a core
+        `WorkflowEvent` (its `type` becomes the SSE event name). 🔴 NOT RESUMABLE — the source is REPLICA-LOCAL +
+        in-process (no durable seq, no `Last-Event-ID`); a drop is a FULL restart (re-`GET /v1/workflows/:id` for
+        the snapshot), not a resume. Owner-gated (non-owner → 404). Gated off → 501 (before any frame).
+      responses:
+        '200':
+          description: SSE stream of workflow events (`meta` first, then core WorkflowEvents; non-resumable).
+          content:
+            text/event-stream:
+              schema: { $ref: '#/components/schemas/WorkflowStreamEvent' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/fleet/stream:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [fleet]
+      operationId: fleetStream
+      x-status: live             # service 1bf7a5c — streamFleet (http/server.ts:4874) + fleet/fleet-bus.ts. Owner-gated; in-process bus; NOT resumable.
+      summary: Live multi-row fleet view SSE (NON-resumable).
+      description: >
+        MF-Fleet (shell-host data contract). The LIVE fleet as an SSE PUSH stream: a SNAPSHOT on connect, then a
+        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.
+        🔴 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).
+        🔴 NOT RESUMABLE — replica-local + in-process (no durable seq / Last-Event-ID); a drop is a FULL restart
+        (re-connect for a fresh snapshot), not a resume. No fleet wiring (`deps.fleetBus` absent) → 501 before any frame.
+      responses:
+        '200':
+          description: SSE stream of fleet frames (`meta` first, then `snapshot`, then per-row upserts/removes; non-resumable).
+          content:
+            text/event-stream:
+              schema: { $ref: '#/components/schemas/FleetFrame' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/leader:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [leader]
+      operationId: leaderCreate
+      x-status: gated            # v2 pipeline; LEADER_ENABLED (default OFF) + REMOTE_EXEC=e2b. NOT the default door-B path.
+      summary: Start a v2 leader run (gated; E2B + git push).
+      description: >
+        🔴 The v2 leader pipeline (E2B workers + git push), NOT door B's brain. Gated server-side:
+        `LEADER_ENABLED` (default OFF) + `REMOTE_EXEC=e2b`. Mode is a SERVER deploy flag, not a client choice:
+        `LEADER_FANOUT_ENABLED=true` (default) lets the router fan out to N isolated workers (= the value-HOLD
+        correctness bet); `=false` pins a single worker. Either way it runs the E2B+git pipeline. Door B's brain
+        is the strong single agent via `/v1/tasks`+`/v1/runs`+`scenario`. When disabled → 501.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [objective]
+              additionalProperties: true
+              properties:
+                objective: { type: string }
+                sessionId: { type: string }
+                jobId: { type: string, minLength: 1, maxLength: 64 }
+      responses:
+        '202':
+          description: Leader run accepted.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/LeaderReceipt' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+
+  /v1/leader/{leaderRunId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - in: path
+        name: leaderRunId
+        required: true
+        schema: { type: string }
+    get:
+      tags: [leader]
+      operationId: leaderGet
+      x-status: gated
+      summary: Read leader run state.
+      responses:
+        '200':
+          description: Leader run state.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/LeaderRecord' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /metrics/summary:
+    get:
+      tags: [metrics]
+      operationId: metricsSummary
+      x-status: draft            # ops surface; uses a metricsToken (NOT a principal). Shape loose.
+      summary: Worker health/cost summary (ops).
+      description: Uses `metricsToken` (operator), not `x-agent-principal`. Shape is loose/ops-defined.
+      security:
+        - metricsToken: []
+      responses:
+        '200':
+          description: Metrics summary (shape draft).
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+
+# ─────────────────────────────────────────────────────────────────────────────
+
+components:
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: >
+        Worker `SERVICE_AUTH_TOKEN`. SERVER-SIDE ONLY (the SDK browser guard refuses to construct a
+        token-bearing client in a browser; the portal's browser calls its own BFF). Missing → 503; bad → 401.
+    metricsToken:
+      type: http
+      scheme: bearer
+      description: Operator metrics token (ops only; distinct from the service auth token and from any principal).
+
+  parameters:
+    PrincipalHeader:
+      in: header
+      name: x-agent-principal
+      required: true
+      schema: { $ref: '#/components/schemas/Principal' }
+      description: >
+        Authenticated end-user identity (REQUIRED; principal-first, CORE-PRINCIPLES §3). Opaque to the service
+        (memory scope + session owner key; format NOT validated server-side). The SDK normalizes; anonymous must
+        be explicit (`anon:<id>`). On the multi-tenant doors this is set PER REQUEST.
+    IdempotencyKey:
+      in: header
+      name: idempotency-key
+      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.
+    LastEventId:
+      in: header
+      name: Last-Event-ID
+      required: false
+      schema: { type: string }
+      description: Resume an SSE stream from after this event id (= the durable `task_event.seq`).
+    TaskIdPath:
+      in: path
+      name: taskId
+      required: true
+      schema: { type: string }
+    WorkflowRunIdPath:
+      in: path
+      name: workflowRunId
+      required: true
+      schema: { type: string }
+
+  responses:
+    BadRequest:
+      description: >
+        Bad request — malformed input only (e.g. missing `objective`, or `jobId` present but empty or >64 chars,
+        NOT silently truncated). NOTE: budget rejections are NOT 4xx — they are result-level
+        (HTTP 200 + `TaskResult.errorCode`), see the TaskResult/RateLimited notes (pinned wire contract).
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+    Unauthorized:
+      description: Fail-closed auth — 401 (bad token) / 503 (missing token). Mapped to AuthError.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+    NotFound:
+      description: >
+        No such resource for this principal. Owner-scoped reads/cancel return 404 (not 403) for a non-owned or
+        unknown id — existence is not leaked across principals.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+    Conflict:
+      description: >
+        409 — session already has an active run, OR an idempotency/session-CAS conflict. Body carries
+        `activeTaskId` (the task holding the session lock). ⚠️ The SDK surfaces this as a TYPED ConflictError and
+        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.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+    RateLimited:
+      description: >
+        429 — per-principal CUMULATIVE quota exceeded (`quotaExceeded`). `Retry-After` (seconds) honored by the
+        SDK on retry. This is the ONLY budget/limit signal at the HTTP layer; per-task budget gates are
+        result-level (200 + errorCode), NOT here (pinned wire contract).
+      headers:
+        Retry-After:
+          schema: { type: integer }
+          description: Seconds to wait before retrying.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/QuotaError' }
+    NotImplemented:
+      description: 501 — capability not available (e.g. no TiDB run store; leader gated off; `wake` unsupported).
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+    PayloadTooLarge:
+      description: >
+        413 — the request body exceeded a server cap (2c session-sync: a blob PUT past the 64 MiB per-blob cap, or a
+        Phase-B NDJSON line past the per-line cap). Rejected mid-stream (no unbounded buffer). Not retryable verbatim.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+    UnprocessableEntity:
+      description: >
+        422 — a semantically-invalid submission the server understood but cannot apply (2c session-sync: a referenced
+        blob is missing at import Phase A `missing_blob`, or the staged entry log failed the tree invariants
+        `invalid_entries`). Fix the offending data + retry; deterministic, not a transient.
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  schemas:
+
+    Principal:
+      type: string
+      description: >
+        Opaque end-user identity. Convention (NOT enforced server-side): `user:` / `org:` / `ai:` / `anon:`.
+      examples: ['user:42', 'org:acme', 'anon:7f3c']
+
+    Scenario:
+      type: string
+      description: >
+        Primary routing axis (one image serves many; unknown → "default"). Selects model/tools/skills/prompt.
+      examples: ['default', 'oa', 'code-review', 'team']
+
+    RunStatus:
+      type: string
+      enum: [running, completed, failed, suspended, needs_review]
+      description: >
+        `suspended` = HITL (an F4 policy gate or AskUserQuestion is waiting on a human) — NOT an error.
+        `needs_review` (design/80 D-0) = durable TERMINAL of a dry-run/shadow review (POST-prediction),
+        distinct from the mid-run `suspended` pause. A user-cancelled run is `failed` with `errorCode`
+        "cancelled" (cancel is LIVE; `cancelling` is a cancel-ack field, NOT a member of this enum).
+
+    TaskStats:
+      type: object
+      properties:
+        turns: { type: integer }
+        tokens: { type: integer }
+        promptTokens: { type: integer }
+        cachedTokens: { type: integer }
+        outputTokens: { type: integer }
+        costUsd: { type: number }
+        cacheHitRate: { type: number }
+      required: [turns, tokens]
+
+    TaskRequest:
+      type: object
+      description: >
+        Common request body. `[additionalProperties]` mirrors the service passthrough — scenario-specific fields
+        (code-review's `repo`/`council`/`debate`/`rounds`, etc.) ride here.
+      required: [objective]
+      additionalProperties: true
+      properties:
+        objective:
+          type: string
+          description: The task. Put per-request context here (keep `systemPrompt` stable/cacheable).
+        scenario: { $ref: '#/components/schemas/Scenario' }
+        sessionId:
+          type: string
+          description: Continue a conversation (same sessionId across turns). Omit on first turn → service mints one.
+        jobId:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: >
+            Work-view correlation key (the anti-fragmentation substrate, DIRECTION §2). LIVE server-side
+            (service 63b8696): persisted to `task_run.job_id`, groupable via `GET /v1/tasks?jobId=`.
+            Set one jobId across a job's sub-runs so they group into one Task across BOTH doors. >64 chars or empty
+            → 400 (not silently truncated). The SDK auto-generates one if absent.
+        systemPrompt:
+          type: string
+          maxLength: 16384
+          description: >
+            Business/UX system prompt the CLIENT owns — STABLE per integrator version (cacheable prefix).
+            Server cap 16384 chars → 400.
+        skills:
+          type: array
+          maxItems: 10
+          description: >
+            Per-request user skills (LIVE, service 170c384) — progressive disclosure, same
+            mechanism as scenario skills. Merge: scenario WINS on name collision (user's dropped, warn-logged).
+            Caps server-enforced; violations 400 with the offending rule named.
+          items: { $ref: '#/components/schemas/SkillSpec' }
+        reasoningEffort:
+          type: string
+          enum: [off, minimal, low, medium, high, xhigh, max]
+          description: >
+            Per-turn reasoning strength (CC /effort parity). Mapped to TaskSpec.thinking; an UNKNOWN value
+            is a 400 (fail-loud). Omit ⇒ engine default (the model/role default). The shell stamps the
+            user's /effort pick here per turn.
+        model:
+          type: string
+          description: >
+            Per-turn MODEL (CC /model picker parity). Alias ('sonnet'/'opus') or full id. The service
+            resolveTaskModel CATALOG-GATES it (body.model wins over @mention wins over the deployment default;
+            out-of-roster falls back). Maps to core TaskSpec.model. Omit ⇒ deployment/role default.
+        mcpServers:
+          type: array
+          maxItems: 32
+          description: >
+            Per-request MCP servers (CC .mcp.json parity). The trusted BFF/shell projects the local .mcp.json
+            here so the engine mounts those servers' tools. HONORED only on a SINGLE-USER deployment
+            (mcpInjectionHonored = requirePrincipal!==true); multi-tenant ignores it (fail-closed). Merge:
+            deployment/center baseline wins on name collision (caller can ADD, never SHADOW).
+          items: { $ref: '#/components/schemas/McpServerSpec' }
+        resumeAt:
+          type: string
+          description: >
+            CC Rewind parity (E18). Fork the conversation FROM this user-message SessionTreeEntry.id (non-destructive
+            branch via setLeafId). With rewindFiles=true ⇒ "both" (also restore the working tree). Alone ⇒
+            "conversation". HONORED only where the deployment wired a resume-anchor store + getLeafId (capabilities.resumeAt);
+            unknown anchor ⇒ 4xx, capability-off ⇒ 501. Cannot combine with a durable resume.
+        rewindFiles:
+          type: boolean
+          description: >
+            CC Rewind parity (E18). On a NORMAL turn ⇒ CAPTURE a working-tree snapshot at turn end (per-turn, by leaf;
+            required so later rewinds have something to restore). On a resumeAt turn ⇒ RESTORE the tree to resumeAt's
+            snapshot ("both"). Needs a fileSnapshotStore wired (capabilities.rewindFiles).
+        rewindFilesTo:
+          type: string
+          description: >
+            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.
+        permissionMode:
+          type: string
+          enum: [default, plan, acceptEdits, bypassPermissions]
+          description: >
+            CC permission-mode INTENT. The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE
+            INTERPRETS it (axis-aware, tighten-only): `plan` ⇒ mount present_plan (core enablePlanMode) + read-only
+            hands (handsReadOnly) = CC EnterPlanMode read-only research; `acceptEdits`/`bypassPermissions` are
+            loosening, not honorable remotely (coerced to default engine-side, enforced client-side). Carrying the
+            intent (not pre-interpreted core fields) = one interpretation across frontends + service-owned governance.
+        images:
+          type: array
+          items:
+            oneOf:
+              - type: object
+                required: [data, mimeType]
+                properties:
+                  data: { type: string }
+                  mimeType: { type: string }
+              - type: object
+                required: [url]
+                properties:
+                  url: { type: string }
+        maxCostUsd:
+          type: number
+          description: Caller-requested cost ceiling; server caps to the operator max (may ask less, never more).
+        maxTokens: { type: integer, description: Caller-requested token ceiling; server-capped. }
+        verify:
+          type: boolean
+          description: Adversarial verify gate (impl → independent read-only verify → fix loop). Not on `/v1/tasks/stream`.
+        verifyRounds: { type: integer }
+        cascade:
+          type: boolean
+          description: Quality-gate cascade (cheap→strong). Mutually exclusive with `verify`. Not on the stream.
+        suggestNextPrompts:
+          description: >
+            E12 (shell-host; service spec-fields.ts:9 / runs.ts:392, SHIPPED) — opt-in post-completion "what to ask
+            next" suggestions. After a COMPLETED run, core runs an LLM pass and the service appends a `suggestions`
+            event to the durable run-events tail. `true` = core defaults; the object form tunes count / generating
+            role. 🔴 Mutually exclusive with `verify`/`cascade` (those return a result, not a streamed run → 400).
+            Only meaningful on `/v1/runs` (the sync `/v1/tasks` has no events tail). UNTRUSTED model text (redacted)
+            — UI-only, never re-fed to a model.
+          oneOf:
+            - type: boolean
+            - type: object
+              properties:
+                count: { type: integer }
+                role: { type: string, description: A model role name. }
+
+    TaskResult:
+      type: object
+      description: Synchronous task result (`POST /v1/tasks`).
+      required: [taskId, sessionId, status, stats]
+      properties:
+        taskId: { type: string }
+        sessionId: { type: string }
+        status: { $ref: '#/components/schemas/RunStatus' }
+        result: { type: string }
+        errorCode:
+          type: string
+          description: >
+            Result-level terminal code (NOT an HTTP error). Includes `budget.precall` / `budget.exceeded`
+            (cost gate, non-retryable) — branch on this, not on a 4xx (pinned wire contract).
+        errorMessage: { type: string }
+        stats: { $ref: '#/components/schemas/TaskStats' }
+        verification:
+          type: object
+          description: Present when run behind the verify gate.
+          properties:
+            verdict: { type: string, enum: [PASS, FAIL, PARTIAL, unverified] }
+            rounds: { type: integer }
+            findings: { type: array, items: { type: string } }
+
+    RunReceipt:
+      type: object
+      description: Async run receipt (`POST /v1/runs` → 202). The capability token is NEVER on the wire.
+      required: [taskId, sessionId, status]
+      properties:
+        taskId: { type: string }
+        sessionId: { type: string }
+        status: { $ref: '#/components/schemas/RunStatus' }
+
+    RunRecord:
+      type: object
+      description: >
+        Run state (`GET /v1/runs/:id`) — live shape per the pinned wire contract Drift 2: `result` is the NESTED TaskResult
+        object (output text in result.result, stats in result.stats; NO top-level stats), and the error text
+        field is `error` (not errorMessage; errorCode is floated up from result.errorCode).
+      required: [taskId, sessionId, status]
+      properties:
+        taskId: { type: string }
+        sessionId: { type: string }
+        status: { $ref: '#/components/schemas/RunStatus' }
+        result: { $ref: '#/components/schemas/TaskResult' }
+        errorCode:
+          type: string
+          description: Result-level terminal code (e.g. `budget.exceeded`, `cancelled`); NOT an HTTP error.
+        error: { type: string }
+        jobId:
+          type: string
+          description: Present when the run has a job correlation (omitted when null). LIVE.
+        source:
+          type: string
+          description: >
+            System attribution DERIVED FROM the authenticating credential (unforgeable; body injection ignored).
+            e.g. oa | cc-mcp | portal. LIVE (service cf1be73).
+
+    CancelAck:
+      type: object
+      description: >
+        Synchronous ack for `POST /v1/runs/:id/cancel`. `status` is "cancelling" (accepted) or a terminal status
+        (idempotent no-op). NOTE: "cancelling" is NOT a RunStatus enum member — it only appears here.
+      required: [taskId, status]
+      properties:
+        taskId: { type: string }
+        status: { type: string }
+        note: { type: string }
+
+    ResumeEvicted:
+      type: object
+      description: >
+        416 body for an evicted SSE resume point (`GET /v1/runs/:id/events`). There is NO machine `code` field —
+        match the 416 STATUS and read `retainedFrom`, then full-sync via `/v1/tasks/:id/turns` (pinned SSE contract).
+      required: [error, retainedFrom]
+      properties:
+        error: { type: string }
+        retainedFrom: { type: integer, description: Lowest event seq still retained; resume events from here. }
+
+    QuotaError:
+      type: object
+      description: 429 per-principal cumulative-quota body (`quotaExceeded`).
+      additionalProperties: true
+      properties:
+        error: { type: string }
+        usedMicroUsd: { type: integer }
+        limitMicroUsd: { type: integer }
+        retryAfterSec: { type: integer }
+
+    TraceTurn:
+      type: object
+      description: >
+        Trace turn (true shape, service-pinned). role currently only "assistant" (user/system/tool reserved —
+        the user/objective opening turn is NOT projected today). blocks is an OPEN set; tool-result.output
+        is currently ALWAYS absent (session-storage join not wired — known gap).
+      required: [seq, ts, role, blocks]
+      additionalProperties: true
+      properties:
+        seq: { type: integer }
+        ts: { type: string }
+        role: { type: string }
+        blocks:
+          type: array
+          items:
+            type: object
+            required: [type]
+            additionalProperties: true
+            properties:
+              type: { type: string, description: 'thinking | content | tool-call | tool-result | (open)' }
+              text: { type: string }
+              id: { type: string, description: tool-call — matches approvals toolCallId. }
+              name: { type: string }
+              input: { description: tool-call — redacted args. }
+              callId: { type: string }
+              isError: { type: boolean }
+        tokens:
+          type: object
+          properties:
+            in: { type: integer }
+            out: { type: integer }
+            cacheRead: { type: integer }
+            cacheWrite: { type: integer }
+
+    TurnList:
+      type: object
+      description: >
+        Turn trace envelope (`GET /v1/tasks/:id/turns`). Key is `turns` (resource-named). `retainedFrom` marks
+        the lowest retained seq. Turn ITEM shape is draft (co-design with artifacts, Q7).
+      required: [turns]
+      properties:
+        turns:
+          type: array
+          items: { $ref: '#/components/schemas/TraceTurn' }
+        nextCursor: { type: string }
+        retainedFrom: { type: integer }
+
+    TaskList:
+      type: object
+      description: Paginated run summaries (`GET /v1/tasks`). Envelope key is `tasks` (resource-named, NOT `items`).
+      required: [tasks]
+      properties:
+        tasks:
+          type: array
+          items: { $ref: '#/components/schemas/TaskSummary' }
+        nextCursor: { type: string, description: Keyset cursor for the next page (absent at end). }
+
+    TaskSummary:
+      type: object
+      description: >
+        Run list item (the live `runSummary` cheap summary — the pinned wire contract Drift 1). NOTE the wire names:
+        `id` (not taskId), `startedAt` (not createdAt), `costMicroUsd` (micro-USD ×1e6, not costUsd); no sessionId.
+      required: [id, status, startedAt, lastStep]
+      additionalProperties: true
+      properties:
+        id: { type: string }
+        status: { $ref: '#/components/schemas/RunStatus' }
+        scenario: { type: string }
+        jobId: { type: string }
+        source: { type: string, description: 'Credential-derived system attribution (service-pinned).' }
+        objectivePreview: { type: string, maxLength: 120, description: 'Objective, secret-redacted then truncated (service-pinned; older rows absent).' }
+        owner: { type: string, description: 'Run owner principal (service-pinned; operator view).' }
+        startedAt: { type: string, format: date-time }
+        endedAt: { type: string, format: date-time }
+        turns: { type: integer }
+        tokens: { type: integer }
+        costMicroUsd: { type: integer }
+        lastStep:
+          type: object
+          required: [type]
+          properties:
+            type: { type: string, enum: [thinking, tool-call, responding, idle] }
+            label: { type: string }
+
+    Artifact:
+      type: object
+      description: >
+        Workspace artifact — a deterministic PROJECTION of persisted tool_start/tool_end pairs (no new write
+        path; args already redacted at persist time). Co-signed the pinned wire contract. kind is an OPEN set — render
+        unknown kinds as a generic row, never crash. v1 emits "file" (successful write_file/edit_file, deduped
+        by path) and "git-push" (successful bash containing git push); "diff" is reserved, not emitted.
+      required: [id, taskId, kind, ref, createdAt]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: '"<taskId>:<n>" — stable within the task (UI key).' }
+        taskId: { type: string }
+        jobId: { type: string, description: Present when the run has a job (job-level aggregation key). }
+        kind: { type: string, description: 'Open set; v1: "file" | "git-push" ("diff" reserved).' }
+        ref: { type: string, description: 'file: workspace-relative path; git-push: refspec tail or command.' }
+        summary: { type: string }
+        createdAt: { type: string, format: date-time, description: ts of the last successful contributing call. }
+        additions:
+          type: integer
+          description: file kind only — hunk-level line stats from logged args (NOT a git diff). the pinned wire contract.
+        deletions: { type: integer }
+
+    ArtifactList:
+      type: object
+      required: [artifacts]
+      properties:
+        artifacts:
+          type: array
+          items: { $ref: '#/components/schemas/Artifact' }
+
+    LeaderReceipt:
+      type: object
+      required: [leaderRunId, status]
+      properties:
+        leaderRunId: { type: string }
+        status: { type: string, enum: [running, completed, failed] }
+
+    LeaderRecord:
+      type: object
+      required: [id, status]
+      properties:
+        id: { type: string }
+        status: { type: string, enum: [running, completed, failed] }
+        result: {}
+        error: { type: string }
+
+    ApprovalDecision:
+      type: object
+      description: HITL decision (`POST /v1/approvals/:sessionId/decide`).
+      required: [decision]
+      properties:
+        decision: { type: string, enum: [approve, deny] }
+        answer:
+          description: >
+            AskUserQuestion answer — TRUE WIRE SHAPE (worker-validated, 400 otherwise; found in prod
+            integration, service-pinned): {answers:[{header, selected:string[], note?}]} where header matches
+            the question's header. Omit for a plain F4 approve/deny.
+          type: object
+          properties:
+            answers:
+              type: array
+              items:
+                type: object
+                required: [header, selected]
+                properties:
+                  header: { type: string }
+                  selected: { type: array, items: { type: string } }
+                  note: { type: string }
+        reason: { type: string }
+        # design/80 D-1 — action binding (TOCTOU guard). Read the three off the PendingCheckpoint the human saw
+        # and echo VERBATIM; server resolves THAT exact checkpoint, fail-closed on mismatch (approval_binding_mismatch).
+        # Omit only against a pre-D-1 worker. boundInputHash is OPAQUE — never hashed/recomputed client-side.
+        checkpointToken: { type: string, description: 'Single-use token of the exact checkpoint the human saw.' }
+        boundCallId: { type: string, description: '= PendingCheckpoint.boundCallId (the bound pendingAction.toolCallId).' }
+        boundInputHash: { type: string, description: 'Echo PendingCheckpoint.boundInputHash byte-for-byte; server-minted opaque, NEVER recompute.' }
+        updatedInput:
+          description: >
+            Approve-with-edit (design/37 last-wins): operator's rewritten tool args, applied AFTER the binding
+            check. `boundInputHash` STILL binds the ORIGINAL input the human saw — never hash updatedInput.
+
+    Capabilities:
+      type: object
+      description: >
+        Worker capability map (`GET /v1/capabilities`). Open set — ignore unknown keys.
+        Booleans share deps with the route gates (can't say yes and then 501).
+      required: [version]
+      additionalProperties: true
+      properties:
+        asyncRuns: { type: boolean }
+        artifacts: { type: boolean }
+        approvals: { type: boolean }
+        leader: { type: boolean }
+        version: { type: string }
+        scenarios:
+          type: array
+          items: { type: string }
+        pricingConfigured:
+          type: boolean
+          description: false ⇒ stats.costMicroUsd=0 may mean "no MODEL_COST_* configured", not "free".
+        memory:
+          type: boolean
+          description: Memory transparency endpoints (GET/DELETE /v1/memory) available. the pinned wire contract.
+        memoryWrite:
+          type: boolean
+          description: MF-30 — memory WRITE (append/edit/forget) available (deps.memory.append; server.ts:828).
+        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; server.ts:850). Gate the whole sync surface off this.
+
+    SkillSpec:
+      type: object
+      description: A per-request skill (passed as an object; core-native TaskSpec.skills shape).
+      required: [name, description, content]
+      properties:
+        name: { type: string, maxLength: 64 }
+        description: { type: string, maxLength: 1024 }
+        content: { type: string, maxLength: 32768 }
+
+    McpServerSpec:
+      type: object
+      description: >
+        A per-request MCP server (CC .mcp.json parity) — core-native McpServerSpec shape. stdio = a local
+        command the worker spawns (single-user only); http = a remote streamable-HTTP server.
+      required: [name, transport]
+      properties:
+        name: { type: string }
+        transport:
+          oneOf:
+            - type: object
+              required: [kind, command]
+              properties:
+                kind: { type: string, enum: [stdio] }
+                command: { type: string }
+                args: { type: array, items: { type: string } }
+                env: { type: object, additionalProperties: { type: string } }
+            - type: object
+              required: [kind, url]
+              properties:
+                kind: { type: string, enum: [http] }
+                url: { type: string }
+                headers: { type: object, additionalProperties: { type: string } }
+                principalHeader: { type: string }
+        allowTools: { type: array, items: { type: string } }
+        elicitation: { type: boolean }
+        toolAxes:
+          type: object
+          additionalProperties:
+            type: object
+            properties:
+              effect: { type: string, enum: [read, write] }
+              egress: { type: boolean }
+              irreversibility: { type: string, enum: [always, never] }
+
+    MemoryRecord:
+      type: object
+      description: The caller's own <user_memory> (owner-scoped by construction). content null = empty.
+      required: [scope, content]
+      properties:
+        scope: { type: string }
+        content: { type: ['string', 'null'] }
+
+    MemoryWriteAck:
+      type: object
+      description: MF-30 write ack — unified { ok, id, scope } for append/edit/forget (service; the handler
+        always returns ok — the old src:2880 summary comment that dropped it was a doc-bug). id = the note (unchanged on edit).
+      required: [ok, id, scope]
+      properties:
+        ok: { type: boolean }
+        id: { type: string }
+        scope: { type: string }
+
+    ModelInfo:
+      type: object
+      description: >
+        A non-secret `@model` catalog entry (GET /v1/models; service server.ts:860-880). `name` = the `@handle` the
+        user types in the objective body to pick this model per-task. 🔴 NON-SECRET — name/capabilities only, never
+        baseUrl/apiKey/headers (the service strips them). Open set (additive future fields).
+      required: [name]
+      additionalProperties: true
+      properties:
+        name: { type: string, description: 'the @mention handle (user-pickable model name).' }
+        id: { type: string, description: 'underlying model id (display, e.g. deepseek-v4-pro).' }
+        provider: { type: string }
+        reasoning: { type: boolean, description: 'a reasoning-tier model (picker can badge it).' }
+        vision: { type: boolean, description: 'accepts image input.' }
+        contextWindow: { type: integer, description: 'E4 (SHIPPED) — context-window token DENOMINATOR for the %-used gauge; omitted when unknown.' }
+        maxOutputTokens: { type: integer, description: 'E4 (SHIPPED) — single-call max output tokens; omitted when unknown.' }
+        supportedEffortLevels:
+          type: array
+          items: { type: string }
+          description: 'E7 (SHIPPED) — the /effort picker default set (minimal/low/medium/high); present ONLY for a reasoning model.'
+
+    ElicitResponse:
+      type: object
+      description: >
+        The shell's answer to an inbound-MCP elicitation (= core McpElicitResponse). On `accept`, `content` is a flat
+        record of scalars / string[] — an OPAQUE passthrough core NEVER validates against requestedSchema; the service
+        validates only this OUTER shape. A non-accept carries no content.
+      required: [action]
+      properties:
+        action: { type: string, enum: [accept, decline, cancel] }
+        content:
+          type: object
+          description: 'accept only — submitted form values (flat scalars).'
+          additionalProperties:
+            oneOf:
+              - { type: string }
+              - { type: number }
+              - { type: boolean }
+              - { type: array, items: { type: string } }
+
+    ElicitRespondAck:
+      type: object
+      description: The 200 ack from a successful elicitation respond (service elicitation.ts:267).
+      required: [elicitationId, delivery, action]
+      properties:
+        elicitationId: { type: string }
+        delivery: { const: applied }
+        action: { type: string, enum: [accept, decline, cancel] }
+
+    QuestionAnswer:
+      type: object
+      description: >
+        The shell's answer to a live `question` frame (= core QuestionAnswer, ask-question.ts:69). The service validates
+        only this OUTER shape (`answers[]` of `{header, selected:string[], note?}`); core owns the semantic fence
+        (`selected ⊆ the offered options`, `note` wrapped in an untrusted-DATA fence).
+      required: [answers]
+      properties:
+        answers:
+          type: array
+          items: { $ref: '#/components/schemas/QuestionAnswerItem' }
+
+    QuestionAnswerItem:
+      type: object
+      description: >
+        One question's answer, keyed by the question's `header`. `selected` echoes the EXACT offered option label(s)
+        (core rejects any not in the offered options); single-select → a one-element array, multiSelect → 0..n labels.
+      required: [header, selected]
+      properties:
+        header: { type: string }
+        selected: { type: array, items: { type: string } }
+        note: { type: string, description: 'optional free-text / off-list ("Other") input; core untrusted-fences it.' }
+
+    QuestionRespondAck:
+      type: object
+      description: The 200 ack from a successful question respond (service question.ts:226).
+      required: [questionId, delivery]
+      properties:
+        questionId: { type: string }
+        delivery: { const: applied }
+
+    UsageInfo:
+      type: object
+      description: >
+        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. Open set (additive future fields).
+      required: [enabled]
+      additionalProperties: true
+      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).' }
+        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).' }
+        limitUsd: { type: number, description: 'Window quota ceiling (USD).' }
+        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.' }
+        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).' }
+
+    PolicyInfo:
+      type: object
+      description: >
+        Effective-governance snapshot (GET /v1/policy; shape audited from source). Worker-GLOBAL
+        config (same for every principal). 🔴 INSPECT-ONLY — the client never re-decides/admits from this (command
+        admission + approval enforcement is 100% server-side). Open set; nested shapes permissive (evolution-safe).
+      additionalProperties: true
+      properties:
+        autonomy: { type: ['string', 'null'], description: 'Effective autonomy band (open string; null = unset/default).' }
+        commandPolicy:
+          type: array
+          description: 'Command → decision table (internal shape permissive; read command/decision).'
+          items:
+            type: object
+            additionalProperties: true
+            properties:
+              command: { type: string }
+              decision: { type: string }
+        approvalRequire:
+          type: array
+          description: 'Conditions that force human approval (open structure; passed through, not parsed).'
+          items: {}
+        limits:
+          type: object
+          description: 'Effective ceilings (single-task + principal-level + quota window). Tolerate missing fields.'
+          additionalProperties: true
+          properties:
+            maxTaskCostUsd: { type: number }
+            maxTaskTokens: { type: integer }
+            maxPrincipalCostUsd: { type: number }
+            costQuotaWindowSec: { type: integer }
+
+    WorkflowRunStatus:
+      type: string
+      description: >
+        S8 self-orchestration run lifecycle (core WorkflowRunStatus, workflow-run-store.ts). Open set (oneOf NOT
+        exhaustive — render an unknown future state generically).
+      examples: [running, completed, failed]
+
+    WorkflowRunSummary:
+      type: object
+      description: >
+        GET /v1/workflows list row = core summarizeWorkflowRun projection (owner-scoped; scope = the creating
+        principal). All times are epoch MS. Open set.
+      required: [id, scope, status, phaseCount, agentCount, tokens, startedAt, createdAt]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: 'Run id (= WorkflowRun.id).' }
+        scope: { type: string, description: 'Tenant/group scope (= the creating principal).' }
+        status: { $ref: '#/components/schemas/WorkflowRunStatus' }
+        phaseCount: { type: integer, description: 'Phases recorded.' }
+        agentCount: { type: integer, description: 'Agent-runs recorded.' }
+        tokens: { type: integer, description: 'Total tokens = own + nested (folded in the summary; a triage sort key).' }
+        startedAt: { type: integer, description: 'Start epoch ms.' }
+        endedAt: { type: integer, description: 'End epoch ms (absent while running).' }
+        createdAt: { type: integer, description: 'Record-creation epoch ms (listByScope sort key).' }
+
+    WorkflowRun:
+      type: object
+      description: >
+        GET /v1/workflows/:id full run (core WorkflowRun). Non-owner → 404 (no existence oracle).
+        🔴 phases/agents/stats nested shapes may evolve → permissive (read length/known fields, tolerate the rest).
+      required: [id, scope, status, phases, agents, stats, startedAt, createdAt]
+      additionalProperties: true
+      properties:
+        id: { type: string }
+        scope: { type: string }
+        status: { $ref: '#/components/schemas/WorkflowRunStatus' }
+        phases: { type: array, description: 'Phase records (permissive).', items: {} }
+        agents: { type: array, description: 'Agent-run records (permissive).', items: {} }
+        stats:
+          type: object
+          description: 'Token stats — own at stats.tokens, nested at stats.nested.tokens (R-5 own/nested split).'
+          additionalProperties: true
+          properties:
+            tokens: { type: integer }
+            nested:
+              type: object
+              additionalProperties: true
+              properties:
+                tokens: { type: integer }
+        startedAt: { type: integer }
+        endedAt: { type: integer }
+        createdAt: { type: integer }
+
+    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).
+        NOTE: on the wire this is SSE framing (event name + JSON data), not a JSON body — schema describes one
+        decoded frame.
+      required: [event, data]
+      additionalProperties: true
+      properties:
+        event: { type: string, description: 'SSE event name = "meta" for the opener, else the core WorkflowEvent type (open set).' }
+        data: { type: object, additionalProperties: true, description: 'The frame JSON data: payload (core WorkflowEvent shape; permissive).' }
+
+    # ── MF-Fleet (shell-host data contract) — GET /v1/fleet/stream frame vocabulary (service fleet/fleet-bus.ts) ──
+    FleetTaskStatus:
+      type: string
+      description: >
+        The fleet vocabulary the shell renders (service FleetTaskStatus, fleet-bus.ts:27-36). The service maps its
+        run/workflow status onto this NEUTRAL set: `awaiting approval` = a needs-review/plan-approval park,
+        `waiting` = a durable suspend. CLOSED on the wire; render OPEN (branch known, fall back generically).
+      enum: [queued, running, waiting, stopping, 'awaiting approval', idle, completed, failed, killed]
+    FleetTaskRow:
+      type: object
+      description: >
+        One active task row (service FleetTaskRow fleet-bus.ts:40-54) — MINUS the wire-STRIPPED `scope` (a
+        tenant-isolation field the service removes AFTER the owner-gate; never rendered, never on this wire). A
+        `task` frame carries the POST-MERGE FULL row → replace by `id`, NOT a sparse patch. A subagent child row
+        sets `parentId` (E2 parentToolCallId) + an id of `"<runId> <taskId>"`.
+      required: [id, name, status]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: 'Stable identity (durable runId/taskId; subagent child = "<runId> <taskId>"). Update/remove by this.' }
+        name: { type: string }
+        description: { type: string }
+        parentId: { type: string, description: 'Subagent nesting (E2 parentToolCallId) — top-level when absent.' }
+        status: { $ref: '#/components/schemas/FleetTaskStatus' }
+        elapsedMs: { type: integer }
+        tokens: { type: integer }
+        tokenDir: { type: string, enum: [up, down], description: 'Token-meter direction for the row animation.' }
+        queuedCount: { type: integer }
+        awaitingPlanApproval: { type: boolean }
+    FleetWorkflowRow:
+      type: object
+      description: >
+        One workflow row (service FleetWorkflowRow fleet-bus.ts:57-69) — MINUS the wire-stripped `scope`. `status`
+        is the NEUTRAL workflow run status (running|completed|failed), open on read.
+      required: [id, name, status]
+      additionalProperties: true
+      properties:
+        id: { type: string }
+        name: { type: string }
+        description: { type: string }
+        status: { type: string, description: 'Neutral workflow run status (running|completed|failed; open).' }
+        doneCount: { type: integer }
+        totalCount: { type: integer }
+        failedCount: { type: integer }
+        elapsedMs: { type: integer }
+        tokens: { type: integer }
+    FleetFrame:
+      description: >
+        One decoded frame off GET /v1/fleet/stream (service streamFleet emit set, http/server.ts:4877-4908). On the
+        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.
+        OPEN set — branch on `type`, ignore an unknown future frame.
+      oneOf:
+        - $ref: '#/components/schemas/FleetFrame_meta'
+        - $ref: '#/components/schemas/FleetFrame_snapshot'
+        - $ref: '#/components/schemas/FleetFrame_task'
+        - $ref: '#/components/schemas/FleetFrame_task_remove'
+        - $ref: '#/components/schemas/FleetFrame_workflow'
+        - $ref: '#/components/schemas/FleetFrame_workflow_remove'
+      discriminator:
+        propertyName: type
+        mapping:
+          meta: '#/components/schemas/FleetFrame_meta'
+          snapshot: '#/components/schemas/FleetFrame_snapshot'
+          task: '#/components/schemas/FleetFrame_task'
+          task_remove: '#/components/schemas/FleetFrame_task_remove'
+          workflow: '#/components/schemas/FleetFrame_workflow'
+          workflow_remove: '#/components/schemas/FleetFrame_workflow_remove'
+    FleetFrame_meta:
+      type: object
+      description: 'FIRST frame — `{version, scoped}`. `scoped:true` ⇒ owner-scoped view; `false` ⇒ fleet-wide (operator/trace token).'
+      required: [type, version, scoped]
+      properties:
+        type: { const: meta }
+        version: { type: integer }
+        scoped: { type: boolean }
+    FleetFrame_snapshot:
+      type: object
+      description: 'Connect-time FULL state (the visible, scope-stripped rows). Seed the active-set Map from this.'
+      required: [type, tasks, workflows, ts]
+      properties:
+        type: { const: snapshot }
+        tasks: { type: array, items: { $ref: '#/components/schemas/FleetTaskRow' } }
+        workflows: { type: array, items: { $ref: '#/components/schemas/FleetWorkflowRow' } }
+        ts: { type: integer }
+    FleetFrame_task:
+      type: object
+      description: 'A task-row UPSERT — `row` is the POST-MERGE FULL row → replace the Map entry by `row.id`.'
+      required: [type, row, ts]
+      properties:
+        type: { const: task }
+        row: { $ref: '#/components/schemas/FleetTaskRow' }
+        ts: { type: integer }
+    FleetFrame_task_remove:
+      type: object
+      description: 'A task row left the active set (terminal + swept) → delete `id` from the Map.'
+      required: [type, id, ts]
+      properties:
+        type: { const: task_remove }
+        id: { type: string }
+        ts: { type: integer }
+    FleetFrame_workflow:
+      type: object
+      description: 'A workflow-row UPSERT — `row` is the POST-MERGE FULL row → replace by `row.id`.'
+      required: [type, row, ts]
+      properties:
+        type: { const: workflow }
+        row: { $ref: '#/components/schemas/FleetWorkflowRow' }
+        ts: { type: integer }
+    FleetFrame_workflow_remove:
+      type: object
+      description: 'A workflow row left the active set → delete `id`.'
+      required: [type, id, ts]
+      properties:
+        type: { const: workflow_remove }
+        id: { type: string }
+        ts: { type: integer }
+
+    TraceStreamEvent:
+      type: object
+      description: >
+        One frame of GET /v1/tasks/:id/stream — the workspace LIVE timeline (streamTaskTrace + mapTraceEvent). A
+        DISTINCT vocabulary from AgentEvent (the durable log is BLOCK-grained, each frame is a delta to append).
+        Resumable (each `id:` = the durable task_event.seq; on 416 the server returns `{retainedFrom}` and the SDK
+        resumes from there after a turns full-sync). Known events: meta / block-thinking-delta / block-content-delta
+        / tool-call / tool-result / turn / done / error (+ heartbeat keep-alives the SDK swallows). Open set.
+        NOTE: SSE framing on the wire (event name + JSON data + optional id), not a JSON body.
+      required: [event, data]
+      additionalProperties: true
+      properties:
+        event: { type: string, description: 'SSE event name (open set; dispatch on this).' }
+        id: { type: string, description: 'The durable seq (id: line) when present — feed back as Last-Event-ID to resume. meta/heartbeat carry none.' }
+        data: { type: object, additionalProperties: true, description: 'The frame JSON data: payload (shape varies by event; permissive).' }
+
+    PendingList:
+      type: object
+      description: Envelope for pending HITL checkpoints (key `pending`, NOT a bare array — the pinned wire contract).
+      required: [pending]
+      properties:
+        pending:
+          type: array
+          items: { $ref: '#/components/schemas/PendingCheckpoint' }
+
+    ExemptionList:
+      type: object
+      description: Envelope for a session's approval exemptions (; key `exemptions`, NOT a bare array).
+      required: [exemptions]
+      properties:
+        exemptions:
+          type: array
+          items: { $ref: '#/components/schemas/ApprovalExemption' }
+
+    ApprovalExemption:
+      type: object
+      description: >
+        One granted "don't ask again" exemption (service ApprovalExemptionRow). An APPROVAL
+        MEMORY only — deny/neverAuto always outrank it; it never loosens the session-policy layer.
+      required: [toolName, grantedBy, createdAt]
+      properties:
+        toolName: { type: string, description: Canonical tool name the exemption covers. }
+        grantedBy:
+          type: ['string', 'null']
+          description: Principal that granted it; null = ownerless/anonymous grant.
+        createdAt: { type: number, description: Epoch MS of the FIRST grant (re-grant refreshes grantedBy only). }
+
+    PendingCheckpoint:
+      type: object
+      description: >
+        A pending HITL checkpoint (true shape). NEVER includes a capability token.
+        ⚠️ `createdAt`/`deadline` are EPOCH MILLISECONDS (numbers), not ISO strings.
+        🔴 ASSISTANT-WIRE-CONTRACT §1/§7 (service main 6cd0164 / core 1.110.0): this MIRRORS the core
+        `CheckpointSummary` — `token`/`gateKind`/`severity?`/`spentMicroUsd?` are §1 fields (the inbox endpoint
+        projects the full set; legacy `/v1/approvals` may omit them, so they are optional here). Project ONLY
+        the `severity` SCALAR — NEVER a `riskDescriptor` object.
+      required: [sessionId, scope]
+      additionalProperties: true
+      properties:
+        sessionId: { type: string, description: 'The decide handle: POST /v1/approvals/:sessionId/decide.' }
+        token: { type: string, description: 'ASSISTANT §1 — resume capability token (opaque; echo, never parse).' }
+        gateKind:
+          type: string
+          enum: [human, irreversible_ask, resource_limit, needs_review, plan_review, task_done]
+          description: 'ASSISTANT §1 — which kind of pause (6-arm open set).'
+        severity:
+          type: integer
+          enum: [1, 2, 3, 4, 5]
+          description: >
+            ASSISTANT §1 — deterministic risk tier = the inbox SORT KEY. PRESENT ONLY for human/irreversible_ask
+            gates; ABSENT for resource_limit/needs_review/plan_review — the UI MUST tolerate undefined.
+        spentMicroUsd: { type: number, description: 'ASSISTANT §1 — cumulative spend on the suspend chain.' }
+        taskId: { type: ['string', 'null'], description: 'Suspended run holding the session claim (service-pinned) — join key to trace tool-call blocks + context link.' }
+        scope: { type: string, description: 'Principal; "_" = submitted without one.' }
+        toolName: { type: ['string', 'null'], description: Tool awaiting approval (AskUserQuestion = the question gate). }
+        toolCallId: { type: ['string', 'null'] }
+        input:
+          description: >
+            The pending tool call's args (post-hook), REDACTED + size-bounded — for a tool gate the write
+            payload, for an AskUserQuestion the question itself. Lets the approval card render WITHOUT an N+1
+            `trace.turns` fetch per item. Oversized payloads collapse to `{ truncated, bytes }`.
+            `null` for checkpoints suspended before this field existed (consumer falls back to the trace join).
+        # design/80 D-1 — the three binding values the human implicitly approves; the consumer reads them here
+        # and echoes them VERBATIM into decide (TOCTOU guard). Absent on pre-D-1 checkpoints → omit from decide.
+        checkpointToken: { type: string, description: 'Single-use token for the exact pending checkpoint the human saw.' }
+        boundCallId: { type: string, description: '= toolCallId of the action the human saw (the bound call).' }
+        boundInputHash: { type: string, description: 'Server-minted OPAQUE sha256 over the pending action args; echo verbatim, NEVER recompute. Binds the input the human SAW, not any updatedInput.' }
+        createdAt: { type: integer, description: epoch ms. }
+        deadline: { type: ['integer', 'null'], description: epoch ms; expired checkpoints are reaped. }
+
+    # ── assistant-scheduler wire (ASSISTANT-WIRE-CONTRACT.md, service main 6cd0164 / core 1.110.0, LIVE) ──
+    CheckpointSummary:
+      type: object
+      description: >
+        ASSISTANT-WIRE-CONTRACT §1 — core's lightweight projection of every PENDING checkpoint
+        (`summarizeCheckpoint`, identical across all store backends). The shared inbox/overview row shape.
+        Null-able fields are OMITTED when absent, not null. 🔴 projects ONLY the `severity` SCALAR — NO
+        `riskDescriptor` object.
+      required: [token, sessionId, scope, gateKind]
+      additionalProperties: true
+      properties:
+        token: { type: string, description: 'resume capability token (opaque; echo, never parse).' }
+        sessionId: { type: string, description: 'the suspended task/session id.' }
+        scope: { type: string, description: 'the multi-tenant owner scope.' }
+        gateKind:
+          type: string
+          enum: [human, irreversible_ask, resource_limit, needs_review, plan_review, task_done]
+          description: 'which kind of pause (6-arm open set).'
+        severity:
+          type: integer
+          enum: [1, 2, 3, 4, 5]
+          description: >
+            deterministic risk tier = the inbox SORT KEY. PRESENT ONLY for human/irreversible_ask gates
+            (they carry a RiskDescriptor); ABSENT for resource_limit/needs_review/plan_review — UI tolerates undefined.
+        spentMicroUsd: { type: number, description: 'cumulative spend on the suspend chain (when a resource ledger is attached).' }
+        deadline: { type: integer, description: 'awaiting-human SLA deadline (epoch ms).' }
+
+    InboxRow:
+      description: >
+        ASSISTANT-WIRE-CONTRACT §2 — an inbox row = a CheckpointSummary + an `objective` (enriched from the
+        task ctx; `null` if unavailable).
+      allOf:
+        - $ref: '#/components/schemas/CheckpointSummary'
+        - type: object
+          properties:
+            objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
+
+    InboxList:
+      type: object
+      description: 'ASSISTANT-WIRE-CONTRACT §2 — `GET /v1/assistant/inbox` envelope. Already severity-sorted by core.'
+      required: [inbox]
+      additionalProperties: true
+      properties:
+        inbox:
+          type: array
+          items: { $ref: '#/components/schemas/InboxRow' }
+
+    AssistantTaskRow:
+      type: object
+      description: >
+        ASSISTANT-WIRE-CONTRACT §3 — a scheduler-overview row = run-store `listRuns(owner)` joined with the core
+        scheduler seam. ⚠️ `createdAt`/`updatedAt` are ISO date-time strings (unlike inbox/§1 epoch-ms).
+      required: [taskId, sessionId, status, needsAttention, createdAt, updatedAt]
+      additionalProperties: true
+      properties:
+        taskId: { type: string }
+        sessionId: { type: string }
+        status: { type: string, enum: [running, suspended] }
+        needsAttention: { type: boolean, description: '= suspended on a HITL gate.' }
+        gate:
+          type: ['object', 'null']
+          description: 'the active gate, or null. severity/spentMicroUsd/deadline may themselves be null on the wire.'
+          additionalProperties: true
+          properties:
+            kind: { type: string, description: 'same open set as gateKind.' }
+            severity: { type: ['integer', 'null'], enum: [1, 2, 3, 4, 5, null] }
+            spentMicroUsd: { type: ['number', 'null'] }
+            deadline: { type: ['integer', 'null'], description: epoch ms. }
+        createdAt: { type: string, description: ISO date-time. }
+        updatedAt: { type: string, description: ISO date-time. }
+
+    AssistantTaskList:
+      type: object
+      description: >
+        ASSISTANT-WIRE-CONTRACT §3 — `GET /v1/assistant/tasks` envelope. Triage-ordered by core (needs-attention
+        first, then severity DESC, then spend DESC). Empty `{tasks:[]}` when no TiDB run store.
+      required: [tasks]
+      additionalProperties: true
+      properties:
+        tasks:
+          type: array
+          items: { $ref: '#/components/schemas/AssistantTaskRow' }
+
+    PlanReviewRequest:
+      type: object
+      description: >
+        ASSISTANT-WIRE-CONTRACT §4c — `POST /v1/assistant/tasks/:id/plan_review` body (3-state). `editedPlan` is
+        REQUIRED iff `decision==="edit"` (FORBIDDEN otherwise → 400).
+      required: [decision]
+      additionalProperties: false
+      properties:
+        decision: { type: string, enum: [approve, edit, reject] }
+        editedPlan: { type: string, description: 'the operator''s revised plan — required iff decision==="edit".' }
+        reason: { type: string }
+
+    SessionRecord:
+      type: object
+      description: >
+        Session audit (`GET /v1/sessions/:id`) — true shape. `messages` = current model context
+        (older history folded into a summary message); can be large.
+      required: [sessionId, createdAt, messages]
+      additionalProperties: true
+      properties:
+        sessionId: { type: string }
+        owner: { type: ['string', 'null'], description: Principal. }
+        createdAt: { type: string, description: ISO timestamp (NOTE — unlike approvals' epoch-ms). }
+        floorEntryId: { type: ['string', 'null'], description: Compaction window floor; null = never compacted. }
+        thinkingLevel: { type: string }
+        model:
+          type: ['object', 'null']
+          properties:
+            provider: { type: string }
+            modelId: { type: string }
+        messages:
+          type: array
+          items: {}
+
+    SessionSummary:
+      type: object
+      description: >
+        E16 (shell-host sessionPicker; service SessionSummary tidb-run-store.ts:42) — a `GET /v1/sessions` list row
+        aggregating a session's run ledger (last activity + most-recent objective preview + status). owner-scoped.
+        All timestamps ISO. `objectivePreview` is service-redacted + truncated (genuinely `null` when no run).
+      required: [sessionId, owner, lastActivityAt, firstActivityAt, runCount, objectivePreview, lastStatus]
+      additionalProperties: true
+      properties:
+        sessionId: { type: string }
+        owner: { type: ['string', 'null'] }
+        lastActivityAt: { type: string }
+        firstActivityAt: { type: string }
+        runCount: { type: integer }
+        objectivePreview: { type: ['string', 'null'] }
+        lastStatus: { type: string }
+
+    SessionListPage:
+      type: object
+      description: Keyset page envelope for `GET /v1/sessions`. `nextCursor` absent = last page.
+      required: [sessions]
+      properties:
+        sessions:
+          type: array
+          items: { $ref: '#/components/schemas/SessionSummary' }
+        nextCursor: { type: string, description: "Opaque keyset cursor (echo verbatim as ?cursor=)." }
+
+    SessionPermissionRules:
+      type: object
+      description: >
+        E6 (shell-host permissionMode; core SessionPermissionRules session-policy-store.ts:23) — operator-tightened
+        per-session tool-permission rules (core reads them at prepare-time, SUBTRACT-only). 5 optional `string[]`
+        fields. tighten-only invariant is core-enforced (a loosen needs an operator).
+      properties:
+        toolAllow: { type: array, items: { type: string }, description: Narrowing allowlist (only these tools allowed). }
+        toolDeny: { type: array, items: { type: string }, description: Always-denied tool names (deny wins). }
+        allowDirs: { type: array, items: { type: string }, description: Write tools confined to these dirs; bash denied while set. }
+        commandAllow: { type: array, items: { type: string }, description: "Only these bash command names (argv[0]) allowed." }
+        commandDeny: { type: array, items: { type: string }, description: "Always-denied bash command names (argv[0])." }
+
+    StoredSessionRules:
+      description: '{@link SessionPermissionRules} + the monotonic `rev` the store stamps (the OCC key).'
+      allOf:
+        - $ref: '#/components/schemas/SessionPermissionRules'
+        - type: object
+          required: [rev]
+          properties:
+            rev: { type: integer }
+
+    McpServerStatus:
+      type: object
+      description: >
+        E9 (shell-host mcpStatus; core McpServerStatus core/mcp.ts:76) — one MCP server's status at materialization
+        time. `status` is connected | failed (core never emits disabled). `error` (failed only) is service-redacted
+        + length-bounded.
+      required: [name, status]
+      additionalProperties: true
+      properties:
+        name: { type: string }
+        status: { type: string, description: "connected | failed (open set)" }
+        serverInfo:
+          type: object
+          properties:
+            name: { type: string }
+            version: { type: string }
+        toolNames: { type: array, items: { type: string } }
+        error: { type: string }
+
+    McpStatusPanel:
+      type: object
+      description: >
+        `GET /v1/sessions/:id/mcp` envelope. `asOf` = THIS materialization moment (ISO). `degraded:true` (servers
+        empty) ⇒ materialize timed out/failed (NOT "no MCP"). No MCP configured ⇒ `servers:[]` without `degraded`.
+      required: [asOf, servers]
+      additionalProperties: true
+      properties:
+        asOf: { type: string }
+        servers:
+          type: array
+          items: { $ref: '#/components/schemas/McpServerStatus' }
+        degraded: { type: boolean }
+
+    # ── 2c session-sync (P1d) — the cloud-as-a-SYNC-PEER schemas ──────────────────────────────────────────────
+    SyncEntry:
+      type: object
+      description: >
+        ONE session-tree entry as it crosses the sync wire — OPAQUE to the SDK (verbatim, cross-backend-stable ids).
+        The SDK reads only `.id` (for the §7 id-set classify) and pipes the rest through untouched; the cloud
+        re-validates the whole tree (unique ids / parent-before-child / one-root / leaf-resolvable).
+      required: [id]
+      additionalProperties: true
+      properties:
+        id: { type: string, description: Stable entry id, unique within a session (the §7 divergence key). }
+        parentId: { type: [string, 'null'] }
+        type: { type: string, description: Entry discriminator (message / leaf / compaction / …) — opaque to the SDK. }
+
+    SyncSnapshot:
+      type: object
+      description: >
+        One E19 file snapshot keyed by a `SessionTreeEntry.id`. `manifest` = `[relPath, blobHash]` tuples; the blob
+        BYTES are NOT inlined (they ride the content-addressed blob routes).
+      required: [key, manifest]
+      properties:
+        key: { type: string }
+        manifest:
+          type: array
+          items:
+            type: array
+            minItems: 2
+            maxItems: 2
+            items: { type: string }
+            description: A `[relPath, blobHash]` tuple.
+
+    SyncAnchor:
+      type: object
+      description: One E18 resume-at anchor. `owner` is RE-KEYED to the importing principal on a PUSH (§9).
+      required: [eventId, entryId, owner]
+      properties:
+        eventId: { type: string }
+        entryId: { type: string }
+        owner: { type: [string, 'null'] }
+
+    SessionRulesRecord:
+      type: object
+      description: A (principal, rules) policy record — one row across ALL principals (E6 `listBySession`). Replayed verbatim on import (the cloud applies the tighten-only gate).
+      required: [rules]
+      properties:
+        principal: { type: string, description: Absent = the session-default rules. }
+        rules: { $ref: '#/components/schemas/StoredSessionRules' }
+
+    SessionManifest:
+      type: object
+      description: >
+        2c session-sync `GET …/sync/manifest` payload (wrapped server-side as `{ manifest }`). The THIN cross-backend
+        snapshot: entry IDS (oldest-first, NOT payloads) + per-snapshot relPath→blobHash + policy + anchors + leaf.
+      required: [sessionId, entryIds, entryCount, leafId, snapshots, policy, anchors]
+      properties:
+        sessionId: { type: string }
+        entryIds: { type: array, items: { type: string }, description: Oldest-first, verbatim cross-backend. }
+        entryCount: { type: integer, description: '= entryIds.length (the `/sync/entries` trailer count).' }
+        leafId: { type: [string, 'null'] }
+        snapshots: { type: array, items: { $ref: '#/components/schemas/SyncSnapshot' } }
+        policy: { type: array, items: { $ref: '#/components/schemas/SessionRulesRecord' } }
+        anchors: { type: array, items: { $ref: '#/components/schemas/SyncAnchor' } }
+
+    SessionBundle:
+      type: object
+      description: >
+        The portable state of ONE session, ready to replay into another backend. Blobs are NOT inlined (each
+        snapshot carries only its `manifest`; the bytes stream through the content-addressed blob routes). The SDK
+        assembles this from a manifest + the streamed entries for a PUSH.
+      required: [sessionId, entries, snapshots, policy, anchors]
+      properties:
+        sessionId: { type: string }
+        entries: { type: array, items: { $ref: '#/components/schemas/SyncEntry' } }
+        snapshots: { type: array, items: { $ref: '#/components/schemas/SyncSnapshot' } }
+        policy: { type: array, items: { $ref: '#/components/schemas/SessionRulesRecord' } }
+        anchors: { type: array, items: { $ref: '#/components/schemas/SyncAnchor' } }
+
+    SyncRelation:
+      description: >
+        §7 — how a SOURCE log relates to a DESTINATION log, decided over the entry-ID SETS. A discriminated union on
+        `relation`. `fresh`/`identical` carry nothing else; `fast_forward` the appended tail; `stale` the dst entries
+        the src lacks; `fork` the common ancestor + each side's exclusive ids.
+      oneOf:
+        - type: object
+          required: [relation]
+          properties: { relation: { const: fresh } }
+        - type: object
+          required: [relation]
+          properties: { relation: { const: identical } }
+        - type: object
+          required: [relation, newEntryIds]
+          properties:
+            relation: { const: fast_forward }
+            newEntryIds: { type: array, items: { type: string } }
+        - type: object
+          required: [relation, dstAheadBy]
+          properties:
+            relation: { const: stale }
+            dstAheadBy: { type: array, items: { type: string } }
+        - type: object
+          required: [relation, commonAncestor, srcExclusive, dstExclusive]
+          properties:
+            relation: { const: fork }
+            commonAncestor: { type: [string, 'null'] }
+            srcExclusive: { type: array, items: { type: string } }
+            dstExclusive: { type: array, items: { type: string } }
+      discriminator:
+        propertyName: relation
+        mapping:
+          fresh: '#/components/schemas/SyncRelation'
+          identical: '#/components/schemas/SyncRelation'
+          fast_forward: '#/components/schemas/SyncRelation'
+          stale: '#/components/schemas/SyncRelation'
+          fork: '#/components/schemas/SyncRelation'
+
+    ImportStaged:
+      type: object
+      description: >
+        `POST …/sync/import` Phase-A result. `identical` → no `stagingId` (skip Phase B); `fresh`/`fast_forward` →
+        `{ stagingId, relation }`. `relation` is the BARE classifier tag (not the full object).
+      required: [relation]
+      properties:
+        stagingId: { type: string, description: Present iff Phase B is needed (absent on `identical`). }
+        relation: { type: string, enum: [fresh, identical, fast_forward], description: The §7 tag classified at Phase A. }
+
+    ImportCommitted:
+      type: object
+      description: '`POST …/sync/import/:stagingId/entries` (Phase B) commit result — the AUTHORITATIVE in-txn re-classify tag.'
+      required: [relation]
+      properties:
+        relation: { type: string, enum: [fresh, identical, fast_forward], description: The committed §7 tag. }
+
+    SyncConflict:
+      type: object
+      description: >
+        409 body for a 2c session-sync PUSH that would lose destination history. `errorCode:"conflict"` + the §7
+        `relation` (`fork`/`stale`) carrying the exclusive entry sets → the SDK surfaces a typed SyncConflictError.
+        The SAME envelope also carries an active-run / in-flight-import conflict WITHOUT a `relation` (ConflictError).
+      additionalProperties: true
+      properties:
+        error: { type: string }
+        errorCode: { type: string, enum: [conflict, session_active, import_in_flight] }
+        relation: { $ref: '#/components/schemas/SyncRelation' }
+        activeTaskId: { type: string, description: Present on `session_active` — the task holding the session lock. }
+
+    ErrorResponse:
+      type: object
+      description: >
+        Typed-error source. The SDK maps (status, errorCode) → a semantic error class so callers branch on the
+        error, not a string. Messages are secret-scrubbed before surfacing.
+      additionalProperties: true
+      properties:
+        errorCode:
+          type: string
+          description: >
+            HTTP-error typed code. Known: `conflict` (409 session active / CAS), `quotaExceeded` (429).
+            NOTE: budget (`budget.precall`/`budget.exceeded`) and `cancelled` are RESULT-level codes on
+            TaskResult/RunRecord, NOT HTTP errors (pinned wire contract).
+        error: { type: string }
+        errorMessage: { type: string }
+        activeTaskId:
+          type: string
+          description: On a 409 — the task currently holding the session lock (see the Conflict response note).
+
+    # ── Streaming event taxonomy (the UX 命脉). Each SSE `data:` line is one JSON-serialized AgentEvent. ──
+    # TWO vocabularies (the pinned wire contract Drift 3):
+    #   live  (POST /v1/tasks/stream):  text_delta / reasoning_delta (delta = string fragment, core-native)
+    #                                   + tool_start/tool_end/turn_end/compacted/done
+    #   durable (GET /v1/runs/:id/events): text / reasoning (turn-AGGREGATED, no deltas)
+    #                                   + tool_start/tool_end/turn_end/compacted/suspended/done/failed
+    AgentEvent:
+      oneOf:
+        - $ref: '#/components/schemas/Event_reasoning'
+        - $ref: '#/components/schemas/Event_text'
+        - $ref: '#/components/schemas/Event_reasoning_delta'
+        - $ref: '#/components/schemas/Event_text_delta'
+        - $ref: '#/components/schemas/Event_tool_start'
+        - $ref: '#/components/schemas/Event_tool_end'
+        - $ref: '#/components/schemas/Event_turn_end'
+        - $ref: '#/components/schemas/Event_compacted'
+        - $ref: '#/components/schemas/Event_suggestions'
+        - $ref: '#/components/schemas/Event_status'
+        - $ref: '#/components/schemas/Event_task_progress'
+        - $ref: '#/components/schemas/Event_workspace_changed'
+        - $ref: '#/components/schemas/Event_suspended'
+        - $ref: '#/components/schemas/Event_done'
+        - $ref: '#/components/schemas/Event_failed'
+      discriminator:
+        propertyName: type
+        mapping:
+          reasoning: '#/components/schemas/Event_reasoning'
+          text: '#/components/schemas/Event_text'
+          reasoning_delta: '#/components/schemas/Event_reasoning_delta'
+          text_delta: '#/components/schemas/Event_text_delta'
+          tool_start: '#/components/schemas/Event_tool_start'
+          tool_end: '#/components/schemas/Event_tool_end'
+          turn_end: '#/components/schemas/Event_turn_end'
+          compacted: '#/components/schemas/Event_compacted'
+          suggestions: '#/components/schemas/Event_suggestions'
+          status: '#/components/schemas/Event_status'
+          task_progress: '#/components/schemas/Event_task_progress'
+          workspace_changed: '#/components/schemas/Event_workspace_changed'
+          suspended: '#/components/schemas/Event_suspended'
+          done: '#/components/schemas/Event_done'
+          failed: '#/components/schemas/Event_failed'
+
+    # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
+    # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
+    # `text` re-stamps the turn's first text_delta eventId, runs.ts:250); parentToolCallId = sub-agent attribution.
+    EventIdentity:
+      type: object
+      properties:
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+    Event_reasoning:
+      type: object
+      description: durable stream only — turn-aggregated thinking.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, text]
+      properties:
+        type: { const: reasoning }
+        text: { type: string }
+    Event_text:
+      type: object
+      description: durable stream only — turn-aggregated answer text (carries the E18 resume-handle eventId).
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, text]
+      properties:
+        type: { const: text }
+        text: { type: string }
+    Event_reasoning_delta:
+      type: object
+      description: live stream only — per-token thinking fragment (`delta` is the string fragment).
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, delta]
+      properties:
+        type: { const: reasoning_delta }
+        delta: { type: string }
+    Event_text_delta:
+      type: object
+      description: live stream only — per-token answer fragment.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, delta]
+      properties:
+        type: { const: text_delta }
+        delta: { type: string }
+    Event_tool_start:
+      type: object
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, toolCallId, toolName]
+      properties:
+        type: { const: tool_start }
+        toolCallId: { type: string }
+        toolName: { type: string }
+        args: {}
+    Event_tool_end:
+      type: object
+      description: >
+        design/99 §E1 (SHIPPED) — `output` is the model-facing action-card BODY: NON-UNIFORM (a string, or a
+        (TextContent|ImageContent)[] block array) and degrades to a single TRUNCATED string over the core size cap
+        (`truncated: true`). Absent ⇒ the tool produced no body. 🔴 UNTRUSTED RAW + observability-only: the service
+        has redactDeep'd + size-bounded it; a consumer MAY further bound, MUST never re-feed it to a model.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, toolCallId, toolName, isError]
+      properties:
+        type: { const: tool_end }
+        toolCallId: { type: string }
+        toolName: { type: string }
+        isError: { type: boolean }
+        output: {}   # NON-UNIFORM: string | (TextContent|ImageContent)[] | (truncated) string. Absent ⇒ no body.
+        truncated: { type: boolean }  # true ⇒ output was size-bounded to a truncated string.
+    Event_turn_end:
+      type: object
+      required: [type]
+      properties:
+        type: { const: turn_end }
+        usage:
+          type: object
+          description: Full live shape — the portal cost bar's data source.
+          properties:
+            inputTokens: { type: integer }
+            outputTokens: { type: integer }
+            cacheReadTokens: { type: integer }
+            cacheWriteTokens: { type: integer }
+            costMicroUsd: { type: integer }
+    Event_compacted:
+      type: object
+      required: [type]
+      properties:
+        type: { const: compacted }
+        tokensBefore: { type: integer }
+    Event_suggestions:
+      type: object
+      description: >
+        E12 (shell-host; service runs.ts:392 + server.ts:3633, opt-in via `TaskRequest.suggestNextPrompts`) —
+        post-completion "what to ask next" prompt suggestions. Appended to the DURABLE run-events tail AFTER a
+        `done` with `status:"completed"` (core's fire-and-forget LLM pass). 🔴 UNTRUSTED model text, service-
+        redacted, UI-ONLY — render as clickable next-prompt chips; NEVER re-feed to a model. Empty/absent ⇒ none.
+      required: [type, suggestions]
+      properties:
+        type: { const: suggestions }
+        suggestions: { type: array, items: { type: string } }
+    Event_status:
+      type: object
+      description: >
+        design/99 §E3/§E10 (SHIPPED, LIVE-only) — a brain-layer liveness status the brain would otherwise absorb
+        silently (429 rate-limit / 5xx-or-network retry / reconnect / open circuit breaker). EPHEMERAL — never
+        persisted/replayed on resume; provider-neutral (NO HTTP status / stop_reason). `phase` is core's closed
+        BrainStatusPhase but render open (a deployment may add a phase on its own channel).
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, phase]
+      properties:
+        type: { const: status }
+        phase: { type: string, description: "rate_limited | retrying | reconnecting | circuit_open (open set)" }
+        detail: { type: string, description: "neutral human hint (NO provider/HTTP detail)" }
+        retryInSec: { type: number }
+    Event_task_progress:
+      type: object
+      description: >
+        design/99 MF-10 (core 1.147+, `task_progress` arm) — a SUBAGENT PROGRESS TICK: a delegated sub-run's usage
+        ACCRUING at each turn boundary WHILE it runs (tokens/tool-uses climbing), so a parent UI animates the Task
+        card rollup. Emitted ONLY for a subagent (a task carrying a `parentToolCallId`, via EventIdentity); a
+        top-level run's own usage is the consumer's own (turn_end). `status` is the literal "running" (the terminal
+        usage is the `done` result). LIVE/EPHEMERAL — NOT persisted, NOT replayed on resume.
+        🔴 WIRE NOTE: core mints this arm, but as of service 1bf7a5c NO service projection forwards it onto a CLIENT
+        wire (/v1/tasks/stream or /v1/runs/:id/events) — the service consumes it INTERNALLY (fleetRunPublisher) and
+        re-expresses it as a fleet CHILD row on /v1/fleet/stream. So today MF-10 is observable via the fleet stream
+        subagent child rows; this arm is the core-arm MIRROR and surfaces on the task/run streams ONLY IF a future
+        service projection passes it through. Additive / tolerate-absent.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, taskId, usage, status]
+      properties:
+        type: { const: task_progress }
+        taskId: { type: string, description: 'The subagent task id (the delegated sub-run).' }
+        usage:
+          type: object
+          description: 'Cumulative usage as of this turn boundary (closed 3-field set, byte-aligned to core).'
+          required: [totalTokens, toolUses, durationMs]
+          properties:
+            totalTokens: { type: integer }
+            toolUses: { type: integer }
+            durationMs: { type: integer }
+        status: { const: running, description: 'Always "running" mid-run (the terminal usage is the done result).' }
+    Event_workspace_changed:
+      type: object
+      description: >
+        design/99 §E13 (SHIPPED, LIVE-only) — a `bash` `cd` moved the task's tracked working directory; carries the
+        new RAW logical cwd so a shell UI updates its prompt/path. Only fires with a real shell mounted; the initial
+        cwd is NOT announced (only subsequent changes). EPHEMERAL — not persisted; resets across suspend/resume.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      required: [type, cwd]
+      properties:
+        type: { const: workspace_changed }
+        cwd: { type: string }
+    Event_suspended:
+      type: object
+      description: HITL — the run paused on an F4 gate or AskUserQuestion. Resolve via approvals.decide, then resume.
+      required: [type]
+      properties:
+        type: { const: suspended }
+        gate:
+          description: >
+            CheckpointGate — OPEN DISCRIMINATED SET (design/80 D-0), mirrors core src/core/checkpoint-store.ts.
+            5 known kinds below; consumers MUST branch on `kind` and render an UNKNOWN kind generically (core
+            can mint a kind this contract predates — a core→wire contract test fails CI, not prod). Tool
+            args/question text are NOT here — join the task's trace tool-call block via approvals' toolCallId.
+          oneOf:
+            - type: object       # plain human approval (budget-auto-approvable)
+              required: [kind, reason, toolName]
+              properties: { kind: { const: human }, reason: { type: string }, toolName: { type: string } }
+            - type: object       # design/37 irreversibility / design/70 egress safety-tighten — NOT budgetable (load-bearing safety gate)
+              required: [kind, reason, toolName]
+              properties: { kind: { const: irreversible_ask }, reason: { type: string }, toolName: { type: string } }
+            - type: object       # design/74 resource (cost/token/time) slice boundary — resolve { decision: "continue" }
+              required: [kind, reason]
+              properties: { kind: { const: resource_limit }, reason: { type: string } }
+            - type: object       # design/76 dry-run/shadow → durable needs_review TERMINAL (POST-prediction review, disjoint from approval family)
+              required: [kind, reason]
+              properties: { kind: { const: needs_review }, reason: { type: string } }
+            - type: object       # design/38 Path A background sub-task handle (door B never sees it)
+              required: [kind]
+              properties: { kind: { const: task_done } }
+            - type: object       # OPEN SET — unknown future kind (e.g. design/80 D-B plan_review); render generically, never crash
+              required: [kind]
+              # 🔴 the pinned wire contract: exclude the 5 KNOWN kinds so a known kind matches ONLY its const member above
+              #   (not also this fallback) → keeps `oneOf` unambiguous AND preserves each kind's shape validation.
+              #   This fallback matches ONLY a future kind this contract predates. Add new known kinds to the enum.
+              properties: { kind: { type: string, not: { enum: [human, irreversible_ask, resource_limit, needs_review, task_done] } } }
+            - type: 'null'
+    Event_done:
+      type: object
+      description: Carries the full TaskResult (output string at .result, stats at .stats) — service Drift 4.
+      required: [type, result]
+      properties:
+        type: { const: done }
+        result: { $ref: '#/components/schemas/TaskResult' }
+    Event_failed:
+      type: object
+      required: [type]
+      properties:
+        type: { const: failed }
+        errorCode: { type: string }
+        errorMessage: { type: string }