admin-api.openapi.yaml

openapi: 3.1.0
info:
  title: agentic-sandbox Admin/Fleet API
  version: 2.0.0
  summary: Operator-facing fleet-management API for an agentic-sandbox host (Surface 1 of ADR-022)
  description: |
    Admin/Fleet HTTP API for operating an agentic-sandbox host: provisioning
    instances, managing their lifecycle, browsing the agentshare storage tree,
    enumerating container images and loadout manifests, polling async
    operations, and streaming logs and events.

    This is **Surface 1** in the three-surface model defined by
    [ADR-022](https://github.com/jmagly/agentic-sandbox/blob/main/.aiwg/architecture/adr/ADR-022-three-surface-architecture.md).
    It is the *operator* surface — distinct from and **NOT part of A2A**.
    The Agent-to-Agent protocol (Surface 2) is exposed *per-instance* under
    `/agents/{instance_id}/...` with its own AgentCard, securitySchemes, and
    bindings; this admin spec deliberately does not model agent operations.

    ### Surfaces (for orientation)

    | Surface | Path prefix | Audience | Spec |
    |---|---|---|---|
    | 1. Admin / Fleet (this doc) | `/api/v2/admin/...` | operators, fleet controllers, sandboxctl | this OpenAPI 3.1 file |
    | 2. Per-instance A2A | `/agents/{instance_id}/...` | orchestrators (AIWG, third parties) | A2A core spec + agentic-sandbox extensions |
    | 3. Observability | `/healthz`, `/readyz`, `/metrics`, plus log/event SSE under `/api/v2/admin/...` | Prometheus, on-call | k8s probes + Prometheus exposition |

    Log/event SSE endpoints are routed under the admin prefix for
    operational convenience but are observability-semantic (operator
    surfaces, not agent surfaces).

    ### Authentication

    Three auth mechanisms are supported; deployments enable one or more.
    All operations on this API accept any of them unless otherwise noted.

    - **Bearer token** (`Authorization: Bearer <token>`) — operator credential issued out of band.
    - **mTLS** — client certificate verified against the operator CA bundle.
    - **UNIX socket peer-credentials** — when the server is also bound to a UNIX domain socket (e.g. `/run/agentic-sandbox/admin.sock`), requests over that socket are authenticated by `SO_PEERCRED` of the connecting process. Effective uid/gid is matched against the configured operator allow-list. No HTTP credential is required on this transport. The `unix-peer-creds` security scheme is documentary only — it tells clients that requests on the UNIX socket transport carry implicit identity from the kernel.

    These credentials are independent of the per-instance A2A
    `securitySchemes` declared in each instance's AgentCard.

    ### Async operations

    Long-running operations (provision, lifecycle transitions, reprovision)
    return `202 Accepted` with an `OperationStatus` body containing an
    `id`. Clients poll `GET /operations/{id}` until `state` is `succeeded`,
    `failed`, or `canceled`.

    Mutating operations
    accept an optional `Idempotency-Key`. The key is bound to the authenticated
    operator identity plus the exact HTTP method, path/query, and request body
    for 24 hours. Repeating the same
    intent returns the original response with `Idempotency-Replayed: true`;
    reusing the key for a different request returns `409 Conflict`, and a
    concurrent duplicate returns `409` with `Retry-After`.

    ### Errors

    All non-2xx responses use the
    [error-envelope schema](./admin-api/error-envelope.schema.json)
    (RFC 7807 Problem Details with `code`, `instance`, `trace_id`
    extensions). The response media type is
    `application/problem+json`.

    ### Streaming

    `/logs` and `/events` endpoints with `follow=true` use Server-Sent
    Events (`text/event-stream`). Each event uses the standard SSE
    framing (`id:`, `event:`, `data:` lines). The `data:` payload is one
    JSON object per event (`LogEntry` or `Event`).
  contact:
    name: agentic-sandbox maintainers
    url: https://github.com/jmagly/agentic-sandbox
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://{host}/api/v2/admin
    description: Default deployment. `host` defaults to the loopback bind for local dev.
    variables:
      host:
        default: localhost:8122
        description: Host:port of the agentic-sandbox management server.
security:
  - bearer: []
  - mtls: []
  - unix-peer-creds: []
tags:
  - name: instances
    description: Fleet membership and provisioning. List, create, inspect instances.
  - name: lifecycle
    description: Start/stop/destroy/restart/reprovision actions on a provisioned instance.
  - name: runtimes
    description: Runtime-provider discovery and provider-specific capability negotiation.
  - name: secrets
    description: Per-instance secret rotation.
  - name: cloud-hypervisor
    description: Cloud Hypervisor fast-start, fork, and warm-pool operations.
  - name: operations
    description: Polling endpoint for async work units returned by provision and lifecycle endpoints.
  - name: storage
    description: CRUD over the virtiofs-backed agentshare tree (global RO, inbox/outbox RW).
  - name: container-images
    description: Curated container image catalog used by provisioning.
  - name: loadouts
    description: YAML-defined provisioning manifests describing instance shapes.
  - name: bootstrap
    description: Client-safe CA/bootstrap readiness and enrollment error taxonomy.
  - name: mcp
    description: Machine-readable discovery for the optional MCP management adapter.
  - name: streaming
    description: SSE endpoints for live log and event consumption.

paths:
  /bootstrap/readiness:
    get:
      tags: [bootstrap]
      operationId: getBootstrapReadiness
      summary: Inspect sanitized CA/bootstrap readiness
      description: |
        Returns client-safe readiness metadata for gRPC mTLS bootstrap. The
        response reports the public management WebSocket endpoint, CA backend status, trust-domain/freshness metadata,
        bootstrap token-store counts, and stable enrollment error codes. It
        never returns PEM bodies, token hashes, bearer values, CSRs, private
        keys, or filesystem paths.
      responses:
        '200':
          description: CA/bootstrap readiness posture.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BootstrapReadinessResponse' }
              examples:
                secure:
                  value:
                    status: secure
                    management_websocket:
                      endpoint: ws://{host}:8121/
                      source: server_advertised
                      protocol_version: '1.0'
                    ca_provider:
                      configured: true
                      status: secure
                      backend: local
                      trust_domain: sandbox.agentic.local
                      root_key_store: file
                      trust_bundle: { present: true, freshness: fresh, revision: null, expires_at_unix_ms: 1780000000000 }
                      reason: null
                    bootstrap:
                      token_store_configured: true
                      status: ready
                      enrollment_endpoint: /api/v1/bootstrap-enrollment/consume
                      auth: one_time_bootstrap_token_bound_to_spiffe_id
                      token_counts: { active: 1, consumed: 4, revoked: 0, expired: 0 }
                      origin_posture:
                        path: /api/v1/bootstrap-enrollment/consume
                        tls_required_by_contract: true
                        listener_state: not_reported
                        reason: listener bind address and TLS private material are intentionally not exposed through this admin response
                      reason: null
                    error_taxonomy:
                      - http_status: 503
                        code: bootstrap.ca_unavailable
                        message: Bootstrap CA unavailable
                        recovery: configure a local or remote gRPC CA backend before requiring mTLS bootstrap
                    notes:
                      - response omits token hashes, PEM bodies, CSRs, private keys, bearer values, and filesystem paths
                disabled:
                  value:
                    status: disabled
                    management_websocket:
                      endpoint: ws://{host}:8121/
                      source: server_advertised
                      protocol_version: '1.0'
                    ca_provider:
                      configured: false
                      status: disabled
                      backend: null
                      trust_domain: null
                      root_key_store: null
                      trust_bundle: { present: false, freshness: unknown, revision: null, expires_at_unix_ms: null }
                      reason: gRPC CA backend is not configured
                    bootstrap:
                      token_store_configured: false
                      status: disabled
                      enrollment_endpoint: /api/v1/bootstrap-enrollment/consume
                      auth: one_time_bootstrap_token_bound_to_spiffe_id
                      token_counts: null
                      origin_posture:
                        path: /api/v1/bootstrap-enrollment/consume
                        tls_required_by_contract: true
                        listener_state: not_reported
                        reason: listener bind address and TLS private material are intentionally not exposed through this admin response
                      reason: bootstrap token store and CA signing are not configured
                    error_taxonomy: []
                    notes: []
        default:
          $ref: '#/components/responses/Internal'

  /mcp/discovery:
    get:
      tags: [mcp]
      operationId: getMcpDiscovery
      summary: Discover the optional MCP management adapter contract
      description: |
        Returns client-safe metadata for the separately authenticated `POST /mcp`
        Streamable HTTP adapter. This admin response reports enabled/disabled
        state, configured client IDs and scopes, supported protocol versions,
        stateless transport behavior, allowed tool/resource shapes, and stable
        error cases. It never returns bearer tokens or token hashes.
      responses:
        '200':
          description: MCP discovery document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/McpDiscoveryResponse' }
              examples:
                enabled:
                  value:
                    enabled: true
                    status: enabled
                    reason_code: null
                    endpoint:
                      path: /mcp
                      methods: [POST]
                      transport: streamable-http
                      stateless: true
                      get_behavior: 405_method_not_allowed
                      mcp_session_id: false
                    protocol:
                      latest: '2025-11-25'
                      supported: ['2025-03-26', '2025-06-18', '2025-11-25']
                    auth:
                      scheme: bearer
                      required: true
                      principal_config: mcp-principals.toml
                      principals:
                        - client_id: codex-local
                          scopes: [fleet.read, session.read, output.read]
                      scopes: [fleet.read, output.read, session.read]
                    capabilities:
                      tools: { listChanged: false }
                      resources: { subscribe: false, listChanged: false }
                    tools:
                      - name: list_sandboxes
                        title: List sandboxes
                        description: List the canonical management fleet inventory.
                    resources:
                      - uri: sandbox://fleet
                        name: fleet
                        description: Current sandbox fleet inventory
                        mimeType: application/json
                    resource_templates:
                      - uriTemplate: sandbox://instances/{instance_id}
                        name: sandbox-instance
                        description: One sandbox instance from the canonical fleet inventory
                        mimeType: application/json
                    errors:
                      - http_status: 401
                        code: mcp.unauthorized
                        message: missing or invalid MCP bearer token
                    notes:
                      - GET /mcp is not a session endpoint.
                disabled:
                  value:
                    enabled: false
                    status: disabled
                    reason_code: mcp.principals_absent_or_disabled
                    endpoint:
                      path: /mcp
                      methods: [POST]
                      transport: streamable-http
                      stateless: true
                      get_behavior: 405_method_not_allowed
                      mcp_session_id: false
                    protocol:
                      latest: '2025-11-25'
                      supported: ['2025-03-26', '2025-06-18', '2025-11-25']
                    auth:
                      scheme: bearer
                      required: true
                      principal_config: mcp-principals.toml
                      principals: []
                      scopes: []
                    capabilities:
                      tools: { listChanged: false }
                      resources: { subscribe: false, listChanged: false }
                    tools: []
                    resources: []
                    resource_templates: []
                    errors: []
                    notes:
                      - GET /mcp is not a session endpoint.
        default:
          description: RFC 7807 error envelope.
          content:
            application/problem+json:
              schema: { $ref: '#/components/schemas/ErrorEnvelope' }

  /runtime/providers:
    get:
      tags: [runtimes]
      operationId: listRuntimeProviders
      summary: Discover runtime kinds, VM providers, and capabilities
      description: |
        Returns additive host, Docker, and QEMU runtime availability while
        preserving the effective default VM provider and provider list used by
        older clients. Runtime, provider, and capability identifiers are open
        strings; clients MUST preserve unknown values and MAY render them opaquely.
        Conditional exclusions, including VFIO incompatibilities, are reported
        as constraints rather than inferred from provider names.
      responses:
        '200':
          description: Runtime-provider discovery document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RuntimeProvidersResponse' }
              examples:
                local-host:
                  value:
                    default_vm_provider: cloud-hypervisor
                    runtimes:
                      - id: host
                        available: false
                        isolation_tier: full-host-access
                        architecture: x86_64
                        capabilities: [task.exec, session.pty, workspace.bind]
                        unavailable_code: host.supervisor_unconfigured
                        unavailable_reason: Host runtime supervisor is not configured
                      - id: docker
                        available: true
                        isolation_tier: shared-kernel
                        architecture: amd64
                        capabilities: [task.exec, session.pty, workspace.bind, image.oci]
                      - id: qemu
                        available: true
                        isolation_tier: hardware-virtualized
                        architecture: x86_64
                        capabilities: [instance.start, instance.stop, instance.checkpoint]
                    providers:
                      - id: libvirt
                        runtime: vm
                        available: true
                        is_default: false
                        capabilities: [instance.start, instance.stop, instance.restart, instance.destroy, instance.reprovision, instance.checkpoint, instance.restore, warm_pool.manage]
                      - id: cloud-hypervisor
                        runtime: vm
                        available: true
                        is_default: true
                        capabilities: [instance.start, instance.stop, instance.restart, instance.destroy, instance.reprovision, instance.snapshot, instance.restore, instance.fork, warm_pool.manage, device.vfio]
                        constraints:
                          - condition: device.vfio
                            excludes: [instance.snapshot, instance.restore, instance.fork, warm_pool.manage]
                            reason: Generic VFIO devices do not provide migratable device state; GPU VMs require cold hand-out and reset-gated teardown.
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances:
    get:
      tags: [instances]
      operationId: listInstances
      summary: List fleet instances
      description: |
        Returns a summary of every registered instance on this host. Use to
        discover ids for further admin operations and to obtain each
        instance's per-instance A2A AgentCard URL.
      parameters:
        - name: state
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/InstanceState'
          description: Filter by lifecycle state.
        - name: runtime
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/InstanceRuntime'
          description: Filter by broad runtime kind.
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/RuntimeProvider'
          description: Filter by concrete VM provider. Unknown provider identifiers are matched opaquely.
      responses:
        '200':
          description: Fleet snapshot.
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Instance'
                  degraded_providers:
                    type: array
                    description: Provider health degradations that did not prevent returning known inventory. Clients should keep rendering existing instances while using this field to disable affected lifecycle/provision controls.
                    items:
                      $ref: '#/components/schemas/DegradedProvider'
              examples:
                two-instances:
                  value:
                    items:
                      - id: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe
                        name: agent-01
                        runtime: qemu
                        provider: cloud-hypervisor
                        capabilities: [instance.start, instance.stop, instance.restart, instance.destroy, instance.reprovision, instance.snapshot, instance.restore, instance.fork, warm_pool.manage, device.vfio]
                        state: running
                        agent_card_url: https://localhost:8122/agents/8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe/.well-known/agent-card.json
                        loadout: profiles/claude-only.yaml
                        created_at: '2026-05-01T12:00:00Z'
                      - id: 1f3c9e2a-7b21-4f88-aa00-9d0b27cb1234
                        name: agent-02
                        runtime: docker
                        state: stopped
                        agent_card_url: https://localhost:8122/agents/1f3c9e2a-7b21-4f88-aa00-9d0b27cb1234/.well-known/agent-card.json
                        loadout: profiles/dual-review.yaml
                        created_at: '2026-05-02T09:30:00Z'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }
    post:
      tags: [instances]
      operationId: provisionInstance
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Provision a new instance (async)
      description: |
        Kicks off async provisioning. Returns `202` with an
        `OperationStatus` describing the work unit. Poll
        `GET /operations/{id}` for terminal state. The created instance's
        id is reported in the operation `result.instance_id` once
        provisioning succeeds. For `runtime: qemu`, `runtime_options` may
        carry provider-neutral cold, restore, fork, or warm-pool launch
        intent; non-cold modes delegate to the matching fast-start operation
        and still return the same async operation envelope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceProvisionRequest'
            examples:
              qemu-claude-only:
                value:
                  name: agent-03
                  runtime: qemu
                  provider: cloud-hypervisor
                  loadout: profiles/claude-only.yaml
                  agentshare: true
                  start: true
              qemu-restore:
                value:
                  name: agent-restore-01
                  runtime: qemu
                  runtime_options:
                    kind: vm
                    provider: cloud-hypervisor
                    launch_strategy:
                      mode: restore
                      asset_ref: ch-snapshot-agentic-dev
                      restore_mode: ondemand
      responses:
        '202':
          description: Provisioning accepted.
          headers:
            Location:
              description: URL of the operation status resource.
              schema: { type: string, format: uri-reference }
            Idempotency-Replayed:
              description: Present with value `true` when this response was recovered from a completed keyed request.
              schema: { type: string, enum: ['true'] }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
              examples:
                accepted:
                  value:
                    id: op_01HZK4XQ5G8XGE
                    kind: instance.provision
                    state: pending
                    target: agent-dev-01
                    created_at: '2026-05-09T14:01:00Z'
                    progress: { percent: 0 }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Validation' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}:
    parameters:
      - $ref: '#/components/parameters/InstanceId'
    get:
      tags: [instances]
      operationId: getInstance
      summary: Get a single instance
      description: Returns the full `Instance` record including the per-instance A2A AgentCard URL.
      responses:
        '200':
          description: Instance found.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Instance' }
              examples:
                running-qemu:
                  value:
                    id: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe
                    name: agent-01
                    runtime: qemu
                    provider: libvirt
                    capabilities: [instance.start, instance.stop, instance.restart, instance.destroy, instance.reprovision, instance.checkpoint, instance.restore, warm_pool.manage]
                    state: running
                    agent_card_url: https://localhost:8122/agents/8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe/.well-known/agent-card.json
                    loadout: profiles/claude-only.yaml
                    created_at: '2026-05-01T12:00:00Z'
                    network:
                      ip: 192.168.122.201
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}/start:
    parameters: [{ $ref: '#/components/parameters/InstanceId' }]
    post:
      tags: [lifecycle]
      operationId: startInstance
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Start a stopped instance (async)
      description: Transitions a stopped instance to `running`. Returns `202` with an `OperationStatus`. Idempotent for instances already running.
      responses:
        '202': { $ref: '#/components/responses/OperationAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}/stop:
    parameters: [{ $ref: '#/components/parameters/InstanceId' }]
    post:
      tags: [lifecycle]
      operationId: stopInstance
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Stop a running instance (async)
      description: Graceful shutdown. QEMU instances use libvirt shutdown; host instances are routed to the configured host supervisor and marked unready in the executor registry. Returns `202` with an `OperationStatus`. Idempotent for instances already stopped.
      responses:
        '202': { $ref: '#/components/responses/OperationAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}/destroy:
    parameters: [{ $ref: '#/components/parameters/InstanceId' }]
    post:
      tags: [lifecycle]
      operationId: destroyInstance
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Destroy an instance (async, irreversible)
      description: Hard teardown. QEMU instances are destroyed/undefined through libvirt; host instances are routed to the configured host supervisor, then removed from the executor registry and signing-key state. Returns `202` with an `OperationStatus`. Cannot be reversed; the instance id is retired.
      responses:
        '202': { $ref: '#/components/responses/OperationAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}/restart:
    parameters: [{ $ref: '#/components/parameters/InstanceId' }]
    post:
      tags: [lifecycle]
      operationId: restartInstance
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Restart an instance (async)
      description: Stop-then-start cycle preserving instance id, configuration, and persistent state. Returns `202` with an `OperationStatus`.
      responses:
        '202': { $ref: '#/components/responses/OperationAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}/reprovision:
    parameters: [{ $ref: '#/components/parameters/InstanceId' }]
    post:
      tags: [lifecycle]
      operationId: reprovisionInstance
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Reprovision an instance in place (async)
      description: |
        Re-runs the provisioning pipeline against the existing instance id,
        applying the supplied loadout (or the current one if omitted).
        Persistent inbox/outbox storage is preserved; the runtime image
        and global cache are rebuilt. Returns `202` with an
        `OperationStatus`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                loadout:
                  type: string
                  description: Loadout name or path. Omit to reuse the current loadout.
                  examples: [profiles/dual-review.yaml]
      responses:
        '202': { $ref: '#/components/responses/OperationAccepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /instances/{id}/rotate-secret:
    parameters: [{ $ref: '#/components/parameters/InstanceId' }]
    post:
      tags: [secrets]
      operationId: rotateInstanceSecret
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Retired legacy shared-secret rotation endpoint
      description: |
        Retired in #412 with the legacy agent shared-secret path. Agents now
        authenticate with transport identity credentials.
      responses:
        '410':
          description: Legacy shared-secret rotation is gone.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 410 }
                  code: { type: string, example: legacy_agent_secret.retired }
                  detail: { type: string }
              examples:
                retired:
                  value:
                    type: about:blank
                    title: Legacy agent shared-secret retired
                    status: 410
                    code: legacy_agent_secret.retired
                    detail: legacy agent shared-secret rotation was retired; use transport identity credentials
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /libvirt/checkpoints:
    post:
      tags: [libvirt]
      operationId: createLibvirtCheckpoint
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Capture a pre-enrollment QEMU/libvirt checkpoint
      description: |
        Quiesces and detaches virtiofs, captures RAM/device state with
        `virsh save`, and persists NVRAM plus restore metadata. The management
        path rejects secret-bearing checkpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibvirtCheckpointRequest' }
      responses:
        '202':
          description: Checkpoint operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /libvirt/checkpoints/{checkpoint_id}/restore:
    parameters:
      - name: checkpoint_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [libvirt]
      operationId: restoreLibvirtCheckpoint
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Restore and enroll a fresh tenant in the saved libvirt domain
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibvirtRestoreRequest' }
      responses:
        '202':
          description: Restore operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /libvirt/warm-pools:
    post:
      tags: [libvirt]
      operationId: initializeLibvirtWarmPool
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Reserve N distinct pre-booted libvirt checkpoint slots
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibvirtWarmPoolInitRequest' }
      responses:
        '202':
          description: Warm-pool operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /libvirt/warm-pools/{pool}/handoff:
    parameters:
      - name: pool
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [libvirt]
      operationId: handoffLibvirtWarmPool
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Atomically claim, restore, and enroll one libvirt warm slot
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibvirtWarmPoolHandoffRequest' }
      responses:
        '202':
          description: Handoff operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /cloud-hypervisor/snapshots:
    post:
      tags: [cloud-hypervisor]
      operationId: createCloudHypervisorSnapshot
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Capture a Cloud Hypervisor clean-base snapshot
      description: |
        Captures a CH snapshot through `ch-faststart.sh snapshot`. Clean-base
        snapshots must be pre-enrollment and signed; secret-bearing snapshots
        require a seal key and are encrypted at rest.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChSnapshotRequest' }
      responses:
        '202':
          description: Snapshot operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /cloud-hypervisor/snapshots/{snapshot_id}/restore:
    parameters:
      - name: snapshot_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [cloud-hypervisor]
      operationId: restoreCloudHypervisorSnapshot
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Restore a CH child from a verified clean-base snapshot
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChRestoreRequest' }
      responses:
        '202':
          description: Restore operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /cloud-hypervisor/snapshots/{snapshot_id}/fork:
    parameters:
      - name: snapshot_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [cloud-hypervisor]
      operationId: forkCloudHypervisorSnapshot
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Fork N CH children from one verified warm-base snapshot
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChForkRequest' }
      responses:
        '202':
          description: Fork operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /cloud-hypervisor/warm-pools:
    post:
      tags: [cloud-hypervisor]
      operationId: initializeCloudHypervisorWarmPool
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Initialize CH warm-pool accounting for a clean-base snapshot
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChWarmPoolInitRequest' }
      responses:
        '202':
          description: Warm-pool operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /cloud-hypervisor/warm-pools/{pool}/handoff:
    parameters:
      - name: pool
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [cloud-hypervisor]
      operationId: handoffCloudHypervisorWarmPool
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Restore and hand out one CH child from a warm pool
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChWarmPoolHandoffRequest' }
      responses:
        '202':
          description: Handoff operation accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/Internal' }

  /operations/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
        description: Operation id returned by an async endpoint.
        example: op_01HZK4XQ5G8XGE
    get:
      tags: [operations]
      operationId: getOperation
      summary: Poll an async operation's status
      description: |
        Returns the current state of an async operation. State machine:
        `pending` → `running` → (`succeeded` | `failed` | `canceled`).
        Terminal records are retained per the server's retention policy
        (default 24 h).
      responses:
        '200':
          description: Operation found.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OperationStatus' }
              examples:
                succeeded:
                  value:
                    id: op_01HZK4XQ5G8XGE
                    kind: instance.provision
                    state: succeeded
                    target: agent-dev-01
                    created_at: '2026-05-09T14:01:00Z'
                    completed_at: '2026-05-09T14:02:43Z'
                    progress: { percent: 100 }
                    result:
                      instance_id: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/Internal' }

  /storage/{scope}/{path}:
    parameters:
      - name: scope
        in: path
        required: true
        schema: { $ref: '#/components/schemas/StorageScope' }
        description: |
          Storage scope. `global` is read-only shared resources; `inbox`
          is per-agent inbound (RW); `outbox` is per-agent outbound
          artifacts (RW). `inbox`/`outbox` paths begin with the
          instance id.
      - name: path
        in: path
        required: true
        schema: { type: string }
        description: |
          Object path within the scope. Slashes within the path are
          permitted and conveyed as-is. For example:
          `inbox/8a3f.../missions/m-001.json`.
        example: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe/missions/m-001.json
    get:
      tags: [storage]
      operationId: getStorageObject
      summary: Browse a storage directory or read a bounded object's metadata and contents
      description: |
        Directories return a metadata-only listing capped at 500 entries.
        Objects larger than 1 MiB are rejected with `413` so this management
        surface cannot materialize unbounded content. Otherwise returns the
        object's metadata and contents.
        When the `Accept` header is `application/json` (default), returns
        the `StorageObject` envelope with `content_base64` for binary or
        `content` for text. When `Accept` is the object's media type
        (e.g. `application/octet-stream`), returns the raw bytes.
      responses:
        '200':
          description: Object found.
          content:
            application/json:
              schema:
                oneOf:
                  - { $ref: '#/components/schemas/StorageObject' }
                  - { $ref: '#/components/schemas/StorageDirectory' }
              examples:
                json-mission:
                  value:
                    scope: inbox
                    path: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe/missions/m-001.json
                    media_type: application/json
                    size_bytes: 412
                    sha256: 6e3a2c1f...
                    modified_at: '2026-05-09T14:03:00Z'
                    content: '{"mission_id":"m-001","prompt":"..."}'
            application/octet-stream:
              schema: { type: string, format: binary }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '413': { $ref: '#/components/responses/BadRequest' }
        '503': { $ref: '#/components/responses/StorageUnavailable' }
    put:
      tags: [storage]
      operationId: putStorageObject
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Create or replace a storage object
      description: |
        Writes at most 1 MiB of supplied bytes at `scope/path`. `global` is read-only
        and rejects writes (`scope_disabled`). When the body is JSON
        with the `StorageObjectWrite` shape, `content` (text) or
        `content_base64` (binary) supplies the bytes. When the body is
        any other media type, the raw bytes are stored as-is and
        `Content-Type` becomes the object's `media_type`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StorageObjectWrite' }
            examples:
              text-write:
                value:
                  media_type: text/plain
                  content: hello
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        '200':
          description: Object written.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StorageObject' }
        '201':
          description: Object created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StorageObject' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Validation' }
        '503': { $ref: '#/components/responses/StorageUnavailable' }
    delete:
      tags: [storage]
      operationId: deleteStorageObject
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Delete a storage object
      description: Removes the object at `scope/path`. Returns `204` on success. `global` rejects deletes (`scope_disabled`). Idempotent — `404` is returned if the object does not exist at deletion time.
      responses:
        '204': { description: Object deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '503': { $ref: '#/components/responses/StorageUnavailable' }

  /container-images:
    get:
      tags: [container-images]
      operationId: listContainerImages
      summary: List the curated container image catalog
      description: |
        Returns the catalog of container images registered on this host,
        used by the dashboard image picker and by docker-runtime
        provisioning. The catalog is curated server-side and is not a
        live registry view.
      responses:
        '200':
          description: Catalog snapshot.
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/ContainerImage' }
              examples:
                two-images:
                  value:
                    items:
                      - name: agentic-dev
                        reference: ghcr.io/agentic/agentic-dev:1.4.0
                        digest: sha256:e3b0c44...
                        size_bytes: 1387654321
                        labels: { profile: agentic-dev }
                      - name: minimal
                        reference: ghcr.io/agentic/minimal:0.2.1
                        digest: sha256:9f86d08...
                        size_bytes: 87654321
                        labels: { profile: basic }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }

  /loadouts:
    get:
      tags: [loadouts]
      operationId: listLoadouts
      summary: List loadout manifests
      description: Returns the loadout manifests registered on this host. A loadout is a YAML provisioning manifest describing an instance shape (runtime, profile, agentshare, MCP servers, etc.).
      responses:
        '200':
          description: Loadouts listed.
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Loadout' }
              examples:
                two-loadouts:
                  value:
                    items:
                      - name: claude-only
                        version: '1'
                        runtime: qemu
                        description: Claude Code single-agent profile.
                        compatibility:
                          - runtime_kind: vm
                            provider: cloud-hypervisor
                            eligible: true
                            launch_strategy: { mode: cold }
                          - runtime_kind: vm
                            provider: libvirt
                            eligible: true
                            launch_strategy: { mode: cold }
                      - name: dual-review
                        version: '1'
                        runtime: qemu
                        description: Two agents wired for cross-review.
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }
    post:
      tags: [loadouts]
      operationId: createLoadout
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      summary: Register a new loadout manifest
      description: |
        Uploads a loadout manifest. The manifest body is the YAML
        loadout document; the server parses, validates, and persists
        it. Names must be unique; use a different name to publish a
        new revision.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoadoutCreateRequest' }
            examples:
              minimal:
                value:
                  name: security-audit
                  manifest: |
                    metadata:
                      name: security-audit
                      description: Security audit loadout
                    runtime_options:
                      kind: vm
                      provider: cloud-hypervisor
      responses:
        '201':
          description: Loadout created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Loadout' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Validation' }
        '500': { $ref: '#/components/responses/Internal' }

  /logs:
    get:
      tags: [streaming]
      operationId: streamLogs
      summary: Stream or fetch admin log entries
      description: |
        Returns log entries from the in-memory ring buffer. When
        `follow=true`, the response is `text/event-stream` and the
        connection stays open, emitting one SSE event per new
        `LogEntry`. When `follow=false` (default), returns a JSON
        array snapshot bounded by `limit`.

        Each SSE event has:
        - `id:` — monotonic sequence number.
        - `event: log` — fixed.
        - `data:` — one `LogEntry` JSON object.

        Heartbeat comments (`: keepalive\n\n`) are emitted every 15
        seconds when no log activity is occurring.
      parameters:
        - name: follow
          in: query
          required: false
          schema: { type: boolean, default: false }
          description: When true, returns SSE; when false, returns a snapshot.
        - name: level
          in: query
          required: false
          schema:
            type: string
            enum: [trace, debug, info, warn, error]
          description: Minimum log level to include.
        - name: target
          in: query
          required: false
          schema: { type: string }
          description: Filter by tracing target (e.g. `management::dispatch`).
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 200, minimum: 1, maximum: 5000 }
          description: Max entries to return when `follow=false`.
        - name: cursor
          in: query
          required: false
          schema: { type: string }
          description: Resume after this stable log ID or SSE cursor. Last-Event-ID is also accepted.
        - name: Last-Event-ID
          in: header
          required: false
          schema: { type: string }
          description: SSE resume cursor. When present, this takes precedence over the query cursor.
      responses:
        '200':
          description: Snapshot or live stream.
          content:
            application/json:
              schema:
                type: object
                required: [items, cursor, gap, bounded]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/LogEntry' }
                  cursor: { type: string, description: Latest server log cursor. }
                  gap: { type: boolean, description: True when the requested cursor predates retained evidence. }
                  bounded: { type: boolean, const: true }
              examples:
                snapshot:
                  value:
                    items:
                      - id: log_42
                        timestamp: '2026-05-09T14:00:00Z'
                        level: info
                        target: management::dispatch
                        message: dispatched mission m-001
                        fields: { instance_id: 8a3f... }
                    cursor: '42'
                    gap: false
                    bounded: true
            text/event-stream:
              schema:
                type: string
                description: SSE stream of `LogEntry` JSON objects.
              examples:
                stream:
                  value: |
                    id: 1
                    event: log
                    data: {"timestamp":"2026-05-09T14:00:00Z","level":"info","target":"management::dispatch","message":"dispatched mission m-001"}

        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }

  /events:
    get:
      tags: [streaming]
      operationId: streamEvents
      summary: Stream or fetch admin events
      description: |
        Returns events from the in-memory event bus (instance lifecycle,
        operation transitions, storage mutations). When `follow=true`,
        the response is `text/event-stream` and the connection stays
        open, emitting one SSE event per new `Event`. When
        `follow=false`, returns a JSON array snapshot bounded by
        `limit`.

        Each SSE event has:
        - `id:` — monotonic sequence number.
        - `event: event` — fixed; the dotted event kind remains in `data.kind`.
        - `data:` — one `Event` JSON object.

        Heartbeat comments are emitted every 15 seconds.
      parameters:
        - name: follow
          in: query
          required: false
          schema: { type: boolean, default: false }
        - name: kind
          in: query
          required: false
          schema: { type: string }
          description: Filter by event kind glob (e.g. `instance.*`).
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 200, minimum: 1, maximum: 5000 }
        - name: cursor
          in: query
          required: false
          schema: { type: string }
          description: Resume after this stable event ID or SSE cursor. Last-Event-ID is also accepted.
        - name: Last-Event-ID
          in: header
          required: false
          schema: { type: string }
          description: SSE resume cursor. When present, this takes precedence over the query cursor.
      responses:
        '200':
          description: Snapshot or live stream.
          content:
            application/json:
              schema:
                type: object
                required: [items, cursor, gap, bounded]
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Event' }
                  cursor: { type: string, description: Latest server event cursor. }
                  gap: { type: boolean, description: True when the requested cursor predates retained evidence. }
                  bounded: { type: boolean, const: true }
              examples:
                snapshot:
                  value:
                    items:
                      - id: ev_42
                        kind: instance.state_changed
                        timestamp: '2026-05-09T14:02:43Z'
                        subject: instance/8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe
                        data: { from: provisioning, to: running }
                    cursor: '42'
                    gap: false
                    bounded: true
            text/event-stream:
              schema:
                type: string
                description: SSE stream of `Event` JSON objects.
              examples:
                stream:
                  value: |
                    id: 1
                    event: event
                    data: {"id":"ev_01HZK4Y9","kind":"instance.state_changed","timestamp":"2026-05-09T14:02:43Z","subject":"instance/8a3f...","data":{"from":"provisioning","to":"running"}}

        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }

  /deprecation/v1-counters:
    get:
      tags: [observability]
      operationId: getV1Counters
      summary: V1-route deprecation counter snapshot
      description: |
        Returns a snapshot of the per-path hit counter for legacy `/api/v1/*`
        routes (incremented by the `CompatLayer` middleware), the canonical
        `v1 → v2` path map, and the configured `Sunset` date. Used by the
        dashboard's deprecation panel (issue #250) so operators can see v1
        usage without scraping Prometheus.
      responses:
        '200':
          description: Counter snapshot.
          content:
            application/json:
              schema:
                type: object
                required: [counters, path_map, sunset]
                properties:
                  counters:
                    type: object
                    additionalProperties:
                      type: integer
                      minimum: 0
                    description: Per-v1-path hit counts since process start.
                  path_map:
                    type: object
                    additionalProperties: { type: string }
                    description: Canonical `v1 → v2` path translation map.
                  sunset:
                    type: string
                    format: date-time
                    description: Configured Sunset date for v1 routes.
              examples:
                snapshot:
                  value:
                    counters:
                      "/api/v1/vms": 142
                      "/api/v1/agents": 89
                    path_map:
                      "/api/v1/vms": "/api/v2/admin/instances"
                      "/api/v1/agents": "/api/v2/admin/instances"
                    sunset: "2027-05-09T00:00:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/Internal' }

components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: Stable operator-intent key. Reuse is allowed only for an identical method, URI, and body.
    InstanceId:
      name: id
      in: path
      required: true
      schema: { type: string, format: uuid }
      description: Instance UUID (stable across restart).
      example: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe

  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Operator bearer token. Issued out of band; may be a long-lived API key or a short-lived OIDC-derived token depending on deployment.
    mtls:
      type: mutualTLS
      description: Mutual TLS using a client certificate signed by the configured operator CA bundle. The CN/SAN is matched against the operator allow-list.
    unix-peer-creds:
      type: apiKey
      in: header
      name: X-Unix-Peer-Creds
      description: |
        Sentinel scheme indicating the request is being made over the
        UNIX domain socket transport (e.g. `/run/agentic-sandbox/admin.sock`)
        and is authenticated by kernel `SO_PEERCRED`. The header is
        not actually transmitted by clients; it appears here only so
        OpenAPI tooling can model the auth mode. Over the UNIX socket
        no Authorization header is needed; over TCP this scheme does
        not apply.

  responses:
    OperationAccepted:
      description: Async operation accepted.
      headers:
        Location:
          description: URL of the operation status resource.
          schema: { type: string, format: uri-reference }
        Idempotency-Replayed:
          description: Present with value `true` when this response was recovered from a completed keyed request.
          schema: { type: string, enum: ['true'] }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/OperationStatus' }
          examples:
            accepted:
              value:
                id: op_01HZK4XQ5G8XGE
                kind: instance.start
                state: pending
                target: 8a3f8b94-1c4e-4d2b-9c1a-1ad44e6b0dfe
                created_at: '2026-05-09T14:10:00Z'
                progress: { percent: 0 }
    BadRequest:
      description: Malformed request.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Unauthorized:
      description: No or invalid credentials.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Forbidden:
      description: Authenticated but not authorized.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    NotFound:
      description: Resource not found.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Conflict:
      description: State conflict (e.g. start while already running, name in use).
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Validation:
      description: Validation error. Body includes per-field details under `errors`.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    StorageUnavailable:
      description: Storage backend not configured for this scope (`storage.scope_disabled`).
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    ServiceUnavailable:
      description: Runtime provider temporarily unavailable or degraded. Responses may include `Retry-After`.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Internal:
      description: Unexpected server error.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }

  schemas:
    ErrorEnvelope:
      $ref: './admin-api/error-envelope.schema.json'

    BootstrapReadinessResponse:
      type: object
      required: [status, management_websocket, ca_provider, bootstrap, error_taxonomy, notes]
      properties:
        status:
          type: string
          enum: [secure, degraded, disabled]
        management_websocket:
          $ref: '#/components/schemas/ManagementWebSocketDiscovery'
        ca_provider:
          $ref: '#/components/schemas/CaProviderReadiness'
        bootstrap:
          $ref: '#/components/schemas/BootstrapReadiness'
        error_taxonomy:
          type: array
          items: { $ref: '#/components/schemas/ClientSafeBootstrapError' }
        notes:
          type: array
          items: { type: string }

    ManagementWebSocketDiscovery:
      type: object
      required: [endpoint, source, protocol_version]
      properties:
        endpoint:
          type: [string, 'null']
          description: Public ws/wss URL, optionally containing the literal `{host}` browser-host placeholder.
        source:
          type: string
          enum: [server_advertised, same_origin_fallback]
        protocol_version:
          type: string
          pattern: '^[0-9]+\.[0-9]+$'

    CaProviderReadiness:
      type: object
      required: [configured, status, backend, trust_domain, root_key_store, trust_bundle, reason]
      properties:
        configured: { type: boolean }
        status:
          type: string
          enum: [secure, degraded, disabled]
        backend:
          anyOf:
            - type: string
              enum: [local, remote-mock, remote]
            - type: 'null'
        trust_domain: { type: [string, 'null'] }
        root_key_store:
          type: [string, 'null']
          description: Backend class for CA private material, not a filesystem path.
        trust_bundle:
          $ref: '#/components/schemas/TrustBundleReadiness'
        reason: { type: [string, 'null'] }

    TrustBundleReadiness:
      type: object
      required: [present, freshness, revision, expires_at_unix_ms]
      properties:
        present: { type: boolean }
        freshness:
          type: string
          enum: [fresh, expired, unknown]
        revision:
          type: [string, 'null']
          description: Opaque provider revision when supplied by a remote CA provider.
        expires_at_unix_ms:
          type: [integer, 'null']
          format: int64

    BootstrapReadiness:
      type: object
      required: [token_store_configured, status, enrollment_endpoint, auth, token_counts, origin_posture, reason]
      properties:
        token_store_configured: { type: boolean }
        status:
          type: string
          enum: [ready, degraded, failed, disabled]
        enrollment_endpoint:
          type: string
          enum: [/api/v1/bootstrap-enrollment/consume]
        auth:
          type: string
          enum: [one_time_bootstrap_token_bound_to_spiffe_id]
        token_counts:
          anyOf:
            - $ref: '#/components/schemas/BootstrapTokenCounts'
            - type: 'null'
        origin_posture:
          $ref: '#/components/schemas/BootstrapOriginPosture'
        reason: { type: [string, 'null'] }

    BootstrapTokenCounts:
      type: object
      required: [active, consumed, revoked, expired]
      properties:
        active: { type: integer, minimum: 0 }
        consumed: { type: integer, minimum: 0 }
        revoked: { type: integer, minimum: 0 }
        expired: { type: integer, minimum: 0 }

    BootstrapOriginPosture:
      type: object
      required: [path, tls_required_by_contract, listener_state, reason]
      properties:
        path:
          type: string
          enum: [/api/v1/bootstrap-enrollment/consume]
        tls_required_by_contract: { type: boolean }
        listener_state:
          type: string
          enum: [not_reported]
        reason:
          type: string
          description: Sanitized explanation; does not include bind address, port, certificate path, or key path.

    ClientSafeBootstrapError:
      type: object
      required: [http_status, code, message, recovery]
      properties:
        http_status: { type: integer }
        code:
          type: string
          enum:
            - bootstrap.ca_unavailable
            - bootstrap.store_unavailable
            - bootstrap.spiffe_mismatch
            - bootstrap.csr_invalid
            - bootstrap.token_invalid
            - bootstrap.token_consumed
            - bootstrap.persistence_failed
        message: { type: string }
        recovery:
          type: string
          description: Client-safe operator recovery guidance.

    McpDiscoveryResponse:
      type: object
      required: [enabled, status, endpoint, protocol, auth, capabilities, tools, resources, resource_templates, errors, notes]
      properties:
        enabled:
          type: boolean
          description: Whether the separately authenticated `POST /mcp` endpoint is configured.
        status:
          type: string
          enum: [enabled, disabled]
        reason_code:
          type: [string, 'null']
          description: Stable disabled/degraded reason. `mcp.principals_absent_or_disabled` means the principals file is absent or explicitly disabled.
        endpoint:
          $ref: '#/components/schemas/McpEndpointDiscovery'
        protocol:
          $ref: '#/components/schemas/McpProtocolDiscovery'
        auth:
          $ref: '#/components/schemas/McpAuthDiscovery'
        capabilities:
          type: object
          additionalProperties: true
          description: MCP initialize-style capability flags.
        tools:
          type: array
          items: { $ref: '#/components/schemas/McpToolDiscovery' }
        resources:
          type: array
          items: { $ref: '#/components/schemas/McpResourceDiscovery' }
        resource_templates:
          type: array
          items: { $ref: '#/components/schemas/McpResourceTemplateDiscovery' }
        errors:
          type: array
          items: { $ref: '#/components/schemas/McpErrorDiscovery' }
        notes:
          type: array
          items: { type: string }

    McpEndpointDiscovery:
      type: object
      required: [path, methods, transport, stateless, get_behavior, mcp_session_id]
      properties:
        path:
          type: string
          enum: [/mcp]
        methods:
          type: array
          items:
            type: string
            enum: [POST]
        transport:
          type: string
          enum: [streamable-http]
        stateless:
          type: boolean
          enum: [true]
        get_behavior:
          type: string
          enum: [405_method_not_allowed]
        mcp_session_id:
          type: boolean
          enum: [false]

    McpProtocolDiscovery:
      type: object
      required: [latest, supported]
      properties:
        latest:
          type: string
          examples: ['2025-11-25']
        supported:
          type: array
          items: { type: string }

    McpAuthDiscovery:
      type: object
      required: [scheme, required, principal_config, principals, scopes]
      properties:
        scheme:
          type: string
          enum: [bearer]
        required:
          type: boolean
          enum: [true]
        principal_config:
          type: string
          enum: [mcp-principals.toml]
        principals:
          type: array
          description: Configured client IDs and scopes. Token hashes are never exposed.
          items: { $ref: '#/components/schemas/McpPrincipalDiscovery' }
        scopes:
          type: array
          items: { type: string }

    McpPrincipalDiscovery:
      type: object
      required: [client_id, scopes]
      properties:
        client_id:
          type: string
        scopes:
          type: array
          items: { type: string }

    McpToolDiscovery:
      type: object
      required: [name]
      additionalProperties: true
      properties:
        name: { type: string }
        title: { type: string }
        description: { type: string }
        inputSchema:
          type: object
          additionalProperties: true
        outputSchema:
          type: object
          additionalProperties: true
        annotations:
          type: object
          additionalProperties: true

    McpResourceDiscovery:
      type: object
      required: [uri, name, mimeType]
      properties:
        uri: { type: string }
        name: { type: string }
        description: { type: string }
        mimeType: { type: string }

    McpResourceTemplateDiscovery:
      type: object
      required: [uriTemplate, name, mimeType]
      properties:
        uriTemplate: { type: string }
        name: { type: string }
        description: { type: string }
        mimeType: { type: string }

    McpErrorDiscovery:
      type: object
      required: [http_status, code, message]
      properties:
        http_status:
          type: integer
        jsonrpc_code:
          type: integer
        code:
          type: string
        message:
          type: string

    InstanceRuntime:
      type: string
      enum: [qemu, docker, host]
      description: Broad runtime kind hosting the instance. For qemu instances, inspect `provider` for the concrete VMM integration.

    RuntimeProvider:
      type: string
      minLength: 1
      description: Concrete runtime provider identifier. Open for forward compatibility; current VM providers are `libvirt` and `cloud-hypervisor`.
      examples: [libvirt, cloud-hypervisor]

    RuntimeCapability:
      type: string
      minLength: 1
      description: Open capability identifier. Clients MUST preserve unknown values.
      examples: [instance.snapshot, instance.checkpoint, device.vfio]

    RuntimeCapabilityConstraint:
      type: object
      required: [condition, excludes, reason]
      properties:
        condition:
          $ref: '#/components/schemas/RuntimeCapability'
        excludes:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        reason:
          type: string

    RuntimeProviderDescriptor:
      type: object
      required: [id, runtime, available, is_default, capabilities]
      properties:
        id: { $ref: '#/components/schemas/RuntimeProvider' }
        runtime:
          type: string
          description: Provider family. Currently `vm`; open for future runtime families.
          examples: [vm]
        available:
          type: boolean
          description: Whether the required provider tools are available on this management host.
        is_default: { type: boolean }
        capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        constraints:
          type: array
          items: { $ref: '#/components/schemas/RuntimeCapabilityConstraint' }
        unavailable_code:
          type: string
          description: Stable machine-readable reason code when the provider is unavailable.
        unavailable_reason: { type: string }

    RuntimeKindDescriptor:
      type: object
      required: [id, available, isolation_tier, architecture, capabilities]
      properties:
        id:
          type: string
          minLength: 1
          description: Runtime-kind identifier. Current values are host, docker, qemu, and optional worker-celld; clients preserve unknown future values.
          examples: [host, docker, qemu, worker-celld]
        available:
          type: boolean
          description: Whether this server can currently provision the runtime kind.
        isolation_tier:
          type: string
          enum: [full-host-access, shared-kernel, hardware-virtualized, constrained-isolate]
        architecture:
          type: string
          description: Runtime architecture reported by the host or active Docker daemon.
          examples: [aarch64, arm64, x86_64, amd64]
        capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        constraints:
          type: array
          items: { $ref: '#/components/schemas/RuntimeCapabilityConstraint' }
        unavailable_code:
          type: string
          description: Stable machine-readable reason code when the runtime is unavailable.
        unavailable_reason:
          type: string
          description: Sanitized operator-facing reason without raw command output or host paths.

    RuntimeProvidersResponse:
      type: object
      required: [default_vm_provider, providers, runtimes]
      properties:
        default_vm_provider: { $ref: '#/components/schemas/RuntimeProvider' }
        providers:
          type: array
          items: { $ref: '#/components/schemas/RuntimeProviderDescriptor' }
        runtimes:
          type: array
          description: Additive runtime-kind discovery for host, Docker, QEMU, and optional constrained Worker/Wasm runtimes.
          items: { $ref: '#/components/schemas/RuntimeKindDescriptor' }

    InstanceState:
      type: string
      enum: [provisioning, stopped, starting, running, stopping, failed, destroying, destroyed]
      description: Instance lifecycle state.

    DegradedProvider:
      type: object
      required: [runtime, code, detail]
      properties:
        runtime:
          $ref: '#/components/schemas/InstanceRuntime'
        code:
          type: string
          description: Stable degradation code, such as `libvirt.unresponsive` or `libvirt.error`.
        detail:
          type: string
          description: Sanitized operator-facing explanation.
        retry_after:
          type: integer
          format: int64
          minimum: 1
          description: Suggested retry delay in seconds when the provider circuit exposes one.

    Instance:
      type: object
      required: [id, name, runtime, state, agent_card_url, created_at]
      properties:
        id: { type: string, format: uuid, description: Stable instance identifier. }
        name: { type: string, description: Operator-friendly name (e.g. agent-01). }
        runtime: { $ref: '#/components/schemas/InstanceRuntime' }
        provider:
          $ref: '#/components/schemas/RuntimeProvider'
        capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        capability_constraints:
          type: array
          items: { $ref: '#/components/schemas/RuntimeCapabilityConstraint' }
        state: { $ref: '#/components/schemas/InstanceState' }
        agent_card_url:
          type: string
          format: uri
          description: URL of the per-instance A2A AgentCard (Surface 2).
        loadout:
          type: string
          description: Loadout manifest in use, if any.
          examples: [profiles/claude-only.yaml]
        image:
          type: string
          description: Runtime image reference used at launch. Present for docker and image-backed host/qemu contexts when known.
          examples: [agentic/codex:latest]
        image_ref:
          type: string
          description: Alias for `image` matching the runtime AgentCard extension field name.
          examples: [agentic/codex:latest]
        source:
          type: string
          description: Provisioning source/provider that created the row, when known.
          examples: [admin-v2]
        cwd:
          type: string
          description: Runtime-native default working directory for interactive sessions. Clients must not substitute their own control-plane cwd.
          examples: [/home/agent]
        operation_status:
          type: string
          description: Coarse provisioning/runtime operation status for inventory views.
          enum: [ready, registered, bootstrap_pending, not_ready, stopped, unknown]
          examples: [bootstrap_pending]
        agent_registered:
          type: boolean
          description: Whether a v1 agent registry entry exists for this instance. Docker inventory sets this to `false` until the container successfully registers.
          examples: [false]
        agent_ready:
          type: boolean
          description: Whether the registered agent has reached Ready status. Consumers must not infer session readiness from runtime/card metadata alone.
          examples: [false]
        container_finished_at:
          type: string
          format: date-time
          description: Docker container completion timestamp when the backing container has exited before agent readiness.
        created_at: { type: string, format: date-time }
        transport:
          type: string
          enum: [mtls, uds, vsock, bootstrap-pending, plaintext-dev, unknown]
          description: Normalized agent control-plane transport code. `unknown` is reserved for genuinely missing transport evidence.
          examples: [mtls]
        transport_posture:
          type: string
          enum: [secure, local, pending, dev, unknown]
          description: Normalized transport posture for operator UIs.
        security_posture:
          type: object
          description: Structured security posture for clients that render posture and label separately. Managed Docker rows add client-safe identity evidence; host socket paths and raw control UIDs are never returned.
          properties:
            posture:
              type: string
              enum: [secure, local, pending, dev, unknown]
            label:
              type: string
            transport_mode:
              type: string
              description: Provisioned managed-Docker transport, when retained in container labels.
              enum: [uds, mtls-bootstrap, operator-configured]
            control_identity_present:
              type: boolean
              description: Whether the managed container retains a control-identity label. The raw host UID is intentionally omitted.
            control_identity_range_valid:
              type: boolean
              description: Whether the retained control identity belongs to the range reserved for managed containers.
            workload_uid:
              type: integer
              minimum: 0
              description: Fixed in-container workload UID when retained as managed evidence.
            workload_boundary_separated:
              type: boolean
              description: Whether the fixed workload UID and separated-boundary label agree.
            reason_code:
              type: string
              description: Stable managed-Docker compatibility, fallback, or remediation reason code.
              examples: [managed_docker.uds_identity_ready]
            recreation_required:
              type: boolean
              description: Whether missing, invalid, or unsupported retained identity evidence requires replacing the container.
        host_daemon:
          type: object
          description: Host-runtime supervisor/daemon status. Present for host-backed instances.
          properties:
            status:
              type: string
              enum: [available, unavailable]
            label:
              type: string
        network:
          type: object
          properties:
            ip: { type: string, description: Reachable IP on the libvirt or docker network. }
            ssh_port:
              type: integer
              description: Direct-runtime SSH port for qemu dev/break-glass diagnostics only; managed-profile SSH should use gateway-mediated access.
        labels:
          type: object
          additionalProperties: { type: string }
          description: Free-form operator labels.

    InstanceProvisionRequest:
      type: object
      required: [name, runtime]
      properties:
        name:
          type: string
          pattern: '^[a-z][a-z0-9-]{1,62}$'
          description: Operator-friendly name. Must be unique on the host.
        runtime: { $ref: '#/components/schemas/InstanceRuntime' }
        provider:
          allOf:
            - $ref: '#/components/schemas/RuntimeProvider'
          description: >-
            Optional concrete VM provider. Valid only with runtime qemu;
            omission selects the configured default (legacy default libvirt).
        runtime_options:
          allOf:
            - $ref: '#/components/schemas/LoadoutRuntimeOptions'
          description: >-
            Provider-neutral launch intent. `kind` must match `runtime`;
            `provider` must match the top-level provider when both are supplied.
            Cold launch is accepted for all compatible runtimes. With
            `runtime: qemu`, restore, fork, and warm_pool modes are accepted and
            delegated to the matching provider fast-start operation. Non-cold
            qemu requests require `launch_strategy.asset_ref` and may not be
            combined with cold-provision-only fields such as `loadout`,
            `profile`, `image`, `agentshare`, `mounts`, `labels`,
            `working_dir`, `startup_profile_id`, or `ssh_key`. Unsupported
            provider/mode combinations fail with 422.
        loadout:
          type: string
          description: Loadout manifest name or path. Mutually compatible with `profile` and `image`.
        profile:
          type: string
          description: Provisioning profile (e.g. agentic-dev, basic). Used when `loadout` is omitted.
        image:
          type: string
          description: Container image reference (docker runtime only). Omitted for host runtime because no image boundary exists.
        agentshare:
          type: boolean
          default: false
          description: Mount shared workspace storage. For qemu this enables agentshare virtiofs (`global` RO, `inbox`/`outbox` RW). For docker this creates a per-instance host workspace and bind-mounts it at `/workspace` unless an explicit `/workspace` mount is supplied.
        mounts:
          type: array
          description: Docker bind mounts as `host_path:container_path` strings. Docker only.
          items:
            type: string
            example: /srv/agent-ops:/workspace
        network:
          type: string
          description: >-
            Optional existing Docker network name. When omitted, management
            creates a scoped internal network with default-deny egress.
            Selecting `bridge`, `host`, or another operator-managed network is
            an explicit Tier 0 compatibility choice and may permit upstream
            egress.
          example: bridge
        start:
          type: boolean
          default: false
          description: Start the instance after provisioning succeeds.
        vcpus:
          type: integer
          minimum: 1
          maximum: 256
          description: QEMU virtual CPU count. Ignored for non-QEMU runtimes.
        memory_mb:
          type: integer
          minimum: 256
          description: QEMU memory allocation in MiB. Ignored for non-QEMU runtimes.
        disk_gb:
          type: integer
          minimum: 1
          description: QEMU root-disk capacity in GiB. Ignored for non-QEMU runtimes.
        working_dir:
          type: string
          description: Optional launch working directory for host runtime instances. Ignored by qemu/docker provisioning.
        ssh_key:
          type: string
          description: Optional SSH public key path for qemu/VM provisioning, forwarded to provision-vm.sh as `--ssh-key`. When omitted, the script auto-detects a key from the management server's `$HOME/.ssh`. Ignored by host/docker provisioning.
        labels:
          type: object
          description: Free-form labels. Docker labels are forwarded except the reserved `agentic-sandbox` key.
          additionalProperties: { type: string }

    OperationKind:
      type: string
      description: Operation kind. New kinds may be introduced; clients SHOULD treat unknown kinds opaquely.
      examples:
        - instance.provision
        - instance.snapshot
        - instance.restore
        - instance.fork
        - warm_pool.manage
        - instance.start
        - instance.stop
        - instance.destroy
        - instance.restart
        - instance.reprovision
        - fleet.reconcile

    ChSnapshotRequest:
      type: object
      required: [vm, snapshot_id]
      properties:
        vm:
          type: string
          description: Existing CH VM/base name to snapshot.
        snapshot_id:
          type: string
          description: Snapshot bundle id under the CH snapshot root.
        pre_enrollment:
          type: boolean
          default: false
          description: Marks this as a clean base captured before enrollment material is injected.
        secret_bearing:
          type: boolean
          default: false
          description: Marks this as a live/secret-bearing snapshot; requires `seal_key`.
        seal_key:
          type: string
          description: Host path to the sealing passphrase file for secret-bearing snapshots.
        sign_key:
          type: string
          description: GPG signing key id for base snapshot provenance; required for `pre_enrollment` unless the server configures `CH_SNAPSHOT_SIGN_KEY`.

    LibvirtCheckpointRequest:
      type: object
      required: [vm, checkpoint_id, pre_enrollment]
      properties:
        vm:
          type: string
          description: Running clean-base libvirt domain to checkpoint.
        checkpoint_id:
          type: string
          description: Unique checkpoint bundle id.
        pre_enrollment:
          type: boolean
          enum: [true]
          description: Must be true; the management path does not capture secret-bearing RAM.

    LibvirtRestoreRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Source domain name retained by the libvirt save image.
        instance_id:
          type: string
          format: uuid
          description: Optional canonical instance id; generated when omitted.

    LibvirtWarmPoolInitRequest:
      type: object
      required: [checkpoint_ids, pool]
      properties:
        checkpoint_ids:
          type: array
          minItems: 1
          maxItems: 64
          uniqueItems: true
          description: Distinct pre-enrollment save images; libvirt UUID identity makes each slot single-use.
          items:
            type: string
        pool:
          type: string

    LibvirtWarmPoolHandoffRequest:
      type: object
      additionalProperties: false
      description: Empty body; the consumed checkpoint supplies its immutable libvirt name and UUID.

    ChRestoreRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: New child VM name.
        mode:
          type: string
          enum: [ondemand, copy]
          default: ondemand
          description: CH memory restore mode.
        instance_id:
          type: string
          description: Optional canonical instance id for fresh CID/enrollment metadata.

    ChForkRequest:
      type: object
      required: [prefix, count]
      properties:
        prefix:
          type: string
          description: Prefix used to name children as `{prefix}-1..N`.
        count:
          type: integer
          minimum: 1
        mode:
          type: string
          enum: [ondemand, copy]
          default: ondemand

    ChWarmPoolInitRequest:
      type: object
      required: [snapshot_id, size, prefix]
      properties:
        snapshot_id:
          type: string
        size:
          type: integer
          minimum: 1
        prefix:
          type: string
          description: Warm-pool name/prefix.

    ChWarmPoolHandoffRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: New child VM name handed out from the pool.
        mode:
          type: string
          enum: [ondemand, copy]
          default: ondemand

    OperationState:
      type: string
      enum: [pending, running, succeeded, failed, canceled]

    OperationStatus:
      type: object
      required: [id, kind, state, target, created_at, progress]
      properties:
        id:
          type: string
          description: Operation id. ULID-format string.
          examples: [op_01HZK4XQ5G8XGE]
        kind: { $ref: '#/components/schemas/OperationKind' }
        state: { $ref: '#/components/schemas/OperationState' }
        target:
          type: string
          description: Stable instance id or operator target name associated with the operation.
        created_at: { type: string, format: date-time }
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        result:
          type: object
          description: Kind-specific result payload (present on `succeeded`).
          additionalProperties: true
        error:
          allOf:
            - $ref: '#/components/schemas/ErrorEnvelope'
          description: Error envelope (present on `failed`).
        progress:
          type: object
          description: Optional progress snapshot.
          properties:
            percent: { type: number, minimum: 0, maximum: 100 }
            phase: { type: string, examples: [downloading-image, configuring-network, starting-runtime] }

    StorageScope:
      type: string
      enum: [global, inbox, outbox]
      description: |
        - `global` — read-only shared resources. Writes/deletes return 403.
        - `inbox` — per-instance inbound (RW). Path is prefixed by instance id.
        - `outbox` — per-instance outbound artifacts (RW). Path is prefixed by instance id.

    StorageObject:
      type: object
      required: [scope, path, media_type, size_bytes, modified_at]
      properties:
        scope: { $ref: '#/components/schemas/StorageScope' }
        path: { type: string }
        media_type: { type: string, examples: [application/json, text/plain, application/octet-stream] }
        size_bytes: { type: integer, minimum: 0 }
        sha256:
          type: string
          description: Hex-encoded SHA-256 of the object contents.
        modified_at: { type: string, format: date-time }
        content:
          type: string
          description: Object contents as text (UTF-8). Present on read when the object is text and the client accepts JSON.
        content_base64:
          type: string
          format: byte
          description: Object contents base64-encoded. Used for binary objects when the client accepts JSON.

    StorageObjectWrite:
      type: object
      properties:
        media_type: { type: string }
        content: { type: string, description: UTF-8 text contents. }
        content_base64: { type: string, format: byte, description: Base64-encoded binary contents. }
      oneOf:
        - required: [content]
        - required: [content_base64]

    StorageDirectory:
      type: object
      required: [kind, scope, path, items, truncated, limit]
      properties:
        kind: { type: string, enum: [directory] }
        scope: { $ref: '#/components/schemas/StorageScope' }
        path: { type: string }
        items:
          type: array
          maxItems: 500
          items:
            type: object
            required: [name, kind]
            properties:
              name: { type: string }
              kind: { type: string, enum: [directory, object] }
              size_bytes: { type: integer, minimum: 0, nullable: true }
        truncated: { type: boolean }
        limit: { type: integer, enum: [500] }

    ContainerImage:
      type: object
      required: [name, reference]
      properties:
        name: { type: string, description: Catalog name. }
        reference:
          type: string
          description: Fully qualified image reference (registry/repo:tag).
          examples: [ghcr.io/agentic/agentic-dev:1.4.0]
        digest: { type: string, description: 'Image digest (sha256:...).' }
        size_bytes: { type: integer, minimum: 0 }
        labels:
          type: object
          additionalProperties: { type: string }

    Loadout:
      type: object
      required: [name, version]
      properties:
        name:
          type: string
          description: Loadout manifest name or path.
          examples: [profiles/claude-only.yaml]
        version: { type: string, examples: ['1'] }
        runtime: { $ref: '#/components/schemas/InstanceRuntime' }
        description: { type: string }
        manifest:
          type: string
          description: Raw YAML manifest body. Returned on detail; omitted in list to keep payloads small.
        runtime_options:
          $ref: '#/components/schemas/LoadoutRuntimeOptions'
        compatibility:
          type: array
          description: Provider/runtime compatibility resolved from runtime_options and safe defaults.
          items: { $ref: '#/components/schemas/LoadoutCompatibility' }

    LoadoutRuntimeOptions:
      type: object
      description: Portable loadout launch intent for provider-aware management clients.
      properties:
        kind:
          type: string
          enum: [host, container, vm]
          description: Portable runtime kind requested by the loadout.
        provider:
          $ref: '#/components/schemas/RuntimeProvider'
        required_capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        excluded_capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        launch_strategy:
          $ref: '#/components/schemas/LoadoutLaunchStrategy'
        constraints:
          type: object
          properties:
            allow_vfio_fast_start:
              type: boolean
              description: Must be false for VFIO/GPU passthrough loadouts.
            fallback_mode:
              type: string
              enum: [fail, cold]

    LoadoutLaunchStrategy:
      type: object
      required: [mode]
      properties:
        mode:
          type: string
          enum: [cold, restore, fork, warm_pool]
        prefer_fast_start:
          type: boolean
          default: false
        asset_ref:
          type: string
          description: Provider-local snapshot/checkpoint/fork-base/warm-pool identifier. This is an opaque id, not a host path.
        restore_mode:
          type: string
          enum: [ondemand, copy]
          description: Provider-specific restore behavior. Cloud Hypervisor uses `ondemand` or `copy`; providers that do not expose a restore mode ignore this value.

    LoadoutCompatibility:
      type: object
      required: [runtime_kind, provider, eligible]
      properties:
        runtime_kind:
          type: string
          examples: [vm]
        provider:
          $ref: '#/components/schemas/RuntimeProvider'
        eligible:
          type: boolean
        required_capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        excluded_capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        constraints:
          type: array
          items: { $ref: '#/components/schemas/RuntimeCapabilityConstraint' }
        launch_strategy:
          $ref: '#/components/schemas/LoadoutLaunchStrategy'
        fast_start_assets:
          type: array
          items: { $ref: '#/components/schemas/LoadoutFastStartAsset' }
        reason:
          type: string
          description: Sanitized operator-facing degraded or unavailable reason.

    LoadoutFastStartAsset:
      type: object
      required: [id, provider, kind, state, capabilities, reason]
      properties:
        id:
          type: string
          description: Opaque provider asset id. Host filesystem paths and secret material must not be exposed.
        provider:
          $ref: '#/components/schemas/RuntimeProvider'
        kind:
          type: string
          enum: [snapshot, checkpoint, fork_base, warm_pool, none]
        state:
          type: string
          enum: [ready, degraded, unavailable]
        capabilities:
          type: array
          uniqueItems: true
          items: { $ref: '#/components/schemas/RuntimeCapability' }
        reason:
          type: string
          description: Sanitized readiness explanation.

    LoadoutCreateRequest:
      type: object
      required: [name, manifest]
      properties:
        name:
          type: string
          pattern: '^[a-z0-9][a-z0-9_-]{0,79}$'
          description: Unique catalog key. The manifest metadata.name value must match it.
        manifest:
          type: string
          maxLength: 262144
          description: Raw YAML manifest body containing a matching metadata.name value.

    LogEntry:
      type: object
      required: [id, timestamp, level, target, message]
      properties:
        id: { type: string, pattern: '^log_[0-9]+$', description: Stable server-assigned log sequence identifier. }
        timestamp: { type: string, format: date-time }
        level:
          type: string
          enum: [trace, debug, info, warn, error]
        target: { type: string, description: Tracing target / module path. }
        message: { type: string }
        fields:
          type: object
          additionalProperties: true
          description: Structured fields attached to the event.
        trace_id: { type: string, description: "W3C trace-id, when telemetry is enabled." }
        span_id: { type: string }

    Event:
      type: object
      required: [id, kind, timestamp]
      properties:
        id: { type: string, pattern: '^ev_[0-9]+$', description: Stable server-assigned event sequence identifier. }
        kind:
          type: string
          description: Dotted event kind (e.g. `instance.state_changed`, `operation.completed`, `storage.object_written`).
          examples: [instance.state_changed, operation.completed, storage.object_written]
        timestamp: { type: string, format: date-time }
        subject:
          type: string
          description: |
            Resource the event is about, in `kind/id` form (e.g.
            `instance/8a3f...`, `operation/op_01...`).
        data:
          type: object
          additionalProperties: true
          description: Kind-specific payload.