# Especificación OpenAPI 3.1 de la API de HQ Fabric, escrita a partir de internal/api (router en server.go).
# internal/api/openapi_rutas_test.go falla si una ruta del router no está aquí, o si aquí sobra alguna.
# Linter: cd apps/docs && pnpm lint:openapi
openapi: 3.1.0
info:
  title: API de HQ Fabric
  version: 0.1.0
  description: |
    API REST del servidor de HQ Fabric (`cmd/server`, router en `internal/api/server.go`).
    Todas las respuestas son JSON (`Content-Type: application/json; charset=utf-8`).
    Los errores tienen la forma `{"error": "<código>", "message": "<texto>"}`.
  license:
    name: Ver LICENSE
    url: https://github.com/jarciahdz111/hqfabric/blob/main/LICENSE
servers:
  - url: http://127.0.0.1:8080
    description: Servidor local de desarrollo (`make dev`)
tags:
  - name: Autenticación
    description: Código por correo, sesión del navegador (JWT) y su cierre.
  - name: Cuenta y tokens
    description: Tu perfil, tus preferencias de aviso y tus tokens de API (`hqf_`).
  - name: Workspaces y miembros
    description: Crear y configurar workspaces, y quién es miembro con qué rol.
  - name: Organización
    description: Roles del SDLC y políticas de la organización del workspace.
  - name: Conectores
    description: "Azure DevOps y Jira: configuración, prueba y el work item de un issue."
  - name: GitHub
    description: GitHub App, token del workspace, OAuth de tu cuenta, repositorios y webhooks.
  - name: Daemon
    description: Lo que usa el daemon `hqf` con el token del runtime, y el agente con el token de la tarea.
  - name: Actividad
    description: El registro de actividad del workspace.
  - name: SDLC
    description: "El pipeline SDLC nativo de un proyecto y de sus issues: jugadas, huecos, revisiones y bandeja."
  - name: Artefactos
    description: "Los artefactos del SDLC: leer, editar, aprobar, pedir cambios y su sensibilidad."
  - name: Issues
    description: "Issues del tablero: crear, leer, cambiar, comentar, lanzar a un agente y fan-out."
  - name: Proyectos
    description: Proyectos del workspace, su configuración SDLC, roles, recetas y métricas.
  - name: Tareas
    description: "Las ejecuciones de agentes: estado, eventos, checkpoints, diff, aprobar, publicar y conducir."
  - name: Revisión
    description: Comentarios por línea en el diff, revisión agéntica y hallazgos.
  - name: Preguntas y permisos
    description: Preguntas estructuradas de los agentes y solicitudes de permiso del modo supervised.
  - name: Búsqueda
    description: Búsqueda en las sesiones de agentes.
  - name: Agentes
    description: "Los agentes del workspace: CLI, runtime, autonomía y skills."
  - name: Skills
    description: Los patrones (skills) que reciben los agentes.
  - name: Runtimes
    description: "Máquinas que ejecutan agentes: registro, configuración, repos, cuota, consentimientos, Docker y SSH."
  - name: Terminales
    description: Terminales en vivo en un runtime.
  - name: Sistema
    description: Estado del servidor.
  - name: Tiempo real
    description: La conexión WebSocket del navegador. Sus mensajes están en la página WebSocket.
  - name: Malla de Contexto
    description: Nodos, aristas, grafo, vista previa del lienzo, estadísticas y ciclo de vida.
  - name: Uso
    description: Tokens y coste por agente y por día.
security: []
paths:
  /api/auth/logout:
    post:
      operationId: logout
      tags:
        - Autenticación
      summary: Cierra la sesión actual
      description: |
        Revoca en el servidor la sesión con la que llamas: su identificador (`jti`) queda en la lista de sesiones
        revocadas hasta que caduca. Con un token de API no hace nada y responde 204 igualmente.
      x-source: internal/api/sessions.go:11
      security:
        - session: []
        - apiToken: []
      responses:
        "204":
          description: Sesión revocada (o nada que revocar).
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/Internal"
  /api/auth/logout-all:
    post:
      operationId: logoutAll
      tags:
        - Autenticación
      summary: Cierra todas tus sesiones
      description: |
        Invalida todas tus sesiones del navegador emitidas hasta ahora, también la actual: dejan de valer las
        emitidas en este mismo segundo o antes. No toca los tokens de API. También funciona llamando con un token
        de API.
      x-source: internal/api/sessions.go:24
      security:
        - session: []
        - apiToken: []
      responses:
        "204":
          description: Sesiones invalidadas.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/Internal"
  /api/auth/reauth:
    post:
      operationId: reauth
      tags:
        - Autenticación
      summary: Renueva la autenticación con un código nuevo
      description: |
        Autenticación reciente (step-up). Con la sesión abierta, pide antes un código con
        `POST /api/auth/request-code` para tu correo y envíalo aquí. Devuelve una sesión nueva con `auth_time` =
        ahora y revoca la anterior. Algunas acciones (p. ej. `PUT /api/w/{ws}/organization/policy`) exigen haber
        entrado con un código hace menos de 10 minutos.

        La sesión la comprueba el handler: con un token de API, 403 `session_required`. Límite de 30 intentos por
        IP en 10 minutos (compartido con `POST /api/auth/verify`) y los mismos bloqueos por correo que el login.
      x-source: internal/api/identity.go:270
      security:
        - session: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReauthRequest"
      responses:
        "200":
          description: La sesión nueva.
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - auth_time
                properties:
                  token:
                    type: string
                    description: JWT de la sesión nueva (7 días).
                  auth_time:
                    type: integer
                    description: Momento de la autenticación, en segundos Unix.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: "`unauthorized` (sin sesión válida) o `invalid_code` (código inválido, caducado o agotado)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          description: "`rate_limited`: demasiados intentos desde esta IP."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/auth/refresh:
    post:
      operationId: refreshSession
      tags:
        - Autenticación
      summary: Renueva la sesión
      description: |
        Cambia el JWT vigente por uno nuevo de 7 días y revoca el anterior. Conserva el `auth_time` de la sesión:
        renovar no cuenta como autenticación reciente. Sólo para sesiones del navegador: el middleware admite un
        token de API, pero el handler le responde 400 `not_a_session`.
      x-source: internal/api/sessions.go:35
      security:
        - session: []
      responses:
        "200":
          description: La sesión nueva.
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - expires_in
                properties:
                  token:
                    type: string
                    description: JWT de la sesión nueva.
                  expires_in:
                    type: integer
                    description: Segundos hasta que caduca (siempre 604800, 7 días).
        "400":
          description: "`not_a_session`: llamaste con un token de API."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/Internal"
  /api/auth/request-code:
    post:
      operationId: requestCode
      tags:
        - Autenticación
      summary: Pide un código de acceso por correo
      description: |
        Pide un código de 6 dígitos para entrar, que vale 10 minutos. Con correo configurado (RESEND_API_KEY) se
        envía por email; sin él, se escribe en el log del servidor.

        La respuesta es la misma para cualquier correo, tenga cuenta o no y sea o no de un administrador, y llega
        antes del envío (SEC-200): ni la respuesta ni lo que tarda dicen si una cuenta existe. Antes de responder
        sólo se comprueba:
        - El correo se normaliza (minúsculas, sin espacios alrededor); tiene que llevar `@` y tener 254
          caracteres como mucho (400 `invalid_email`).
        - Como mucho 20 peticiones por IP en 10 minutos (429 `rate_limited`; el contador vive en la memoria del
          proceso).

        Después, sin cambiar la respuesta, se decide si se crea y se envía el código. No se envía nada si:
        - el registro está deshabilitado (ALLOW_SIGNUP=false), el correo no tiene cuenta y no está en
          INSTANCE_ADMINS;
        - ese correo ya pidió 5 códigos en 10 minutos;
        - en producción y sin correo configurado, no es el de un administrador de la instancia ni, mientras no
          exista ningún usuario, el de la primera cuenta;
        - la instancia pasó el tope de 300 códigos por hora, salvo para los administradores de la instancia (deja
          una alerta de seguridad `login_codes_instance_cap`).
        Si el envío falla, queda en el log del servidor.

        `locale` sólo elige el idioma del correo: si empieza por `en`, inglés; si no, español.
      x-source: internal/api/identity.go:23
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestCodeRequest"
      responses:
        "200":
          description: La petición se aceptó. Si ese correo puede entrar, se crea el código y se envía (o va al log).
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - email_sent
                properties:
                  ok:
                    type: boolean
                    description: Siempre `true`.
                  email_sent:
                    type: boolean
                    description: "`true` si la instancia tiene correo configurado; `false` si los códigos van al log del servidor. No depende del correo pedido."
        "400":
          description: "`bad_json` o `invalid_email`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "`rate_limited`: límite por IP."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/auth/verify:
    post:
      operationId: verifyCode
      tags:
        - Autenticación
      summary: Canjea el código por una sesión
      description: |
        Canjea el código de correo por una sesión del navegador (JWT de 7 días). Si el correo no tiene cuenta y el
        registro está abierto, o está cerrado y el correo está en INSTANCE_ADMINS, crea el usuario: el nombre es `name` (si viene vacío, lo que va antes de la `@`) y
        el idioma, `locale` o, si no viene, el DEFAULT_LOCALE de la instancia, normalizado a `es` o `en`. A una
        cuenta que ya existe no le cambia ni el nombre ni el idioma.

        Reglas:
        - Como mucho 30 intentos por IP en 10 minutos (429 `rate_limited`, en memoria).
        - Bloqueo por correo: con 10 fallos desde la misma IP en 15 minutos, o 100 fallos del correo en una hora
          desde todas las IPs, 429 `rate_limited`. Al llegar al techo por hora se avisa a los administradores de
          la instancia (alerta `login_email_ceiling`).
        - Se compara con el último código vigente del correo; cada código admite 5 intentos por IP y vale una
          sola vez.
        - Fuera de producción, desde loopback y sin cabeceras de proxy, también vale el código fijo
          DEV_VERIFICATION_CODE.
        - Código inválido, caducado o agotado: 401 `invalid_code`.
        - Correo sin cuenta con el registro deshabilitado, que no está en INSTANCE_ADMINS: 403 `signup_disabled` (el
          código ya quedó consumido).
      x-source: internal/api/identity.go:144
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyCodeRequest"
      responses:
        "200":
          description: La sesión y el usuario.
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - user
                properties:
                  token:
                    type: string
                    description: JWT de la sesión (7 días). Va en `Authorization Bearer`.
                  user:
                    $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: "`invalid_code`: código inválido, caducado, ya usado o con los intentos agotados."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "`signup_disabled`: el registro está deshabilitado, el correo no tiene cuenta y no está en INSTANCE_ADMINS."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "`rate_limited`: límite por IP o correo bloqueado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/config:
    get:
      operationId: getConfig
      tags:
        - Autenticación
      summary: Lee la configuración pública de la instancia
      description: |
        Sin autenticación. Lo que la web necesita antes de entrar: si se admite el registro, el idioma por
        defecto, si hay correo configurado, si se puede usar el código fijo de desarrollo y la versión del
        servidor.
      x-source: internal/api/server.go:989
      security: []
      responses:
        "200":
          description: La configuración pública.
          content:
            application/json:
              schema:
                type: object
                required:
                  - allow_signup
                  - default_locale
                  - email_configured
                  - dev_code_hint
                  - version
                properties:
                  allow_signup:
                    type: boolean
                    description: Si se pueden crear cuentas nuevas (ALLOW_SIGNUP).
                  default_locale:
                    type: string
                    description: El idioma por defecto (DEFAULT_LOCALE, tal cual se configuró).
                  email_configured:
                    type: boolean
                    description: Si hay correo configurado (RESEND_API_KEY); sin él, los códigos van al log del servidor.
                  dev_code_hint:
                    type: boolean
                    description: |
                      `true` sólo fuera de producción, con DEV_VERIFICATION_CODE definido, si la petición llega
                      desde loopback y sin cabeceras de proxy (X-Forwarded-For, X-Real-Ip, Forwarded,
                      Cf-Connecting-Ip, X-Forwarded-Host): entonces el código fijo de desarrollo vale para entrar.
                  version:
                    type: string
                    description: La versión del servidor.
  /api/daemon/artifact-writes/{wid}/applied:
    post:
      operationId: daemonArtifactWriteApplied
      tags:
        - Daemon
      summary: Confirma un commit humano de artefacto
      description: |
        El daemon confirma (o no) que aplicó en el worktree del issue un commit humano de artefacto que le llegó por
        `artifact.write` o en el claim (`sdlc.pending_writes`).

        Sólo puede confirmarlo el runtime de la última jugada del SDLC reclamada en ese issue (tras un relevo, el
        anterior ya no): si no, 404 `not_found`.

        - La escritura pasa a `applied` (con `ok: true`) o `failed`, con el commit y el error (recortado a 2000
          caracteres), sólo si seguía `pending`.
        - Con `ok: true`, el artefacto guarda el commit (en `approved_commit_sha` si la escritura era una aprobación;
          si no, en `commit_sha`), queda la actividad `artifact.committed` y se registra el empuje de `pushed` (como en
          `/tasks/{tid}/issue-pushed`). En una aprobación, el work item enlazado se sincroniza en segundo plano.
      x-source: internal/api/sdlc.go:1224
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonWid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonArtifactWriteAppliedRequest"
      responses:
        "200":
          description: Registrado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/claim:
    post:
      operationId: daemonClaim
      tags:
        - Daemon
      summary: Reclama la siguiente tarea
      description: |
        El daemon pide trabajo. No lleva cuerpo. Responde 204 si no hay nada que entregarle y 200 con todo lo que
        necesita para ejecutar la tarea si la reclama.

        Antes de reclamar, el servidor revisa las tareas que este runtime podría ejecutar y no se le entregan por la
        audiencia del issue: sin persona responsable quedan en cola con el motivo (`task.no_responsible`); si la
        responsable ya no ve el issue, la tarea falla cerrada y sin reintento (`task.responsible_lost_access`); si el
        dueño del runtime no ve el issue, queda en cola con el motivo en `queue_reason`.

        Responde 204 (sin reclamar) si el runtime ya tiene `max_parallel` tareas `claimed` o `running` (sin contar las
        esperas largas sin proceso), si el workspace gastó su presupuesto mensual (`monthly_budget_usd`) o si no hay
        ninguna tarea elegible. Una tarea es elegible si está en cola en tu workspace; su agente está activo, atado a
        este runtime o libre, y su CLI está en los `providers` del runtime; no continúa el worktree de otro runtime
        (salvo el relevo con la rama empujada); hay persona responsable y ella y el dueño del runtime ven el issue; el
        agente no llegó a su `concurrency`; no hay otro escritor del SDLC en esa rama; y no la retiene el límite WIP,
        la cuota de este runtime ni el presupuesto del árbol de subtareas. Se toma la más antigua.

        La tarea elegida falla sin reintento (y la respuesta es 204) si su rama recibió secretos (`copy_secrets`) y el
        agente no puede verlos (MAC), si el issue es high o marcado y este runtime tiene el proyecto vinculado a un
        repo local, o si es una subtarea que correría con más permisos que la tarea que la pidió (S6).

        Si no, pasa a `claimed` con su rama (`hqf/<prefijo>-<número>-<agente>-<id>` si no tenía) y su base (la rama
        por defecto del proyecto o `HEAD`), recibe un token de tarea nuevo (`task.agent_token`, prefijo `hqftk_`,
        sólo para el agente y mientras la tarea está en curso), se le añaden las menciones que esperaban y se arma el
        claim con el paquete de contexto. Si armarlo falla, la tarea vuelve a la cola y la respuesta es el error.
      x-source: internal/api/daemon.go:437
      security:
        - runtimeToken: []
      responses:
        "200":
          description: La tarea reclamada y todo lo que necesita el daemon.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClaimResponse"
        "204":
          description: No hay ninguna tarea que entregarte ahora (o la elegida falló al reclamarla).
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/consents/check:
    post:
      operationId: daemonConsentCheck
      tags:
        - Daemon
      summary: Comprueba un consentimiento vigente
      description: |
        Para el teardown y el recolector de worktrees, que corren fuera de una tarea: dice si el dueño del runtime
        tiene un consentimiento vigente (concedido, sin revocar y sin vencer) para ese proyecto, tipo y hash exacto, y
        qué ejecución de código del agente permite ahora la máquina (`host_exec`).

        `host_exec` se calcula con la autonomía con la que se reclamó `task_id` (si es una tarea de este runtime); sin
        ella, como `safe`.
      x-source: internal/api/ops_o1.go:450
      security:
        - runtimeToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonConsentCheckRequest"
      responses:
        "200":
          description: Si sigue vigente y el permiso de ejecución actual.
          content:
            application/json:
              schema:
                type: object
                required:
                  - allowed
                  - host_exec
                properties:
                  allowed:
                    type: boolean
                    description: Hay un consentimiento vigente para ese hash exacto.
                  host_exec:
                    type: string
                    enum:
                      - docker
                      - full
                      - host
                      - ""
                    description: |
                      `docker` si el runtime tiene contenedores; `full` si la autonomía no es `safe` ni `supervised`;
                      `host` si el dueño dio el permiso de ejecutar en el host (para el proyecto o para todos); si no,
                      cadena vacía.
        "400":
          description: "`bad_json` o `invalid` (project_id, kind o subject_hash inválidos)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
  /api/daemon/heartbeat:
    post:
      operationId: daemonHeartbeat
      tags:
        - Daemon
      summary: Envía el latido del daemon
      description: |
        El daemon informa de su estado. El runtime queda `online`, con sus proveedores, sus repos vinculados y, si
        los envías (distintos de 0 / cadena vacía), `max_parallel` y `task_timeout`; si no, se conservan los
        guardados.

        - `repos` reemplaza los repos vinculados: cada clave (slug o id de un proyecto del workspace) se guarda por el
          id del proyecto; las que no son de ningún proyecto se descartan.
        - Las tareas de `running` (de este runtime y en curso) renuevan su latido.
        - `supervised_profile` se guarda si llega.
        - `quota` se registra si trae entre 1 y 256 ventanas (si trae más, se ignora entera).

        Si el runtime estaba offline o cambiaron sus proveedores, se avisa a la web. También se reenvían por el
        WebSocket las purgas de sesiones pendientes de este runtime.
      x-source: internal/api/daemon.go:36
      x-duda: |
        La forma de cada elemento de `providers` la decide el daemon; el servidor la guarda sin validar (la
        reclamación sólo busca objetos con `id`). El campo `version` se decodifica pero el handler no lo usa.
      security:
        - runtimeToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonHeartbeatRequest"
      responses:
        "200":
          description: Los proyectos del workspace y los repos vinculados que quedaron guardados.
          content:
            application/json:
              schema:
                type: object
                required:
                  - projects
                  - repo_paths
                  - server_version
                properties:
                  projects:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectRef"
                  repo_paths:
                    description: Lo guardado en el runtime, id del proyecto → ruta local (JSON tal cual).
                    type:
                      - object
                      - "null"
                    additionalProperties:
                      type: string
                  server_version:
                    type: string
                    description: Versión del servidor.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/permission-requests/{prid}/cancel:
    post:
      operationId: daemonPermCloseCancelled
      tags:
        - Daemon
      summary: Cancela una solicitud de permiso
      description: |
        El daemon cancela una solicitud de permiso suya (fin de la ejecución, hibernar, el CLI la abandonó). Sólo
        cambia si seguía `pending`: pasa a `cancelled` (con motivo `cancelled` si no tenía otro), queda la actividad
        `permission.cancelled`, sale de la bandeja de quienes la deciden y se despierta la consulta de decisión
        abierta. Si ya no estaba pendiente, no cambia nada y la respuesta es la misma.

        Sólo la ve el runtime que la creó (ni otro runtime del workspace ni el agente): si no, 404 `not_found`.
      x-source: internal/api/ops_o3.go:863
      x-duda: |
        Las dos rutas `…/cancel` y `…/expire` usan el mismo handler (`daemonPermClose("cancelled")` y
        `daemonPermClose("expired")`); el operationId lleva el estado para que sea único.
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonPrid"
      responses:
        "200":
          description: El id de la solicitud.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonPermId"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/permission-requests/{prid}/decision:
    get:
      operationId: daemonPermDecision
      tags:
        - Daemon
      summary: Espera la decisión de una solicitud de permiso
      description: |
        Long poll: mientras la solicitud siga `pending`, espera hasta `wait` (como mucho 25 s) a que alguien la
        decida. Una decisión se entrega una sola vez.

        - Sigue pendiente: 200 con `status: pending`.
        - Venció (aunque después la aprobaran desde la bandeja; esa aprobación es para la siguiente idéntica): 200
          con `status: expired`.
        - Decidida: se marca entregada y 200 con el estado y, si lo hay, el motivo. Si ya se había entregado, 409
          `consumed`.

        Sólo la ve el runtime que la creó: si no, 404 `not_found`.
      x-source: internal/api/ops_o3.go:807
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonPrid"
        - name: wait
          in: query
          required: false
          description: |
            Cuánto esperar: segundos (admite decimales) o una duración de Go (`10s`). Como mucho 25 s; vacío, cero,
            negativo o inválido, no espera.
          schema:
            type: string
      responses:
        "200":
          description: El estado de la solicitud.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - status
                  - input_sha256
                  - interrupt
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    description: "`pending`, `expired` o el estado decidido (`approved`, `denied`, `cancelled`)."
                  input_sha256:
                    type: string
                    description: Hash canónico de la entrada.
                  interrupt:
                    type: boolean
                    description: La canceló una persona al cancelar la tarea (deny con interrupt).
                  reason:
                    type: string
                    description: El motivo, sólo al entregar una decisión que lo tiene.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`consumed`: la decisión ya se entregó."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/permission-requests/{prid}/expire:
    post:
      operationId: daemonPermCloseExpired
      tags:
        - Daemon
      summary: Registra el vencimiento de una solicitud de permiso
      description: |
        El daemon registra que venció a su hora una solicitud de permiso suya. Sólo cambia si seguía `pending`: pasa
        a `expired` (motivo `timeout`), queda la actividad `permission.expired`, sale de la bandeja de quienes la
        deciden y se despierta la consulta de decisión abierta. Si ya no estaba pendiente, no cambia nada y la
        respuesta es la misma.

        Sólo la ve el runtime que la creó: si no, 404 `not_found`.
      x-source: internal/api/ops_o3.go:863
      x-duda: |
        Las dos rutas `…/cancel` y `…/expire` usan el mismo handler (`daemonPermClose("cancelled")` y
        `daemonPermClose("expired")`); el operationId lleva el estado para que sea único.
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonPrid"
      responses:
        "200":
          description: El id de la solicitud.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonPermId"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/restarted:
    post:
      operationId: daemonRestarted
      tags:
        - Daemon
      summary: Avisa de que el daemon arrancó
      description: |
        El daemon arrancó de nuevo. No lleva cuerpo. Sus tareas vivas (hasta 200: `claimed` o `running` sin espera
        larga, y las hibernadas) pasan a `blocked` con motivo `restart`; se cancelan sus solicitudes de permiso
        pendientes, la sesión activa queda reanudable y se encola una sola continuación (`trigger: restart`) en la
        misma rama y worktree, que reanuda la sesión si la política lo permite.

        Sólo con el token del runtime: un token de tarea recibe 403 `task_scope`.
      x-source: internal/api/ops_o5.go:402
      security:
        - runtimeToken: []
      responses:
        "200":
          description: Cuántas continuaciones se encolaron.
          content:
            application/json:
              schema:
                type: object
                required:
                  - continued
                properties:
                  continued:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/sessions/purged:
    post:
      operationId: daemonSessionsPurged
      tags:
        - Daemon
      summary: Confirma la purga de sesiones
      description: |
        El daemon borró los transcripts de esas sesiones (tras `sessions.purge`). Se cierran las solicitudes de purga
        de esas tareas que son de tu runtime y la sesión, si todavía existe, queda `purged`. Queda la actividad
        `session.purged` (sin issue si ya no existe).

        Se toman como mucho 500 ids válidos; los que no son uuid se ignoran. Sólo con el token del runtime: un token
        de tarea recibe 403 `task_scope`.
      x-source: internal/api/ops_o5.go:571
      security:
        - runtimeToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonSessionsPurgedRequest"
      responses:
        "200":
          description: Cuántas purgas quedaron confirmadas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - purged
                properties:
                  purged:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/ask:
    post:
      operationId: daemonTaskAsk
      tags:
        - Daemon
      summary: Registra huecos de conocimiento
      description: |
        `hqf agent ask`: el agente pregunta lo que la malla de contexto no sabe. Cada pregunta queda como hueco de
        conocimiento, con quién puede responderla fijado ahora; la tarea queda con un bloqueo, se comentan las
        preguntas en el issue y van a la bandeja de quien puede responderlas (si ve el issue).

        - Cada pregunta se limpia (sin Unicode invisible ni controles, con los secretos redactados) y se corta a 2000
          caracteres; las vacías se descartan. Tiene que quedar de 1 a 10 (si no, 400 `questions_required`).
        - Como mucho 30 huecos por tarea en total (si no, 429 `too_many_questions`).
        - `domain` se limpia, se pasa a minúsculas y se corta a 80 bytes.
      x-source: internal/api/gaps.go:59
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskAskRequest"
      responses:
        "201":
          description: Los huecos creados.
          content:
            application/json:
              schema:
                type: object
                required:
                  - gap_ids
                properties:
                  gap_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
        "400":
          description: "`invalid_id`, `bad_json` o `questions_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/DaemonTaskWaiting"
        "429":
          description: "`too_many_questions`: más de 30 huecos en la tarea."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/binaries:
    post:
      operationId: daemonUploadBinary
      tags:
        - Daemon
      summary: Sube un binario resumido para escanearlo
      description: |
        Antes de completar, el daemon sube cada binario que resumió en el diff para que el servidor lo escanee en L3.
        El servidor comprueba que el contenido es el blob declarado (hash de git, SHA-1 o SHA-256 según la longitud
        de `blob`) y lo pasa por el escáner de secretos.

        - Limpio: queda como hallazgo `uninspected_binary` ya descartado («inspeccionado por el servidor»).
        - Con un secreto: queda un hallazgo `secret` que bloquea y la actividad `guardrail.binary_secret`; al
          completar, la jugada falla.

        Reglas: la tarea tiene que estar `claimed` o `running` (si no, 409 `not_running`); la ruta tiene que
        normalizarse, `blob` ser un id de git (40 o 64 hex) y `data` ocupar como mucho 8 MB (si no, 400 `invalid`);
        como mucho 10 binarios por jugada (409 `too_many`).
      x-source: internal/api/review.go:904
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonUploadBinaryRequest"
      responses:
        "200":
          description: El veredicto del escáner.
          content:
            application/json:
              schema:
                type: object
                required:
                  - verdict
                properties:
                  verdict:
                    type: string
                    enum:
                      - clean
                      - secret
        "400":
          description: "`invalid_id`, `bad_json`, `invalid` o `blob_mismatch` (el contenido no es el blob declarado)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_running` (la tarea no está en curso) o `too_many` (ya hay 10 binarios en la jugada)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/daemon/tasks/{tid}/block:
    post:
      operationId: daemonTaskBlock
      tags:
        - Daemon
      summary: Bloquea la tarea con un motivo
      description: |
        `hqf agent block`: el agente declara un bloqueo. El motivo (con los secretos redactados) queda en la tarea,
        en un comentario del agente en el issue y en la actividad `task.blocker_raised`. El handler no mira el estado
        de la tarea.
      x-source: internal/api/daemon.go:1586
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskBlockRequest"
      responses:
        "200":
          description: Registrado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          description: "`invalid_id`, `bad_json` o `reason_required` (motivo vacío)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/DaemonTaskWaiting"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/checkpoint:
    post:
      operationId: daemonTaskCheckpoint
      tags:
        - Daemon
      summary: Guarda un checkpoint del agente
      description: |
        `hqf agent checkpoint`: el agente deja dónde está, qué sigue y qué le bloquea. Devuelve el checkpoint nuevo y
        el anterior de la cadena de continuaciones (o `null`).

        - La tarea tiene que estar `claimed` o `running` (si no, 409 `task_finished`).
        - El cuerpo, como mucho 64 KB; `step` + `next` + `blockers`, como mucho 2048 bytes (si no, 413 `too_large`).
        - Los tres textos se limpian (sin Unicode invisible ni controles salvo salto de línea y tabulador, con los
          secretos redactados); si la redacción los alarga, se recortan para caber en 2048 bytes. `step` es
          obligatorio (400 `step_required`).
        - Como mucho 200 checkpoints por tarea (429 `too_many`).
      x-source: internal/api/ops_o1.go:106
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonCheckpointRequest"
      responses:
        "201":
          description: El checkpoint guardado y el anterior.
          content:
            application/json:
              schema:
                type: object
                required:
                  - checkpoint
                  - previous
                  - stripped
                properties:
                  checkpoint:
                    $ref: "#/components/schemas/Checkpoint"
                  previous:
                    description: El último checkpoint de la cadena antes de éste, o `null`.
                    oneOf:
                      - $ref: "#/components/schemas/Checkpoint"
                      - type: "null"
                  stripped:
                    type: boolean
                    description: Se quitó Unicode invisible o caracteres de control de algún texto.
        "400":
          description: "`invalid_id`, `bad_json` (también si el cuerpo pasa de 64 KB) o `step_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            `task_finished` (la tarea ya terminó) o `waiting` (token de tarea con la tarea en espera y el proceso
            detenido).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: "`too_large`: step, next y blockers pasan de 2048 bytes."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "`too_many`: la tarea ya tiene 200 checkpoints."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/comment:
    post:
      operationId: daemonTaskComment
      tags:
        - Daemon
      summary: Comenta en el issue de la tarea
      description: |
        `hqf agent comment`: el agente escribe un comentario en el issue de su tarea, con los secretos redactados y la
        tarea como procedencia. Lo ve quien ve el issue.

        Si `body` está vacío (o sólo con espacios), el handler no escribe respuesta: llega un 200 sin cuerpo.
      x-source: internal/api/daemon.go:1561
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskCommentRequest"
      responses:
        "200":
          description: Sin cuerpo (`body` vacío; no se crea nada).
        "201":
          description: El comentario creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/DaemonTaskWaiting"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/complete:
    post:
      operationId: daemonTaskComplete
      tags:
        - Daemon
      summary: Completa la tarea
      description: |
        El daemon informa del final de una ejecución: estado, resumen, uso, diff, lecciones y, en el SDLC, el
        artefacto, la verificación, los hallazgos, la revisión y el diff acumulado. El servidor no se fía del runtime:
        aplica sus guardarraíles y puede cambiar el estado.

        Cuándo se puede completar: la tarea está `claimed` o `running`, o falló con `runtime lost` y nadie la aprobó.
        Si estaba `cancelled`, sólo se suma el uso y la respuesta es `{"ignored": "cancelled"}`. Si no, 409
        `task_finished` (también si otra petición la completó a la vez).

        `status`:
        - `quota`: la ejecución se cortó por un límite de cuota. La tarea no termina: sigue `running` esperando la
          cuota (`wait_state: quota`) hasta el reset que indiques en `quota.resets_at` (si es futuro y a menos de 8
          días) o, si no, una espera que crece con cada continuación por cuota (15 min, 30 min… hasta 4 h). Exige que
          la tarea esté `running` (409 `not_running`) y que `quota.provider`, si llega, sea el del agente (400
          `invalid_quota`). Repetirlo no vuelve a sumar: responde con `repeated: true`.
        - `completed`, `failed`, `blocked`, `cancelled` o `pending_verification`; cualquier otro, 400
          `invalid_status`. `completed` con `blocked` o con un bloqueo ya registrado pasa a `blocked`.

        Lo que el servidor comprueba (puede pasar la tarea a `failed`, sin reintento):
        - Con suelo de sensibilidad alto, el diff no puede tocar archivos que copió `copy_secrets` (no se guarda el
          patch).
        - En el SDLC: el artefacto de la jugada (forma y rutas), los guardarraíles L3 sobre el patch real, L4 sobre el
          diff acumulado, los binarios subidos a `/binaries` (un secreto hace fallar), la revisión, secretos en el
          artefacto y la redacción del resultado (con secretos, falla). Con la configuración SDLC inválida, una jugada
          que verifica falla. `pending_verification` sólo vale en jugadas que verifican.
        - Sin SDLC: se redactan los secretos sin cambiar el estado (actividad `task.secrets_redacted`);
          `pending_verification` pasa a `failed`.

        Con preguntas abiertas y la sesión reanudable, una tarea `running` que completa o se bloquea no termina:
        queda esperando la respuesta (`wait_state: input`) y la respuesta es `{"status": "input"}`.

        Al terminar se guardan el estado, el resumen, el error (recortado a 4000 caracteres), el uso (se suma), el
        diff (el patch se recorta a 4 MB) y el cuerpo del PR (60000 caracteres); el curador aplica las lecciones; se
        aplican las transiciones del issue, los comentarios y el reintento si toca. Si la jugada del SDLC escribe en
        la rama del issue y terminó en verde, sin hallazgos que bloqueen y sin `agent_alive`, `push` lleva un token
        recién emitido para empujarla (nunca en un issue high o marcado).
      x-source: internal/api/daemon.go:1060
      x-duda: |
        La forma de `signals`, de los elementos de `diff.files` (el servidor sólo lee `path`) y de `verdict` en cada
        verificación la decide el daemon.
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteIn"
      responses:
        "200":
          description: |
            Según el caso: terminada (`ok`, `curated`, `push`), esperando cuota (`status: quota`), esperando la
            respuesta a una pregunta (`status: input`) o ignorada por estar cancelada (`ignored: cancelled`).
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Terminada
                    required:
                      - ok
                      - curated
                      - push
                    properties:
                      ok:
                        type: boolean
                        const: true
                      curated:
                        description: Lo que aplicó el curador con las lecciones, o `null`.
                        oneOf:
                          - $ref: "#/components/schemas/CuratorResult"
                          - type: "null"
                      push:
                        description: El token para empujar la rama del issue, o `null`.
                        oneOf:
                          - type: object
                            required:
                              - token
                              - expires_at
                              - revoke_url
                            properties:
                              token:
                                type: string
                              expires_at:
                                type: string
                                format: date-time
                                description: Caducidad del token de la App (fecha cero con el PAT).
                              revoke_url:
                                type: string
                                description: Con la App, adónde revocarlo al terminar el empuje.
                          - type: "null"
                  - type: object
                    title: Esperando cuota
                    required:
                      - status
                      - wait_until
                    properties:
                      status:
                        type: string
                        const: quota
                      wait_until:
                        type:
                          - string
                          - "null"
                        format: date-time
                      repeated:
                        type: boolean
                        description: Ya estaba esperando cuota (el daemon reintentó).
                  - type: object
                    title: Esperando respuesta
                    required:
                      - status
                    properties:
                      status:
                        type: string
                        const: input
                  - type: object
                    title: Ignorada
                    required:
                      - ignored
                    properties:
                      ignored:
                        type: string
                        const: cancelled
        "400":
          description: "`invalid_id`, `bad_json`, `invalid_status` o `invalid_quota`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`task_finished` (ya terminó) o `not_running` (cuota sin estar en ejecución)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/context-metrics:
    post:
      operationId: daemonContextMetrics
      tags:
        - Daemon
      summary: Envía el medidor de contexto
      description: |
        El medidor de contexto de la tarea en vivo: el máximo de tokens de contexto y los turnos. Se guarda como
        mucho uno cada 5 s (los demás se descartan sin error), con la proporción de crecimiento sobre el paquete de
        contexto, y se avisa a quien ve el issue.
      x-source: internal/api/ops_o5.go:669
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonContextMetricsRequest"
      responses:
        "204":
          description: Recibido.
        "400":
          description: "`invalid_id`, `bad_json` o `invalid` (fuera de rango)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/env-consent:
    post:
      operationId: daemonEnvConsent
      tags:
        - Daemon
      summary: Pide el consentimiento para worktree.yaml
      description: |
        Antes de ejecutar el setup de `.hqfabric/worktree.yaml`, copiar secretos, enlazar directorios, clonar
        excepciones o dejar que la lista permitida apruebe sola, el daemon pregunta si el dueño del runtime lo
        consintió para ese proyecto y ese hash exacto. El servidor decide.

        - La tarea tiene que estar `claimed` o `running` (409 `task_finished`). El cuerpo, como mucho 64 KB + 4 KB.
        - `kind` válido, `subject_hash` de 64 hex y `subject` JSON válido de hasta 64 KB (si no, 400 `invalid`).
          Las rutas de `subject.paths` tienen que ser relativas, literales y dentro del repo (400 `invalid_path`).
        - Se niega (200 con `allowed: false` y `reason`): `no_project` (tarea sin proyecto), `full_autonomy` (`link`
          con autonomía total), `sdlc_forbids_link` (`link` en un proyecto con SDLC), `delegation_forbidden`
          (`supervised.allow` con `forbid_host_approval_delegation`), `copy_secrets_off` (`copy_secrets` está
          apagado en esta versión), `agent` (el agente podría leer los secretos) o `mac` (el agente no tiene
          sensibilidad máxima alta).
        - En `supervised.allow`, `subject.allow` tiene que ser la lista `supervised.allow` actual del proyecto, no
          vacía y con ese hash (si no, 400 `invalid`).
        - Con un consentimiento vigente: `allowed: true` y su id; queda la actividad (`worktree.setup`,
          `worktree.linked` o `worktree.secrets_copied`; con `copy_secrets`, la tarea y el issue pasan a
          sensibilidad alta).
        - Sin él: la solicitud queda pendiente para el dueño (un consentimiento vencido de ese hash vuelve a
          pendiente), se le avisa y la respuesta es `allowed: false` con `reason: consent_required` y el id. Al
          permitirlo, la tarea se reencola.
      x-source: internal/api/ops_o1.go:299
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnvConsentIn"
      responses:
        "200":
          description: Si está permitido.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Permitido
                    required:
                      - allowed
                      - consent_id
                    properties:
                      allowed:
                        type: boolean
                        const: true
                      consent_id:
                        type: string
                        format: uuid
                  - type: object
                    title: Negado
                    required:
                      - allowed
                      - reason
                      - message
                      - consent_id
                    properties:
                      allowed:
                        type: boolean
                        const: false
                      reason:
                        type: string
                        enum:
                          - no_project
                          - full_autonomy
                          - sdlc_forbids_link
                          - delegation_forbidden
                          - copy_secrets_off
                          - agent
                          - mac
                          - consent_required
                      message:
                        type: string
                        description: El motivo para personas, en el idioma del workspace.
                      consent_id:
                        type:
                          - string
                          - "null"
                        format: uuid
                        description: La solicitud pendiente (sólo con `consent_required`).
        "400":
          description: "`invalid_id`, `bad_json`, `invalid` o `invalid_path`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`task_finished`: la tarea ya terminó."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/events:
    post:
      operationId: daemonTaskEvents
      tags:
        - Daemon
      summary: Envía eventos de la ejecución
      description: >
        El daemon manda un lote de eventos de la ejecución. Cada uno se guarda con el siguiente número de secuencia

        de la tarea, con los secretos redactados (sin `payload`, `{}`). Los de tipo `pty` se redactan por líneas: si

        su `data` no es base64 válido, o la línea aún no está completa, no se guardan. Renueva el latido de la tarea y
        suma los `tool_call`. Los eventos (salvo `pty`) llegan en vivo a

        quien ve el issue; un `subagents` avisa de que cambió el árbol de subagentes.
      x-source: internal/api/daemon.go:925
      x-duda: Los tipos (`kind`) y la forma de cada `payload` los decide el daemon; el servidor no los valida.
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskEventsRequest"
      responses:
        "200":
          description: Cuántos eventos llegaron en el lote (también los que no se guardaron).
          content:
            application/json:
              schema:
                type: object
                required:
                  - accepted
                properties:
                  accepted:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/issue:
    post:
      operationId: daemonTaskIssue
      tags:
        - Daemon
      summary: Crea un issue desde el agente
      description: |
        `hqf agent issue`: el agente crea un issue nuevo en `backlog`, en el proyecto del issue de su tarea, del que
        hereda en la misma transacción la marca, el high y los participantes. El título y la descripción van con los
        secretos redactados; una prioridad que no es válida pasa a `none`.

        Si el issue nuevo tuviera una audiencia más amplia que el de la tarea, no se crea (409 `audience_mismatch`).
      x-source: internal/api/daemon.go:1660
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskIssueRequest"
      responses:
        "201":
          description: El issue creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Issue"
        "400":
          description: "`invalid_id`, `bad_json` o `title_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            `audience_mismatch` (tendría una audiencia más amplia) o `waiting` (token de tarea con la tarea en espera
            y el proceso detenido).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/issue-pushed:
    post:
      operationId: daemonIssuePushed
      tags:
        - Daemon
      summary: Registra el empuje de la rama del issue
      description: |
        El daemon cuenta el empuje de la rama del issue que autorizó el token `push` de `/complete`. Sólo para una
        jugada del SDLC ya `completed` (si no, 409 `not_completed`). Se ignora `head` (el HEAD ya lo contó la
        finalización): se registra el destino empujado (o el fallo, o por qué se saltó) y se envían al runtime los
        commits humanos pendientes.
      x-source: internal/api/daemon.go:291
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PushedIn"
      responses:
        "200":
          description: Registrado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_completed`: no es una jugada del SDLC completada."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/daemon/tasks/{tid}/manifest:
    post:
      operationId: daemonTaskManifest
      tags:
        - Daemon
      summary: Entrega el manifiesto de publicación
      description: |
        Respuesta del daemon a `task.manifest`: lo que saldría exactamente a GitHub al empujar la rama de un issue
        high o marcado. Sólo vale la respuesta al último pedido de la tarea (`request_id`) que aún no tenga
        manifiesto ni error; si no, 200 con `ok: false` sin cambiar nada.

        El pedido queda con error (y `ok: false`) si no llega manifiesto (con tu `error` o `publish_unknown`), si el
        manifiesto no pasa la comprobación de forma, o si no es exactamente lo pedido (commit de la tarea, rama,
        repo y su id, base, título y cuerpo del PR y check). Si lo es, se guarda la copia con los secretos
        redactados y el hash del original, y `ok: true`.
      x-source: internal/api/publish.go:517
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskManifestRequest"
      responses:
        "200":
          description: Si el manifiesto quedó guardado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/merged:
    post:
      operationId: daemonTaskMerged
      tags:
        - Daemon
      summary: Informa del resultado de un merge local
      description: |
        El daemon informa del merge de la rama de la tarea. Con `ok: true`, la tarea queda fusionada, el issue pasa a
        `done` y queda un comentario del sistema con la rama y `base`; con `ok: false`, un comentario con el error.
        Siempre responde `ok`.
      x-source: internal/api/daemon.go:1699
      x-duda: El campo `commit` se decodifica pero el handler no lo usa.
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskMergedRequest"
      responses:
        "200":
          description: Registrado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/daemon/tasks/{tid}/permission-requests:
    post:
      operationId: daemonCreatePermission
      tags:
        - Daemon
      summary: Crea una solicitud de permiso
      description: |
        Autonomía `supervised`: el agente quiere usar una herramienta fuera de lo permitido y el daemon pide permiso.
        El cuerpo, como mucho 1 MB. La tarea tiene que estar `claimed` o `running` (409 `task_finished`).
        `run_id` (hasta 100), `tool_use_id` (hasta 200) y `tool_name` (`[A-Za-z0-9_.:-]`, hasta 200) son obligatorios
        (400 `invalid`).

        - `auto: denied`: el daemon ya la negó sin mandar la entrada; sólo con `reason` `too_large` o `l1` y sin
          `input` (si no, 400 `invalid`). Queda registrada como negada.
        - Si no, la entrada tiene que ser un objeto JSON (400 `invalid_input`). Se niega sola si su forma canónica
          pasa del tope del proyecto (`too_large`) o si al redactarla quedaría tapado lo que se ejecuta
          (`secret_unreviewable`). La descripción se guarda limpia y recortada a 4 KB.
        - `auto: allowed`: el servidor vuelve a evaluar la lista permitida del proyecto (sólo `Bash`, con el
          consentimiento vigente del dueño y el mismo argv); si no aprueba, 409 `allowlist_mismatch`. Si aprueba,
          queda aprobada.
        - Vacío: a la bandeja. Una idéntica pendiente de la misma ejecución se reutiliza (`pending`); la aprobación
          desde la bandeja de una vencida idéntica en la última hora se consume (`approved`); se niega sola si una
          idéntica ya venció (`timeout_sticky`), si la tarea llegó a su tope de solicitudes (`too_many`) o si ya hay
          otra pendiente en esa ejecución (`one_pending`). Si no, queda `pending` hasta el tiempo del proyecto, la
          tarea pasa a `wait_state: permission` y avisa a quienes pueden decidirla.

        Cualquier otro valor de `auto`, 400 `invalid`.
      x-source: internal/api/ops_o3.go:378
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PermCreateIn"
      responses:
        "200":
          description: La solicitud y su estado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermOut"
        "400":
          description: "`invalid_id`, `bad_json`, `invalid` o `invalid_input`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`task_finished` (la tarea no está en ejecución) o `allowlist_mismatch`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/pushed:
    post:
      operationId: daemonTaskPushed
      tags:
        - Daemon
      summary: Informa del empuje de la rama de la tarea
      description: |
        El daemon informa de que empujó (o no) la rama de la tarea tras `task.push`. Siempre responde `ok`; el
        resultado queda en la tarea (`pr_error`) y en comentarios del sistema en el issue.

        - En un issue high o marcado, el empuje sólo cuenta si había una publicación confirmada pendiente y
          `manifest` es el confirmado (o, en una publicación que sigue, del mismo repo, base, rama y commit de la
          tarea); si no, se registra el fallo y no se abre el PR. Un reintento del mismo empuje ya registrado no hace
          nada más.
        - `ok: false`: se guarda el error.
        - Con SDLC, una jugada de código pasa L4 contra GitHub antes del PR; si falla, no se abre ni se actualiza
          (actividad `pr.l4_blocked`).
        - Si no, la tarea queda empujada, se publica el check `hqf/approval` sobre el commit y se abre el PR (o se
          adopta el que ya existe).
      x-source: internal/api/github.go:525
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskPushedRequest"
      responses:
        "200":
          description: Recibido.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/daemon/tasks/{tid}/questions:
    post:
      operationId: daemonTaskQuestions
      tags:
        - Daemon
      summary: Hace una pregunta estructurada
      description: |
        `hqf agent ask --question`: el agente hace una pregunta con opciones, valor por defecto y plazo. La tarea
        queda bloqueada por la pregunta (`block_reason: question`), queda un comentario en el issue (sin el texto de
        la pregunta) y llega a la bandeja de quien puede responderla, fijado ahora.

        - La tarea tiene que estar `claimed` o `running` (409 `task_finished`). El cuerpo, como mucho 64 KB.
        - `question`: hasta 2000 caracteres (400 `question_too_long`); se limpia (sin Unicode invisible, con los
          secretos redactados) y no puede quedar vacía (400 `question_required`).
        - `options`: ninguna o de 2 a 8, cada una de hasta 200 caracteres (400 `option_too_long`), no vacías ni
          repetidas sin distinguir mayúsculas (400 `invalid_options`).
        - `default`: tiene que ser una de las opciones (400 `invalid_default`) y exige `timeout_sec` (400
          `default_needs_timeout`).
        - `timeout_sec`: de 60 s a 7 días (400 `invalid_timeout`).
        - `role`: `product_owner`, `engineer`, `code_owner` o `context_owner` (400 `invalid_role`).
        - `domain`: también crea un hueco de conocimiento (dominio en minúsculas, hasta 80 bytes).
        - Como mucho 30 preguntas por tarea, contando las continuaciones que nadie respondió (429
          `too_many_questions`).
      x-source: internal/api/ops_o2.go:202
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskQuestionsRequest"
      responses:
        "201":
          description: La pregunta creada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - question_id
                  - gap_id
                  - timeout_at
                properties:
                  question_id:
                    type: string
                    format: uuid
                  gap_id:
                    type:
                      - string
                      - "null"
                    format: uuid
                    description: El hueco de conocimiento, sólo con `domain`.
                  timeout_at:
                    type:
                      - string
                      - "null"
                    format: date-time
                    description: Cuándo vence, sólo con `timeout_sec`.
        "400":
          description: |
            `invalid_id`, `bad_json`, `question_too_long`, `question_required`, `invalid_options`, `option_too_long`,
            `invalid_default`, `default_needs_timeout`, `invalid_timeout` o `invalid_role`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            `task_finished` (la tarea ya terminó) o `waiting` (token de tarea con la tarea en espera y el proceso
            detenido).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "`too_many_questions`: la tarea ya hizo 30 preguntas."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/remember:
    post:
      operationId: daemonTaskRemember
      tags:
        - Daemon
      summary: Guarda una lección en la malla de contexto
      description: |
        `hqf agent remember`: el agente deja una lección. El cuerpo (con los secretos redactados en `body` y
        `section`) tiene que tener al menos 12 caracteres (400 `too_short`). El curador la añade o la fusiona con una
        parecida; si no cabe en su ámbito (o el issue es high o marcado), baja al issue. Hereda la sensibilidad alta
        de la tarea si la tiene.
      x-source: internal/api/daemon.go:1633
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Lesson"
      responses:
        "200":
          description: Lo que aplicó el curador.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CuratorResult"
        "400":
          description: "`invalid_id`, `bad_json` o `too_short`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/DaemonTaskWaiting"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/session:
    post:
      operationId: daemonTaskSession
      tags:
        - Daemon
      summary: Registra o actualiza la sesión de la tarea
      description: |
        El daemon registra la sesión del CLI de la tarea (para reanudarla) o actualiza su estado y sus acumulados. El
        servidor fija todo salvo `session_id` y los acumulados.

        - `session_id` tiene que ser un uuid en minúsculas (400 `invalid_session`); `status`, `active` (o vacío),
          `resumable` o `closed` (400 `invalid_status`). Un `head_sha` que no es un SHA de 40 hex se ignora.
        - Primer registro: el `session_id` no puede ser de otra tarea (409 `session_taken`) y `cwd` tiene que ser el
          worktree de la tarea (409 `cwd_mismatch`).
        - Después, el `session_id` queda fijado (409 `session_fixed`), salvo que la reanudación concedida no
          arrancara y el daemon siguiera con una sesión nueva (`fresh: true`): entonces se adopta, si no es de otra
          tarea y el cwd cuadra (si no, 409 `session_taken`).
        - Una sesión purgada no se toca (409 `purged`); con otro cwd, la sesión se cierra (409 `cwd_mismatch`). Una
          cerrada no vuelve a abrirse. Los acumulados sólo crecen.
      x-source: internal/api/ops_o5.go:277
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonSessionRequest"
      responses:
        "200":
          description: El estado que quedó guardado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                    enum:
                      - active
                      - resumable
                      - closed
        "400":
          description: "`invalid_id`, `bad_json`, `invalid_session` o `invalid_status`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`session_taken`, `cwd_mismatch`, `session_fixed` o `purged`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/start:
    post:
      operationId: daemonTaskStart
      tags:
        - Daemon
      summary: Marca la tarea como iniciada
      description: |
        El daemon preparó el worktree y arranca el agente. Si la tarea está `claimed` o `running`, pasa a `running`
        (la hora de inicio, la primera vez) con su worktree y su base si llegan; `base_sha` (un SHA de 40 hex; si
        no, se ignora) sólo se guarda la primera vez. El issue pasa a `in_progress` si estaba en `backlog`, `todo` o
        `in_review`, y queda la actividad `task.started`.
      x-source: internal/api/daemon.go:887
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskStartRequest"
      responses:
        "200":
          description: Registrado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/status:
    get:
      operationId: daemonTaskStatus
      tags:
        - Daemon
      summary: Lee el estado de la tarea
      description: |
        `hqf agent status`: el estado actual de la tarea (p. ej. para saber si la cancelaron).
      x-source: internal/api/daemon.go:919
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      responses:
        "200":
          description: El estado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                    enum:
                      - queued
                      - claimed
                      - running
                      - blocked
                      - completed
                      - failed
                      - cancelled
                      - pending_verification
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/DaemonTaskWaiting"
  /api/daemon/tasks/{tid}/steers/{sid}:
    get:
      operationId: daemonSteerText
      tags:
        - Daemon
      summary: Lee un mensaje de conducción en vivo
      description: |
        El texto (ya redactado) de un mensaje de conducción en vivo de esa tarea y el nombre de quien lo escribió
        (`?` si no se sabe), para entregárselo al agente.
      x-source: internal/api/ops_o5.go:627
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
        - $ref: "#/components/parameters/daemonSid"
      responses:
        "200":
          description: El mensaje.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - author
                  - text
                properties:
                  id:
                    type: string
                    format: uuid
                  author:
                    type: string
                  text:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          description: "`not_found`: la tarea no es de tu runtime o el mensaje no es de esa tarea."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/daemon/tasks/{tid}/steers/{sid}/delivered:
    post:
      operationId: daemonSteerDelivered
      tags:
        - Daemon
      summary: Marca entregado un mensaje de conducción
      description: |
        El daemon entregó al agente ese mensaje de conducción en vivo. Se guarda la hora de entrega (sólo la primera
        vez). No lleva cuerpo.
      x-source: internal/api/ops_o5.go:646
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
        - $ref: "#/components/parameters/daemonSid"
      responses:
        "204":
          description: Marcado.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          description: "`not_found`: la tarea no es de tu runtime o el mensaje no es de esa tarea."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/subtask:
    post:
      operationId: daemonTaskSubtask
      tags:
        - Daemon
      summary: Crea una subtarea
      description: |
        `hqf agent subtask`: el agente crea un issue hijo con su tarea. Sólo con el token de la tarea: el token del
        runtime recibe 403 `task_token_required`. El cuerpo, como mucho 64 KB.

        - `title` y `prompt` se limpian (sin Unicode invisible, con los secretos redactados); el título va en una
          línea y hasta 200 bytes, el prompt hasta 16000 bytes. Los dos son obligatorios (400 `invalid`).
        - Profundidad máxima 3 (409 `depth_limit`) y como mucho 5 subtareas por cadena de continuaciones de la tarea
          (409 `children_limit`).
        - El hijo nace en `todo`, sin asignado, en el proyecto del padre y con su audiencia (marca, high y
          participantes). No corre con más autonomía ni sensibilidad máxima que la tarea que lo pidió.
        - Con SDLC en el padre, el hijo entra en su pista (por defecto `chore`); si la pista espera a una persona, no
          se lanza tarea y `task_id` llega vacío. Sin SDLC, se encola su tarea con la persona responsable de la tarea
          padre.
      x-source: internal/api/ops_o5.go:1099
      security:
        - runtimeToken: []
        - taskToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonSubtaskRequest"
      responses:
        "201":
          description: El issue hijo y su tarea.
          content:
            application/json:
              schema:
                type: object
                required:
                  - key
                  - issue_id
                  - task_id
                  - depth
                properties:
                  key:
                    type: string
                    description: Clave del issue hijo (p. ej. `HQ-42`).
                  issue_id:
                    type: string
                    format: uuid
                  task_id:
                    type: string
                    description: La tarea del hijo; vacío si no se lanzó ninguna (pista del SDLC que espera a una persona).
                  depth:
                    type: integer
        "400":
          description: "`invalid_id`, `bad_json` (también si el cuerpo pasa de 64 KB) o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: |
            `task_token_required` (llegó el token del runtime) o `task_scope` (el token de tarea es de otra tarea).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            `depth_limit`, `children_limit` o `waiting` (la tarea está en espera con el proceso detenido).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/wait:
    post:
      operationId: daemonTaskWait
      tags:
        - Daemon
      summary: Pone o quita el subestado de espera
      description: |
        El daemon pone o quita el subestado (`wait_state`) de una tarea `running` (si no, 409 `not_running`). Sólo con
        el token del runtime: el agente no fabrica señales.

        - `state`: `input`, `permission`, `quota`, `hibernated` o vacío para quitarlo (400 `invalid_state`).
        - `until`: RFC 3339, entre hace un minuto y dentro de 8 días (400 `invalid_until`).
        - `ref`: se limpia, va en una línea y hasta 200 bytes; uno que empieza por `question:` se descarta (esa
          espera sólo la fija el servidor).
        - Con `state: input`, como mucho 10 avisos por tarea; pasado el tope se ignora (204) y se audita una vez
          (`task.wait_capped`).

        Queda la actividad de inicio o fin de la espera (y `session.hibernated` al hibernar) y, con `input`, la
        espera llega a la bandeja de quien lanzó la tarea si ve el issue.
      x-source: internal/api/ops_o2.go:52
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTaskWaitRequest"
      responses:
        "204":
          description: Registrado (o ignorado por el tope de avisos de entrada).
        "400":
          description: "`invalid_id`, `bad_json`, `invalid_state` o `invalid_until`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_running`: la tarea no está en ejecución."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/tasks/{tid}/worktree-proposal:
    post:
      operationId: daemonWorktreeProposal
      tags:
        - Daemon
      summary: Propone un worktree.yaml para el proyecto
      description: |
        El daemon encontró en la base `.worktreeinclude`, `orca.yaml` o `conductor.json` y ningún `worktree.yaml`, y
        propone uno. El texto viene del repo: se guarda limpio (sin Unicode invisible, con los secretos redactados).
        Queda una propuesta por proyecto (la nueva sustituye a la anterior).

        - El cuerpo, como mucho 80 KB. El YAML no puede quedar vacío ni pasar de 64 KB y tiene que haber alguna
          fuente conocida en `sources` (las demás se descartan); si no, 400 `invalid`.
        - Sólo con una tarea cuya base es la rama por defecto del proyecto (409 `base_not_default`).
      x-source: internal/api/ops_o1.go:709
      security:
        - runtimeToken: []
      parameters:
        - $ref: "#/components/parameters/daemonTid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonWorktreeProposalRequest"
      responses:
        "200":
          description: Guardada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaemonOk"
        "400":
          description: "`invalid_id`, `bad_json` (también si el cuerpo pasa de 80 KB) o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`base_not_default`: la base de la tarea no es la rama por defecto del proyecto."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/worktrees/status:
    post:
      operationId: daemonWorktreesStatus
      tags:
        - Daemon
      summary: Pregunta qué worktrees ya no hacen falta
      description: |
        Para el recolector de worktrees: de las tareas que el daemon conserva en disco, cuáles ya no necesitan su
        worktree. Lo son las de tu runtime cuyo issue está `done` o `cancelled` y en cuya rama no hay nada en cola ni
        en marcha ni nada terminado en las últimas 24 h. Se toman como mucho 500 ids válidos; los que no son uuid se
        ignoran.
      x-source: internal/api/ops_o1.go:791
      security:
        - runtimeToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonWorktreesStatusRequest"
      responses:
        "200":
          description: Las tareas cuyo worktree se puede quitar.
          content:
            application/json:
              schema:
                type: object
                required:
                  - done
                properties:
                  done:
                    type: array
                    items:
                      type: string
                      format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/worktrees/teardown-skipped:
    post:
      operationId: daemonTeardownSkipped
      tags:
        - Daemon
      summary: Avisa de un teardown que no se ejecutó
      description: |
        El daemon no ejecutó el teardown de un worktree con cambios del agente porque falta el permiso de ejecutar en
        el host. Queda un aviso en la bandeja del dueño del runtime (uno por worktree sin descartar; uno nuevo lo
        sustituye), con el puerto y los procesos que seguían vivos, y la actividad `worktree.teardown_skipped`.

        - El cuerpo, como mucho 64 KB. El texto viene de la máquina del daemon: se guarda limpio y en una línea
          (worktree hasta 1024 bytes, cada comando hasta 200).
        - `project_id` uuid, `worktree` no vacío y `port` de 0 a 65535 (si no, 400 `invalid`). El proyecto tiene que
          ser de tu workspace (404 `not_found`).
        - `task_id` sólo se guarda si es una tarea de tu runtime en ese proyecto. De `processes`, como mucho 50 con
          `pid` positivo.
      x-source: internal/api/ops_o1.go:840
      security:
        - runtimeToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DaemonTeardownSkippedRequest"
      responses:
        "200":
          description: El aviso.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    format: uuid
        "400":
          description: "`bad_json` (también si el cuerpo pasa de 64 KB) o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "404":
          description: "`not_found`: el proyecto no es de tu workspace."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/daemon/ws:
    get:
      operationId: daemonWS
      tags:
        - Daemon
      summary: Abre el WebSocket del daemon
      description: |
        Canal en vivo entre el servidor y el daemon (avisos de tareas, terminales, empujes, purgas, configuración).
        El token del runtime puede ir en `Authorization: Bearer` o, por ser una ruta `/ws`, en `?token=`. No se
        comprueba el origen (el daemon no es un navegador). Al conectar, el runtime queda `online` y el servidor manda
        `task.available`; si se corta y no vuelve en 30 s, se cierran sus terminales. Los mensajes se documentan
        aparte.
      x-source: internal/api/daemon.go:1890
      security:
        - runtimeToken: []
      parameters:
        - name: token
          in: query
          required: false
          description: El token del runtime (`hqfrt_`), si no va en la cabecera `Authorization`.
          schema:
            type: string
      responses:
        "101":
          description: Cambio a WebSocket.
        "400":
          description: Handshake inválido (versión de WebSocket o `Sec-WebSocket-Key`); texto plano de la biblioteca.
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/DaemonTaskScope"
        "426":
          description: No es una petición de cambio a WebSocket; texto plano de la biblioteca.
          content:
            text/plain:
              schema:
                type: string
  /api/github/app/callback:
    get:
      operationId: githubAppCallback
      tags:
        - GitHub
      summary: Recibe la vuelta del manifest flow de GitHub
      description: |
        GitHub vuelve aquí al crear la App con el manifest. Sin sesión: la autentica el `state` firmado
        (propósito manifest, 30 minutos, de un solo uso). No canjea el `code`: lo guarda cifrado 10 minutos y
        redirige a la web (`<APP_URL>/<slug>/settings?tab=github&gh_confirm=<id>`), que lo canjea con
        `POST /api/w/{ws}/github/confirm`. Con un `state` inválido, caducado o ya usado responde 400 en texto
        plano.
      x-source: internal/api/github_app.go:500
      security: []
      parameters:
        - name: state
          in: query
          required: true
          schema:
            type: string
        - name: code
          in: query
          required: false
          schema:
            type: string
      responses:
        "302":
          description: Redirección a los ajustes del workspace en la web.
          headers:
            Location:
              description: "`<APP_URL>/<slug>/settings?tab=github&gh_confirm=<id>`."
              schema:
                type: string
        "400":
          description: State inválido, caducado o ya usado.
          content:
            text/plain:
              schema:
                type: string
  /api/github/app/setup/{wsID}:
    get:
      operationId: githubAppSetup
      tags:
        - GitHub
      summary: Recibe la vuelta de GitHub tras instalar la App
      description: |
        GitHub vuelve aquí tras instalar la App. Sin sesión: la instalación se comprueba con el JWT de la App del
        workspace `wsID` (una instalación de otra App no se acepta) y se guardan sus repos. Como mucho 30
        peticiones por IP en 10 minutos. Redirige a la web: `install=ok` o, si GitHub no confirma la
        instalación, `install=error`. Si la instalación es nueva o cambió, queda en la actividad. Los errores van
        en texto plano.
      x-source: internal/api/github_app.go:633
      security: []
      parameters:
        - name: wsID
          in: path
          required: true
          description: Id del workspace (no se valida su formato; si no tiene App, 404).
          schema:
            type: string
        - name: installation_id
          in: query
          required: true
          description: Id de la instalación (entero positivo).
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "302":
          description: Redirección a los ajustes del workspace en la web.
          headers:
            Location:
              description: "`<APP_URL>/<slug>/settings?tab=github&install=ok` o `…&install=error`."
              schema:
                type: string
        "400":
          description: "`installation_id` ausente o inválido."
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: El workspace no tiene GitHub App (o sus secretos no se descifran).
          content:
            text/plain:
              schema:
                type: string
        "429":
          description: Demasiadas peticiones desde esta IP.
          content:
            text/plain:
              schema:
                type: string
  /api/github/oauth/callback:
    get:
      operationId: githubOAuthCallback
      tags:
        - GitHub
      summary: Recibe la vuelta del OAuth de usuario de GitHub
      description: |
        GitHub vuelve aquí tras autorizar la vinculación de tu cuenta (OAuth de usuario de la App). Sin sesión: la
        autentica el `state` firmado (propósito oauth, 10 minutos, de un solo uso). No canjea el `code`: lo
        guarda cifrado 10 minutos y redirige a la web (`<APP_URL>/<slug>/settings?tab=profile&gh_confirm=<id>`),
        que lo canjea con `POST /api/w/{ws}/github/confirm`. Con un `state` inválido, caducado o ya usado
        responde 400 en texto plano.
      x-source: internal/api/github_oauth.go:42
      security: []
      parameters:
        - name: state
          in: query
          required: true
          schema:
            type: string
        - name: code
          in: query
          required: false
          schema:
            type: string
      responses:
        "302":
          description: Redirección al perfil en la web.
          headers:
            Location:
              description: "`<APP_URL>/<slug>/settings?tab=profile&gh_confirm=<id>`."
              schema:
                type: string
        "400":
          description: State inválido, caducado o ya usado.
          content:
            text/plain:
              schema:
                type: string
  /api/github/webhooks/{wsID}:
    post:
      operationId: githubWebhook
      tags:
        - GitHub
      summary: Recibe un webhook de la GitHub App
      description: |
        Receptor de webhooks de la GitHub App del workspace `wsID`. Sin sesión: lo autentica la firma.
        Comprobaciones, en orden:
        1. Cuerpo de 1 MB como mucho (413).
        2. Una IP con 30 rechazos por firma inválida o por workspace sin App en 10 minutos deja de ser atendida
           (429).
        3. El workspace tiene App con secreto de webhook (404).
        4. `X-Hub-Signature-256` es el HMAC SHA-256 del cuerpo con ese secreto (401).
        5. `X-GitHub-Hook-Installation-Target-ID`, si viene, es el id de la App (401).
        6. Vienen `X-GitHub-Delivery` (8 a 64 caracteres hexadecimales o guiones) y `X-GitHub-Event` (400).
        7. El payload es JSON (400), salvo en `ping`.

        Pasadas, responde 200 con el resultado, que queda registrado por `X-GitHub-Delivery`:
        - `ping`: `{"ok": "pong"}`.
        - `stale`: la fecha del evento en el payload tiene más de 1 hora o está más de 5 minutos en el futuro.
        - `ignored`: evento que no se atiende (o `installation`/`installation_repositories` sin instalación).
        - `undated`: `pull_request`, `issue_comment`, `pull_request_review_comment`, `check_run`, `check_suite` o
          `push` sin fecha.
        - `foreign`: la instalación no es del workspace o el repo (por su id) no es el de uno de sus proyectos en
          esa instalación.
        - `duplicate`: esa entrega ya se registró, o el mismo cuerpo se aceptó en la última hora con otro id.
        - `accepted`: en segundo plano refresca la instalación (con `deleted`, la borra sólo si GitHub confirma
          que ya no existe) o vuelve a sondear los PR afectados. Del payload sólo se usan ids y URLs.

        Los errores van en texto plano.
      x-source: internal/api/webhooks.go:121
      security: []
      parameters:
        - name: wsID
          in: path
          required: true
          description: Id del workspace dueño de la App.
          schema:
            type: string
        - name: X-Hub-Signature-256
          in: header
          required: true
          description: "`sha256=<hmac>` del cuerpo con el secreto del webhook."
          schema:
            type: string
        - name: X-GitHub-Event
          in: header
          required: true
          schema:
            type: string
        - name: X-GitHub-Delivery
          in: header
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
        - name: X-GitHub-Hook-Installation-Target-ID
          in: header
          required: false
          description: Si viene, tiene que ser el id de la App del workspace.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: El payload del evento de GitHub (1 MB como mucho). No se valida su forma más allá de los campos que se usan
                para enrutar y fechar.
      responses:
        "200":
          description: Entrega procesada.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - ok
                    properties:
                      ok:
                        type: string
                        enum:
                          - pong
                  - type: object
                    required:
                      - outcome
                    properties:
                      outcome:
                        type: string
                        enum:
                          - accepted
                          - duplicate
                          - stale
                          - ignored
                          - undated
                          - foreign
        "400":
          description: Faltan `X-GitHub-Delivery` o `X-GitHub-Event`, o el payload no se puede leer.
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Firma inválida, o la entrega es de otra App.
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: El workspace no tiene App con webhook.
          content:
            text/plain:
              schema:
                type: string
        "413":
          description: Cuerpo de más de 1 MB.
          content:
            text/plain:
              schema:
                type: string
        "429":
          description: Demasiadas firmas inválidas desde esta IP.
          content:
            text/plain:
              schema:
                type: string
  /api/me:
    get:
      operationId: getMe
      tags:
        - Cuenta y tokens
      summary: Lee tu usuario
      description: |
        Tu usuario y si eres administrador de la instancia (INSTANCE_ADMINS o, si no está definida, la primera
        cuenta registrada), que es quien puede usar runtimes en la máquina del servidor. También vale con un token
        de alcance `runtime`.
      x-source: internal/api/identity.go:330
      security:
        - session: []
        - apiToken: []
      responses:
        "200":
          description: Tu usuario.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    patch:
      operationId: patchMe
      tags:
        - Cuenta y tokens
      summary: Cambia tu nombre o tu idioma
      description: |
        Cambia tu nombre o tu idioma; lo que no envíes no cambia. El idioma se normaliza: lo que empieza por `en`
        queda `en` y cualquier otro valor, `es`. El nombre no se valida (puede quedar vacío).
      x-source: internal/api/identity.go:339
      security:
        - session: []
        - apiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchMeRequest"
      responses:
        "200":
          description: Tu usuario como queda.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/Internal"
  /api/me/notification-prefs:
    get:
      operationId: getNotificationPrefs
      tags:
        - Cuenta y tokens
      summary: Lee tus preferencias de notificación
      description: |
        Tus preferencias de notificación, una por categoría y siempre en este orden: `questions`, `permissions`,
        `gates`, `quota`, `ci`, `teardown`. Si no guardaste la de una categoría, va la de por defecto: en la app sí
        (`in_app: true`) y en el navegador no (`browser: false`).
      x-source: internal/api/ops_o2.go:1005
      security:
        - session: []
        - apiToken: []
      responses:
        "200":
          description: Las seis preferencias.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationPref"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      operationId: putNotificationPrefs
      tags:
        - Cuenta y tokens
      summary: Guarda tus preferencias de notificación
      description: |
        Guarda tus preferencias de notificación. Cada elemento de `prefs` reemplaza la preferencia de su
        categoría; las categorías que no envíes no cambian. Como mucho 6 elementos (400 `invalid`); una categoría
        desconocida da 400 `invalid_category` y entonces no se guarda nada. Devuelve las seis preferencias como
        quedan, en el mismo orden que `GET`. Sólo con la sesión del navegador.
      x-source: internal/api/ops_o2.go:1010
      security:
        - session: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutNotificationPrefsRequest"
      responses:
        "200":
          description: Las seis preferencias como quedan.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationPref"
        "400":
          description: "`bad_json`, `invalid` (más de 6 elementos) o `invalid_category`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/Internal"
  /api/security-alerts:
    get:
      operationId: listSecurityAlerts
      tags:
        - Autenticación
      summary: Lista las alertas de seguridad de la instancia
      description: |
        Las alertas de seguridad de los últimos 30 días, las más recientes primero y como mucho 50. Cada tipo y
        sujeto se registra como mucho una vez por hora. Tipos (`kind`):
        - `login_email_ceiling`: un correo llegó a 100 intentos fallidos de login en una hora desde todas las IPs;
          `subject` es el correo y `detail` lleva `failures_last_hour`, `distinct_ips` y `limit`.
        - `login_codes_instance_cap`: la instancia llegó al tope de códigos de login por hora; `subject` vacío y
          `detail` con `codes_last_hour` y `limit`.
        - `task_token_while_waiting`: se usó el token de una tarea que esperaba con el proceso detenido;
          `subject` es un hash opaco y `detail` lleva `runtime_id`, `wait_state`, `method`, `route` y
          `own_task_route`.

        Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está definida, la primera cuenta
        registrada).
      x-source: internal/api/security_alerts.go:98
      security:
        - session: []
        - apiToken: []
      responses:
        "200":
          description: Las alertas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - alerts
                properties:
                  alerts:
                    type: array
                    items:
                      $ref: "#/components/schemas/SecurityAlert"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/Internal"
  /api/tokens:
    get:
      operationId: listTokens
      tags:
        - Cuenta y tokens
      summary: Lista tus tokens de API
      description: Tus tokens personales de API, los más recientes primero. Nunca devuelve el token, sólo sus datos.
      x-source: internal/api/identity.go:372
      security:
        - session: []
        - apiToken: []
      responses:
        "200":
          description: Tus tokens.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TokenRow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createToken
      tags:
        - Cuenta y tokens
      summary: Crea un token de API
      description: |
        Crea un token personal de API (prefijo `hqf_`). El token sólo se devuelve en esta respuesta: el servidor
        guarda su hash. Sólo con la sesión del navegador (un token no fabrica tokens).
        - `name`: si viene vacío, `cli`. No se valida su longitud.
        - `scopes`: `api` y/o `runtime` (otro valor: 400 `invalid_scope`). Sin alcances, `runtime` si el nombre
          empieza por `hqf@` (el token de `hqf login`) y `api` en el resto.
        - `days`: días hasta que caduca; 0 o negativo, no caduca.
      x-source: internal/api/identity.go:382
      security:
        - session: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTokenRequest"
      responses:
        "201":
          description: El token creado, con su valor (no se vuelve a mostrar).
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - token
                  - name
                  - scopes
                properties:
                  id:
                    type: string
                    format: uuid
                  token:
                    type: string
                    description: El token (`hqf_` + 64 caracteres hexadecimales).
                  name:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                      enum:
                        - api
                        - runtime
        "400":
          description: "`bad_json` o `invalid_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/Internal"
  /api/tokens/{id}:
    delete:
      operationId: deleteToken
      tags:
        - Cuenta y tokens
      summary: Borra un token de API
      description: |
        Borra uno de tus tokens. Si no existe o no es tuyo, responde 204 igualmente. Sólo con la sesión del
        navegador.
      x-source: internal/api/identity.go:423
      security:
        - session: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Borrado (o no existía).
        "400":
          description: "`invalid_id`: el id no es un uuid."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}:
    get:
      operationId: getWorkspace
      tags:
        - Workspaces y miembros
      summary: Lee el workspace
      description: El workspace, con tu rol en él. También responde sin la barra final (`/api/w/{ws}`).
      x-source: internal/api/identity.go:566
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: patchWorkspace
      tags:
        - Workspaces y miembros
      summary: Cambia el workspace
      description: |
        Cambia los datos del workspace; lo que no envíes no cambia. También responde sin la barra final.
        - `name` e `issue_prefix` no se validan (pueden quedar vacíos); `issue_prefix` se guarda en mayúsculas.
        - `locale` se normaliza a `es` o `en`.
        - `monthly_budget_usd`: tope de gasto de agentes al mes, de 0 a 1.000.000 (400 `invalid_budget`); 0 lo
          quita. Se guarda en `settings.monthly_budget_usd`.
        - `quota_hold_threshold`: umbral de retención por cuota proactiva, de 0,5 a 1 (400 `invalid_threshold`).
          Sólo con la sesión del navegador (403 `session_required`). Queda en la actividad del workspace.
        - `search_audit_days`: días que se guarda la auditoría de búsquedas, de 1 a 365 (400 `invalid_retention`).
          Sólo con la sesión del navegador (403 `session_required`). Si cambia, queda en la actividad.

        Devuelve el workspace como queda.

        Rol mínimo en el workspace: admin.
      x-source: internal/api/identity.go:570
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchWorkspaceRequest"
      responses:
        "200":
          description: El workspace como queda.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "400":
          description: "`bad_json`, `invalid_budget`, `invalid_threshold`, `invalid_retention` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/activity:
    get:
      operationId: listActivity
      tags:
        - Actividad
      summary: Lista la actividad del workspace
      description: |
        Devuelve las 100 actividades más recientes del workspace que puedes ver, de la más nueva a la más
        antigua: la de los issues que ves, la que no es de ningún issue y `issue.audience_narrowed` sólo si
        eres admin del workspace.

        Con `before` (marca de tiempo RFC 3339, con nanosegundos opcionales) sólo salen las anteriores a ese
        instante, para paginar hacia atrás. Si `before` no se puede leer, se ignora y sale la primera página.
      x-source: internal/api/issues.go:696
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: before
          in: query
          required: false
          description: Sólo actividades creadas antes de este instante (RFC 3339). Si no se puede leer, se ignora.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Hasta 100 actividades, de la más nueva a la más antigua.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Activity"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/agents:
    post:
      operationId: createAgent
      tags:
        - Agentes
      summary: Crea un agente
      description: >
        Crea un agente en el workspace. `name` (no vacío) y `provider` son obligatorios, y `provider` tiene que ser

        uno de los CLIs conocidos.


        Si no los mandas: `slug` sale del nombre (si mandas `slug`, se normaliza igual), `color` es el del proveedor,

        `model` e `instructions` vacíos, `concurrency` 1, `triggers`
        `{"on_assign":true,"on_mention":true,"on_comment":false}`,

        `enabled` true, `context_budget_tokens` 24000, `context_target_util` 0.7, `max_sensitivity` `moderate`,

        `run_mode` `headless`, `autonomy` `safe`, `extra_args` vacío y `command_template` vacío.


        Reglas:

        - `autonomy` `supervised` o `full`, o `extra_args` no vacío: sólo un admin u owner del workspace, el owner de la
          organización o un platform_engineer (403 `forbidden`).
        - `command_template` no vacío: sólo un admin u owner del workspace o el owner de la organización (403
        `forbidden`).

        - `quota_hold_threshold`: sólo un admin y con la sesión del navegador (403 `forbidden` o `session_required`);
          0 vuelve al umbral del workspace.
        - `skills_mode`: sólo un admin (403 `forbidden`). Esta comprobación va después de crear el agente: si falla,
          el agente ya quedó creado.
        - `supervised` sólo con `provider` `claude-code` y nunca con `run_mode` `interactive` (400 `invalid`).

        - `extra_args`: como mucho 16 palabras, sólo las flags permitidas para el proveedor y cada una con su valor
          (`--flag valor` o `--flag=valor`).
        - `skill_ids`: sólo se enlazan las skills de este workspace; las demás se ignoran sin error.


        Difunde `agent.updated` y deja en la actividad `agent.mode_changed` (al crear en `supervised` o `full`) y

        `agent.config_changed` (si hay `extra_args` o `command_template`).
      x-source: internal/api/agents.go:148
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AgentInput"
                - required:
                    - name
                    - provider
      responses:
        "201":
          description: El agente creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agent"
        "400":
          description: >
            `bad_json`; `invalid` (falta el nombre o el proveedor, un valor fuera de rango o de su lista, `extra_args`
            no

            permitidos, `supervised` con otro proveedor o en interactivo, un `runtime_id` que no es un UUID o no existe,

            o un id de `skill_ids` que no es un UUID).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (rol insuficiente para la autonomía, `extra_args`, `command_template`, el umbral de cuota o
            `skills_mode`), `session_required` (umbral de cuota con un token de API) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`conflict`: ya hay un agente con ese slug en el workspace."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    get:
      operationId: listAgents
      tags:
        - Agentes
      summary: Lista los agentes del workspace
      description: |
        Devuelve los agentes del workspace ordenados por nombre, con sus skills, las tareas que tienen en marcha
        (`claimed` o `running`), el total de tareas y su coste acumulado, y el catálogo de proveedores (CLIs) que
        conoce el servidor.
      x-source: internal/api/agents.go:61
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Los agentes y los proveedores.
          content:
            application/json:
              schema:
                type: object
                required:
                  - agents
                  - providers
                properties:
                  agents:
                    type: array
                    items:
                      $ref: "#/components/schemas/Agent"
                  providers:
                    type: array
                    description: El catálogo fijo de CLIs de agentes del servidor (`agentcli.Providers`).
                    items:
                      $ref: "#/components/schemas/Provider"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/agents/{aid}:
    get:
      operationId: getAgent
      tags:
        - Agentes
      summary: Lee un agente
      description: Devuelve un agente del workspace.
      x-source: internal/api/agents.go:70
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El agente.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agent"
        "400":
          description: "`invalid_id`: `aid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`not_found` (el agente no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    patch:
      operationId: patchAgent
      tags:
        - Agentes
      summary: Cambia un agente
      description: |
        Cambia sólo los campos que mandas. `slug` se ignora (no se puede cambiar). `runtime_id`: si la clave está en
        el cuerpo se aplica, y `""` o `null` lo quitan (cualquier runtime con el proveedor). El cuerpo se lee con un
        tope de 4 MiB; si un campo trae un tipo equivocado, ese campo se ignora sin error.

        Reglas:
        - Pasar a `supervised` o `full` desde otra autonomía, o cambiar `extra_args`, exige admin u owner del
          workspace, owner de la organización o platform_engineer (403 `forbidden`). Bajar a `safe`, no.
        - Cambiar `command_template` exige admin u owner del workspace u owner de la organización (403 `forbidden`).
        - `quota_hold_threshold`: sólo un admin con la sesión del navegador (se comprueba antes de cambiar nada);
          0 vuelve al umbral del workspace.
        - `skills_mode`: sólo un admin. Se comprueba después de guardar el resto: si falla (403), los demás cambios
          ya quedaron hechos.
        - Con la autonomía, el proveedor y el modo resultantes: `supervised` sólo con `claude-code` y no en
          `interactive` (400 `invalid`).
        - `extra_args` se valida contra el proveedor resultante.
        - `skill_ids` reemplaza las skills del agente (sólo las de este workspace).

        Difunde `agent.updated` y deja `agent.mode_changed` y `agent.config_changed` en la actividad cuando cambian la
        autonomía, `extra_args` o `command_template`.
      x-source: internal/api/agents.go:382
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentInput"
      responses:
        "200":
          description: El agente tras el cambio.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agent"
        "400":
          description: "`invalid_id`, `bad_json` o `invalid` (valor fuera de rango o de su lista, `extra_args` no permitidos,
            `supervised` incompatible, un `runtime_id` que no es un UUID o no existe, o un id de `skill_ids` que no es
            un UUID)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (rol insuficiente), `session_required` (umbral de cuota con un token de API) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el agente no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteAgent
      tags:
        - Agentes
      summary: Borra un agente
      description: |
        Quita el agente de los issues del workspace que lo tenían asignado y lo borra. Responde 204 aunque el agente
        no exista. No exige rol: basta ser miembro del workspace. La base de datos borra en cascada las tareas del
        agente (`tasks.agent_id … ON DELETE CASCADE`). Difunde `agent.deleted`.
      x-source: internal/api/agents.go:562
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Borrado (o no existía).
        "400":
          description: "`invalid_id`: `aid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/agents/{aid}/skills:
    put:
      operationId: setAgentSkills
      tags:
        - Agentes
      summary: Reemplaza las skills de un agente
      description: |
        Borra las skills enlazadas al agente y enlaza las de `skill_ids` que sean de este workspace (las demás se
        ignoran). Una lista vacía o ausente deja el agente sin skills. No exige rol. Con un agente inexistente y alguna
        skill válida responde 400 `invalid`; con la lista vacía, 204.
      x-source: internal/api/agents.go:544
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetAgentSkillsRequest"
      responses:
        "204":
          description: Skills reemplazadas.
        "400":
          description: "`invalid_id`, `bad_json` o `invalid` (un id de `skill_ids` que no es un UUID, o el agente no existe)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/approvals:
    get:
      operationId: approvalsInbox
      tags:
        - SDLC
      summary: Lee tu bandeja de aprobaciones
      description: |
        Junta todo lo que espera algo de ti, sólo de los issues que ves y filtrado por persona:

        - `artifacts`: artefactos en revisión que puedes aprobar (sin `content`; hasta 300, sin los issues de
          origen `eval`).
        - `concerns`: preocupaciones abiertas de esos artefactos que puedes resolver.
        - `gaps` y `questions`: huecos de conocimiento y preguntas abiertas que puedes responder (hasta 300
          cada uno).
        - `code`: issues con Deploy esperando la aprobación del código; `no_four_eyes` y `no_four_eyes_30d`:
          aprobaciones sin cuatro ojos de los últimos 30 días.
        - `merged_outside`, `merged_outside_30d` y `local_only_approvals_30d`: PRs integrados en GitHub sin la
          aprobación de HQ Fabric y aprobaciones con verificación sólo local (30 días).
        - `secret_incidents`, `teardown_pending`, `quota_notices`, `conflicts`, `publish_incidents`,
          `waiting_input`, `wall_time` y `permissions`: avisos y solicitudes que te tocan.
        - `total`: el número de la insignia (en `code` sólo cuenta lo que puedes aprobar; en `permissions`,
          sólo las pendientes).

        Efecto lateral: si lees una solicitud de permiso cuya tarea no ves (por ser dueño del runtime o
        delegado), sale recortada (`limited`) y queda una actividad `permission.read_without_task`, una vez
        por persona y solicitud.
      x-source: internal/api/sdlc.go:1830
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: La bandeja.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApprovalsInbox"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/artifacts/{aid}:
    get:
      operationId: getArtifact
      tags:
        - Artefactos
      summary: Lee un artefacto
      description: |
        Devuelve el artefacto (con su contenido) y sus preocupaciones, cada una con si tú puedes resolverla
        (`can_resolve`: tienes el rol, está abierta y el artefacto está en revisión) y el rol que la resuelve.
        `artifact.can_approve` dice si puedes aprobarlo (tienes el rol y está en revisión). Si no ves el issue
        del artefacto, o no existe, 404.
      x-source: internal/api/sdlc.go:1042
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El artefacto y sus preocupaciones.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`: `aid` no es un UUID."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    put:
      operationId: editArtifact
      tags:
        - Artefactos
      summary: Edita un artefacto
      description: |
        Corriges el artefacto a mano: se crea una versión nueva (`version + 1`, en revisión, con tu nombre en
        `edited_by_name`) y la anterior pasa a `superseded`. El contenido se normaliza (front-matter con la
        procedencia) y se encola un commit humano en la rama del issue, que el runtime aplica cuando no hay
        una jugada escribiendo. En un `spec`, las preocupaciones se vuelven a leer de la tabla del documento y
        sólo se conserva la resolución de las que no cambiaron.

        Sólo se edita la última versión y si está `in_review` o `changes_requested`. El código no exige
        ningún rol más allá de ver el issue.
      x-source: internal/api/sdlc.go:1287
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  maxLength: 400000
                  description: El documento entero en Markdown. El cuerpo (sin front-matter) no puede quedar vacío.
      responses:
        "200":
          description: La versión nueva del artefacto.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactRow"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json`, `empty` (el cuerpo queda vacío) o `invalid` (base de datos)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_editable` (no está en revisión ni con cambios pedidos), `stale` (hay una versión más nueva) o
            `conflict`."
        "413":
          description: "`too_large`: el contenido pasa de 400 000 bytes."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/artifacts/{aid}/approve:
    post:
      operationId: approveArtifact
      tags:
        - Artefactos
      summary: Aprueba un artefacto
      description: |
        Aprueba la versión en revisión del artefacto. Hace falta el rol aprobador del tipo de artefacto en el
        proyecto (o, si ese rol no tiene miembros, el mínimo de `approval_role` del proyecto) y que no quede
        ninguna preocupación abierta.

        Al aprobar: normaliza el contenido, encola el commit de aprobación en la rama del issue, crea o
        actualiza el nodo del artefacto en la malla de contexto, deja la actividad `artifact.approved` y un
        comentario del sistema, y avisa a la máquina del pipeline (que puede lanzar la siguiente jugada).
        Devuelve la vista SDLC del issue.
      x-source: internal/api/sdlc.go:1413
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La vista SDLC del issue tras la aprobación.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueSDLCView"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` (un token de API) o `approval_forbidden` (no tienes el rol aprobador; el mensaje dice
            por qué)."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_in_review` (no está en revisión, o dejó de estarlo) o `concerns_open` (quedan preocupaciones por
            resolver; las lista el mensaje)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/artifacts/{aid}/concerns/{cid}/resolve:
    post:
      operationId: resolveConcern
      tags:
        - Artefactos
      summary: Resuelve una preocupación de un artefacto
      description: |
        Marca como resuelta una preocupación del artefacto en revisión, con tu explicación. La resuelve el
        rol dueño de su categoría (`policy_owner` para security, compliance, brand y ux; `context_owner` para
        los dominios), con el alcance de la categoría, o, si ese rol no tiene miembros, el mínimo de
        `approval_role`. Queda tu nombre en `resolved_by` y la actividad `concern.resolved`. Devuelve el
        artefacto como `GET /artifacts/{aid}`.
      x-source: internal/api/sdlc.go:1563
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
        - name: cid
          in: path
          required: true
          description: Id de la preocupación (p. ej. `P-01`).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - resolution
              properties:
                resolution:
                  type: string
                  description: Cómo se resolvió. No puede ir vacía.
      responses:
        "200":
          description: El artefacto con la preocupación resuelta.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json`, `resolution_required` o `invalid`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden` (no tienes el rol de la categoría)."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el artefacto (o su issue no lo ves) o la preocupación no existen."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_in_review`."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/artifacts/{aid}/request-changes:
    post:
      operationId: requestArtifactChanges
      tags:
        - Artefactos
      summary: Pide cambios en un artefacto
      description: |
        Devuelve la jugada al agente: encola una continuación (trigger `review`) de la última jugada que
        escribió en la rama del artefacto (o de la tarea que lo produjo), con los comentarios abiertos de su
        diff y tu resumen (si no mandas resumen, uno por defecto). El artefacto pasa a `changes_requested` y
        la máquina del pipeline recibe el evento. El cuerpo es opcional y un JSON inválido se ignora.

        El código no exige ningún rol más allá de ver el issue, ni la sesión del navegador.
      x-source: internal/api/sdlc.go:1504
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                summary:
                  type: string
                  description: Lo que hay que cambiar. Vacío = un texto por defecto.
      responses:
        "201":
          description: La continuación encolada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`review_failed` cuando la puerta de encolar te rechaza (tú o la persona responsable no veis el issue)."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el artefacto o la tarea que lo produjo."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_in_review`, `no_task` (el artefacto no tiene tarea de origen) o `review_failed` (la tarea no tiene
            worktree para continuar)."
        "500":
          $ref: "#/components/responses/Internal"
          description: "`review_failed` o `internal`."
  /api/w/{ws}/artifacts/{aid}/sensitivity:
    put:
      operationId: setArtifactSensitivity
      tags:
        - Artefactos
      summary: Cambia la sensibilidad de un artefacto
      description: |
        Fija la sensibilidad del artefacto (todas sus versiones del mismo tipo en el issue). `high` impide
        sincronizarlo con el sistema externo. La decide quien puede aprobar el artefacto o un admin del
        workspace. Queda la actividad `artifact.sensitivity`. Devuelve el artefacto como
        `GET /artifacts/{aid}`.
      x-source: internal/api/connectors.go:420
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sensitivity
              properties:
                sensitivity:
                  type: string
                  enum:
                    - low
                    - moderate
                    - high
      responses:
        "200":
          description: El artefacto con la sensibilidad nueva.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json` o `invalid` (sensibilidad fuera de low, moderate, high)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden` (ni apruebas el artefacto ni eres admin)."
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/artifacts/{aid}/sync:
    post:
      operationId: syncArtifactNow
      tags:
        - Artefactos
      summary: Sincroniza un artefacto con el work item externo
      description: |
        Reintenta a mano la sincronización con el sistema externo (Azure DevOps, Jira): el work item enlazado
        al issue recibe un hipervínculo al artefacto en el SHA aprobado y un comentario. Hace falta ver el
        issue y un rol que pueda usar el conector (admin, owner de la organización o product_owner, engineer
        o context_owner del proyecto), y que la aprobación ya esté commiteada en la rama.

        No se sincroniza nada, y la respuesta es igualmente 200, si el proyecto no usa la fuente de verdad
        `link` o `external`, si el issue no tiene work item enlazado, si el artefacto es `high` o si el issue
        es high o está marcado (en estos dos últimos casos queda `artifact.sync_skipped`). Devuelve el
        artefacto como `GET /artifacts/{aid}`.
      x-source: internal/api/connectors.go:398
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El artefacto (con `external` actualizado si se sincronizó).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`role_required`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found` (artefacto) o `connector_not_found` (el sistema externo no encuentra el work item)."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_committed`: no está aprobado o la aprobación no está commiteada."
        "502":
          description: "`connector_auth`, `connector_api_version` o `connector_error` (el conector falló o no existe)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/artifacts/{aid}/versions:
    get:
      operationId: artifactVersions
      tags:
        - Artefactos
      summary: Lista las versiones de un artefacto
      description: |
        Todas las versiones del mismo tipo de artefacto en el issue, de la más nueva a la más antigua, con su
        contenido. En esta lista no se calcula quién puede aprobar: `can_approve` sale siempre `false` y
        `approver_role` vacío.
      x-source: internal/api/sdlc.go:1066
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: aid
          in: path
          required: true
          description: Id del artefacto (una versión concreta).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las versiones.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArtifactRow"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/assignees:
    get:
      operationId: listAssignees
      tags:
        - Workspaces y miembros
      summary: Lista a quién se puede asignar trabajo
      description: |
        Para el selector de responsables: los miembros (`type: user`) y los agentes activos del workspace
        (`type: agent`); primero las personas y luego los agentes, cada grupo por nombre. En las personas, `slug`
        es lo que va antes de la `@` del correo, `color` es `#64748b` y `provider` va vacío.
      x-source: internal/api/identity.go:749
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Personas y agentes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Assignee"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/conflict-notices/{id}/dismiss:
    post:
      operationId: dismissConflictNotice
      tags:
        - SDLC
      summary: Descarta un aviso de conflicto
      description: |
        Descarta un aviso de conflicto en ruta protegida (queda quién y cuándo, y la actividad
        `conflict.notice_dismissed`). Lo descarta quien está en la audiencia del aviso o cualquier admin u
        owner del workspace, si ve el issue. Si no, si no existe o si ya estaba descartado, 404.
      x-source: internal/api/ops_o6.go:442
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: id
          in: path
          required: true
          description: Id del aviso.
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Aviso descartado.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found` (también ante cualquier error de la base de datos)."
  /api/w/{ws}/connectors:
    get:
      operationId: listConnectors
      tags:
        - Conectores
      summary: Lista los conectores del workspace
      description: |
        Los conectores del workspace con sistemas de work items (Azure DevOps, Jira), por nombre. Nunca devuelve el
        token: sólo `token_hint`.
      x-source: internal/api/connectors.go:44
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Los conectores.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ConnectorRow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/connectors/{name}:
    put:
      operationId: putConnector
      tags:
        - Conectores
      summary: Crea o actualiza un conector
      description: |
        Crea o actualiza el conector `name`. Sólo un admin u owner del workspace o un owner de la organización
        (403 `forbidden`), y con la sesión del navegador.
        - `name` (en la ruta): minúsculas, números y guiones, empieza por letra o número, 40 caracteres como mucho
          (400 `invalid_name`).
        - `kind`: `azure_devops` o `jira`.
        - `base_url`: `https://` (`http://` sólo con CONNECTORS_ALLOW_HTTP=true), sin credenciales, query ni
          fragmento. Se guarda sin la barra final.
        - `api_version` (Azure DevOps): por defecto `7.0`; formato `N.N` con `-preview` o `-preview.N` opcional.
        - `username` (Jira): obligatorio, el correo de la cuenta del token.
        - `token` (PAT): obligatorio al crear; vacío al editar conserva el guardado (si no hay ninguno, 400
          `token_required`). Se guarda cifrado.

        La configuración se valida antes de guardar nada (400 `invalid_connector`, con el motivo). Queda en la
        actividad. Devuelve el conector.
      x-source: internal/api/connectors.go:72
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: name
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]{0,39}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutConnectorRequest"
      responses:
        "200":
          description: El conector como queda.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectorRow"
        "400":
          description: "`invalid_name`, `bad_json`, `token_required`, `invalid_connector` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteConnector
      tags:
        - Conectores
      summary: Borra un conector
      description: |
        Borra el conector `name`; responde 204 aunque no existiera (y queda igualmente en la actividad). Sólo un
        admin u owner del workspace o un owner de la organización (403 `forbidden`), y con la sesión del
        navegador.
      x-source: internal/api/connectors.go:143
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Borrado (o no existía).
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/connectors/{name}/test:
    post:
      operationId: testConnector
      tags:
        - Conectores
      summary: Prueba un conector
      description: |
        Prueba el conector `name` contra su sistema, con 20 segundos de tope (Jira: `GET /rest/api/3/myself`;
        Azure DevOps: su proyecto o, sin proyecto, la lista de proyectos), y guarda el resultado en
        `last_check_at` y `last_check_error`. Lo puede hacer cualquier miembro: no exige rol ni sesión del
        navegador. Conector inexistente, token que no se descifra o configuración inválida: 400 `connector`.
      x-source: internal/api/connectors.go:174
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: El sistema respondió bien.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    description: Siempre `true`.
        "400":
          description: "`connector`: no existe, su token no se descifra o su configuración es inválida."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: "`workspace_not_found` o `connector_not_found` (el sistema externo no encuentra el proyecto)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`connector_auth` (credenciales rechazadas), `connector_api_version` o `connector_error`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/context/edges:
    get:
      operationId: listContextEdges
      tags:
        - Malla de Contexto
      summary: Lista las aristas de la malla
      description: |
        Devuelve las aristas del workspace cuyos dos nodos ves (llevan sus títulos), de la más vieja a la más nueva,
        como mucho 5000.
      x-source: internal/api/context.go:425
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Las aristas que ves.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EdgeRow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createContextEdge
      tags:
        - Malla de Contexto
      summary: Crea una arista entre dos nodos
      description: |
        Une dos nodos distintos con una relación. Los dos tienen que existir en este workspace y verse; si no, 404
        exacto (no se distingue un nodo que no ves de uno que no existe).

        Si ya hay una arista con el mismo origen, destino y relación, no se crea otra: se le cambia el peso por el
        que mandes (o por 1.0 si no lo mandas) y se devuelve igualmente con 201. `weight` no se valida.

        Avisa por el WebSocket (`context.updated` con `edge_id`) a quien ve los dos nodos.
      x-source: internal/api/context.go:435
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateContextEdgeRequest"
      responses:
        "201":
          description: La arista creada (o la que ya existía, con el peso nuevo).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EdgeRow"
        "400":
          description: |
            `bad_json`; `invalid` («Arista inválida»: `from_node` o `to_node` no son uuid, son el mismo nodo o
            `relation` no es de la enumeración; o datos que rechaza la base de datos).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/edges/{eid}:
    delete:
      operationId: deleteContextEdge
      tags:
        - Malla de Contexto
      summary: Borra una arista
      description: |
        Borra la arista si es de este workspace y ves sus dos nodos; si no, o si no existe, 404 y no se borra.
        Avisa por el WebSocket (`context.updated` con `deleted_edge`) a quien veía los dos nodos.
      x-source: internal/api/context.go:476
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: eid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Borrada.
        "400":
          description: "`eid` no es un uuid (`invalid_id`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/graph:
    get:
      operationId: contextGraph
      tags:
        - Malla de Contexto
      summary: Devuelve el grafo de la malla
      description: |
        Devuelve los nodos que ves (como mucho 800, los modificados más recientemente primero) y las aristas entre
        ellos.

        Con `project_id` (si es un uuid; si no, se ignora), la malla vista desde ese proyecto: los nodos del
        workspace y de los agentes, los del proyecto y los de los issues del proyecto. Sin `archived=true`, quedan
        fuera los archivados.
      x-source: internal/api/context.go:502
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: project_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: archived
          in: query
          required: false
          description: Con `true`, incluye los nodos archivados. Cualquier otro valor es como no mandarlo.
          schema:
            type: string
            enum:
              - "true"
      responses:
        "200":
          description: Los nodos y las aristas entre ellos.
          content:
            application/json:
              schema:
                type: object
                required:
                  - nodes
                  - edges
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: "#/components/schemas/ContextNode"
                  edges:
                    type: array
                    items:
                      $ref: "#/components/schemas/EdgeRow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/lifecycle:
    post:
      operationId: runLifecycle
      tags:
        - Malla de Contexto
      summary: Ejecuta el ciclo de vida de la malla
      description: |
        Rol mínimo en el workspace: admin.

        Ejecuta ya el ciclo de vida que el servidor corre cada hora: mueve los nodos entre `active`, `warm`, `cold`
        y `archived` según su utilidad (peso y votos útiles y dañinos) y lo reciente de su último uso. Un nodo fijado
        vuelve siempre a `active`; uno con 3 o más votos dañinos y más dañinos que útiles se archiva; uno verificado
        escrito por una persona no baja de `warm` salvo por esa regla. No lleva cuerpo.

        Devuelve cuántos nodos cambiaron de estado y avisa a todo el workspace por el WebSocket
        (`context.updated` con `lifecycle`).
      x-source: internal/api/context.go:644
      x-duda: |
        `contextmesh.Lifecycle` (internal/contextmesh/curator.go:231) no filtra por workspace: actualiza los nodos de
        todos los workspaces de la instancia, y `transitions` los cuenta todos. No consta en el código si es
        intencionado que lo dispare el admin de un solo workspace.
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Cuántos nodos cambiaron de estado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - transitions
                properties:
                  transitions:
                    type: integer
                    format: int64
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/nodes:
    get:
      operationId: listContextNodes
      tags:
        - Malla de Contexto
      summary: Lista los nodos de la malla
      description: |
        Devuelve los nodos del workspace que ves por la audiencia de su ámbito: los de un issue, si ves el issue;
        los de un proyecto, si estás en su audiencia (sus roles y los admins, o todo el workspace si no tiene
        roles); los del workspace y los de agentes, todo miembro.

        Los filtros con un valor que no es válido se ignoran (no dan 400): `scope`, `kind` y `slot` sólo cuentan si
        son de su enumeración, `scope_id` si es un uuid y `verified` si vale `true` o `false`. Sin `state`, quedan
        fuera los nodos archivados. Como mucho 1000 nodos, primero los fijados y luego por ámbito, sección y título.
      x-source: internal/api/context.go:79
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: scope
          in: query
          required: false
          schema:
            type: string
            enum:
              - workspace
              - project
              - agent
              - issue
        - name: scope_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: kind
          in: query
          required: false
          schema:
            type: string
            enum:
              - rule
              - convention
              - doc
              - adr
              - repo
              - skill
              - memory
              - artifact
              - glossary
              - plan
        - name: slot
          in: query
          required: false
          schema:
            type: string
            enum:
              - instructions
              - knowledge
              - tools
              - memory
              - state
              - query
        - name: state
          in: query
          required: false
          description: |
            Uno o varios estados separados por comas (p. ej. `active,warm`). No se valida: un valor que no es un
            estado no casa con ningún nodo. Sin este parámetro, todos menos `archived`.
          schema:
            type: string
        - name: verified
          in: query
          required: false
          schema:
            type: string
            enum:
              - "true"
              - "false"
        - name: q
          in: query
          required: false
          description: Texto que tiene que aparecer en el título o en el cuerpo (sin distinguir mayúsculas). Se recortan los
            espacios.
          schema:
            type: string
      responses:
        "200":
          description: Los nodos que ves (como mucho 1000).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ContextNode"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createContextNode
      tags:
        - Malla de Contexto
      summary: Crea un nodo de la malla
      description: |
        Crea un nodo. `title` es obligatorio (no vale vacío ni sólo espacios); se guarda sin espacios a los lados.

        Valores por omisión: `scope` = `workspace`, `kind` = `doc`, `slot` según el `kind` (`rule` y `convention` →
        `instructions`, `memory` → `memory`, `skill` → `tools`, `plan` → `state`, el resto → `knowledge`), `slug`
        sacado del título (o de `slug`, también normalizado), `body` vacío, `tags` vacío, `weight` 1.0, `pinned`
        false, `sensitivity` `low`, `section` vacía. Un `uri` vacío se guarda como null. `state` y `verified` del
        cuerpo no se usan al crear: el nodo nace `active` (el valor por defecto de la tabla) y verificado, con
        `source_type` = `user` y tú como autor. `token_count` se estima en unos 4 caracteres por token sobre título y
        cuerpo.

        Ámbito: con `scope` distinto de `workspace` hace falta `scope_id` (400 `scope_id_required`); con `workspace`,
        `scope_id` se ignora. Para escribir en un issue tienes que verlo, y en un proyecto, estar en su audiencia; si
        no, o si no existe, 404 `not_found`. Un agente que no es de este workspace da 400 `invalid_scope`.

        Avisa por el WebSocket (`context.updated` con `node_id`) a quien ve el nodo.
      x-source: internal/api/context.go:172
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContextNodeInput"
      responses:
        "201":
          description: El nodo creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContextNode"
        "400":
          description: |
            `bad_json`; `invalid` (`scope`, `slot`, `kind`, `state` o `sensitivity` fuera de su enumeración, `weight`
            fuera de 0…10, `scope_id` que no es un uuid, o datos que rechaza la base de datos); `title_required`;
            `scope_id_required`; `invalid_scope` (el agente de la capa no existe en este workspace).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: El workspace no existe o no eres miembro (`workspace_not_found`), o el issue o el proyecto del ámbito no
            existe o no lo ves (`not_found`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Ya hay un nodo con ese `slug` en el mismo ámbito (`conflict`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/nodes/{nid}:
    get:
      operationId: getContextNode
      tags:
        - Malla de Contexto
      summary: Lee un nodo con sus aristas y deltas
      description: |
        Devuelve el nodo si lo ves por la audiencia de su ámbito (si no, o si no existe, 404 exacto), con las aristas
        que lo tocan y cuyos dos nodos ves, y sus últimos 50 deltas (del más nuevo al más viejo). Un delta que viene
        de una tarea sólo sale si ves el issue de esa tarea.
      x-source: internal/api/context.go:289
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: nid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El nodo, sus aristas y sus deltas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - node
                  - edges
                  - deltas
                properties:
                  node:
                    $ref: "#/components/schemas/ContextNode"
                  edges:
                    type: array
                    items:
                      $ref: "#/components/schemas/EdgeRow"
                  deltas:
                    type: array
                    items:
                      $ref: "#/components/schemas/DeltaRow"
        "400":
          description: "`nid` no es un uuid (`invalid_id`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    patch:
      operationId: patchContextNode
      tags:
        - Malla de Contexto
      summary: Modifica un nodo
      description: |
        Cambia los campos que mandes: `slot`, `kind`, `section`, `title`, `body`, `uri`, `tags`, `weight`, `pinned`,
        `state`, `sensitivity` y `verified`. `scope`, `scope_id` y `slug` se aceptan en el cuerpo pero se ignoran
        (el ámbito y el slug no cambian). Un campo ausente o null no se toca, así que `uri` no se puede volver a null.

        Si cambias `body` y no mandas `verified`, el nodo queda verificado (quien edita el cuerpo lo avala).
        `token_count` se recalcula con el título y el cuerpo resultantes.

        Si no ves el nodo, 404 antes de leer el cuerpo. Avisa por el WebSocket (`context.updated` con `node_id`) a
        quien ve el nodo.
      x-source: internal/api/context.go:317
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: nid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContextNodeInput"
      responses:
        "200":
          description: El nodo modificado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContextNode"
        "400":
          description: |
            `invalid_id` (`nid` no es un uuid); `bad_json`; `invalid` (un valor fuera de su enumeración, `weight`
            fuera de 0…10, `scope_id` que no es un uuid, o datos que rechaza la base de datos).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteContextNode
      tags:
        - Malla de Contexto
      summary: Borra un nodo
      description: |
        Borra el nodo si lo ves (si no, o si no existe, 404 y no se borra nada). Sus aristas se van con él (borrado en
        cascada de la tabla). Avisa por el WebSocket (`context.updated` con `deleted`) a quien lo veía.
      x-source: internal/api/context.go:369
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: nid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Borrado.
        "400":
          description: "`nid` no es un uuid (`invalid_id`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/preview:
    post:
      operationId: contextPreview
      tags:
        - Malla de Contexto
      summary: Previsualiza el contexto que recibiría un agente
      description: |
        Responde «¿qué recibiría exactamente este agente para este issue?»: ensambla el paquete de contexto con la
        misma lógica que al reclamar una tarea (mismo nivel 1 del SDLC del issue), sin guardar nada.

        Primero se comprueba el issue: si no existe o no lo ves, 404. Después `agent_id`: si no es un uuid, 400
        `agent_required`; si no es un agente de este workspace, 404. La rama del paquete es la del SDLC del issue o,
        si no tiene, `hqf/<prefijo en minúsculas>-<número>-<slug del agente>-preview`; la base, la rama por defecto
        del proyecto del issue o `main`. `prompt` hace de petición de la tarea.
      x-source: internal/api/context.go:535
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContextPreviewRequest"
      responses:
        "200":
          description: El paquete de contexto ensamblado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bundle"
        "400":
          description: "`bad_json`; `agent_required` (`agent_id` no es un uuid); `invalid` (datos que rechaza la base de datos)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: El workspace no existe o no eres miembro (`workspace_not_found`), el issue no existe o no lo ves, o el
            agente no es de este workspace (`not_found`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/context/stats:
    get:
      operationId: contextStats
      tags:
        - Malla de Contexto
      summary: Devuelve las estadísticas de la malla
      description: |
        Números de la malla contados sólo sobre lo que ves: los nodos por la audiencia de su ámbito; los deltas y los
        paquetes, por el issue de su tarea.

        - `by_state`: nodos por estado (incluye los archivados).
        - `by_scope` y `by_kind`: nodos no archivados por ámbito y por tipo (`by_kind`, del más frecuente al menos).
        - `deltas_7d`: deltas de los últimos 7 días por operación.
        - `bundles`: sobre los 200 paquetes más recientes de tareas cuyo issue ves, y las memorias de agentes.
        - `top_helpful` y `top_harmful`: hasta 5 nodos con más votos útiles o dañinos (con al menos uno).

        Sólo un fallo de la consulta de `by_state` da error; si falla otra de las listas, sale como null, y si falla
        la de `bundles`, sus campos quedan a cero o null.
      x-source: internal/api/context.go:598
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Las estadísticas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - by_state
                  - by_scope
                  - by_kind
                  - deltas_7d
                  - bundles
                  - top_helpful
                  - top_harmful
                properties:
                  by_state:
                    type: array
                    items:
                      $ref: "#/components/schemas/CountRow"
                  by_scope:
                    type:
                      - array
                      - "null"
                    items:
                      $ref: "#/components/schemas/CountRow"
                  by_kind:
                    type:
                      - array
                      - "null"
                    items:
                      $ref: "#/components/schemas/CountRow"
                  deltas_7d:
                    type:
                      - array
                      - "null"
                    description: "`key` es la operación del delta (`add`, `helpful`, `harmful`, `update`, `archive`)."
                    items:
                      $ref: "#/components/schemas/CountRow"
                  bundles:
                    type: object
                    required:
                      - bundles
                      - avg_utilization
                      - in_target_band
                      - prefix_stability
                      - avg_dropped_budget
                      - avg_clashes
                      - memories
                      - memories_verified
                    properties:
                      bundles:
                        type: integer
                        description: Cuántos paquetes entran en la cuenta (como mucho 200).
                      avg_utilization:
                        type:
                          - number
                          - "null"
                        description: Utilización media del presupuesto de contexto.
                      in_target_band:
                        type:
                          - number
                          - "null"
                        description: Fracción de paquetes con utilización entre 0.6 y 0.8.
                      prefix_stability:
                        type:
                          - number
                          - "null"
                        description: Fracción de paquetes cuyo `prefix_hash` es igual al del paquete anterior del mismo agente.
                      avg_dropped_budget:
                        type:
                          - number
                          - "null"
                        description: Media de nodos descartados por presupuesto (`reason` = `budget`).
                      avg_clashes:
                        type:
                          - number
                          - "null"
                        description: Media de choques por paquete.
                      memories:
                        type: integer
                        description: Memorias escritas por agentes, no archivadas, que ves.
                      memories_verified:
                        type: integer
                        description: De ellas, las verificadas.
                  top_helpful:
                    type:
                      - array
                      - "null"
                    items:
                      $ref: "#/components/schemas/ContextNode"
                  top_harmful:
                    type:
                      - array
                      - "null"
                    items:
                      $ref: "#/components/schemas/ContextNode"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/docker-setup:
    get:
      operationId: getDockerSetup
      tags:
        - Runtimes
      summary: Lee el estado de Docker en la máquina del servidor
      description: |
        Devuelve si el servidor permite runtimes en Docker (`DOCKER_RUNTIME`), si Docker está instalado y corriendo en
        su máquina (con su versión, arquitectura, CPUs y memoria) y si se puede abrir Docker Desktop desde la web
        (macOS con Docker.app). Cualquier miembro puede leerlo.
      x-source: internal/api/docker_runtime.go:177
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El estado de Docker.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DockerSetup"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/docker-setup/start:
    post:
      operationId: startDockerDesktop
      tags:
        - Runtimes
      summary: Abre Docker Desktop en la máquina del servidor
      description: >
        Rol mínimo en el workspace: admin. Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está
        definida, la primera cuenta registrada).


        Abre Docker Desktop en la máquina del servidor (macOS, `open -g -a`) y consulta Docker cada 2 s hasta que

        responde, durante 100 s como mucho. Devuelve el estado al final, esté o no disponible.
      x-source: internal/api/docker_runtime.go:183
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El estado de Docker al terminar la espera.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DockerSetup"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `instance_admin_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`cannot_start_docker`: `DOCKER_RUNTIME` está apagado o no hay Docker.app en la máquina."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`cannot_start_docker`: falló la orden que abre Docker Desktop."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/fanout/{gid}:
    get:
      operationId: getFanout
      tags:
        - Tareas
      summary: Lista las tareas de un fan-out
      description: |
        Devuelve todas las tareas del grupo de fan-out, de la más antigua a la más reciente. Un fan-out es de
        un solo issue: si no ves ese issue, o el grupo no existe, 404 `not_found`.
      x-source: internal/api/tasks.go:783
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: gid
          in: path
          required: true
          description: Id del grupo de fan-out (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las tareas del grupo.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Task"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/gaps/{gid}/answer:
    post:
      operationId: answerGap
      tags:
        - Issues
      summary: Responde un hueco de conocimiento
      description: |
        Respondes una pregunta que dejó un agente (`hqf agent ask`). Con `convert: true`, también se crea un
        nodo borrador en la malla con la pregunta y la respuesta (si falla, sólo se registra en el log). Si la
        tarea queda sin preguntas abiertas, la jugada continúa con las respuestas.

        Si el hueco es de una tarea, sólo responde quien puede (la lista fijada al preguntar o la regla de
        quién responde). Un hueco que viene de una pregunta estructurada se responde como pregunta (409
        `answer_question`). El permiso se comprueba antes que el estado. La respuesta se limpia (sin Unicode
        invisible y con secretos redactados) y se corta a 8000 caracteres.
      x-source: internal/api/gaps.go:158
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: gid
          in: path
          required: true
          description: Id del hueco de conocimiento.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - answer
              properties:
                answer:
                  type: string
                  description: La respuesta. No puede ir vacía.
                convert:
                  type: boolean
                  description: Crear también el nodo borrador en la malla.
      responses:
        "200":
          description: El hueco respondido.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GapRow"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json` o `answer_required`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`not_eligible`: no puedes responderlo."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`answer_question` (viene de una pregunta estructurada) o `not_open` (ya respondido o descartado)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/gaps/{gid}/answerers:
    post:
      operationId: addAnswerer
      tags:
        - Issues
      summary: Añade a alguien que puede responder un hueco
      description: |
        Un mantenedor del proyecto (admin, product_owner o platform_engineer) añade a un miembro del workspace
        a la lista de quien puede responder el hueco. Si el hueco no tenía lista fijada, primero se fija con
        los que podían responder según la regla. La persona tiene que ver el issue. Queda la actividad
        `question.answerer_added` y la persona lo recibe en su bandeja.

        Handler compartido con `POST /questions/{qid}/answerers` (fábrica `addAnswerer("knowledge_gaps")`).
      x-source: internal/api/ops_tras_o2.go:373
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: gid
          in: path
          required: true
          description: Id del hueco de conocimiento.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              properties:
                user_id:
                  type: string
                  format: uuid
                  description: El miembro del workspace que añades.
      responses:
        "204":
          description: Añadido (si ya estaba, no cambia nada).
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json`, `invalid` (`user_id` no es un UUID) o `not_member`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden` (no eres mantenedor del proyecto)."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el hueco no existe o no ves su issue."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_open` o `not_in_audience` (esa persona no ve el issue)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/gaps/{gid}/convert:
    post:
      operationId: convertGap
      tags:
        - Issues
      summary: Convierte un hueco respondido en nodo de la malla
      description: |
        Crea un nodo borrador (sin verificar) en la malla de contexto con la pregunta y la respuesta del
        hueco, y lo marca `converted`. Sólo la respuesta de una persona. El nodo queda en el ámbito del
        proyecto (o del workspace) salvo que el issue sea high, esté marcado o no todos los de ese ámbito lo
        vean: entonces queda en el issue.

        Si el hueco es de una tarea, convierte quien podría responderlo; un hueco sin tarea lo convierte
        cualquiera que lo vea. El permiso va antes que el estado.
      x-source: internal/api/gaps.go:233
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: gid
          in: path
          required: true
          description: Id del hueco de conocimiento.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El nodo creado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - node_id
                properties:
                  node_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id` o `invalid`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`not_eligible`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`not_answered`: no está respondido, o no lo respondió una persona."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/gaps/{gid}/dismiss:
    post:
      operationId: dismissGap
      tags:
        - Issues
      summary: Descarta un hueco de conocimiento
      description: |
        Descarta la pregunta con un motivo (si no mandas ninguno, uno por defecto). El motivo llega al agente
        en la continuación: se limpia y se corta a 2000 caracteres. Las mismas reglas de quién responde que
        `POST /gaps/{gid}/answer`. Si la tarea queda sin preguntas abiertas, la jugada continúa. El cuerpo es
        opcional y un JSON inválido se ignora.
      x-source: internal/api/gaps.go:301
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: gid
          in: path
          required: true
          description: Id del hueco de conocimiento.
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Por qué se descarta. Vacío = un texto por defecto.
      responses:
        "204":
          description: Descartado.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id` o `invalid`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`not_eligible`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`answer_question` o `not_open`."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/github:
    get:
      operationId: getGitHub
      tags:
        - GitHub
      summary: Lee la conexión con GitHub por token
      description: |
        El estado de la conexión del workspace con GitHub por token (modo PAT). Sin conexión, sólo
        `{"connected": false}`. Con conexión: la cuenta del token, su pista (4 primeros y 4 últimos caracteres),
        sus scopes (cabecera X-OAuth-Scopes; vacío con tokens fine-grained), cuándo se guardó por última vez, un
        aviso si un token clásico no tiene el scope `repo`, un error si el token guardado no se puede descifrar y
        lo último que GitHub dijo de su límite de peticiones (`budget`). Nunca devuelve el token.
      x-source: internal/api/github.go:122
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El estado de la conexión.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitHubStatus"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    put:
      operationId: putGitHub
      tags:
        - GitHub
      summary: Conecta un token de GitHub al workspace
      description: |
        Conecta (o reemplaza) el token de GitHub del workspace. Antes de guardarlo cifrado se comprueba contra
        GitHub (`GET /user`). Token vacío: 400 `token_required`; si GitHub lo rechaza (401), 422
        `github_invalid_token`. Queda en la actividad.

        Rol mínimo en el workspace: admin.
      x-source: internal/api/github.go:145
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutGitHubRequest"
      responses:
        "200":
          description: La conexión guardada (sin `budget`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitHubStatus"
        "400":
          description: "`bad_json` o `token_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: "`github_invalid_token`, `github_forbidden` o `github_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: "`github_error`: no se pudo contactar a GitHub."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: deleteGitHub
      tags:
        - GitHub
      summary: Desconecta el token de GitHub del workspace
      description: |
        Olvida el token de GitHub del workspace; responde 204 aunque no hubiera ninguno. No deja actividad.

        Rol mínimo en el workspace: admin.
      x-source: internal/api/github.go:186
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "204":
          description: Desconectado.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/github/app:
    get:
      operationId: getGitHubApp
      tags:
        - GitHub
      summary: Lee el estado de la GitHub App del workspace
      description: |
        El estado de la GitHub App del workspace: la App (o `null`), sus instalaciones con sus repos y su límite
        de peticiones, si puedes gestionarla (`can_manage`: admin u owner), la URL pública de la API
        (PUBLIC_API_URL), si GitHub puede mandar webhooks (PUBLIC_API_URL definida y que no es localhost), si
        HQ Fabric puede leer los logs de CI (`ci_logs`) y `app_error: unreadable` si la App existe pero sus
        secretos no se descifran. Nunca devuelve secretos.
      x-source: internal/api/github_app.go:438
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El estado de la App.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppView"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteGitHubApp
      tags:
        - GitHub
      summary: Olvida la GitHub App del workspace
      description: |
        HQ Fabric olvida la GitHub App del workspace y sus instalaciones (la App hay que borrarla a mano en
        GitHub); los repos vuelven al modo PAT. Sin App: 404 `no_app`. Queda en la actividad.

        Sólo con la sesión del navegador. Rol mínimo en el workspace: admin.
      x-source: internal/api/github_app.go:829
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: App olvidada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    description: Siempre `true`.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`workspace_not_found` o `no_app`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/github/app/installations/refresh:
    post:
      operationId: refreshGitHubInstallations
      tags:
        - GitHub
      summary: Vuelve a leer las instalaciones de la App
      description: |
        Vuelve a leer de GitHub, con el JWT de la App, cada instalación conocida y sus repos (las que GitHub ya no
        tiene se borran y queda en la actividad), y añade las instalaciones de la App que no se conocían (si se
        perdió la vuelta del setup y no hay webhooks); cada una nueva queda en la actividad. Sin App, o con sus
        secretos ilegibles: 404 `no_app`. Devuelve el mismo estado que `GET /github/app`.

        Sólo con la sesión del navegador. Rol mínimo en el workspace: admin.
      x-source: internal/api/github_app.go:768
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El estado de la App tras refrescar.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppView"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`workspace_not_found` o `no_app`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`github_unauthorized`, `github_forbidden` o `github_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`github_error`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/github/app/manifest:
    post:
      operationId: createGitHubAppManifest
      tags:
        - GitHub
      summary: Prepara el manifest para crear la GitHub App
      description: |
        Prepara el manifest flow para crear la GitHub App del workspace. Devuelve el manifest (un JSON en texto,
        App privada con permisos mínimos fijos) y la URL de GitHub a la que el navegador tiene que enviarlo por
        POST, con un `state` firmado que vale 30 minutos. Con `org`, la App se crea en esa organización de GitHub
        (400 `invalid_org` si no es un login válido); sin él, en tu cuenta.

        Las URLs de vuelta (`/api/github/app/callback`, `/api/github/oauth/callback`,
        `/api/github/app/setup/{wsID}`) salen de PUBLIC_API_URL o, si no está definida, del esquema y la cabecera
        `Host` de la petición; el webhook sólo va si PUBLIC_API_URL es pública. El nombre de la App es
        «HQ Fabric <slug>», cortado a 34 caracteres. El cuerpo es opcional (4 KB como mucho; si no se puede leer
        se ignora). Si el workspace ya tiene App, aunque no se descifre: 409 `app_exists`.

        Sólo con la sesión del navegador. Rol mínimo en el workspace: admin.
      x-source: internal/api/github_app.go:444
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGitHubAppManifestRequest"
      responses:
        "200":
          description: Adónde enviar el manifest y el manifest.
          content:
            application/json:
              schema:
                type: object
                required:
                  - post_url
                  - manifest
                properties:
                  post_url:
                    type: string
                    description: "`<github>/settings/apps/new?state=…` o `<github>/organizations/<org>/settings/apps/new?state=…`."
                  manifest:
                    type: string
                    description: El manifest de la App, como texto JSON.
        "400":
          description: "`invalid_org` o `invalid_manifest`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`app_exists`: el workspace ya tiene una GitHub App."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/github/confirm:
    post:
      operationId: confirmGitHubCallback
      tags:
        - GitHub
      summary: Confirma un canje de GitHub con tu sesión
      description: |
        Termina un canje de GitHub en dos pasos. GitHub vuelve a `/api/github/app/callback` o a
        `/api/github/oauth/callback` sin tu sesión; el callback aparca el `code` y manda a la web con
        `gh_confirm=<id>`, y la web lo confirma aquí con tu sesión. El canje se intenta una sola vez, salga como
        salga, y caduca a los 10 minutos (410 `expired`). Sólo lo puede confirmar la persona que lo empezó, en el
        mismo workspace (si no, 403 `wrong_user`, y no se vincula ni se crea nada).

        Según lo que se empezó:
        - Crear la App (manifest): hace falta ser admin (403 `forbidden`). `result` es `created` o `error` (GitHub
          no canjeó el code o no se pudo guardar la App).
        - Vincular tu cuenta (OAuth): `result` es `linked`, `taken` (esa cuenta de GitHub ya está vinculada a otra
          persona) o `error`. El token de usuario de GitHub se revoca en cuanto se lee el id de la cuenta.

        Sólo con la sesión del navegador.
      x-source: internal/api/github_app.go:592
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmGitHubCallbackRequest"
      responses:
        "200":
          description: El resultado del canje.
          content:
            application/json:
              schema:
                type: object
                required:
                  - result
                properties:
                  result:
                    type: string
                    enum:
                      - created
                      - error
                      - linked
                      - taken
        "400":
          description: "`bad_json` o `invalid` (propósito desconocido)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required`, `wrong_user` o `forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "410":
          description: "`expired`: el canje caducó o ya se usó."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/github/owners:
    get:
      operationId: listGitHubOwners
      tags:
        - GitHub
      summary: Lista dónde se puede crear un repo
      description: |
        Dónde se puede crear un repo: la cuenta del token del workspace (`type: user`, primero) y, si GitHub las
        informa, sus organizaciones (`type: org`). Si GitHub no deja leer las organizaciones (p. ej. con tokens
        fine-grained), sólo la cuenta.
      x-source: internal/api/github.go:241
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: La cuenta y sus organizaciones.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GitHubOwner"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`github_not_connected` o `github_token_unreadable`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`github_unauthorized`, `github_forbidden` o `github_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`github_error`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/github/repos:
    get:
      operationId: listGitHubRepos
      tags:
        - GitHub
      summary: Lista los repos a los que llega el token
      description: |
        Los repos a los que llega el token del workspace (`GET /user/repos`, por último push), como mucho 50. `q`
        filtra, sin distinguir mayúsculas, por el nombre completo o la descripción; se buscan como mucho 500 repos
        (5 páginas de 100).
      x-source: internal/api/github.go:208
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: q
          in: query
          required: false
          description: Texto que tiene que aparecer en `full_name` o en la descripción.
          schema:
            type: string
      responses:
        "200":
          description: Los repos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GitHubRepo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`github_not_connected` o `github_token_unreadable`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`github_unauthorized`, `github_forbidden` o `github_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`github_error`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      operationId: createGitHubRepo
      tags:
        - GitHub
      summary: Crea un repo en GitHub
      description: |
        Crea un repo en GitHub con un commit inicial, para que exista la rama base de la que parten los agentes.
        - `name`: letras, números, `-`, `.` o `_`, 100 caracteres como mucho, ni `.` ni `..` ni acabado en `.git`
          (400 `github_repo_name`).
        - `owner`: la organización donde crearlo; vacío o igual a la cuenta del token, en la cuenta (400
          `github_owner` si no es un nombre válido).
        - `private`: por defecto `true`.
        - `description`: los espacios y saltos de línea se juntan en uno y se corta a 350 caracteres.
        - `token`: token puntual (p. ej. con permiso Administration) sólo para crear este repo; no se guarda.
          Tiene que tener al menos 20 caracteres y ningún espacio (400 `invalid_token`); si GitHub lo rechaza, 422
          `github_unauthorized`.

        Hace falta GitHub conectado en el workspace (409 `github_not_connected`) aunque uses un token puntual.
        Después de crearlo se comprueba con el token del workspace que puede escribir en él: si no, el repo queda
        creado igual y la respuesta lleva `warning` (y `can_push: false`). Si ya existe: 409
        `github_repo_exists`. Queda en la actividad.

        Rol mínimo en el workspace: admin.
      x-source: internal/api/github.go:276
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGitHubRepoRequest"
      responses:
        "201":
          description: El repo creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitHubCreatedRepo"
        "400":
          description: "`bad_json`, `github_repo_name`, `github_owner` o `invalid_token`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`github_not_connected`, `github_token_unreadable` o `github_repo_exists`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: |
            `github_unauthorized`, `github_repo_create_failed`, `github_repo_forbidden`, `github_org_not_found`,
            `github_forbidden` o `github_not_found`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`github_error`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/host-runtime:
    get:
      operationId: getHostRuntime
      tags:
        - Runtimes
      summary: Lee el estado del runtime de la máquina del servidor
      description: |
        Devuelve si el servidor permite usar su propia máquina como runtime («Usar esta máquina», `HOST_RUNTIME`), los
        datos de esa máquina, los CLIs detectados en ella (caché de 5 minutos) y, si el workspace ya lo tiene, su
        runtime, si está encendido y si su proceso corre. Cualquier miembro puede leerlo.
      x-source: internal/api/hostruntime.go:417
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El estado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostRuntimeStatus"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: putHostRuntime
      tags:
        - Runtimes
      summary: Enciende o apaga el runtime de la máquina del servidor
      description: >
        Rol mínimo en el workspace: admin. Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está
        definida, la primera cuenta registrada).


        Con `enabled` true (exige `HOST_RUNTIME` activo): si el workspace no tiene aún ese runtime, lo crea a tu nombre;

        lo marca encendido, lanza `hqf daemon run` en la máquina del servidor y espera hasta unos 10 s a que se conecte.

        Con `enabled` false: lo apaga, cierra sus terminales y lo marca desconectado (si no existe, sólo devuelve el

        estado). Queda en la actividad (`runtime.host_started` o `runtime.host_stopped`) y difunde `runtime.updated`.
      x-source: internal/api/hostruntime.go:424
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutHostRuntimeRequest"
      responses:
        "200":
          description: El estado tras el cambio.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostRuntimeStatus"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `instance_admin_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`host_runtime_disabled`: el servidor no permite usar su máquina (`HOST_RUNTIME`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues:
    get:
      operationId: listIssues
      tags:
        - Issues
      summary: Lista los issues del workspace
      description: |
        Los issues que ves, ordenados por prioridad (urgent, high, medium, low, none) y después por
        actualización, del más reciente al más antiguo. Los filtros que no tienen el formato esperado se
        ignoran.
      x-source: internal/api/issues.go:78
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: status
          in: query
          description: Estados separados por comas (p. ej. `todo,in_progress`).
          schema:
            type: string
        - name: project_id
          in: query
          description: Sólo los de este proyecto (se ignora si no es un UUID).
          schema:
            type: string
            format: uuid
        - name: assignee_id
          in: query
          description: Sólo los de este asignado (se ignora si no es un UUID).
          schema:
            type: string
            format: uuid
        - name: assignee_type
          in: query
          description: Sólo los asignados a una persona o a un agente (otro valor se ignora).
          schema:
            type: string
            enum:
              - user
              - agent
        - name: q
          in: query
          description: |
            Texto: busca en el título (contiene, sin distinguir mayúsculas) o compara con la clave del issue
            (`HQF-12`, sin distinguir mayúsculas; `%` y `_` actúan como comodines).
          schema:
            type: string
        - name: limit
          in: query
          description: Máximo de issues, de 1 a 1999 (500 por defecto; otro valor se ignora).
          schema:
            type: integer
            minimum: 1
            maximum: 1999
            default: 500
      responses:
        "200":
          description: Los issues.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Issue"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createIssue
      tags:
        - Issues
      summary: Crea un issue
      description: |
        Crea un issue con el siguiente número del workspace (estado `todo` y prioridad `none` por defecto).

        Con `external` ({connector, id}) se importa un work item: el título y la descripción salen de él si
        no los mandas (la descripción, marcada como importada y con los secretos redactados), el issue queda
        enlazado y deja la actividad `issue.imported`. Importar exige un rol que pueda usar el conector
        (admin, owner de la organización o product_owner, engineer o context_owner del proyecto).

        Si no verías el issue que creas (un proyecto con roles en el que no tienes rol, sin ser su asignado),
        tienes que confirmarlo con `confirm_self_loss: true` (si no, 409 `audience_self_loss`) y la respuesta
        lleva sólo el id y un aviso.

        Efectos: si el asignado es un agente, se le lanza; si el proyecto tiene el SDLC activado, arranca el
        pipeline del issue.
      x-source: internal/api/issues.go:172
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueInput"
      responses:
        "201":
          description: El issue creado, o sólo su id y un aviso si no lo ves.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Issue"
                  - $ref: "#/components/schemas/IssueAudienceSelfLoss"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`bad_json`, `title_required` o `invalid` (estado, prioridad, `assignee_type`, `assignee_id` o `project_id`
            inválidos, o un dato que rechaza la base de datos)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`role_required`: importar exige un rol en el proyecto o ser admin."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`connector_not_found` (el sistema externo no encuentra el work item) o `workspace_not_found`."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`audience_self_loss` (confírmalo con `confirm_self_loss`) o `conflict`."
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: "`connector_auth`, `connector_api_version` o `connector_error` (el conector falló o no existe)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/issues/{num}:
    get:
      operationId: getIssueHandler
      tags:
        - Issues
      summary: Lee un issue
      description: Devuelve el issue. Si no lo ves, o no existe, 404.
      x-source: internal/api/issues.go:360
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: El issue.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    patch:
      operationId: patchIssue
      tags:
        - Issues
      summary: Modifica un issue
      description: |
        Cambia los campos que mandas (los que no vienen no cambian). `project_id` y `assignee_id` se aplican
        si la clave está en el cuerpo, aunque sea `null` o vacía (así se quitan); `assignee_type` sólo cuenta
        junto a `assignee_id`. `external` se ignora aquí (usa `PUT /issues/{num}/external`).

        Reglas:
        - Si no ves el issue, 404 antes de mirar el cuerpo.
        - En un issue con SDLC en curso (ni done ni cancelled), cambiar el proyecto o el asignado lo hace un
          mantenedor (product_owner, platform_engineer o admin) del proyecto actual y del nuevo (403
          `sdlc_role_required`); sacarlo de SDLC con puertas abiertas da 409 `open_gates`.
        - Mover de proyecto exige permiso en el de origen y en el de destino (admin, un rol en él, o un
          proyecto sin roles) y confirmar con `confirm_audience` si más gente verá su historia (409
          `audience_widens`).
        - Cambiar o quitar el asignado exige permiso en su proyecto, y confirmar si la persona que asignas
          no veía el issue.
        - Si tras mover o reasignar dejas de ver el issue, confírmalo con `confirm_self_loss` (409
          `audience_self_loss`); la respuesta lleva sólo el id y un aviso.

        Efectos: actividad por cada cambio (estado, prioridad, título, asignado, proyecto); pasar a done o
        cancelled borra la ref oculta del issue y purga las sesiones; quitar un agente cancela sus tareas en
        cola y asignar uno lo lanza.
      x-source: internal/api/issues.go:366
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueInput"
      responses:
        "200":
          description: El issue modificado, o sólo su id y un aviso si dejaste de verlo.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Issue"
                  - $ref: "#/components/schemas/IssueAudienceSelfLoss"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid` (número, estado, prioridad, `assignee_type`, `assignee_id` o `project_id` inválidos, o la base
            de datos) o `bad_json` (el cuerpo no es un objeto JSON, máx. 4 MiB)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`sdlc_role_required` o `project_permission_required`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el issue (o no lo ves) o el proyecto de destino."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`open_gates`, `audience_widens`, `audience_self_loss` o `conflict`."
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteIssue
      tags:
        - Issues
      summary: Borra un issue
      description: |
        Borra el issue (en cascada, sus tareas, comentarios y sesiones). Antes deja la solicitud de purga de
        los transcripts de sus sesiones para los runtimes, y avisa con `issue.deleted` a quien lo veía. Lo
        borra cualquiera que lo vea (el código no pide más rol); si no lo ves, 404.
      x-source: internal/api/issues.go:535
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "204":
          description: Issue borrado.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/comments:
    post:
      operationId: createComment
      tags:
        - Issues
      summary: Comenta en un issue
      description: |
        Añade tu comentario al issue (hace falta verlo). Si el issue tiene huecos de conocimiento abiertos de
        una tarea en curso o bloqueada que tú puedes responder, el comentario los responde y la jugada
        continúa (no se disparan más agentes). Si no, cada `@slug` de un agente activo del workspace lanza ese
        agente (mención) y, si el issue está asignado a un agente no mencionado, se le lanza con el
        comentario.
      x-source: internal/api/issues.go:743
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - body
              properties:
                body:
                  type: string
                  description: El comentario en Markdown. No puede ir vacío.
      responses:
        "201":
          description: El comentario creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid` (número), `bad_json` o `body_required`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/external:
    put:
      operationId: putIssueExternal
      tags:
        - Issues
      summary: Enlaza el issue con un work item externo
      description: |
        Enlaza el issue con un work item del conector (o lo desenlaza con `id` vacío). Hace falta ver el issue
        y un rol que pueda usar el conector (admin, owner de la organización o product_owner, engineer o
        context_owner del proyecto); el rol se comprueba antes de leer el cuerpo. Deja la actividad
        `issue.external`. Devuelve la referencia guardada, o `{}` al desenlazar.
      x-source: internal/api/connectors.go:248
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connector:
                  type: string
                  description: Nombre del conector del workspace.
                id:
                  type: string
                  description: Id del work item. Vacío = desenlazar.
      responses:
        "200":
          description: La referencia guardada (`{}` si se desenlazó).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/IssueExternal"
                  - type: object
                    maxProperties: 0
                    description: Desenlazado.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid` (número) o `bad_json`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`role_required`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found` (issue) o `connector_not_found` (el sistema externo no encuentra el work item)."
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: "`connector_auth`, `connector_api_version` o `connector_error` (el conector falló o no existe)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/issues/{num}/fanout:
    post:
      operationId: fanoutIssue
      tags:
        - Issues
      summary: Lanza el issue a varios agentes en paralelo
      description: |
        Lanza la misma tarea a entre 2 y 8 agentes a la vez, cada uno en su worktree, con un id de grupo
        común. El cuerpo se lee antes de comprobar que ves el issue.

        Sin SDLC: los ids repetidos, mal formados o de agentes de otro workspace se saltan sin error (la
        respuesta puede traer menos tareas, incluso ninguna); deja un comentario del sistema y pasa el issue
        de todo/backlog a in_progress.

        Con SDLC (el issue tiene pista): las mismas puertas que «Ejecutar agente» (Build activa, plan
        aprobado o repro aceptado, ningún escritor en curso y tu rol para lanzar la jugada de código), y cada
        agente trabaja en una rama hija de la del issue (`<rama>-fN`). Hacen falta al menos 2 agentes válidos.
        La respuesta añade `play`.
      x-source: internal/api/tasks.go:728
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_ids
              properties:
                agent_ids:
                  type: array
                  minItems: 2
                  maxItems: 8
                  items:
                    type: string
                    format: uuid
                prompt:
                  type: string
                  description: Encargo (con SDLC se añade al de la jugada, cortado a 8000 caracteres).
      responses:
        "201":
          description: Las tareas lanzadas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - fanout_group_id
                  - task_ids
                properties:
                  fanout_group_id:
                    type: string
                    format: uuid
                  task_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
                  play:
                    type: string
                    description: Sólo con SDLC. La jugada de código (build o fix).
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`bad_json`, `invalid` (menos de 2 o más de 8 agentes; con SDLC, menos de 2 válidos) o `invalid` del número."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`forbidden` (con SDLC, sin rol para lanzar la jugada) o `history_hidden` (la puerta de encolar)."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "Con SDLC: `sdlc_off`, `stage_not_active`, `prereq_missing`, `busy` o `no_issue_branch`."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/gaps:
    get:
      operationId: listIssueGaps
      tags:
        - Issues
      summary: Lista los huecos de conocimiento de un issue
      description: |
        Todos los huecos del issue (quien lo ve, los ve todos), en orden de creación, sin los que vienen de
        una pregunta estructurada (salen como preguntas). Si eres mantenedor del proyecto,
        `can_add_answerers` es `true` en los abiertos.
      x-source: internal/api/gaps.go:136
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: Los huecos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GapRow"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/history/unlock:
    post:
      operationId: unlockIssueHistory
      tags:
        - Issues
      summary: Quita la marca de la historia de un issue
      description: |
        Quita la marca (`audience_locked_at`) del issue y de sus tareas: vuelven a verlo quienes dice la
        audiencia de su proyecto actual. Sólo un owner de la organización, con autenticación reciente (código
        de hace menos de 10 minutos), con motivo (se limpia y se corta a 2 KiB) y confirmando con
        `confirm_audience` si más gente que no es admin pasará a verlo. Se comprueba que eres owner antes de
        decir si la historia está marcada. Deja la actividad `issue.history_unlocked` con el motivo.
      x-source: internal/api/ops_tras_o7_d7.go:93
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reason
              properties:
                reason:
                  type: string
                  description: Motivo (obligatorio). El cuerpo entero, como mucho 64 KiB.
                confirm_audience:
                  type: boolean
                  description: Confirmas que la audiencia se amplía.
      responses:
        "200":
          description: Marca quitada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - tasks_unlocked
                  - audience_widened
                properties:
                  tasks_unlocked:
                    type: integer
                    description: Tareas del issue a las que se quitó la marca.
                  audience_widened:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid` (número), `bad_json` o `reason_required`."
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: "`unauthorized` o `reauth_required` (vuelve a entrar con un código)."
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` u `org_owner_required`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`issue_changed` (cambió de proyecto mientras tanto), `not_locked` o `audience_widens`."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/locked-tests:
    get:
      operationId: listLockedTests
      tags:
        - SDLC
      summary: Lista los tests bloqueados de un issue
      description: |
        Los tests que dejó bloqueados el repro aceptado del issue (pista bug), por ruta, incluidos los ya
        desbloqueados. Las fechas salen como texto de PostgreSQL (`timestamptz::text`, p. ej.
        `2026-11-15 10:00:00.123+00`), no en RFC 3339.
      x-source: internal/api/sdlc_build.go:252
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: Los tests bloqueados.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LockedTest"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/locked-tests/unlock:
    post:
      operationId: unlockTest
      tags:
        - SDLC
      summary: Desbloquea un test de bug
      description: |
        Desbloquea un test bloqueado del issue. Sólo un engineer del proyecto (rol de proyecto, sin respaldo
        para admins), con autenticación reciente (código de hace menos de 10 minutos). Deja la actividad
        `sdlc.test_unlocked` con el motivo (cortado a 500 caracteres).
      x-source: internal/api/sdlc_build.go:267
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - path
              properties:
                path:
                  type: string
                  description: La ruta del test, tal como sale en la lista.
                reason:
                  type: string
                  description: Motivo (opcional).
      responses:
        "200":
          description: Test desbloqueado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid` (número) o `bad_json`."
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: "`unauthorized` o `reauth_required`."
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden` (no eres engineer del proyecto)."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el issue o un test que no está bloqueado."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/questions:
    get:
      operationId: listIssueQuestions
      tags:
        - Issues
      summary: Lista las preguntas estructuradas de un issue
      description: |
        Las preguntas que hicieron los agentes en el issue (hasta 200, en orden de creación). En las
        abiertas, el servidor dice si puedes responder (`can_answer`, con `cannot_answer_reason` si no) y si
        eres mantenedor del proyecto (`can_add_answerers`).
      x-source: internal/api/ops_o2.go:620
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: Las preguntas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TaskQuestion"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/run:
    post:
      operationId: runIssue
      tags:
        - Issues
      summary: Lanza un agente en el issue
      description: |
        «Ejecutar agente». El cuerpo se lee antes de comprobar que ves el issue.

        Sin SDLC: encola una tarea manual para `agent_id` (o, si no lo mandas, para el agente asignado). Salvo
        con `fresh: true`, continúa el worktree de la última tarea de ese agente en el issue que terminó
        (completed, blocked o failed) sin integrarse.

        Con SDLC (el issue tiene pista): encola la jugada de código (build, o fix en la pista bug) sobre la
        rama del issue, con las puertas de «Siguiente jugada» (Build activa, plan aprobado o repro aceptado,
        ningún escritor en curso y tu rol). `agent_id`, si viene, tiene que ser del workspace y sustituye al
        agente configurado para la jugada; `prompt` se añade al encargo (cortado a 8000 caracteres). El issue
        pasa de todo/backlog a in_progress. La respuesta añade `play`.
      x-source: internal/api/tasks.go:684
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                  format: uuid
                  description: El agente. Vacío = el asignado al issue (sin SDLC) o el de la jugada (con SDLC).
                prompt:
                  type: string
                  description: El encargo.
                fresh:
                  type: boolean
                  description: Sin SDLC, no continuar el worktree anterior.
      responses:
        "201":
          description: La tarea encolada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
                  play:
                    type: string
                    description: Sólo con SDLC. La jugada encolada.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`bad_json`, `invalid` (número o la base de datos) o `agent_required` (sin agente válido; con SDLC, uno que
            no es del workspace)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`forbidden` (con SDLC, sin rol para lanzar la jugada) o `history_hidden` (la puerta de encolar)."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "Con SDLC: `sdlc_off`, `stage_not_active`, `prereq_missing`, `busy` o un error de la jugada (`sdlc_busy`,
            `sdlc_awaiting`, `sdlc_no_play`, `sdlc_not_started`, `sdlc`)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/sdlc:
    get:
      operationId: getIssueSDLC
      tags:
        - SDLC
      summary: Lee el pipeline SDLC de un issue
      description: |
        La vista SDLC del issue: etapas, últimos artefactos (sin contenido, con si puedes aprobarlos), huecos
        abiertos, work item enlazado, empuje, runtime al que se espera, repro pendiente, tests bloqueados, la
        revisión de Deploy y la siguiente jugada con si puedes lanzarla.
      x-source: internal/api/sdlc.go:941
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: La vista SDLC.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueSDLCView"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/sdlc/next:
    post:
      operationId: nextIssuePlay
      tags:
        - SDLC
      summary: Lanza la siguiente jugada del pipeline
      description: |
        «Siguiente jugada»: la máquina del pipeline decide qué toca y, si es encolar una jugada, comprueba que
        tienes el rol para lanzarla. Devuelve la vista SDLC del issue.
      x-source: internal/api/sdlc.go:855
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: La vista SDLC tras aplicar la jugada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueSDLCView"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`forbidden`: no tienes el rol para lanzar la jugada."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`sdlc_off`, `sdlc_busy`, `sdlc_awaiting`, `sdlc_no_play`, `sdlc_not_started` o `sdlc` (otro motivo de la
            máquina)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/sdlc/repro/accept:
    post:
      operationId: acceptRepro
      tags:
        - SDLC
      summary: Acepta el repro de un bug
      description: |
        Confirmas que el último repro completado falla por la razón esperada: queda aprobado con tu nombre
        (actividad `sdlc.repro_accepted`) y la máquina del pipeline recibe el evento (bloquea los tests y
        abre el fix). Hace falta el rol para lanzar `fix`. Si el evento falla después de aceptar, el repro
        queda aceptado igualmente y la respuesta es 409.
      x-source: internal/api/sdlc_build.go:177
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: El repro aceptado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
                    description: La tarea del repro.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid` (número o la base de datos)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`no_repro` (no hay un repro que falle esperando confirmación) o un error de la máquina (`sdlc_off`,
            `sdlc_busy`, `sdlc_awaiting`, `sdlc_no_play`, `sdlc_not_started`, `sdlc`)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/sdlc/start:
    post:
      operationId: startIssueSDLC
      tags:
        - SDLC
      summary: Arranca el pipeline SDLC de un issue
      description: |
        Arranca el pipeline del issue (proyecto con el SDLC activado) con la pista que mandas o, si no es
        válida o no viene, la que sale de sus etiquetas (bug, chore, incident o, por defecto, feature), y su rama
        `hqf/<clave en minúsculas>`. Hace falta el rol para
        lanzar `intent`. El cuerpo es opcional y un JSON inválido se ignora. Devuelve la vista SDLC.
      x-source: internal/api/sdlc.go:833
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                track:
                  type: string
                  enum:
                    - feature
                    - bug
                    - chore
                    - incident
                  description: Otro valor = la pista de las etiquetas.
      responses:
        "200":
          description: La vista SDLC del issue.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueSDLCView"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`forbidden`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`sdlc_off`, `sdlc` (p. ej. el pipeline ya empezó, o un error al leer la configuración), `sdlc_busy`,
            `sdlc_awaiting`, `sdlc_no_play` o `sdlc_not_started`."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/sdlc/sweep:
    post:
      operationId: startSweep
      tags:
        - SDLC
      summary: Arranca el barrido «hasta verde»
      description: |
        Crea el barrido del issue y lanza su primera revisión (o cuenta como primera ronda la revisión válida
        que ya tenga el commit de la cabeza). Hace falta Deploy activa o esperando aprobación, la verificación
        de la cabeza en verde y un revisor que no sea autor del código. Lo lanza un engineer o code owner del
        proyecto (o, si no hay ninguno, el mínimo de `approval_role`).
      x-source: internal/api/review.go:407
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "201":
          description: El barrido creado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - sweep_id
                properties:
                  sweep_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `role_required`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`no_reviewer` (no hay revisor, o es el autor) o `sweep_not_allowed` (SDLC apagado, Deploy no activa,
            verificación no en verde, ya hay un barrido u otro fallo)."
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: cancelSweep
      tags:
        - SDLC
      summary: Cancela el barrido en curso
      description: |
        Para el barrido en curso del issue (`stopped`, motivo cancelado), cancela sus tareas en cola, deja la
        actividad `sweep.cancelled` y devuelve Deploy a la espera de la aprobación. Mismo rol que arrancarlo.
      x-source: internal/api/review.go:483
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: Barrido cancelado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `role_required`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found` (issue) o `no_sweep` (no hay un barrido en curso)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/tasks:
    get:
      operationId: issueTasks
      tags:
        - Issues
      summary: Lista las tareas de un issue
      description: |
        Todas las tareas del issue, de la más nueva a la más antigua. En las que están en cola se añade
        `quota_hold` si están retenidas por cuota.
      x-source: internal/api/tasks.go:521
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: Las tareas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Task"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/issues/{num}/timeline:
    get:
      operationId: issueTimeline
      tags:
        - Issues
      summary: Lee la historia de un issue
      description: |
        El issue, todos sus comentarios y toda su actividad en orden cronológico (sin `comment.created`, que
        ya va en los comentarios; `issue.audience_narrowed` sólo si eres admin). `can_unlock_history` es
        `true` sólo si eres owner de la organización y la historia está marcada.
      x-source: internal/api/issues.go:715
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: num
          in: path
          required: true
          description: Número del issue en el workspace.
          schema:
            type: integer
      responses:
        "200":
          description: La historia del issue.
          content:
            application/json:
              schema:
                type: object
                required:
                  - issue
                  - comments
                  - activities
                  - can_unlock_history
                properties:
                  issue:
                    $ref: "#/components/schemas/Issue"
                  comments:
                    type: array
                    items:
                      $ref: "#/components/schemas/Comment"
                  activities:
                    type: array
                    items:
                      $ref: "#/components/schemas/Activity"
                  can_unlock_history:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid`: el número no es un entero."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/me/github-login:
    get:
      operationId: getMyGitHubLogin
      tags:
        - GitHub
      summary: Lee tu login de GitHub vinculado
      description: |
        Tu login de GitHub vinculado y si el workspace tiene GitHub App legible, en cuyo caso la vinculación es
        por OAuth (`oauth_available`). La vinculación es de tu usuario, no del workspace. Sin vinculación:
        `{"login": null, "oauth_available": …}`. Mientras no esté comprobado, `code` es el código que tienes que
        poner en tu bio pública de GitHub. Una vinculación comprobada sin el id numérico de la cuenta (de antes de
        guardarlo) no cuenta: esta lectura la deja sin comprobar y genera un código nuevo.
      x-source: internal/api/github_review.go:224
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Tu vinculación, o `login` nulo si no tienes.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/GitHubLoginOut"
                  - type: object
                    required:
                      - login
                      - oauth_available
                    properties:
                      login:
                        type: "null"
                      oauth_available:
                        type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: putMyGitHubLogin
      tags:
        - GitHub
      summary: Reserva tu login de GitHub
      description: |
        Reserva un login de GitHub para ti, sin comprobar, y devuelve el código (`hqf-verify-…`) que tienes que
        poner en tu bio pública de GitHub para comprobarlo con `POST …/me/github-login/verify`. Reemplaza tu
        vinculación anterior. Sólo sin GitHub App en el workspace (si la hay, aunque no se descifre, 409
        `use_oauth`: vincula con OAuth). Se admite con `@` delante; login inválido: 400 `invalid_login`. Si ya
        está vinculado a otra persona: 409 `login_taken` (la reserva sin comprobar de otra persona deja de
        bloquear a las 24 horas). Queda en la actividad.

        Sólo con la sesión del navegador.
      x-source: internal/api/github_review.go:254
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutMyGitHubLoginRequest"
      responses:
        "200":
          description: El login reservado y su código.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitHubLoginOut"
        "400":
          description: "`bad_json` o `invalid_login`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`use_oauth` o `login_taken`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: deleteMyGitHubLogin
      tags:
        - GitHub
      summary: Desvincula tu login de GitHub
      description: |
        Desvincula tu login de GitHub. La vinculación es de tu usuario: deja de valer en todos tus workspaces.
        Responde 200 aunque no hubiera ninguna. Queda en la actividad de este workspace.

        Sólo con la sesión del navegador.
      x-source: internal/api/github_review.go:365
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Desvinculado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    description: Siempre `true`.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/me/github-login/oauth:
    post:
      operationId: startGitHubOAuth
      tags:
        - GitHub
      summary: Empieza la vinculación de tu cuenta por OAuth
      description: |
        Empieza la vinculación de tu cuenta de GitHub por el OAuth de usuario de la GitHub App del workspace:
        devuelve la URL de autorización de GitHub a la que mandar el navegador, con un `state` firmado de 10
        minutos y `redirect_uri` a `/api/github/oauth/callback` (de PUBLIC_API_URL o, si no está definida, del
        esquema y la cabecera `Host` de la petición). Sin App, o con App ilegible: 409 `no_app`.

        Sólo con la sesión del navegador.
      x-source: internal/api/github_oauth.go:21
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: La URL de autorización.
          content:
            application/json:
              schema:
                type: object
                required:
                  - authorize_url
                properties:
                  authorize_url:
                    type: string
                    description: "`<github>/login/oauth/authorize?client_id=…&redirect_uri=…&state=…&allow_signup=false`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`no_app`: el workspace no tiene GitHub App (usa el código en la bio)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/me/github-login/verify:
    post:
      operationId: verifyMyGitHubLogin
      tags:
        - GitHub
      summary: Comprueba tu login de GitHub por la bio
      description: |
        Comprueba que la bio pública de tu login de GitHub reservado lleva el código y, si es así, guarda el id
        numérico de la cuenta (y su login actual). No lee cuerpo. En este orden:
        - sin login reservado: 404 `no_login`;
        - si ya está comprobado, lo devuelve tal cual (200);
        - con GitHub App en el workspace: 409 `use_oauth`;
        - reserva de más de 24 horas: 410 `reservation_expired`;
        - el código no está en la bio: 409 `code_not_found`;
        - esa cuenta de GitHub ya está vinculada a otra persona: 409 `login_taken`.

        El perfil se lee con el token del workspace o, sin GitHub conectado, sin token (es público). Queda en la
        actividad.

        Sólo con la sesión del navegador.
      x-source: internal/api/github_review.go:289
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: El login comprobado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitHubLoginOut"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`workspace_not_found` o `no_login`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`use_oauth`, `github_token_unreadable`, `code_not_found` o `login_taken`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "410":
          description: "`reservation_expired`: la reserva tiene más de 24 horas; vuelve a reservar el login."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`github_unauthorized`, `github_forbidden` o `github_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: "`github_error`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/members:
    get:
      operationId: listMembers
      tags:
        - Workspaces y miembros
      summary: Lista los miembros del workspace
      description: Los miembros del workspace con su rol, por fecha de alta.
      x-source: internal/api/identity.go:649
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Los miembros.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MemberRow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: addMember
      tags:
        - Workspaces y miembros
      summary: Añade un miembro
      description: |
        Añade a alguien al workspace por su correo (normalizado; tiene que llevar `@`, si no 400 `invalid_email`).
        Si no tiene cuenta se crea, aunque el registro esté deshabilitado, con el nombre de lo que va antes de la
        `@` y el idioma del workspace. Si ya es miembro, su rol pasa a ser el que envíes. Rol por defecto:
        `member`. No puedes asignar un rol superior al tuyo (403 `forbidden`); un rol que no es `owner`, `admin`
        ni `member` lo rechaza la base de datos (400 `invalid`).

        Rol mínimo en el workspace: admin.
      x-source: internal/api/identity.go:659
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddMemberRequest"
      responses:
        "201":
          description: El id del usuario añadido.
          content:
            application/json:
              schema:
                type: object
                required:
                  - user_id
                properties:
                  user_id:
                    type: string
                    format: uuid
        "400":
          description: "`bad_json`, `invalid_email` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/members/{uid}:
    patch:
      operationId: patchMember
      tags:
        - Workspaces y miembros
      summary: Cambia el rol de un miembro
      description: |
        Cambia el rol de un miembro. El rol tiene que ser `owner`, `admin` o `member` y no superior al tuyo (si
        no, 400 `invalid_role`). Si `uid` no es miembro, responde 204 sin cambiar nada. No comprueba que el
        workspace siga teniendo algún owner.

        Rol mínimo en el workspace: admin.
      x-source: internal/api/identity.go:695
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: uid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchMemberRequest"
      responses:
        "204":
          description: Rol cambiado (o `uid` no era miembro).
        "400":
          description: "`invalid_id`, `bad_json` o `invalid_role`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: removeMember
      tags:
        - Workspaces y miembros
      summary: Saca a un miembro del workspace
      description: |
        Saca a un miembro del workspace. Tiene que quedar al menos un owner que no sea esa persona (si no, 400
        `last_owner`). Si `uid` no es miembro, responde 204 igualmente.

        Rol mínimo en el workspace: admin.
      x-source: internal/api/identity.go:719
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: uid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Miembro sacado (o no lo era).
        "400":
          description: "`invalid_id` o `last_owner`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/organization:
    get:
      operationId: getOrganization
      tags:
        - Organización
      summary: Lee la organización del workspace
      description: |
        La organización del workspace (si aún no existe, la crea con el nombre del workspace), sus roles con la
        persona de cada uno, los roles posibles (`available`), si puedes editarla (`can_edit`: eres owner del
        workspace o tienes el rol `owner` de la organización) y sus políticas.
      x-source: internal/api/sdlc.go:417
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: La organización.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - name
                  - roles
                  - available
                  - can_edit
                  - require_four_eyes
                  - forbid_host_approval_delegation
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  roles:
                    type: array
                    description: Por rol, nombre de la persona y alcance.
                    items:
                      $ref: "#/components/schemas/RoleRow"
                  available:
                    type: array
                    description: Los roles de organización posibles.
                    items:
                      type: string
                      enum:
                        - owner
                        - platform_engineer
                        - context_owner
                  can_edit:
                    type: boolean
                    description: Si eres owner de la organización (puedes cambiar sus roles y políticas).
                  require_four_eyes:
                    type: boolean
                    description: Política de cuatro ojos.
                  forbid_host_approval_delegation:
                    type: boolean
                    description: Si se prohíbe delegar aprobaciones en el host.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/organization/policy:
    put:
      operationId: putOrganizationPolicy
      tags:
        - Organización
      summary: Cambia las políticas de la organización
      description: |
        Cambia las políticas de la organización: `require_four_eyes` y `forbid_host_approval_delegation`. Cada
        campo es opcional, pero tiene que venir al menos uno (400 `invalid`); lo que no llega no cambia. Queda en
        la actividad del workspace.

        Exige, en este orden: ser owner de la organización (owner del workspace o rol `owner` de la organización;
        si no, 403 `org_owner_required`), la sesión del navegador y autenticación reciente (haber entrado con un
        código hace menos de 10 minutos; si no, 401 `reauth_required`: usa `POST /api/auth/reauth`).
      x-source: internal/api/sdlc.go:442
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutOrganizationPolicyRequest"
      responses:
        "200":
          description: Las políticas como quedan.
          content:
            application/json:
              schema:
                type: object
                required:
                  - require_four_eyes
                  - forbid_host_approval_delegation
                properties:
                  require_four_eyes:
                    type: boolean
                  forbid_host_approval_delegation:
                    type: boolean
        "400":
          description: "`bad_json` o `invalid` (no viene ningún campo)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "`unauthorized` (sin sesión válida) o `reauth_required` (autenticación de hace más de 10 minutos)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "`session_required` u `org_owner_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/organization/roles:
    put:
      operationId: putOrganizationRoles
      tags:
        - Organización
      summary: Reemplaza los roles de la organización
      description: |
        Reemplaza todos los roles de la organización por la lista que envías (una lista vacía o sin `roles` los
        quita todos). Roles: `owner`, `platform_engineer`, `context_owner`. Como mucho 500 entradas; cada
        `user_id` tiene que ser el uuid de un miembro del workspace y `scope` (vacío = todo) tener 120 caracteres
        como mucho; si no, 400 `invalid`. Los owners del workspace siguen siendo owners de la organización aunque
        no vengan en la lista. Queda en la actividad. Devuelve la organización como `GET /organization`.

        Sólo un owner de la organización (403 `forbidden`) y con la sesión del navegador.
      x-source: internal/api/sdlc.go:484
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutOrganizationRolesRequest"
      responses:
        "200":
          description: La organización como queda.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - name
                  - roles
                  - available
                  - can_edit
                  - require_four_eyes
                  - forbid_host_approval_delegation
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  roles:
                    type: array
                    items:
                      $ref: "#/components/schemas/RoleRow"
                  available:
                    type: array
                    items:
                      type: string
                      enum:
                        - owner
                        - platform_engineer
                        - context_owner
                  can_edit:
                    type: boolean
                  require_four_eyes:
                    type: boolean
                  forbid_host_approval_delegation:
                    type: boolean
        "400":
          description: "`bad_json` o `invalid` (rol, `user_id`, alcance o persona que no es miembro)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/permission-requests/{prid}:
    get:
      operationId: getPermission
      tags:
        - Preguntas y permisos
      summary: Lee una solicitud de permiso
      description: |
        Devuelve la solicitud con `can_decide` y `cannot_decide_reason` calculados para ti.

        La lee quien ve el issue de la tarea y, en una solicitud que se ejecuta en el host (sin sandbox),
        también el dueño del runtime y sus delegados vigentes aunque no vean el issue. En ese caso sale
        recortada (`limited: true`, sin `issue_title` ni `agent_name`) y queda la actividad
        `permission.read_without_task` (una vez por persona y solicitud). Si no la puedes leer, no es de este
        workspace, no existe o el id no es un UUID, 404 `not_found`.
      x-source: internal/api/ops_o3.go:991
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: prid
          in: path
          required: true
          description: Id de la solicitud (si no es un UUID, 404 `not_found`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La solicitud.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/permission-requests/{prid}/approve:
    post:
      operationId: decidePermissionApprove
      tags:
        - Preguntas y permisos
      summary: Aprueba una solicitud de permiso
      description: |
        Aprueba una solicitud de permiso, una por llamada. Handler: `decidePermission(true)`.

        - La solicitud tiene que poder leerse (ver `GET /permission-requests/{prid}`; si no, 404
          `not_found`). Cuerpo de hasta 64 KiB (si no es JSON válido o es mayor, 400 `bad_json`).
        - Exige haber entrado con código hace menos de 10 minutos (401 `reauth_required`).
        - Tienes que poder decidirla (403 `not_eligible`, con el motivo): en el host, el dueño del runtime o
          un delegado vigente que era elegible al pedirse (si la organización no lo prohíbe); sin host, los
          elegibles fijados al pedirse que ven el issue.
        - `input_sha256` tiene que ser el hash de lo que se va a ejecutar, el que viste (409
          `hash_mismatch`).
        - La tarea tiene que seguir en `claimed` o `running`, y la solicitud pendiente, vencida sin usar, o
          aprobada y vencida cuya ventana de una hora pasó sin usarse (si no, 409 `not_pending`).

        Cuenta como dirigir el cambio. Devuelve la solicitud releída (si releerla falla, sólo `{id}`).
      x-source: internal/api/ops_o3.go:1049
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: prid
          in: path
          required: true
          description: Id de la solicitud (si no es un UUID, 404 `not_found`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DecidePermissionRequest"
      responses:
        "200":
          description: La solicitud tras decidir (o sólo su id).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/PermissionRequest"
                  - type: object
                    required:
                      - id
                    properties:
                      id:
                        type: string
                        format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Sin credencial válida (`unauthorized`) o hace falta volver a entrar con código (`reauth_required`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "`session_required` (con un token de API) o `not_eligible`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`hash_mismatch` o `not_pending`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/permission-requests/{prid}/deny:
    post:
      operationId: decidePermissionDeny
      tags:
        - Preguntas y permisos
      summary: Deniega una solicitud de permiso
      description: |
        Deniega una solicitud de permiso pendiente, una por llamada. Handler: `decidePermission(false)`.

        - La solicitud tiene que poder leerse (ver `GET /permission-requests/{prid}`; si no, 404
          `not_found`). Cuerpo de hasta 64 KiB (si no es JSON válido o es mayor, 400 `bad_json`).
        - Exige haber entrado con código hace menos de 10 minutos (401 `reauth_required`).
        - Tienes que poder decidirla (403 `not_eligible`, con el motivo), con las mismas reglas que aprobar.
        - `input_sha256` se ignora.
        - La tarea tiene que seguir en `claimed` o `running` y la solicitud, pendiente (si no, 409
          `not_pending`).
        - `reason` es opcional: se limpia, se redacta y se recorta a 2 KiB. Con motivo, le llega al agente y
          cuenta como dirigir el cambio; sin motivo, sólo queda en la auditoría.

        Devuelve la solicitud releída (si releerla falla, sólo `{id}`).
      x-source: internal/api/ops_o3.go:1049
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: prid
          in: path
          required: true
          description: Id de la solicitud (si no es un UUID, 404 `not_found`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DecidePermissionRequest"
      responses:
        "200":
          description: La solicitud tras decidir (o sólo su id).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/PermissionRequest"
                  - type: object
                    required:
                      - id
                    properties:
                      id:
                        type: string
                        format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Sin credencial válida (`unauthorized`) o hace falta volver a entrar con código (`reauth_required`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "`session_required` (con un token de API) o `not_eligible`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_pending`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects:
    get:
      operationId: listProjects
      tags:
        - Proyectos
      summary: Lista los proyectos del workspace
      description: |
        Todos los proyectos del workspace, por nombre. `open_issues` cuenta sólo los issues abiertos que ves.
      x-source: internal/api/identity.go:797
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Los proyectos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createProject
      tags:
        - Proyectos
      summary: Crea un proyecto
      description: |
        Crea un proyecto. El slug sale de `slug` o, si no viene, del nombre (minúsculas, sin acentos, máx. 48
        caracteres). Por defecto: rama `main`, `require_review` true, `approval_role` auto y `auto_open_pr`
        false.

        Reglas: `approval_role` y `auto_open_pr` sólo los fija un admin con la sesión del navegador.
        `require_review: false` está deprecado: se guarda `true` y la respuesta lleva las cabeceras
        `Deprecation` y `Warning`. Si `repo_url` es de GitHub y el workspace tiene token, se comprueba que
        puede subir ramas y que la rama existe (422 si no); si no mandas rama, se usa la por defecto del
        repo. `max_task_wall_time_hours` y `live_steering` se ignoran al crear.
      x-source: internal/api/identity.go:908
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectInput"
      responses:
        "201":
          description: El proyecto creado.
          headers:
            Deprecation:
              description: "`true` si mandaste `require_review: false` (deprecado; se guarda `true`)."
              schema:
                type: string
            Warning:
              description: "Con `require_review: false`, un aviso 299 que explica la deprecación."
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`bad_json`, `name_required` o `invalid` (`approval_role` fuera de auto, member, admin, o la base de datos)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden` (cambiar `approval_role` o `auto_open_pr` sin ser admin)."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`conflict`: ya hay un proyecto con ese slug."
        "422":
          description: "`github_repo_readonly`, `github_repo_no_contents`, `github_branch_not_found`, `github_repo_inaccessible` o
            `github_unauthorized`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}:
    patch:
      operationId: patchProject
      tags:
        - Proyectos
      summary: Modifica un proyecto
      description: |
        Cambia los campos que mandas. Reglas, en este orden:
        - `approval_role` y `auto_open_pr`: admin y sesión del navegador. `require_review: false` está
          deprecado: se guarda `true`, con las cabeceras `Deprecation` y `Warning`.
        - `repo_url`: si con `approval_role` auto el cambio cambia quién aprueba (GitHub o no), admin y
          sesión del navegador. Si es de GitHub y el workspace tiene token, se comprueba como al crear (422).
          Si cambia, se vuelve a fijar su id de GitHub.
        - `live_steering` (`true`, `false` o `null` = por defecto) y `max_task_wall_time_hours` (1 a 168):
          admin, owner de la organización o platform engineer. Cada uno deja la actividad
          `project.config_changed`.

        El resto (`name`, `description`, `default_branch`…) lo cambia cualquier miembro del workspace.
      x-source: internal/api/identity.go:943
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectInput"
      responses:
        "200":
          description: El proyecto modificado.
          headers:
            Deprecation:
              description: "`true` si mandaste `require_review: false` (deprecado; se guarda `true`)."
              schema:
                type: string
            Warning:
              description: "Con `require_review: false`, un aviso 299 que explica la deprecación."
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json`, `invalid` (`approval_role`, o la base de datos) o `invalid_wall_time`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el proyecto no existe en el workspace."
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`conflict`."
        "422":
          description: "`github_repo_readonly`, `github_repo_no_contents`, `github_branch_not_found`, `github_repo_inaccessible` o
            `github_unauthorized`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteProject
      tags:
        - Proyectos
      summary: Borra un proyecto
      description: |
        Rol mínimo en el workspace: admin.

        Borra el proyecto sin ampliar la visibilidad: sus issues quedan sin proyecto; antes, en la misma
        transacción, si tenía roles, la historia de sus issues y tareas queda marcada (sólo la ven los admins),
        y los nodos de contexto nacidos en sus issues marcados o high bajan a su issue. Deja la actividad
        `project.deleted`. Si el proyecto no existe (o es de otro workspace), también 204.
      x-source: internal/api/identity.go:1041
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Proyecto borrado (o no existía).
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`forbidden`: no eres admin."
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/recipes:
    get:
      operationId: getRecipes
      tags:
        - Proyectos
      summary: Lee las recetas del proyecto
      description: |
        Las recetas guardadas del proyecto (agente, modelo, esfuerzo y plantilla por jugada), la plantilla
        por defecto de cada jugada con receta, las variables que admite cada una y si puedes editarlas
        (admin, owner de la organización o platform engineer).
      x-source: internal/api/ops_o6.go:159
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las recetas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - recipes
                  - defaults
                  - variables
                  - can_edit
                properties:
                  recipes:
                    type: array
                    items:
                      $ref: "#/components/schemas/Recipe"
                  defaults:
                    type: object
                    description: Jugada (`resolve-conflicts`, `fix-ci`) → plantilla por defecto, en el idioma del workspace.
                    additionalProperties:
                      type: string
                  variables:
                    type: object
                    description: Jugada → variables que admite su plantilla (`{{issue.key}}`, `{{base}}`, `{{conflicts}}` /
                      `{{failing_checks}}`).
                    additionalProperties:
                      type: array
                      items:
                        type: string
                  can_edit:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/recipes/{play}:
    put:
      operationId: putRecipe
      tags:
        - Proyectos
      summary: Guarda la receta de una jugada
      description: |
        Crea o reemplaza la receta de la jugada en el proyecto. La cambia un admin, owner de la organización
        o platform engineer (del proyecto o de la organización). La plantilla se limpia (sin Unicode
        invisible y con secretos redactados), como mucho 8192 bytes, y sólo admite las variables de la
        jugada. Deja la actividad `project.recipe_changed` con el sha256 de la plantilla. El cuerpo, como
        mucho 32 KiB.
      x-source: internal/api/ops_o6.go:193
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
        - name: play
          in: path
          required: true
          description: La jugada con receta.
          schema:
            type: string
            enum:
              - resolve-conflicts
              - fix-ci
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type:
                    - string
                    - "null"
                  format: uuid
                  description: Agente del workspace. Vacío o null = sin agente fijo.
                model:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9.\-]{0,59}$
                  description: Vacío = sin modelo fijo.
                effort:
                  type: string
                  pattern: ^[a-z]{0,20}$
                template:
                  type: string
                  description: Plantilla con `{{variable}}`. Vacía = la de por defecto.
      responses:
        "200":
          description: La receta guardada (`null` si no se pudo releer).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Recipe"
                  - type: "null"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json` o `invalid` (modelo, esfuerzo, plantilla o un agente que no es del workspace)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden`."
        "404":
          $ref: "#/components/responses/NotFound"
          description: "`not_found`: el proyecto, o una jugada sin receta."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/resume-metrics:
    get:
      operationId: getResumeMetrics
      tags:
        - Proyectos
      summary: Lee la métrica de reanudación del proyecto
      description: |
        De las continuaciones reclamadas en el proyecto en los últimos 30 días (sólo de los issues que ves):
        cuántas reanudaron su sesión, los rechazos por motivo y las que no tenían sesión que reanudar. Sólo
        recuentos.
      x-source: internal/api/ops_tras_o5.go:35
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La métrica.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResumeMetrics"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/roles:
    get:
      operationId: getProjectRoles
      tags:
        - Proyectos
      summary: Lee los roles del proyecto
      description: |
        Los roles SDLC del proyecto (rol, alcance y persona), los roles disponibles y si puedes editarlos
        (admin del workspace u owner de la organización).
      x-source: internal/api/sdlc.go:304
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los roles.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectRolesView"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    put:
      operationId: putProjectRoles
      tags:
        - Proyectos
      summary: Reemplaza los roles del proyecto
      description: |
        Reemplaza todos los roles del proyecto por los que mandas (como mucho 500; sólo miembros del
        workspace; alcance de hasta 120 caracteres). Los asigna un admin del workspace o un owner de la
        organización. Dejar sin ningún rol un proyecto que los tenía no lo abre a todo el workspace: la
        historia de sus issues y tareas queda marcada (sólo para admins) y los nodos de contexto nacidos en sus
        issues marcados o high bajan a su issue. Deja la
        actividad `sdlc.roles`. Devuelve los roles como `GET /projects/{pid}/roles`.
      x-source: internal/api/sdlc.go:322
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - roles
              properties:
                roles:
                  type: array
                  maxItems: 500
                  items:
                    $ref: "#/components/schemas/RoleInput"
      responses:
        "200":
          description: Los roles guardados.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectRolesView"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json` o `invalid` (demasiados roles, rol desconocido, `user_id` inválido, alcance
            largo, no miembro, o la base de datos)."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden`."
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/sdlc:
    get:
      operationId: getProjectSDLC
      tags:
        - SDLC
      summary: Lee la configuración SDLC del proyecto
      description: |
        La configuración SDLC del proyecto (por defecto, apagado) con los valores por defecto completados, la
        configuración por defecto, si puedes editarla (admin, owner de la organización o platform engineer),
        la métrica de plan_drift (de los issues que ves), las rutas de toolchain y los globs de tests que
        propone la web, y el modo de GitHub del repo.

        Si la configuración guardada no valida, `config` es la de por defecto con el modo guardado; el motivo
        no sale en la respuesta.
      x-source: internal/api/sdlc.go:142
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La configuración SDLC.
          content:
            application/json:
              schema:
                type: object
                required:
                  - mode
                  - config
                  - defaults
                  - can_edit
                  - plan_drift
                  - suggested_toolchain
                  - default_test_globs
                  - github_mode
                properties:
                  mode:
                    type: string
                    enum:
                      - off
                      - manual
                      - semi
                      - auto
                  config:
                    $ref: "#/components/schemas/SDLCConfig"
                  defaults:
                    $ref: "#/components/schemas/SDLCConfig"
                  can_edit:
                    type: boolean
                  plan_drift:
                    type: object
                    required:
                      - warnings
                      - expected
                      - fp_rate
                      - suggest_block
                    properties:
                      warnings:
                        type: integer
                        description: Avisos plan_drift (L3) en los issues del proyecto que ves.
                      expected:
                        type: integer
                        description: Cuántos se marcaron como esperados.
                      fp_rate:
                        type: number
                        description: expected / warnings (0 si no hay avisos).
                      suggest_block:
                        type: boolean
                        description: 20 avisos o más y una tasa por debajo del 5 %.
                  suggested_toolchain:
                    type: array
                    items:
                      type: string
                  default_test_globs:
                    type: array
                    items:
                      type: string
                  github_mode:
                    type: string
                    enum:
                      - none
                      - pat
                      - app
                      - app_error
                      - app_unverified
                    description: "`app` sólo si el ruleset de la rama exige hqf/approval con la App como origen; si no, `app_unverified`."
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    put:
      operationId: putProjectSDLC
      tags:
        - SDLC
      summary: Guarda la configuración SDLC del proyecto
      description: |
        Guarda el modo y la configuración del SDLC del proyecto. La cambia un admin, owner de la organización
        o platform engineer (del proyecto o de la organización).

        Validación: un campo desconocido en `config` da 400 (no se descarta en silencio); después, las reglas
        de la configuración (modo, pistas con Deploy después del código, rutas con `{key}`, jugadas,
        `source_of_truth` con conector, límites de verify, review, sweep, ci, supervised y globs).
        `ci.required_checks` exige un proyecto de GitHub con `auto_open_pr`; `external.connector`, un
        conector que exista en el workspace. Apagar el SDLC con issues que tienen puertas abiertas da 409.

        Si no mandas `mode`, vale el `mode` de `config` y, si tampoco viene, `off`: guardar sin modo apaga el
        SDLC.

        Efectos: al activarlo siembra las skills SDLC que falten en el workspace; guarda una revisión
        inmutable (con autor y sha256) y la actividad `sdlc.configured`.
      x-source: internal/api/sdlc.go:161
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                    - off
                    - manual
                    - semi
                    - auto
                  description: Si viene, sustituye al de `config`.
                config:
                  $ref: "#/components/schemas/SDLCConfig"
      responses:
        "200":
          description: La configuración guardada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - mode
                  - config
                properties:
                  mode:
                    type: string
                    enum:
                      - off
                      - manual
                      - semi
                      - auto
                  config:
                    $ref: "#/components/schemas/SDLCConfig"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`, `bad_json`, `invalid_config` (el mensaje dice qué falla) o `invalid`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
          description: "`session_required` o `forbidden`."
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
          description: "`open_gates`: hay issues con puertas abiertas (el mensaje los lista)."
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/sdlc/revisions:
    get:
      operationId: projectSDLCRevisions
      tags:
        - SDLC
      summary: Lista las revisiones de la configuración SDLC
      description: Las últimas 100 revisiones de la configuración SDLC del proyecto, de la más nueva a la más antigua.
      x-source: internal/api/connectors.go:476
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las revisiones.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RevisionRow"
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/projects/{pid}/worktree-proposal:
    get:
      operationId: getWorktreeProposal
      tags:
        - Proyectos
      summary: Lee la propuesta de worktree.yaml del proyecto
      description: |
        La propuesta de `worktree.yaml` que armó un daemon a partir de `.worktreeinclude`, `orca.yaml` o
        `conductor.json` (texto del repo, redactado; muéstralo plano). Sigue la audiencia del proyecto: con
        roles, la ven sus roles y los admins; quien no está en ella (o un proyecto que no existe) recibe 404.
        Sin propuesta (o ante cualquier error al leerla), 204.
      x-source: internal/api/ops_o1.go:759
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: pid
          in: path
          required: true
          description: Id del proyecto.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La propuesta.
          content:
            application/json:
              schema:
                type: object
                required:
                  - yaml
                  - sources
                  - runtime_name
                  - created_at
                properties:
                  yaml:
                    type: string
                  sources:
                    type: array
                    items:
                      type: string
                      enum:
                        - .worktreeinclude
                        - orca.yaml
                        - conductor.json
                  runtime_name:
                    type:
                      - string
                      - "null"
                    description: El runtime que la armó.
                  created_at:
                    type: string
                    format: date-time
        "204":
          description: No hay propuesta.
        "400":
          $ref: "#/components/responses/BadRequest"
          description: "`invalid_id`."
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/publish-incidents/{id}/resolve:
    post:
      operationId: resolvePublishIncident
      tags:
        - Revisión
      summary: Da por revisado un incidente de publicación
      description: |
        Marca como resuelto un incidente abierto de la comprobación posterior de una publicación. Lo atiende
        un admin u owner del workspace, o quien confirmó una publicación de esa tarea o de esa rama del
        issue, y sólo si ves el issue. Si no te toca, no lo ves, ya está resuelto o no existe, 404
        `not_found`. No lee cuerpo.

        Deja la actividad `github.publish_incident_resolved`.
      x-source: internal/api/publish.go:995
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: id
          in: path
          required: true
          description: Id del incidente (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Resuelto; sin cuerpo.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/questions/{qid}/answer:
    post:
      operationId: answerQuestion
      tags:
        - Preguntas y permisos
      summary: Responde una pregunta estructurada
      description: |
        Responde una pregunta abierta de un agente, con la sesión del navegador o con un token personal
        (queda `answered_via` = `web` o `api`).

        - Si no ves el issue de la pregunta, o no existe, 404 `not_found`.
        - Tienes que poder responder (403 `not_eligible`, con el motivo): ver el issue de la tarea y estar en
          la lista de quién responde fijada al preguntar (o, si es anterior a esa lista, las reglas de quién
          responde). Esto va antes que el estado.
        - Si ya no está abierta, 409 `not_open`.
        - Con opciones, `option` tiene que ser una de ellas (400 `invalid_option`). Sin opciones, `answer` es
          obligatoria (400 `answer_required`) y de hasta 8000 caracteres (400 `answer_too_long`); se limpia y
          se redacta antes de guardarse.

        Si la pregunta viene de un hueco de conocimiento, el hueco queda respondido también. Cuenta como
        dirigir el cambio; si no queda nada abierto en la tarea, sale su continuación. Devuelve la pregunta
        releída, sin `can_answer` ni `can_add_answerers` calculados (salen `false`).
      x-source: internal/api/ops_o2.go:638
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: qid
          in: path
          required: true
          description: Id de la pregunta (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnswerQuestionRequest"
      responses:
        "200":
          description: La pregunta respondida.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskQuestion"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`not_eligible`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_open`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/questions/{qid}/answerers:
    post:
      operationId: addAnswererTaskQuestions
      tags:
        - Preguntas y permisos
      summary: Añade a alguien a quién responde una pregunta
      description: |
        Un mantenedor del proyecto añade a una persona a la lista de quién responde una pregunta estructurada.
        Handler: `addAnswerer("task_questions")`.

        - Si no ves el issue de la pregunta, o no existe, 404 `not_found` (antes de leer el cuerpo).
        - `user_id` tiene que ser un UUID (400 `invalid`).
        - Hace falta ser mantenedor del proyecto: admin, product_owner o platform_engineer (403 `forbidden`).
          Esto va antes que el estado.
        - La pregunta tiene que estar abierta (409 `not_open`).
        - La persona tiene que ser miembro del workspace (400 `not_member`) y ver el issue (409
          `not_in_audience`: añádela antes como participante).

        Si la pregunta no tenía lista (es anterior a esa regla), primero la fija con los elegibles de siempre.
        Deja la actividad `question.answerer_added` y avisa a la persona en su bandeja.
      x-source: internal/api/ops_tras_o2.go:373
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: qid
          in: path
          required: true
          description: Id de la pregunta (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddAnswererRequest"
      responses:
        "204":
          description: Añadida; sin cuerpo.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_open` o `not_in_audience`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/quota-notices/{nid}/dismiss:
    post:
      operationId: dismissQuotaNotice
      tags:
        - Runtimes
      summary: Descarta un aviso de límite no reconocido
      description: |
        Sólo el dueño del runtime del aviso, con la sesión del navegador. Marca como visto el aviso de «límite no
        reconocido» (una tarea falló con algo que parecía un límite de cuota); no se borra: queda quién y cuándo.
        Queda en la actividad (`quota.notice_dismissed`) y avisa a tu bandeja (`inbox.resolved`).
      x-source: internal/api/ops_tras_o4.go:92
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: nid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Descartado.
        "400":
          description: "`invalid_id`: `nid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el aviso no existe, no es de un runtime tuyo o ya estaba descartado) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/remote-setup:
    get:
      operationId: getRemoteSetup
      tags:
        - Runtimes
      summary: Lee lo necesario para conectar una máquina por SSH
      description: >
        Rol mínimo en el workspace: admin. Devuelve si el servidor permite conectar máquinas por SSH

        (`REMOTE_RUNTIMES`), la URL pública de la API y, si lo permite, la clave SSH pública del workspace con su
        huella.

        La primera vez crea el par de claves del workspace (la privada se guarda cifrada y nunca sale del servidor).
      x-source: internal/api/remote_runtime.go:166
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: La configuración para el formulario.
          content:
            application/json:
              schema:
                type: object
                required:
                  - enabled
                  - server_url
                properties:
                  enabled:
                    type: boolean
                    description: El servidor permite conectar máquinas por SSH (`REMOTE_RUNTIMES`).
                  server_url:
                    type: string
                    description: URL pública de la API del servidor (`PUBLIC_API_URL`).
                  reason:
                    type: string
                    description: Por qué está desactivado (sólo con `enabled` false).
                  public_key:
                    type: string
                    description: Clave SSH pública del workspace (sólo con `enabled` true).
                  fingerprint:
                    type: string
                    description: Huella de la clave pública (sólo con `enabled` true).
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes:
    get:
      operationId: listRuntimes
      tags:
        - Runtimes
      summary: Lista los runtimes del workspace
      description: >
        Devuelve los runtimes del workspace por fecha de alta. Lo que ves depende de quién eres:

        - `waiting`: cada tarea en espera lleva su issue y su tarea sólo si ves el issue; si no, sólo `{"occupied":
        true}`.

        - `pending_consents`: los consentimientos pendientes, sólo en tus runtimes (0 en los demás).

        - `quota`: el detalle (ventanas, límites) sólo si eres admin o el dueño del runtime; `can_release`, sólo el
        dueño.

        - `live`: si el daemon está conectado ahora por WebSocket. `host_error`: sólo en el runtime de la máquina del
          servidor. `outdated`: el contenedor lleva una imagen distinta de la que construiría este servidor.
      x-source: internal/api/agents.go:764
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Los runtimes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Runtime"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/docker:
    post:
      operationId: createDockerRuntime
      tags:
        - Runtimes
      summary: Crea un runtime en Docker
      description: >
        Rol mínimo en el workspace: admin. Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está
        definida, la primera cuenta registrada).


        Exige Docker disponible en la máquina del servidor. Crea un runtime a tu nombre que corre en su propio

        contenedor (`hqf-<workspace>-<8 primeros caracteres del id>`, con el volumen `<contenedor>-home`), en estado

        `installing`, y lanza la instalación en segundo plano. Valores por defecto: `name` «Docker» (se corta a 64

        caracteres), `cpus` 2 (o las del motor si son menos), `memory_mb` 4096 (o la mitad de la del motor, mínimo

        512), `server_url` el configurado en el servidor y `harnesses` `["claude-code"]`. Límites: `cpus` de 0,5 a las

        del motor, `memory_mb` de 512 a la del motor; `harnesses` sólo CLIs conocidos e instalables (no `custom`).

        Queda en la actividad (`runtime.docker_added`) y difunde `runtime.updated`.
      x-source: internal/api/docker_runtime.go:273
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContainerInput"
      responses:
        "202":
          description: Runtime creado; la instalación sigue en segundo plano.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Runtime"
        "400":
          description: "`bad_json`, `invalid_cpus`, `invalid_memory`, `invalid_server_url`, `invalid_harness` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `instance_admin_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "Docker no disponible: `docker_disabled`, `docker_no_docker`, `docker_not_running` o `docker_unsupported`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/register:
    post:
      operationId: registerRuntime
      tags:
        - Runtimes
      summary: Registra un runtime
      description: |
        Lo llama `hqf daemon` con tu credencial: es la única ruta de un workspace que acepta un token de API con alcance
        `runtime`. Devuelve un token de runtime nuevo (prefijo `hqfrt_`), que el daemon usa en `/api/daemon/*`; sólo se
        devuelve aquí.

        Si `runtime_id` es el UUID de un runtime tuyo en este workspace, lo vuelve a registrar: cambia el nombre (si no
        viene vacío), `hostname`, `os`, `arch` y `providers`, rota el token y lo marca en línea. Si no (no viene, no es
        un UUID o no es tuyo), crea un runtime nuevo a tu nombre, con `name` o, si viene vacío, el `hostname`.
        `providers` vacío se guarda como `[]`. Difunde `runtime.updated`.
      x-source: internal/api/agents.go:788
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterRuntimeRequest"
      responses:
        "201":
          description: Registrado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - runtime_id
                  - token
                  - workspace_id
                  - workspace_slug
                properties:
                  runtime_id:
                    type: string
                    format: uuid
                  token:
                    type: string
                    description: Token del runtime (prefijo `hqfrt_`). En la base sólo queda su hash.
                  workspace_id:
                    type: string
                    format: uuid
                  workspace_slug:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/remote:
    post:
      operationId: createRemoteRuntime
      tags:
        - Runtimes
      summary: Conecta una máquina por SSH
      description: >
        Rol mínimo en el workspace: admin. Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está
        definida, la primera cuenta registrada).


        Exige `REMOTE_RUNTIMES` activo. Crea un runtime a tu nombre para una VPS o una instancia EC2 y lanza la

        instalación por SSH en segundo plano (estado `installing`). Reglas:

        - `kind`: `vps` (por defecto) o `ec2`.

        - `host`: IP pública o nombre DNS; acepta `ssh://`, `usuario@host` (si no das `user`) y `host:puerto` (si no
          das `port`).
        - `port`: de 1 a 65535 (22 por defecto). `user`: usuario SSH válido.

        - `auth`: `workspace_key` (la clave del workspace), `private_key` (exige `private_key`, con `passphrase` si
          está cifrada) o `password` (exige `password`).
        - `server_url`: obligatoria, `http(s)://host[:puerto]`; una URL `http://` pública exige `allow_insecure`.

        - No puede haber otro runtime del workspace con el mismo host, puerto y usuario (409 `remote_duplicate`).


        `name` es el host si no lo das (se corta a 64 caracteres). La clave privada y la contraseña se guardan cifradas

        y nunca se devuelven. Queda en la actividad (`runtime.remote_added`) y difunde `runtime.updated`.
      x-source: internal/api/remote_runtime.go:359
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RemoteInput"
      responses:
        "202":
          description: Runtime creado; la instalación sigue en segundo plano.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Runtime"
        "400":
          description: "`bad_json`, `invalid`, `invalid_host`, `invalid_user`, `invalid_server_url`, `insecure_server_url`,
            `ssh_key_passphrase` o `invalid_key`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `instance_admin_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`remote_runtimes_disabled` (el servidor no lo permite) o `remote_duplicate`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}:
    patch:
      operationId: patchRuntime
      tags:
        - Runtimes
      summary: Cambia la configuración de un runtime
      description: |
        Sólo el dueño del runtime. El servidor reenvía el cambio al daemon por su WebSocket y espera su respuesta
        (15 s); el daemon lo valida y lo guarda en el `config.json` de su máquina (`name` de 1 a 64 caracteres,
        `max_parallel` de 1 a 32, `task_timeout` una duración de 1m a 72h, p. ej. `30m`). Con la respuesta, el servidor
        guarda en la base el nombre, las rutas de los repos, `max_parallel` y `task_timeout`, y difunde
        `runtime.updated`.

        Si sólo cambias el nombre y el daemon no está conectado o no responde, el nombre se cambia sólo en el servidor
        y responde 204.
      x-source: internal/api/runtime_config.go:184
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchRuntimeRequest"
      responses:
        "200":
          description: La configuración que confirmó el daemon.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeConfig"
        "204":
          description: Sólo el nombre, cambiado en el servidor con el daemon desconectado o sin respuesta.
        "400":
          description: "`invalid_id`, `bad_json`, `runtime_name` (nombre vacío o de más de 64 caracteres) o `nothing_to_change`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`runtime_config_invalid`: el daemon rechazó el cambio (el mensaje es el suyo)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo (p. ej. la petición se canceló)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: deleteRuntime
      tags:
        - Runtimes
      summary: Borra un runtime
      description: |
        Avisa al daemon (`runtime.deleted`: borra su token de su `config.json` y se detiene); si el runtime lo lanza el
        servidor en su máquina, lo apaga; si es una máquina por SSH, quita su servicio y sus credenciales en segundo
        plano; si corre en Docker, borra su contenedor y su volumen en segundo plano. Después lo borra y difunde
        `runtime.deleted`. Responde 204 aunque no exista. No exige rol ni ser el dueño: basta ser miembro.
      x-source: internal/api/agents.go:845
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Borrado (o no existía).
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/approval-delegations:
    get:
      operationId: listDelegations
      tags:
        - Runtimes
      summary: Lista las delegaciones de aprobación de un runtime
      description: |
        Sólo el dueño del runtime. Devuelve hasta 200 delegaciones (quién aprueba en su nombre los comandos en el host
        de un proyecto), primero las vigentes y luego por fecha.
      x-source: internal/api/ops_o3.go:1160
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las delegaciones.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApprovalDelegation"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres el dueño del runtime) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createDelegation
      tags:
        - Runtimes
      summary: Delega las aprobaciones de un runtime
      description: |
        Sólo el dueño del runtime, con la sesión del navegador y autenticación reciente (código de correo hace menos de
        10 minutos). Delega en `delegate_user_id` aprobar los comandos en el host de este runtime para el proyecto
        `project_id`. Vence a los `expires_days` días (30 si no viene; de 1 a 90). El proyecto y la persona tienen que
        ser de este workspace y no puedes delegar en ti. Si la organización lo prohíbe
        (`forbid_host_approval_delegation`), 403 `delegation_forbidden`. Queda en la actividad
        (`runtime.approval_delegated`).
      x-source: internal/api/ops_o3.go:1176
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDelegationRequest"
      responses:
        "201":
          description: La delegación creada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApprovalDelegation"
        "400":
          description: "`invalid_id` (`rid`), `bad_json` o `invalid` (ids que no son UUID, `expires_days` fuera de 1–90, delegar
            en ti, o proyecto o persona de fuera del workspace)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "`unauthorized` o `reauth_required` (la sesión no entró con código hace menos de 10 minutos)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required`, `delegation_forbidden` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/approval-delegations/{did}:
    delete:
      operationId: revokeDelegation
      tags:
        - Runtimes
      summary: Revoca una delegación de aprobación
      description: |
        Sólo el dueño del runtime, con la sesión del navegador. La delegación deja de valer en ese momento, también
        para las solicitudes ya abiertas; no se borra. Queda en la actividad (`runtime.approval_delegation_revoked`).
      x-source: internal/api/ops_o3.go:1235
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: did
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Revocada.
        "400":
          description: "`invalid_id`: `rid` o `did` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace, o la delegación no existe o ya estaba revocada) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/config:
    get:
      operationId: getRuntimeConfig
      tags:
        - Runtimes
      summary: Lee la configuración de un runtime
      description: |
        Sólo el dueño del runtime. Pide la configuración al daemon por su WebSocket (espera hasta 15 s), guarda en la
        base las rutas de los repos, `max_parallel` y `task_timeout`, y la devuelve. Las API keys de la máquina salen
        sólo por su nombre (`env_keys`).
      x-source: internal/api/runtime_config.go:169
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La configuración del daemon.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeConfig"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/runtimes/{rid}/consents:
    get:
      operationId: listRuntimeConsents
      tags:
        - Runtimes
      summary: Lista los consentimientos de un runtime
      description: |
        Sólo el dueño del runtime, con la sesión del navegador. Devuelve hasta 200 consentimientos (lo que
        `.hqfabric/worktree.yaml` pide hacer en su máquina), primero los pendientes y luego por fecha de petición.
        `requested_task_id` sólo sale si ves el issue de esa tarea.
      x-source: internal/api/ops_o1.go:479
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los consentimientos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RuntimeConsent"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/consents/{cid}/grant:
    post:
      operationId: grantRuntimeConsent
      tags:
        - Runtimes
      summary: Da un consentimiento
      description: |
        Sólo el dueño del runtime, con la sesión del navegador y autenticación reciente (código de correo hace menos de
        10 minutos). Consiente exactamente lo pendiente (su hash). Vence a los `expires_days` días (de 1 a 90; si no
        viene o es 0, 90). Sólo vale para un consentimiento pendiente o vencido, no revocado.
        - `copy_secrets` está apagado en el servidor: 409 `copy_secrets_off`.
        - `supervised.allow` con la organización prohibiendo la delegación (`forbid_host_approval_delegation`): 403
          `delegation_forbidden`.

        Queda en `policy_decisions` y en la actividad (`runtime.consent_granted`). Si la tarea que lo pidió falló por
        infraestructura, nadie la repitió y no le falta otro consentimiento, se vuelve a encolar (`requeued` 1).
      x-source: internal/api/ops_o1.go:499
      x-duda: |
        ¿El cuerpo es opcional? El código ignora el resultado de `decode` (`_ = decode(...)`): con un cuerpo vacío o un
        JSON inválido escribe 400 `bad_json`, sigue, concede el consentimiento y escribe otra respuesta detrás (llega el
        estado 400 con dos JSON seguidos). No se sabe si el contrato es «cuerpo obligatorio» u «opcional».
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: cid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GrantRuntimeConsentRequest"
      responses:
        "200":
          description: El consentimiento y si se reencoló la tarea.
          content:
            application/json:
              schema:
                type: object
                required:
                  - consent
                  - requeued
                properties:
                  consent:
                    $ref: "#/components/schemas/RuntimeConsent"
                  requeued:
                    type: integer
                    enum:
                      - 0
                      - 1
                    description: 1 si la tarea que lo pidió se volvió a encolar.
        "400":
          description: "`invalid_id` (`rid`), `invalid` (`cid` no es un UUID, o `expires_days` fuera de 1–90) o `bad_json`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "`unauthorized` o `reauth_required` (la sesión no entró con código hace menos de 10 minutos)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required`, `delegation_forbidden` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`copy_secrets_off` o `not_pending` (ya se dio, se revocó o no existe)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/consents/{cid}/revoke:
    post:
      operationId: revokeRuntimeConsent
      tags:
        - Runtimes
      summary: Revoca un consentimiento
      description: |
        Sólo el dueño del runtime, con la sesión del navegador. El consentimiento deja de valer en ese momento; no se
        borra. Queda en `policy_decisions` y en la actividad (`runtime.consent_revoked`).
      x-source: internal/api/ops_o1.go:610
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: cid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Revocado.
        "400":
          description: "`invalid_id` (`rid`) o `invalid` (`cid` no es un UUID)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace, o el consentimiento no existe o ya estaba revocado) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/container:
    get:
      operationId: getDockerRuntime
      tags:
        - Runtimes
      summary: Lee el detalle de un runtime en Docker
      description: |
        Rol mínimo en el workspace: admin. Devuelve el contenedor del runtime, sus recursos, su estado, el log de la
        última operación y si hay una operación en curso; si no la hay, consulta a Docker si el contenedor corre
        (5 s como mucho).
      x-source: internal/api/docker_runtime.go:439
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El detalle del contenedor.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContainerRuntime"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (ese runtime no corre en Docker o no es del workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/container/{action}:
    post:
      operationId: dockerAction
      tags:
        - Runtimes
      summary: Ejecuta una acción en un runtime en Docker
      description: >
        Rol mínimo en el workspace: admin. Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está
        definida, la primera cuenta registrada).


        Acciones: `install` (recrea el contenedor), `update` (reconstruye la imagen desde cero), `start`, `stop` y

        `restart`. Exige Docker disponible. Con `install` y `update` puedes mandar un cuerpo para cambiar `name`,

        `cpus`, `memory_mb`, `server_url` y `harnesses` (mismas reglas que al crear; lo que no mandas se conserva); en

        las demás acciones el cuerpo se ignora. Los cambios se guardan antes de comprobar si hay otra operación en

        curso. La acción corre en segundo plano (un `start` sobre un contenedor que ya no existe lo recrea). Queda en

        la actividad (`runtime.docker_<acción>`).
      x-source: internal/api/docker_runtime.go:464
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: action
          in: path
          required: true
          schema:
            type: string
            enum:
              - install
              - update
              - start
              - stop
              - restart
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContainerInput"
      responses:
        "202":
          description: Acción lanzada; el detalle del contenedor.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContainerRuntime"
        "400":
          description: "`invalid_id`, `bad_json`, `invalid_cpus`, `invalid_memory`, `invalid_server_url` o `invalid_harness`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `instance_admin_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (acción desconocida, o ese runtime no corre en Docker o no es del workspace) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_busy` (ya hay una operación en curso) o Docker no disponible (`docker_disabled`,
            `docker_no_docker`, `docker_not_running`, `docker_unsupported`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/harnesses:
    get:
      operationId: getHarnesses
      tags:
        - Runtimes
      summary: Lista los harnesses de un runtime
      description: |
        Sólo el dueño del runtime. Pide al daemon que vuelva a detectar los CLIs de agentes de su máquina, guarda lo
        detectado en el runtime (y difunde `runtime.updated`) y devuelve cada CLI del catálogo (salvo `custom`) con su
        estado: instalado, versión, sesión iniciada y si tiene API key guardada.
      x-source: internal/api/harness.go:84
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los harnesses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Harness"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline` (el daemon no está conectado) o `runtime_outdated` (el daemon es de una versión que no
            detecta)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/runtimes/{rid}/harnesses/{hid}/key:
    put:
      operationId: putHarnessKey
      tags:
        - Runtimes
      summary: Guarda la API key de un harness
      description: |
        Sólo el dueño del runtime. Manda al daemon la API key del CLI `hid` para que la guarde en el `config.json` de
        su máquina, en la variable del CLI (`ANTHROPIC_API_KEY`, `CURSOR_API_KEY`, `GEMINI_API_KEY`,
        `COPILOT_GITHUB_TOKEN` o `AMP_API_KEY`). El servidor no la guarda. La clave, sin espacios alrededor, tiene que
        tener al menos 8 caracteres y ningún espacio, tabulador ni salto de línea. Devuelve los harnesses tras volver a
        detectar.
      x-source: internal/api/harness.go:104
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: hid
          in: path
          required: true
          description: Id del CLI que admite API key (`claude-code`, `cursor`, `gemini`, `copilot`, `amp`).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HarnessKeyRequest"
      responses:
        "200":
          description: Los harnesses tras el cambio.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Harness"
        "400":
          description: "`invalid_id`, `bad_json` o `invalid_key`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace, o ese harness no admite API key) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`runtime_rejected`: el daemon rechazó el cambio."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: deleteHarnessKey
      tags:
        - Runtimes
      summary: Quita la API key de un harness
      description: |
        Sólo el dueño del runtime. Pide al daemon que quite de su `config.json` la variable de la API key del CLI `hid`.
        Devuelve los harnesses tras volver a detectar.
      x-source: internal/api/harness.go:108
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: hid
          in: path
          required: true
          description: Id del CLI que admite API key (`claude-code`, `cursor`, `gemini`, `copilot`, `amp`).
          schema:
            type: string
      responses:
        "200":
          description: Los harnesses tras el cambio.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Harness"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace, o ese harness no admite API key) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`runtime_rejected`: el daemon rechazó el cambio."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/runtimes/{rid}/quota/{provider}/release:
    post:
      operationId: releaseQuotaLimit
      tags:
        - Runtimes
      summary: Libera un límite de cuota activo
      description: |
        Sólo el dueño del runtime, con la sesión del navegador. Quita el límite reactivo activo (`limited_until` en el
        futuro) de ese proveedor en el runtime; restablecer la confianza no lo hace. Las tareas del runtime que
        esperaban cuota de ese proveedor dejan de esperar y se lanza un barrido de cuota. Queda en la actividad
        (`quota.limit_released`) y se avisa al dueño y a los admins (`runtime.updated`).
      x-source: internal/api/ops_tras_o4.go:119
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: provider
          in: path
          required: true
          description: Id del proveedor (p. ej. `claude-code`, `codex`). No se valida contra el catálogo.
          schema:
            type: string
      responses:
        "204":
          description: Límite liberado.
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`owner_only` (no eres el dueño del runtime), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace, o no hay un límite activo que liberar) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/runtimes/{rid}/quota/{provider}/trust:
    post:
      operationId: restoreQuotaTrust
      tags:
        - Runtimes
      summary: Vuelve a fiarse de la cuota de un runtime
      description: |
        Rol mínimo en el workspace: admin. Exige la sesión del navegador. Quita la marca de «cuota no confiable» de ese
        proveedor en el runtime (no libera un límite activo). Queda en la actividad (`quota.trust_restored`) y se avisa
        al dueño y a los admins (`runtime.updated`).
      x-source: internal/api/ops_o4.go:554
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: provider
          in: path
          required: true
          description: Id del proveedor. No se valida contra el catálogo.
          schema:
            type: string
      responses:
        "204":
          description: Confianza restablecida.
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (no hay cuota no confiable de ese proveedor en ese runtime del workspace) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/remote:
    get:
      operationId: getRemoteRuntime
      tags:
        - Runtimes
      summary: Lee el detalle de una máquina conectada por SSH
      description: |
        Rol mínimo en el workspace: admin. Devuelve la conexión SSH del runtime (sin secretos; de la clave del host,
        sólo su huella), su estado, el log de la última operación y si hay una operación en curso.
      x-source: internal/api/remote_runtime.go:425
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El detalle de la máquina.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteRuntime"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (ese runtime no es una máquina remota o no es del workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/remote/{action}:
    post:
      operationId: remoteAction
      tags:
        - Runtimes
      summary: Ejecuta una acción en una máquina conectada por SSH
      description: >
        Rol mínimo en el workspace: admin. Sólo el administrador de la instancia (INSTANCE_ADMINS o, si no está
        definida, la primera cuenta registrada).


        Acciones: `install` (reinstala o actualiza), `start`, `stop` y `restart`. Con `install` puedes mandar un cuerpo

        para cambiar la conexión (mismas reglas que al crear; lo que no mandas se conserva, y cambiar el host o

        `trust_host_key` olvidan la clave del host fijada); en las demás acciones el cuerpo se ignora. Los cambios se

        guardan antes de comprobar si hay otra operación en curso. Un `start` o `restart` sobre una máquina que nunca

        llegó a instalarse hace `install`. La acción corre en segundo plano. Queda en la actividad

        (`runtime.remote_<acción>`).
      x-source: internal/api/remote_runtime.go:449
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: action
          in: path
          required: true
          schema:
            type: string
            enum:
              - install
              - start
              - stop
              - restart
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RemoteInput"
      responses:
        "202":
          description: Acción lanzada; el detalle de la máquina.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteRuntime"
        "400":
          description: "`invalid_id`, `bad_json`, `invalid`, `invalid_host`, `invalid_user`, `invalid_server_url`,
            `insecure_server_url`, `ssh_key_passphrase` o `invalid_key`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres admin), `instance_admin_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (acción desconocida, o ese runtime no es una máquina remota o no es del workspace) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`remote_duplicate` (otra máquina del workspace con el mismo host, puerto y usuario) o `remote_busy` (ya
            hay una operación en curso)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/repos/{pid}:
    put:
      operationId: linkRuntimeRepo
      tags:
        - Runtimes
      summary: Vincula un repo local a un proyecto
      description: |
        Sólo el dueño del runtime. Pide al daemon que vincule la carpeta `path` de su máquina al proyecto `pid` (la
        guarda por el slug del proyecto y quita una posible entrada por id); el daemon comprueba la carpeta. Guarda la
        configuración resultante en la base y difunde `runtime.updated`. Si el `origin` de la carpeta no coincide con
        el repo del proyecto, añade `warning` (el vínculo queda hecho igualmente).
      x-source: internal/api/runtime_config.go:258
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: pid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkRuntimeRepoRequest"
      responses:
        "200":
          description: El repo vinculado y la configuración resultante.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkRuntimeRepoResponse"
        "400":
          description: "`invalid_id` (`rid` o `pid` no es un UUID) o `bad_json`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime o el proyecto no existen en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`runtime_repo_invalid`: el daemon rechazó la carpeta (el mensaje es el suyo)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: unlinkRuntimeRepo
      tags:
        - Runtimes
      summary: Desvincula un repo local de un proyecto
      description: |
        Sólo el dueño del runtime. Pide al daemon que quite el vínculo del proyecto (por su id y, si el proyecto existe
        en el workspace, también por su slug), guarda la configuración resultante y difunde `runtime.updated`.
      x-source: internal/api/runtime_config.go:309
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: pid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La configuración resultante.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeConfig"
        "400":
          description: "`invalid_id`: `rid` o `pid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`runtime_not_owner` (no eres el dueño) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`runtime_config_invalid`: el daemon rechazó el cambio."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "503":
          description: "`runtime_error`: la espera se cortó por otro motivo."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: "`runtime_timeout`: el daemon no respondió en 15 s."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/runtimes/{rid}/verify-grants:
    get:
      operationId: listVerifyGrants
      tags:
        - Runtimes
      summary: Lista los permisos de verificación de un runtime
      description: |
        Devuelve los permisos vigentes (no revocados) del dueño del runtime para ejecutar la verificación de agentes
        `safe` en su máquina, por fecha. Cualquier miembro puede verlos. Si el runtime no es del workspace, la lista
        sale vacía.
      x-source: internal/api/sdlc_build.go:332
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los permisos vigentes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/VerifyGrant"
        "400":
          description: "`invalid_id`: `rid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: grantVerify
      tags:
        - Runtimes
      summary: Permite la verificación en un runtime
      description: |
        Sólo el dueño del runtime, con la sesión del navegador. Permite ejecutar la verificación de agentes `safe` en su
        máquina, para todos los proyectos (sin `project_id` o vacío) o para uno. Si ya había un permiso vigente igual,
        no crea otro. Queda en `policy_decisions` y en la actividad (`verify.host_exec_granted`), y lanza una
        continuación «sólo verificación» por cada tarea del runtime pendiente de verificación (del proyecto, si lo
        das) que no tenga ya una continuación.
      x-source: internal/api/sdlc_build.go:350
      x-duda: >
        ¿El cuerpo es opcional? El código ignora el resultado de `decode` (`_ = decode(...)`): con un cuerpo vacío o un

        JSON inválido escribe 400 `bad_json`, sigue, crea el permiso y escribe otra respuesta detrás (llega el estado
        400

        con dos JSON seguidos). La web siempre manda un cuerpo (`{}` como mínimo).
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GrantVerifyRequest"
      responses:
        "201":
          description: Permiso dado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - requeued
                properties:
                  requeued:
                    type: integer
                    description: Cuántas continuaciones de verificación se encolaron.
        "400":
          description: "`invalid_id` (`rid`), `invalid` (`project_id` no es un UUID o no existe) o `bad_json`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/runtimes/{rid}/verify-grants/{gid}:
    delete:
      operationId: revokeVerify
      tags:
        - Runtimes
      summary: Retira un permiso de verificación
      description: |
        Sólo el dueño del runtime, con la sesión del navegador. El permiso deja de valer; no se borra. Queda en
        `policy_decisions`.
      x-source: internal/api/sdlc_build.go:379
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: rid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: gid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Permiso retirado.
        "400":
          description: "`invalid_id` (`rid`) o `invalid` (`gid` no es un UUID)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`forbidden` (no eres el dueño del runtime), `session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el runtime no existe en el workspace, o el permiso no existe o ya estaba retirado) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/search/sessions:
    post:
      operationId: searchSessions
      tags:
        - Búsqueda
      summary: Busca en las sesiones de los agentes
      description: |
        Busca un texto en los eventos (`message`, `tool_call`, `tool_result`, `error`), los mensajes de
        conducción y las preguntas de las tareas de los issues que ves, en un rango de fechas. Es `POST` para
        que el texto no vaya en la URL.

        - Hasta 30 búsquedas por minuto y usuario (429 `rate_limited`), contado antes de validar.
        - `q`: tras quitar controles e invisibles y plegar espacios, entre 2 y 200 caracteres. `from` y `to`:
          fechas RFC 3339, `from` antes que `to` y como mucho 90 días (más una hora de margen) entre ellas.
          `project_id`, si viene y no está vacío, un UUID. Cualquier fallo: 400 `invalid`.
        - El texto se busca como palabras sueltas (sin operadores). Un texto con forma de secreto no se busca:
          responde sin resultados.
        - Devuelve como mucho 50 resultados, del más reciente al más antiguo, y `more` si había más. Cada uno
          trae un fragmento de unos 240 caracteres en texto plano, en segmentos con `hit` en las palabras que
          casan, con los secretos redactados.
        - La búsqueda queda auditada (el texto redactado y recortado, nunca en la actividad). Si la consulta
          falla o pasa de 8 segundos, 500 `search_failed`.
      x-source: internal/api/search_o7.go:363
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchIn"
      responses:
        "200":
          description: Los resultados.
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                  - more
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/SearchResult"
                  more:
                    type: boolean
                    description: Había más de 50 resultados.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          description: Demasiadas búsquedas (`rate_limited`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: La búsqueda falló (`search_failed`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/sessions/{tid}/resume:
    post:
      operationId: wakeSession
      tags:
        - Tareas
      summary: Despierta una sesión hibernada
      description: |
        Pide al runtime que despierte la sesión hibernada de la tarea. No lee cuerpo.

        Sólo quien lanzó la tarea o el dueño del runtime (403 `forbidden`). La tarea tiene que estar `running`,
        esperando en `hibernated` y con runtime (409 `not_hibernated`). Deja la actividad `session.woken`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o5.go:931
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "202":
          description: Aviso enviado al runtime; sin cuerpo.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_hibernated`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/skills:
    post:
      operationId: createSkill
      tags:
        - Skills
      summary: Crea una skill
      description: |
        Crea una skill en el workspace. `name` (no vacío) es obligatorio. Si no los mandas: `slug` sale del nombre (si
        mandas `slug`, se normaliza igual), `description` y `content` vacíos, `version` `1.0.0` y `files` `[]`.
        Guarda una revisión inmutable de la skill (versión, contenido, archivos, su sha256 y quién la hizo). No exige
        rol.
      x-source: internal/api/agents.go:629
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SkillInput"
                - required:
                    - name
      responses:
        "201":
          description: La skill creada.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Skill"
        "400":
          description: "`bad_json`, `name_required` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`conflict`: ya hay una skill con ese slug en el workspace."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    get:
      operationId: listSkills
      tags:
        - Skills
      summary: Lista las skills del workspace
      description: Devuelve las skills del workspace ordenadas por nombre, con cuántos agentes usan cada una.
      x-source: internal/api/agents.go:598
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Las skills.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Skill"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/skills/{sid}:
    get:
      operationId: getSkill
      tags:
        - Skills
      summary: Lee una skill
      description: Devuelve una skill del workspace.
      x-source: internal/api/agents.go:607
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: sid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La skill.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Skill"
        "400":
          description: "`invalid_id`: `sid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`not_found` (la skill no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    patch:
      operationId: patchSkill
      tags:
        - Skills
      summary: Cambia una skill
      description: |
        Cambia los campos que mandas de `name`, `description`, `version`, `content` y `files`; `slug` se ignora.
        Guarda una revisión nueva si el contenido o los archivos cambiaron. No exige rol.
      x-source: internal/api/agents.go:659
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: sid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkillInput"
      responses:
        "200":
          description: La skill tras el cambio.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Skill"
        "400":
          description: "`invalid_id`, `bad_json` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: "`not_found` (la skill no existe en el workspace) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteSkill
      tags:
        - Skills
      summary: Borra una skill
      description: Borra la skill (y sus enlaces con agentes). Responde 204 aunque no exista. No exige rol.
      x-source: internal/api/agents.go:689
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: sid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Borrada (o no existía).
        "400":
          description: "`invalid_id`: `sid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks:
    get:
      operationId: listTasks
      tags:
        - Tareas
      summary: Lista las tareas del workspace
      description: |
        Devuelve hasta 200 tareas del workspace, de la más reciente a la más antigua, sólo las de los issues
        que ves.

        Filtros opcionales:
        - `status`: uno o varios estados separados por comas. No se valida: un estado que no existe no casa
          con ninguna tarea.
        - `agent_id` y `runtime_id`: sólo se aplican si son un UUID válido; si no, se ignoran.

        En la lista no salen los campos que calcula la vista de una tarea (`defaulted_questions`,
        `can_extend_wall_time`, `can_retry`, `quota_hold`, `queued_inputs`, `pr_conflicts`,
        `can_resolve_conflicts`, `can_fix_ci`).
      x-source: internal/api/tasks.go:476
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: status
          in: query
          required: false
          description: Estados separados por comas (`queued`, `claimed`, `running`, `blocked`, `completed`, `failed`, `cancelled`,
            `pending_verification`).
          schema:
            type: string
        - name: agent_id
          in: query
          required: false
          description: Sólo las tareas de este agente (se ignora si no es un UUID).
          schema:
            type: string
            format: uuid
        - name: runtime_id
          in: query
          required: false
          description: Sólo las tareas de este runtime (se ignora si no es un UUID).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las tareas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Task"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}:
    get:
      operationId: getTaskHandler
      tags:
        - Tareas
      summary: Lee una tarea
      description: |
        Devuelve la tarea si ves su issue; si no la ves, o no existe, 404 `not_found`.

        También de lo que sale en la lista, rellena:
        - `defaulted_questions`: las preguntas de la cadena (la tarea, las que continúa y las que reintenta)
          que se cerraron con la opción por defecto, hasta 50.
        - `can_extend_wall_time`: si está `blocked` por `wall_time` y puedes extender el tope.
        - `quota_hold`: si está en cola y ningún runtime candidato está libre de retención por cuota.
        - `can_retry`: sólo con la sesión del navegador (con un token de API no sale); las mismas reglas que
          `POST /tasks/{tid}/retry`.
        - `queued_inputs`: menciones en cola para la siguiente ejecución, si está en `queued`, `claimed`,
          `running` o `blocked`.
        - `pr_conflicts`, `can_resolve_conflicts`, `can_fix_ci`: sin SDLC, con un PR abierto y la tarea
          terminada.

        Los campos con `omitempty` (`false`, `0` o lista vacía) no salen.
      x-source: internal/api/tasks.go:502
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La tarea.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/tasks/{tid}/approve:
    post:
      operationId: approveTask
      tags:
        - Revisión
      summary: Aprueba una tarea
      description: |
        La puerta humana: aprueba una tarea completada y, con `merge`, integra su rama (o sube la rama y abre
        el PR si el proyecto está en GitHub). El cuerpo (`ApproveIn`) es opcional: si no es JSON válido se
        ignora. Hace falta ver el issue de la tarea (si no, 404 `not_found`).

        Reglas comunes: sólo una tarea `completed` (409 `not_completed`). Con etapa SDLC no se aprueban una
        `review` (409 `review_play`), una jugada de artefacto (409 `artifact_play`), un `repro` (409
        `repro_confirm`) ni una jugada que verifica con `verify_status=failed` (409 `verifier_failed`).

        **Jugada de código SDLC** (con etapa y jugada `build`, `fix` o `resolve-conflicts`):
        - El SDLC del issue tiene que estar activo (409 `sdlc_off`).
        - Si es de un fan-out con Build esperando aprobación, eliges la ganadora: hace falta el rol engineer o
          code owner (403 `role_required`); descarta las demás y responde 200 `{ok: true, winner: true}`
          (un fallo del pipeline sale como 409 `sdlc`, `sdlc_busy`, `sdlc_awaiting`, `sdlc_no_play` o
          `sdlc_not_started`).
        - Si no: configuración SDLC válida (409 `config_invalid`), Deploy activo o esperando (409
          `code_not_ready`), la última tarea de código de la rama (409 `stale_task`), verificación en verde y
          con commit (409 `verify_required`), L4 en verde sobre ese commit (409 `l4_blocked`), revisión
          agéntica del commit si se exige (409 `review_required`), sin binarios sin inspeccionar ni cambios
          de submódulo pendientes (409 `binary_uninspected`), checks de CI exigidos en verde (409
          `ci_needs_publish` en un issue restringido sin publicar, si no `checks_required`) y confirmación de
          los secretos redactados (409 `redacted_confirm`).
        - La decisión de aprobación de código (cobertura de code owners y cuatro ojos): si no se permite, 403
          (o 409 si el código es `confirm_no_four_eyes` o `nothing_left_to_cover`) con
          `{error, message, decision, others}`.
        - Con `merge` en un issue high o marcado y todo cubierto, el camino único del manifiesto (409
          `publish_unknown`, `publish_preparing`, `publish_confirm`, `publish_in_progress`,
          `redacted_confirm` o `runtime_offline`). Los errores de GitHub salen como en el resto de rutas de
          GitHub (409, 422 o 502).
        - Si faltan archivos por cubrir, guarda tu aprobación parcial y responde 202
          `{ok: true, partial: true, decision}`. Si queda cubierto, aprueba (con `merge`, 409 `no_branch` sin
          rama ni runtime y 409 `runtime_offline` si el runtime no está) y responde 200
          `{ok: true, four_eyes, decision}`.

        **Resto de tareas** (sin etapa, o con otra jugada):
        - Una tarea sin etapa en un issue que sigue el SDLC: 409 `outside_pipeline`.
        - Confirmación de los secretos redactados del diff (409 `redacted_confirm`).
        - Con `merge`: hace falta el rol que pide la política de aprobación del proyecto (403
          `approval_forbidden`), rama y runtime (409 `no_branch`). Con GitHub, el runtime sube la rama y el
          servidor abre el PR; en un issue high o marcado, también, 409 `stale_task` si hay una tarea más nueva
          en la rama y el camino del manifiesto (mismos 409). Sin GitHub, fusión local en el runtime; en un
          issue restringido sin commit conocido, 409 `no_commit`. Runtime desconectado: 409
          `runtime_offline`.
        - Marca la tarea aprobada; en un fan-out cancela y descarta las demás tareas del grupo; sin `merge`
          pasa el issue a `done`. Responde 200 `{ok: true}`.
      x-source: internal/api/tasks.go:1043
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApproveIn"
      responses:
        "200":
          description: |
            Aprobada. Sin SDLC, `{ok: true}`; al elegir la ganadora de un fan-out SDLC, `{ok: true, winner: true}`;
            con la aprobación de código SDLC completa, `{ok: true, four_eyes, decision}`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
                  winner:
                    type: boolean
                    description: Sólo al elegir la ganadora de un fan-out SDLC.
                  four_eyes:
                    type: boolean
                    description: Sólo en la aprobación de código SDLC; si todas las aprobaciones fueron con cuatro ojos.
                  decision:
                    $ref: "#/components/schemas/CodeDecision"
        "202":
          description: Aprobación de código SDLC parcial (faltan archivos por cubrir).
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - partial
                  - decision
                properties:
                  ok:
                    type: boolean
                    const: true
                  partial:
                    type: boolean
                    const: true
                  decision:
                    $ref: "#/components/schemas/CodeDecision"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: |
            `session_required`, `approval_forbidden`, `role_required` o un rechazo de la
            aprobación de código (`not_user`, `code_owner_required`, `four_eyes`, `four_eyes_required`,
            `approval_role_required`, con `decision` y `others`).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    required:
                      - error
                      - message
                      - decision
                      - others
                    properties:
                      error:
                        type: string
                        description: Código de rechazo de la aprobación de código.
                      message:
                        type: string
                        description: El motivo y, si hay, quién más puede aprobar.
                      decision:
                        $ref: "#/components/schemas/CodeDecision"
                      others:
                        type: array
                        description: Nombres de quienes podrían aprobar en tu lugar.
                        items:
                          type: string
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            Un error de las reglas de arriba. `publish_confirm` trae también el manifiesto a confirmar
            (`manifest`, `hash`, `redacted`); `confirm_no_four_eyes` y `nothing_left_to_cover` traen `decision`
            y `others`. GitHub: `github_not_connected`, `github_token_unreadable`.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    required:
                      - error
                      - message
                      - manifest
                      - hash
                      - redacted
                    properties:
                      error:
                        type: string
                        const: publish_confirm
                      message:
                        type: string
                      manifest:
                        $ref: "#/components/schemas/Manifest"
                      hash:
                        type: string
                        description: Hash del manifiesto; mándalo en `confirm_publish` para confirmar.
                      redacted:
                        type: integer
                        description: Secretos redactados en los commits que salen.
                  - type: object
                    required:
                      - error
                      - message
                      - decision
                      - others
                    properties:
                      error:
                        type: string
                      message:
                        type: string
                      decision:
                        $ref: "#/components/schemas/CodeDecision"
                      others:
                        type: array
                        items:
                          type: string
        "422":
          description: GitHub rechazó la operación (`github_unauthorized`, `github_forbidden`, `github_not_found`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: Error al contactar con GitHub (`github_error`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/bundle:
    get:
      operationId: taskBundle
      tags:
        - Tareas
      summary: Lee el contexto que recibió una tarea
      description: |
        Devuelve el paquete de contexto de la tarea (presupuesto, lo incluido y lo descartado, el prefijo
        estático y la parte dinámica) y el hash del prefijo del paquete anterior del mismo agente. Si la tarea
        no tiene paquete, 404 `not_found`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:1213
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El paquete de contexto.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BundleRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/cancel:
    post:
      operationId: cancelTask
      tags:
        - Tareas
      summary: Cancela una tarea
      description: |
        Pide cancelar la tarea. Hace falta ver su issue (si no, 404 `not_found`). No lee cuerpo.

        Según su estado:
        - `queued`: pasa a `cancelled`.
        - `claimed` o `running` esperando cuota, o esperando la respuesta de una pregunta con reanudación (sin
          proceso en el daemon): se cancela en el servidor, se cancelan sus preguntas abiertas y se cierran
          sus sesiones. Si mientras tanto dejó de esperar (llegó la respuesta o el reinicio de la cuota),
          409 `state_changed`.
        - `claimed` o `running` con proceso: se envía `task.cancel` a su runtime. Si no tiene runtime o el
          runtime no está conectado, pasa a `cancelled` con el error `runtime offline` y se cancelan sus
          preguntas abiertas.
        - Cualquier otro estado (también `blocked` y `pending_verification`): 409 `not_cancellable`.

        Después deniega (con interrupción) las solicitudes de permiso abiertas de la tarea y deja la
        actividad `task.cancel_requested`.
      x-source: internal/api/tasks.go:569
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "202":
          description: Cancelación pedida o hecha.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_cancellable` (la tarea ya terminó) o `state_changed` (dejó de esperar mientras la cancelabas)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/checkpoints:
    get:
      operationId: taskCheckpoints
      tags:
        - Tareas
      summary: Lista los checkpoints de la cadena de una tarea
      description: |
        Devuelve los checkpoints de la tarea y de las que continúa (siguiendo `continues` hacia atrás, hasta
        50 niveles), sólo de tareas cuyo issue ves, del más reciente al más antiguo, hasta 200.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o1.go:173
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los checkpoints.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Checkpoint"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/deltas:
    get:
      operationId: taskDeltas
      tags:
        - Tareas
      summary: Lista los cambios de la malla de contexto de una tarea
      description: |
        Devuelve los deltas de contexto que propuso la tarea, por fecha. El id y el título del nodo (y el nodo
        en que se fusionó) sólo salen si ves ese nodo por su ámbito; si no, van a `null`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:1241
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los deltas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DeltaRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/diff:
    get:
      operationId: taskDiff
      tags:
        - Revisión
      summary: Lee el diff de una tarea
      description: |
        Devuelve el diff guardado de la tarea. Si no hay ninguno (o falla la lectura), responde 200 con un
        diff vacío: `patch` vacío, `files` = `[]`, `commit_sha` y `pr_url` a `null` y `updated_at` con la
        fecha cero (`0001-01-01T00:00:00Z`).

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:811
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El diff (o uno vacío).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Diff"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/tasks/{tid}/diff-comments:
    get:
      operationId: listDiffComments
      tags:
        - Revisión
      summary: Lista los comentarios del diff de una tarea
      description: |
        Devuelve todos los comentarios de línea de esta tarea (de personas y hallazgos del revisor, en
        cualquier estado), ordenados por archivo, línea y fecha. Sólo los de esta tarea, no los de otras
        tareas de su cadena.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:852
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los comentarios.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DiffComment"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createDiffComment
      tags:
        - Revisión
      summary: Comenta una línea del diff
      description: |
        Crea un comentario de línea en el diff de la tarea, con tu usuario como autor y en estado `open`.

        `file_path` y `body` son obligatorios (`body` sin espacios alrededor no puede quedar vacío; si no,
        400 `invalid`). `side` vale `old` o, con cualquier otro valor (o sin él), `new`. `line` no se
        valida.

        Avisa del comentario (`diff_comment.updated`) sólo a quien ve el issue. Hace falta ver el issue de la
        tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:865
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDiffCommentRequest"
      responses:
        "201":
          description: El comentario creado.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DiffComment"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/diff-comments/{cid}:
    patch:
      operationId: patchDiffComment
      tags:
        - Revisión
      summary: Cambia un comentario del diff
      description: |
        Cambia el texto (`body`) o el estado (`status`: `open` o `resolved`; otro valor, 400 `invalid`) de un
        comentario de la tarea. Lo que no mandes no cambia.

        No comprueba que el comentario exista ni quién es su autor: responde 204 aunque no cambie ninguna
        fila. Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:901
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
        - name: cid
          in: path
          required: true
          description: Id del comentario (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchDiffCommentRequest"
      responses:
        "204":
          description: Hecho; sin cuerpo.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
    delete:
      operationId: deleteDiffComment
      tags:
        - Revisión
      summary: Borra un comentario del diff
      description: |
        Borra un comentario de la tarea. No comprueba que exista ni quién es su autor: responde 204 aunque no
        borre nada. Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:929
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
        - name: cid
          in: path
          required: true
          description: Id del comentario (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Hecho; sin cuerpo.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/diff-comments/{cid}/dismiss:
    post:
      operationId: dismissFinding
      tags:
        - Revisión
      summary: Descarta un hallazgo del revisor
      description: |
        Descarta un hallazgo del revisor agéntico (un comentario del diff con `author_type=agent` aún sin
        descartar): lo pasa a `resolved` con quién, cuándo y por qué.

        Hace falta el rol engineer o code owner del proyecto (o, si el proyecto no tiene ninguno, el rol
        mínimo de su política): si no, 403 `role_required`. El motivo se recorta a 1000 caracteres y se
        redactan sus secretos; si queda vacío, 400 `reason_required`. Si no hay un hallazgo del revisor con
        ese id en la tarea (o ya se descartó, o el id no es válido), 404 `not_found`.

        Deja la actividad `review.finding_dismissed`. Hace falta ver el issue de la tarea.
      x-source: internal/api/review.go:345
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
        - name: cid
          in: path
          required: true
          description: Id del hallazgo (comentario del diff). No se valida su forma; si no casa, 404.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DismissReasonRequest"
      responses:
        "200":
          description: Descartado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `role_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/events:
    get:
      operationId: taskEvents
      tags:
        - Tareas
      summary: Lista los eventos de una tarea
      description: |
        Devuelve los eventos de la tarea con `seq` mayor que `after`, en orden de `seq`, hasta 5000.

        Sin `kinds` salen todos menos los de tipo `pty`. Con `kinds` (tipos separados por comas) salen sólo
        esos, `pty` incluido si lo pides.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:546
      x-duda: El contenido de `payload` depende de cada tipo de evento y lo escribe el daemon; este handler sólo lo reenvía.
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
        - name: after
          in: query
          required: false
          description: Devuelve los eventos con `seq` mayor que éste. Si falta o no es un número, 0.
          schema:
            type: integer
            default: 0
        - name: kinds
          in: query
          required: false
          description: Tipos de evento separados por comas. Si falta, todos menos `pty`.
          schema:
            type: string
      responses:
        "200":
          description: Los eventos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TaskEvent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/extend-wall-time:
    post:
      operationId: extendWallTime
      tags:
        - Tareas
      summary: Extiende el tope de tiempo total de una tarea
      description: |
        Abre una ventana nueva del tope de tiempo total: encola una continuación de la tarea (disparador
        `extend`) en la misma rama y el mismo worktree. No lee cuerpo.

        - La tarea tiene que estar `blocked` por `wall_time` (si no, 409 `not_wall_time`).
        - Tienes que poder extenderlo (403 `forbidden`): ver el issue y, con SDLC y jugada, haber lanzado la
          tarea o poder lanzar la jugada.
        - Si el issue está cerrado o la tarea ya tiene continuación (también si otra petición la extendió a la
          vez), 409 `not_extendable`.
        - El encargo: si no llegó a arrancar, el mismo; si no, las respuestas pendientes de huecos y
          preguntas o el aviso de reanudar (con SDLC, detrás del encargo de la jugada). Con etapa SDLC tú
          quedas como `requested_by`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_tras_o2.go:307
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: La continuación encolada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API), `forbidden` o `history_hidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_wall_time`, `not_extendable` o `conflict`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/findings/expected:
    post:
      operationId: markFindingExpected
      tags:
        - Revisión
      summary: Marca un aviso de plan_drift como esperado
      description: |
        Marca (o desmarca, con `expected: false`) un aviso `plan_drift` de la tarea como esperado, para la
        métrica `plan_drift_fp_rate`.

        Hace falta el rol engineer del proyecto o ser admin del workspace (u owner de la organización): si
        no, 403 `forbidden`. Si la tarea no tiene un aviso `plan_drift` con ese id, 404 `not_found`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/sdlc_build.go:538
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MarkFindingExpectedRequest"
      responses:
        "200":
          description: Hecho.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/findings/{fid}/dismiss:
    post:
      operationId: dismissGuardrailFinding
      tags:
        - Revisión
      summary: Descarta un binario sin inspeccionar o cierra un incidente de secreto
      description: |
        Descarta, con motivo, un hallazgo de guardarraíl de la tarea aún no descartado: un binario sin
        inspeccionar (`uninspected_binary`), un cambio de submódulo (`submodule_change`) o un secreto que L4
        encontró en un binario (`secret` en L4, «secreto rotado»).

        Hace falta el rol engineer o code owner del proyecto (o, si el proyecto no tiene ninguno, el rol
        mínimo de su política): si no, 403 `role_required`. El motivo se recorta a 1000 caracteres y se
        redactan sus secretos; si queda vacío, 400 `reason_required`. Si no hay un hallazgo así con ese id,
        404 `not_found`.

        Deja la actividad `guardrail.finding_dismissed` (o `security.secret_rotated` para un secreto). Hace
        falta ver el issue de la tarea.
      x-source: internal/api/review.go:1015
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
        - name: fid
          in: path
          required: true
          description: Id del hallazgo de guardarraíl. No se valida su forma; si no casa, 404.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DismissReasonRequest"
      responses:
        "200":
          description: Descartado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `role_required`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/fix-ci:
    post:
      operationId: fixCITask
      tags:
        - Tareas
      summary: Lanza «Arreglar CI» sobre el PR de una tarea
      description: |
        Sólo sin SDLC. Lee ahora los check runs de la cabeza del PR de la tarea y, si alguno falló, encola una
        continuación (disparador `ci`, receta `fix-ci` del proyecto) con su salida, sus anotaciones y, si se
        pueden leer, sus logs, como contenido no confiable. No lee cuerpo.

        - Con SDLC, 409 `sdlc`. Sin PR abierto, 409 `no_pr`. Con otra tarea en curso en el issue, 409
          `already_running`.
        - Tope de rondas de CI de la cadena (409 `rounds`) y presupuesto de tokens del agente (409 `budget`).
        - El PR tiene que ser del repositorio de GitHub del proyecto (409 `no_pr`).
        - Un error de GitHub, 502 `github_error`. Ningún check fallido, 409 `no_failed_checks`.
        - Si ya se lanzó «Arreglar CI» desde esta tarea, 409 `already_running`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o6.go:699
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: La continuación encolada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                  - failed
                  - logs
                properties:
                  task_id:
                    type: string
                    format: uuid
                  failed:
                    type: integer
                    description: Checks fallidos que van en el encargo.
                  logs:
                    type: boolean
                    description: Si se leyeron logs de algún job.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `history_hidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`sdlc`, `no_pr`, `already_running`, `rounds`, `budget`, `no_failed_checks` o `conflict`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: Error al contactar con GitHub (`github_error`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/permission-requests:
    get:
      operationId: listTaskPermissions
      tags:
        - Preguntas y permisos
      summary: Lista las solicitudes de permiso de una tarea
      description: |
        Devuelve las solicitudes de permiso (modo supervised) de la tarea, de la más reciente a la más
        antigua, hasta 200, con `can_decide` y, si no puedes decidir, `cannot_decide_reason`, calculados
        para ti.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o3.go:1003
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las solicitudes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PermissionRequest"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/pr/sync:
    post:
      operationId: syncTaskPR
      tags:
        - Revisión
      summary: Sincroniza el PR de una tarea
      description: |
        Consulta ya en GitHub el PR de la tarea (y vuelve a revisarlo cada minuto) y aplica lo nuevo a todas
        las tareas que lo comparten. Devuelve la tarea releída, sin los campos que calcula la vista de una
        tarea. No lee cuerpo.

        Sin PR, 409 `no_pr`. Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/github.go:715
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La tarea tras sincronizar.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`no_pr`, `github_not_connected` o `github_token_unreadable`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: GitHub rechazó la operación (`github_unauthorized`, `github_forbidden`, `github_not_found`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Error al contactar con GitHub (`github_error`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/publish:
    post:
      operationId: publishTask
      tags:
        - Revisión
      summary: Publica la rama de una tarea antes de aprobarla
      description: |
        En un issue high o marcado de un proyecto con CI exigido, sube la rama y abre el PR antes de aprobar,
        para que corra el CI. No es una aprobación. El cuerpo es opcional (si no es JSON válido se ignora).

        Reglas (en este orden):
        - Sólo con SDLC activo, CI exigido e issue restringido (409 `publish_not_needed`).
        - Una jugada de código que verifica, `completed`, con rama y runtime (409 `not_code`).
        - Deploy activo o esperando (409 `code_not_ready`); la última tarea de código de la rama (409
          `stale_task`); verificación local en verde con commit (409 `verify_required`); L4 en verde sobre
          ese commit (409 `l4_blocked`); revisión agéntica si se exige (409 `review_required`).
        - Publica quien cubre todo el diff como code owner, el product_owner del proyecto o un admin del
          workspace (403 `publish_forbidden`).
        - Si la rama ya se publicó en ese repo y con esa base, 409 `already_published`.
        - Sin binarios sin inspeccionar ni cambios de submódulo pendientes (409 `binary_uninspected`) y con
          los secretos redactados del diff confirmados (409 `redacted_confirm`).
        - Sin GitHub, 409 `no_github`. Después, el camino único del manifiesto: 409 `publish_unknown`,
          `publish_preparing` (vuelve a intentarlo en unos segundos), `publish_confirm` (con el manifiesto a
          confirmar: repite con su `hash` en `confirm_publish`), `publish_in_progress` o `redacted_confirm`.
        - Runtime desconectado, 409 `runtime_offline`.

        Si todo va bien, envía el empuje al runtime y responde 200 con `pending: true` (el resultado llega
        cuando el runtime lo cuenta). Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/publish.go:1066
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishRequest"
      responses:
        "200":
          description: Empuje enviado al runtime.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - published
                  - pending
                properties:
                  ok:
                    type: boolean
                    const: true
                  published:
                    type: boolean
                    const: false
                  pending:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `publish_forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            Un error de las reglas de arriba (también `github_not_connected` y `github_token_unreadable`).
            `publish_confirm` trae también `manifest`, `hash` y `redacted`.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    required:
                      - error
                      - message
                      - manifest
                      - hash
                      - redacted
                    properties:
                      error:
                        type: string
                        const: publish_confirm
                      message:
                        type: string
                      manifest:
                        $ref: "#/components/schemas/Manifest"
                      hash:
                        type: string
                        description: Hash del manifiesto; mándalo en `confirm_publish` para confirmar.
                      redacted:
                        type: integer
                        description: Secretos redactados en los commits que salen.
        "422":
          description: GitHub rechazó la operación (`github_unauthorized`, `github_forbidden`, `github_not_found`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: Error al contactar con GitHub (`github_error`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/publish/retry:
    post:
      operationId: retryPublish
      tags:
        - Revisión
      summary: Reintenta el empuje de una tarea aprobada
      description: |
        Para una tarea aprobada de un issue high o marcado cuyo empuje no salió. La aprobación se conserva.
        El cuerpo es opcional (si no es JSON válido se ignora).

        - Sólo en issues restringidos (409 `retry_not_needed`); la tarea tiene que estar aprobada, con rama y
          runtime (409 `not_approved`); si su empuje ya salió, 409 `already_published`.
        - Con etapa SDLC, reintenta quien puede publicar: quien cubre todo el diff como code owner, el
          product_owner o un admin (403 `publish_forbidden`). Sin SDLC, quien ve la tarea.
        - Sin `confirm_publish`, usa el último hash confirmado de la aprobación (y da por confirmados sus
          secretos redactados). Se recalcula el manifiesto: si coincide, sale sin preguntar; si cambió, 409
          `publish_confirm` con el nuevo. Otros 409 del manifiesto: `publish_unknown` (también sin GitHub App),
          `publish_preparing`, `publish_in_progress`, `redacted_confirm`.
        - Runtime desconectado, 409 `runtime_offline`.

        Deja la actividad `github.publish_retry`. Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/publish.go:1179
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishRequest"
      responses:
        "200":
          description: Empuje enviado al runtime.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - pending
                properties:
                  ok:
                    type: boolean
                    const: true
                  pending:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `publish_forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            Un error de las reglas de arriba (también `github_not_connected` y `github_token_unreadable`).
            `publish_confirm` trae también `manifest`, `hash` y `redacted`.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    required:
                      - error
                      - message
                      - manifest
                      - hash
                      - redacted
                    properties:
                      error:
                        type: string
                        const: publish_confirm
                      message:
                        type: string
                      manifest:
                        $ref: "#/components/schemas/Manifest"
                      hash:
                        type: string
                        description: Hash del manifiesto; mándalo en `confirm_publish` para confirmar.
                      redacted:
                        type: integer
                        description: Secretos redactados en los commits que salen.
        "422":
          description: GitHub rechazó la operación (`github_unauthorized`, `github_forbidden`, `github_not_found`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          description: Error al contactar con GitHub (`github_error`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/questions:
    get:
      operationId: listTaskQuestions
      tags:
        - Preguntas y permisos
      summary: Lista las preguntas de una tarea y de su cadena
      description: |
        Devuelve las preguntas estructuradas de la tarea y de las tareas que continúa o reintenta (toda la
        cadena, dentro del issue), por fecha, hasta 200. En las abiertas rellena `can_answer` (y, si no
        puedes, `cannot_answer_reason`) y `can_add_answerers` (si eres mantenedor del proyecto).

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o2.go:600
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Las preguntas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TaskQuestion"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/resolve-conflicts:
    post:
      operationId: resolveConflictsTask
      tags:
        - Tareas
      summary: Lanza «Resolver conflictos» sobre el PR de una tarea
      description: |
        Sólo sin SDLC. Encola una continuación (disparador `conflicts`, jugada `resolve-conflicts`, receta del
        proyecto) que integra la base en la rama del PR. No lee cuerpo.

        - Con SDLC, 409 `sdlc`. Sin PR abierto, 409 `no_pr`. Con otra tarea en curso en el issue, 409
          `already_running`.
        - Si el PR no tiene conflictos con la base, 409 `no_conflicts`.
        - Si ya se lanzó la resolución desde esta tarea, 409 `already_running`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o6.go:512
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: La continuación encolada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `history_hidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`sdlc`, `no_pr`, `already_running`, `no_conflicts` o `conflict`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/retry:
    post:
      operationId: retryTask
      tags:
        - Tareas
      summary: Reintenta una tarea
      description: |
        Encola una tarea nueva con el mismo encargo, el mismo agente y la misma cadena (`continues`,
        `fanout_group_id`). Reintentar es relanzar: valen las reglas de lanzar. No lee cuerpo.

        Reglas (en este orden):
        - La tarea no puede estar en `queued`, `claimed` ni `running` (409 `running`).
        - Tienes que ver su issue (403 `history_hidden`; 404 `not_found` si falla la lectura del issue).
        - Sin etapa SDLC en un issue que ya está en SDLC: 409 `sdlc` (va por la «Siguiente jugada»).
        - Con etapa: tienes que poder lanzar la jugada (403 `forbidden`, con el motivo). La jugada se repite
          sobre la rama del issue, desde el worktree del intento fallido, con `retry_of` apuntando a él y tú
          como `requested_by`.
        - Si es una continuación de «Arreglar CI» o «Resolver conflictos» sin SDLC, se repite en la misma
          rama con su jugada y su disparador; 409 `already_running` si hay otra tarea en curso en el issue
          y, en «Arreglar CI», 409 `rounds` (tope de rondas) o `budget` (presupuesto de tokens del agente).

        Al encolar, quien encola y la persona responsable tienen que ver el issue (403 `history_hidden`).
      x-source: internal/api/tasks.go:645
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: La tarea nueva.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API), `history_hidden` o `forbidden` (no puedes lanzar la jugada)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`running`, `sdlc`, `already_running`, `rounds`, `budget` o `conflict`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/review:
    post:
      operationId: sendReview
      tags:
        - Revisión
      summary: Envía la revisión al agente
      description: |
        Junta los comentarios abiertos del diff de la tarea (los de personas y los hallazgos del revisor, con
        su severidad y pase) y el resumen opcional, y se los manda al mismo agente como continuación en la
        misma rama y el mismo worktree (disparador `review`).

        El cuerpo es opcional: si no es JSON válido se ignora. Sin comentarios abiertos y sin resumen, 400
        `empty_review`. Sin worktree, 409 `no_worktree`. Si quien encola o la persona responsable no ven el
        issue, 403 `history_hidden`.

        Después marca los comentarios como `sent`, pasa el issue a `in_progress` y deja en el issue un
        comentario con las notas enviadas. Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/tasks.go:947
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendReviewRequest"
      responses:
        "201":
          description: La continuación encolada.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                properties:
                  task_id:
                    type: string
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`history_hidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`no_worktree`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Error interno. Sale con el campo `error` vacío (ver el informe de rarezas).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/tasks/{tid}/session:
    get:
      operationId: getTaskSession
      tags:
        - Tareas
      summary: Lee el estado de la sesión de una tarea
      description: |
        Devuelve el estado de la sesión del agente, sin su `session_id` (la llave del transcript en la máquina
        del dueño). `status`, `resumed` y `last_turn_at` sólo salen si la sesión existe; `context`, sólo si el
        daemon informó métricas de contexto en vivo.

        `can_wake`: la sesión está hibernada y la lanzaste tú o eres el dueño del runtime. `can_steer`: puedes
        conducirla (ver `POST /tasks/{tid}/steer`). `live`: la tarea corre con la conducción activa.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o5.go:957
      x-duda: La forma de `context` (columna `live_metrics`) la decide el daemon; este handler la reenvía tal cual.
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El estado de la sesión.
          content:
            application/json:
              schema:
                type: object
                required:
                  - task_id
                  - exists
                  - hibernated
                  - can_wake
                  - can_steer
                  - live
                properties:
                  task_id:
                    type: string
                    format: uuid
                  exists:
                    type: boolean
                  hibernated:
                    type: boolean
                    description: La tarea espera en `hibernated`.
                  status:
                    type: string
                    description: active, resumable, closed o purged. Sólo si existe.
                  resumed:
                    type: boolean
                    description: La sesión reanuda la de otra tarea. Sólo si existe.
                  last_turn_at:
                    type: string
                    format: date-time
                    description: Sólo si existe.
                  can_wake:
                    type: boolean
                  can_steer:
                    type: boolean
                  live:
                    type: boolean
                  context:
                    description: Métricas de contexto en vivo que informó el daemon (JSON tal cual). Sólo si hay.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/tasks/{tid}/steer:
    post:
      operationId: steerTask
      tags:
        - Tareas
      summary: Conduce una tarea en vivo
      description: |
        Manda un mensaje al agente mientras trabaja (conducción en vivo).

        - Conducen el asignado humano del issue, quien lanzó la tarea y los miembros con rol de escritura del
          proyecto (product_owner, engineer, code_owner, context_owner); si el proyecto no tiene roles, el
          rol mínimo de su política. Nunca un admin por serlo. Hace falta ver el issue. Si no, 403 `forbidden`
          (antes de leer el cuerpo).
        - Cuerpo de hasta 64 KiB (si no, 400 `bad_json`); `message` de hasta 4096 bytes (400 `too_large`).
        - Se quitan los caracteres invisibles. Si lleva un secreto, 400 `secret`. Si queda vacío, 400 `empty`.
        - La tarea tiene que estar `running`, con la conducción activa y sin espera larga (como mucho
          esperando un permiso), y no ser una revisión ni una verificación (409 `not_live`).
        - Un mensaje cada 5 segundos por tarea, sea conducción o mención (429 `rate_limited`).

        Guarda el mensaje, te deja como «dirigida por», lo audita sin el texto, con SDLC lo deja como
        comentario del issue y avisa al runtime de la tarea (el texto lo pide el daemon).
      x-source: internal/api/ops_o5.go:760
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SteerRequest"
      responses:
        "202":
          description: Mensaje guardado y aviso enviado al runtime.
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Id del mensaje de conducción.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_live`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Un mensaje cada 5 s por tarea (`rate_limited`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/steers:
    get:
      operationId: getTaskSteers
      tags:
        - Tareas
      summary: Lista los mensajes de conducción de una tarea
      description: |
        Devuelve los mensajes de conducción de la tarea (ya redactados) y las menciones entregadas en vivo, por
        fecha, hasta 200. Si la lectura falla, devuelve una lista vacía.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o5.go:1001
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Los mensajes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TaskSteer"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/tasks/{tid}/subagents:
    get:
      operationId: getTaskSubagents
      tags:
        - Tareas
      summary: Lee el árbol de subagentes de una tarea
      description: |
        Devuelve el último árbol de subagentes que informó el daemon (el último evento `subagents` de la
        tarea). Si no hay ninguno, `branches` es una lista vacía.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/ops_o5.go:982
      x-duda: La forma de cada rama la decide el daemon; el handler sólo reenvía la lista `branches` del evento.
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: El árbol de subagentes.
          content:
            application/json:
              schema:
                type: object
                required:
                  - branches
                properties:
                  branches:
                    type: array
                    items:
                      type: object
                      description: Una rama del árbol, tal como la informó el daemon.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/w/{ws}/tasks/{tid}/verification:
    get:
      operationId: taskVerification
      tags:
        - Revisión
      summary: Lee la verificación y los hallazgos de una tarea
      description: |
        Devuelve el estado de verificación de la tarea, cada ejecución de la verificación (comando,
        pre-commit o verifier) y los hallazgos de los guardarraíles (L1–L4), los dos por id.

        `can_grant` es `true` si la tarea está en `pending_verification`, todavía no tiene continuación y eres
        el dueño de su runtime. `continued_by` es la última tarea que la continúa, si hay.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/sdlc_build.go:503
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: La verificación.
          content:
            application/json:
              schema:
                type: object
                required:
                  - verify_status
                  - error_class
                  - rounds
                  - verifications
                  - findings
                  - runtime_name
                  - project_id
                  - can_grant
                  - continued_by
                properties:
                  verify_status:
                    type:
                      - string
                      - "null"
                    description: passed, failed, unconfigured, not_permitted, reproduced o not_reproduced.
                  error_class:
                    type:
                      - string
                      - "null"
                    description: guardrail, verify, verifier, agent, timeout, budget o infra.
                  rounds:
                    type: integer
                  verifications:
                    type: array
                    items:
                      $ref: "#/components/schemas/VerificationRow"
                  findings:
                    type: array
                    items:
                      $ref: "#/components/schemas/FindingRow"
                  runtime_name:
                    type:
                      - string
                      - "null"
                  project_id:
                    type:
                      - string
                      - "null"
                    format: uuid
                  can_grant:
                    type: boolean
                  continued_by:
                    type:
                      - string
                      - "null"
                    format: uuid
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/tasks/{tid}/verifier/dismiss:
    post:
      operationId: dismissVerifier
      tags:
        - Revisión
      summary: Descarta el veredicto del verifier
      description: |
        Con `verifier: required`, un fallo del verifier bloquea Test hasta que una persona lo descarta. Esto
        pasa la verificación de la tarea a `passed` y borra su `error_class`; queda la actividad
        `verify.verifier_dismissed` con el motivo (recortado a 1000 caracteres).

        Hace falta el rol engineer del proyecto o ser admin del workspace (u owner de la organización): si
        no, 403 `forbidden`. La tarea tiene que estar `completed` con `verify_status=failed` y
        `error_class=verifier` (si no, 409 `nothing_to_dismiss`). Sin motivo, 400 `reason_required`.

        Hace falta ver el issue de la tarea (si no, 404 `not_found`).
      x-source: internal/api/sdlc_build.go:438
      x-duda: El handler ignora el resultado de `decode`; con un cuerpo que no es JSON válido escribe 400 `bad_json` y sigue
        adelante, así que la respuesta real queda indefinida (ver el informe de bugs).
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: tid
          in: path
          required: true
          description: Id de la tarea (si no es un UUID, 400 `invalid_id`).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DismissReasonRequest"
      responses:
        "200":
          description: Descartado.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` (con un token de API) o `forbidden`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`nothing_to_dismiss`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/teardown-notices/{nid}/dismiss:
    post:
      operationId: dismissTeardownNotice
      tags:
        - Runtimes
      summary: Descarta un aviso de teardown
      description: |
        Sólo el dueño del runtime del aviso, con la sesión del navegador. Marca como revisado el aviso de lo que quedó
        vivo al saltarse un teardown (worktree, puerto, procesos); no se borra: queda quién y cuándo. Queda en la
        actividad (`worktree.teardown_dismissed`) y avisa a tu bandeja (`inbox.resolved`).
      x-source: internal/api/ops_o1.go:930
      security:
        - session: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: nid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Descartado.
        "400":
          description: "`invalid_id`: `nid` no es un UUID."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`session_required` o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (el aviso no existe, no es de un runtime tuyo o ya estaba descartado) o `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/w/{ws}/terminals:
    get:
      operationId: listTerminals
      tags:
        - Terminales
      summary: Lista las sesiones de terminal del workspace
      description: |
        Devuelve las sesiones de terminal abiertas en memoria del servidor para el workspace: las shells sólo de los
        runtimes de los que eres dueño, y las de agente sólo de las tareas cuyo issue ves (las de agente sin tarea
        salen siempre). La salida de cada terminal va por WebSocket (`/api/ws`).
      x-source: internal/api/tasks.go:1299
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      responses:
        "200":
          description: Las sesiones.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SessionInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: openTerminal
      tags:
        - Terminales
      summary: Abre una terminal en un runtime
      description: |
        Pide al daemon que abra una shell en su máquina, en el worktree de una tarea (`task_id`) o en la carpeta de
        trabajo (`runtime_id`). Sólo el dueño del runtime puede abrirla.

        Con un `task_id` válido, el runtime es el de la tarea (manda sobre `runtime_id`). Si ves el issue de la tarea,
        el título es `<clave del issue> · <rama>`; si no lo ves pero eres el dueño de su runtime, se abre con un título
        genérico; si no, la tarea no existe para ti (404). `command` sólo admite atajos conocidos, que la terminal
        escribe al abrirse: `harness-install:<id>`, `harness-upgrade:<id>`, `harness-login:<id>` (con `<id>` un CLI del
        catálogo, no `custom`, que se pueda instalar o iniciar sesión) y `claude-login` (igual a
        `harness-login:claude-code`). `cols` y `rows` se reenvían tal cual. Difunde `term.sessions` y queda en la
        actividad (`runtime.terminal_opened`, con el atajo).
      x-source: internal/api/tasks.go:1322
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OpenTerminalRequest"
      responses:
        "201":
          description: Terminal abierta.
          content:
            application/json:
              schema:
                type: object
                required:
                  - session_id
                  - title
                properties:
                  session_id:
                    type: string
                    format: uuid
                    description: Id de la sesión; su entrada y su salida van por WebSocket (`/api/ws`).
                  title:
                    type: string
        "400":
          description: "`bad_json` o `invalid` (atajo desconocido, o falta un `runtime_id` válido)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "`not_owner` (no eres el dueño del runtime) o `token_scope`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "`not_found` (la tarea no existe para ti o no tiene runtime, o el runtime no es del workspace) o
            `workspace_not_found`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "`runtime_offline`: el daemon no está conectado."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Internal"
  /api/w/{ws}/usage:
    get:
      operationId: usage
      tags:
        - Uso
      summary: Devuelve el uso de agentes por día
      description: |
        Agrupa por día (truncado al día) y por agente las tareas del workspace creadas en los últimos `days` días:
        cuántas, cuántas completadas y fallidas, tokens de entrada y salida, coste en dólares y la utilización media
        del contexto de sus paquetes. Ordenado por día y por nombre del agente.
      x-source: internal/api/tasks.go:1276
      x-duda: |
        No filtra por la audiencia del issue (a diferencia de las demás lecturas de tareas): cuenta también las
        tareas de issues que quien pide no ve. No consta en el código si es intencionado por ser un agregado.
      security:
        - session: []
        - apiToken: []
      parameters:
        - $ref: "#/components/parameters/ws"
        - name: days
          in: query
          required: false
          description: Días hacia atrás. Un valor que no es un entero, o fuera de 1…365, se toma como 30.
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
      responses:
        "200":
          description: Una fila por día y agente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UsageRow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/Internal"
  /api/workspaces:
    get:
      operationId: listWorkspaces
      tags:
        - Workspaces y miembros
      summary: Lista tus workspaces
      description: |
        Los workspaces de los que eres miembro, por fecha de creación, con tu rol en cada uno. También vale con un
        token de alcance `runtime`.
      x-source: internal/api/identity.go:438
      security:
        - session: []
        - apiToken: []
      responses:
        "200":
          description: Tus workspaces.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/Internal"
    post:
      operationId: createWorkspace
      tags:
        - Workspaces y miembros
      summary: Crea un workspace
      description: |
        Crea un workspace y te deja como su owner.
        - `name` es obligatorio (se recortan los espacios; 400 `name_required`).
        - `slug`: el que envíes o, si no, el del nombre; siempre se normaliza (minúsculas, á é í ó ú ñ ü sin
          tilde, cualquier otro carácter fuera de `a-z0-9` pasa a guion, sin guiones en los extremos, 48 caracteres
          como mucho; si queda vacío, `item`). Si ya existe: 409 `conflict`.
        - `issue_prefix`: se guarda en mayúsculas; si no viene, las 4 primeras letras del slug sin guiones. No se
          valida su longitud.
        - `locale`: el que envíes o, si no, el tuyo, normalizado a `es` o `en`.

        En la misma transacción crea la organización del workspace (contigo como owner), tres nodos de contexto
        iniciales (principios de ingeniería, convención de pruebas y de commits, en el idioma del workspace) y las
        plantillas del SDLC como skills editables.
      x-source: internal/api/identity.go:451
      security:
        - session: []
        - apiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceRequest"
      responses:
        "201":
          description: El workspace creado, con tu rol (`owner`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "400":
          description: "`bad_json`, `name_required` o `invalid`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/Internal"
  /api/ws:
    get:
      operationId: browserWS
      tags:
        - Tiempo real
      summary: Abre el WebSocket del navegador
      description: |
        Abre el canal en vivo del navegador para un workspace. Por él llegan los eventos del workspace (sólo los
        que te tocan por tu audiencia) y viajan las terminales en vivo; los mensajes están en `api/parts/websocket.md`.

        Autenticación: el handler valida él mismo el token, fuera del middleware `requireUser`. Vale la sesión del
        navegador (JWT) o un token personal `hqf_`, en la cabecera `Authorization: Bearer …` o, como el navegador no
        puede poner cabeceras en un WebSocket, en el parámetro `token` de la URL (SEC-23; sólo las rutas que acaban
        en `/ws` lo leen). Si llegan los dos, gana la cabecera. Aquí no se mira el alcance del token.

        Después hay que ser miembro del workspace del parámetro `workspace` (si no, o si falta, 404). Por último se
        comprueba la cabecera `Origin`: sin ella, o con el mismo host que la petición, pasa; si no, tiene que casar
        con el host de alguno de `FRONTEND_ORIGINS` (fuera de producción, también `localhost:*` y `127.0.0.1:*`).

        Lo que lees del cliente tiene un tope de 1 MiB por mensaje. El servidor manda un ping de WebSocket cada
        25 s y cierra con el código 1008 («slow consumer») a quien acumula 512 mensajes sin leer.
      x-source: internal/api/daemon.go:1814
      security:
        - session: []
        - apiToken: []
      parameters:
        - name: workspace
          in: query
          required: true
          description: Slug del workspace cuyos eventos quieres recibir. Hay que ser miembro (si no, o si falta, 404
            `workspace_not_found`).
          schema:
            type: string
        - name: token
          in: query
          required: false
          description: |
            La sesión (JWT) o el token `hqf_`, como alternativa a la cabecera `Authorization: Bearer`. Si hay
            cabecera con `Bearer `, este parámetro no se lee.
          schema:
            type: string
      responses:
        "101":
          description: Cambio a WebSocket. El servidor manda primero `{"type":"hello"}`.
        "400":
          description: |
            Handshake de WebSocket inválido (versión distinta de 13, `Sec-WebSocket-Key` ausente, repetida o
            inválida). Lo responde la biblioteca `coder/websocket` en texto plano, no en JSON.
          content:
            text/plain:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: |
            La cabecera `Origin` no está autorizada. Lo responde la biblioteca `coder/websocket` en texto plano
            (`request Origin "…" is not authorized for Host "…"`), no en JSON.
          content:
            text/plain:
              schema:
                type: string
        "404":
          $ref: "#/components/responses/NotFound"
        "426":
          description: |
            La petición no pide el cambio de protocolo (falta `Connection: Upgrade` o `Upgrade: websocket`, o no es
            HTTP/1.1 o superior). Lo responde la biblioteca `coder/websocket` en texto plano, no en JSON.
          content:
            text/plain:
              schema:
                type: string
  /healthz:
    get:
      operationId: healthz
      tags:
        - Sistema
      summary: Comprueba que el servidor responde
      description: |
        Comprueba el servidor y hace un ping a la base de datos con un tope de 2 segundos. Responde siempre 200
        con `status: ok`; si el ping falla, `checks.db` vale `error` (el código HTTP no cambia).
      x-source: internal/api/server.go:979
      security: []
      responses:
        "200":
          description: El servidor responde; `checks.db` dice si la base de datos contestó al ping.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - checks
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                  checks:
                    type: object
                    required:
                      - db
                    properties:
                      db:
                        type: string
                        enum:
                          - ok
                          - error
components:
  securitySchemes:
    session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Sesión del navegador: el JWT que devuelve `POST /api/auth/verify`. Algunas rutas sólo la aceptan a ella
        (middleware `requireSession`); un token de API recibe 403 `session_required`.
    apiToken:
      type: http
      scheme: bearer
      description: |
        Token personal de API (prefijo `hqf_`), creado con `POST /api/tokens`. Con alcance `api` llega a las rutas
        de usuario salvo las que exigen sesión; con alcance `runtime` sólo a `GET /api/me`, `GET /api/workspaces` y
        `POST /api/w/{ws}/runtimes/register` (si no, 403 `token_scope`).
    runtimeToken:
      type: http
      scheme: bearer
      description: Token del runtime (prefijo `hqfrt_`), que usa el daemon `hqf` en las rutas `/api/daemon/*`.
    taskToken:
      type: http
      scheme: bearer
      description: |
        Token de la tarea en curso (prefijo `hqftk_`), que usa el agente con `hqf agent …`. Sólo sirve para
        `/api/daemon/tasks/{tid}/(comment|block|remember|issue|ask|status|checkpoint|questions|subtask)` de su tarea.
  schemas:
    Activity:
      type: object
      description: Un evento del feed unificado de personas y agentes (`Activity`).
      required:
        - id
        - actor_type
        - kind
        - payload
        - created_at
      properties:
        id:
          type: string
          format: uuid
        issue_id:
          type:
            - string
            - "null"
          format: uuid
        issue_key:
          type:
            - string
            - "null"
        issue_title:
          type:
            - string
            - "null"
        actor_type:
          type: string
          enum:
            - user
            - agent
            - system
        actor_id:
          type:
            - string
            - "null"
          format: uuid
        actor_name:
          type:
            - string
            - "null"
          description: Nombre del usuario o del agente; `HQ Fabric` si es el sistema.
        actor_color:
          type:
            - string
            - "null"
          description: Color del agente (sólo agentes).
        kind:
          type: string
          description: Tipo de evento (p. ej. `issue.created`, `task.queued`, `artifact.approved`).
        payload:
          description: JSON con los datos del evento; su forma depende de `kind`.
        created_at:
          type: string
          format: date-time
    AddAnswererRequest:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          format: uuid
    AddMemberRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          description: Correo de la persona (se normaliza; tiene que llevar `@`).
        role:
          type: string
          enum:
            - owner
            - admin
            - member
          description: Por defecto `member`; no puede ser superior al tuyo.
    Agent:
      type: object
      description: Un agente del workspace (tipo Go `Agent`).
      required:
        - id
        - slug
        - name
        - provider
        - model
        - instructions
        - concurrency
        - color
        - triggers
        - enabled
        - context_budget_tokens
        - context_target_util
        - max_sensitivity
        - run_mode
        - autonomy
        - extra_args
        - command_template
        - max_task_tokens
        - created_at
        - skill_ids
        - running
        - tasks_total
        - cost_usd
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        provider:
          type: string
          description: Id del CLI del agente (ver `providers` en `GET /agents`).
        model:
          type: string
        instructions:
          type: string
          description: Instrucciones (prompt de sistema) del agente.
        runtime_id:
          type:
            - string
            - "null"
          format: uuid
          description: Runtime fijo del agente; `null` = cualquier runtime con su proveedor.
        concurrency:
          type: integer
        color:
          type: string
        triggers:
          description: |
            JSON con los disparadores del agente (`json.RawMessage`); por defecto
            `{"on_assign":true,"on_mention":true,"on_comment":false}`. El servidor no valida su forma.
        enabled:
          type: boolean
        context_budget_tokens:
          type: integer
        context_target_util:
          type: number
        max_sensitivity:
          type: string
          description: "`low`, `moderate` o `high`."
        run_mode:
          type: string
          description: "`headless` o `interactive`."
        autonomy:
          type: string
          description: "`full`, `safe` o `supervised`."
        extra_args:
          type: array
          items:
            type: string
        command_template:
          type: string
          description: Comando del proveedor `custom`.
        max_task_tokens:
          type: integer
          format: int64
          description: Tope de tokens por tarea; 0 = sin tope.
        quota_hold_threshold:
          type:
            - number
            - "null"
          description: Umbral de cuota propio; `null` = el del workspace.
        skills_mode:
          type:
            - string
            - "null"
          description: "`inline`, `served` o `null` (por defecto: servida con SDLC, en el prompt sin él)."
        created_at:
          type: string
          format: date-time
        skill_ids:
          type: array
          items:
            type: string
            format: uuid
        running:
          type: integer
          description: Tareas del agente en `claimed` o `running`.
        tasks_total:
          type: integer
          description: Total de tareas del agente.
        cost_usd:
          type: number
          description: Coste acumulado de sus tareas, en USD.
    AgentInput:
      type: object
      description: Cuerpo para crear o cambiar un agente (tipo Go `agentIn`). Todos los campos son opcionales salvo lo que
        diga cada ruta.
      properties:
        name:
          type: string
        slug:
          type: string
          description: Se normaliza (minúsculas, guiones, 48 caracteres). Sólo al crear; al cambiar se ignora.
        provider:
          type: string
          enum:
            - claude-code
            - codex
            - cursor
            - gemini
            - copilot
            - opencode
            - qwen
            - kimi
            - amp
            - goose
            - custom
        model:
          type: string
        instructions:
          type: string
        runtime_id:
          type:
            - string
            - "null"
          description: UUID de un runtime; `""` o `null` lo quitan.
        concurrency:
          type: integer
          minimum: 1
          maximum: 32
        color:
          type: string
        triggers:
          description: JSON con los disparadores (`json.RawMessage`); se guarda tal cual.
        enabled:
          type: boolean
        context_budget_tokens:
          type: integer
          minimum: 1000
          maximum: 400000
        context_target_util:
          type: number
          exclusiveMinimum: 0.1
          maximum: 1
        max_sensitivity:
          type: string
          enum:
            - low
            - moderate
            - high
        run_mode:
          type: string
          enum:
            - headless
            - interactive
        autonomy:
          type: string
          enum:
            - full
            - safe
            - supervised
        extra_args:
          type: array
          maxItems: 16
          description: Flags permitidas para el proveedor, cada una con su valor (`--flag valor` o `--flag=valor`).
          items:
            type: string
        command_template:
          type: string
        skill_ids:
          type: array
          items:
            type: string
            format: uuid
        max_task_tokens:
          type: integer
          format: int64
          minimum: 0
          maximum: 100000000
          description: 0 = sin tope.
        quota_hold_threshold:
          type: number
          description: 0 vuelve al umbral del workspace; si no, de 0,5 a 1.
        skills_mode:
          type: string
          enum:
            - inline
            - served
            - ""
          description: '`""` vuelve al valor por defecto.'
    AllowRule:
      type: object
      required:
        - argv
      properties:
        argv:
          type: array
          items:
            type: string
        vars:
          type: array
          items:
            type: string
        opts:
          type: array
          description: Las opciones que se dejan pasar detrás del prefijo.
          items:
            type: string
    AnswerQuestionRequest:
      type: object
      properties:
        option:
          type:
            - string
            - "null"
          description: Con opciones, la elegida.
        answer:
          type:
            - string
            - "null"
          description: Sin opciones, la respuesta (hasta 8000 caracteres).
    AppView:
      type: object
      description: El estado de la GitHub App del workspace.
      required:
        - app
        - installations
        - can_manage
        - webhooks_available
        - ci_logs
      properties:
        app:
          description: La App, o `null` si el workspace no tiene.
          oneOf:
            - type: "null"
            - type: object
              required:
                - app_id
                - slug
                - name
                - html_url
                - owner_login
                - install_url
                - webhook
              properties:
                app_id:
                  type: integer
                  format: int64
                slug:
                  type: string
                name:
                  type: string
                html_url:
                  type: string
                owner_login:
                  type: string
                install_url:
                  type: string
                  description: "`<github>/apps/<slug>/installations/new`."
                webhook:
                  type: object
                  required:
                    - active
                    - url
                  properties:
                    active:
                      type: boolean
                    url:
                      type:
                        - string
                        - "null"
                      description: "`<PUBLIC_API_URL>/api/github/webhooks/<id del workspace>` si está activo y hay PUBLIC_API_URL."
        installations:
          type: array
          description: Las instalaciones de la App, por cuenta.
          items:
            type: object
            required:
              - id
              - account_login
              - account_type
              - repository_selection
              - repos
              - suspended
              - budget
            properties:
              id:
                type: integer
                format: int64
              account_login:
                type: string
              account_type:
                type: string
              repository_selection:
                type: string
                description: "`all` o `selected`, como lo dice GitHub."
              repos:
                type: array
                items:
                  type: string
                description: Los repos (`owner/name`) de la instalación.
              suspended:
                type: boolean
              budget:
                oneOf:
                  - type: "null"
                  - $ref: "#/components/schemas/BudgetView"
        can_manage:
          type: boolean
          description: Si eres admin u owner del workspace.
        public_url:
          type:
            - string
            - "null"
          description: PUBLIC_API_URL, o `null` si no está definida.
        webhooks_available:
          type: boolean
          description: Si GitHub puede mandar webhooks (PUBLIC_API_URL definida y que no es localhost).
        app_error:
          type: string
          enum:
            - unreadable
          description: Sólo si la App existe pero sus secretos no se descifran.
        ci_logs:
          type: string
          enum:
            - available
            - missing_actions_read
            - pat
            - none
          description: |
            Si HQ Fabric puede leer los logs de CI: `available` (todas las instalaciones activas tienen
            actions:read), `missing_actions_read`, `pat` (sin instalaciones activas, con el token del workspace) o
            `none`.
    ApprovalDelegation:
      type: object
      description: Una delegación de las aprobaciones de comandos en el host de un runtime (tipo Go `ApprovalDelegation`).
      required:
        - id
        - project_id
        - project_name
        - delegate_user_id
        - delegate_name
        - granted_at
        - expires_at
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        delegate_user_id:
          type: string
          format: uuid
        delegate_name:
          type: string
        granted_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        revoked_at:
          type:
            - string
            - "null"
          format: date-time
    ApprovalsInbox:
      type: object
      description: La bandeja de aprobaciones de quien pide (mapa literal de `approvalsInbox`).
      required:
        - artifacts
        - concerns
        - gaps
        - code
        - no_four_eyes
        - no_four_eyes_30d
        - merged_outside
        - merged_outside_30d
        - local_only_approvals_30d
        - secret_incidents
        - teardown_pending
        - quota_notices
        - conflicts
        - publish_incidents
        - questions
        - waiting_input
        - wall_time
        - permissions
        - total
      properties:
        artifacts:
          type: array
          description: Artefactos en revisión que puedes aprobar (sin `content`).
          items:
            $ref: "#/components/schemas/ArtifactRow"
        concerns:
          type: array
          description: Preocupaciones abiertas que puedes resolver.
          items:
            type: object
            required:
              - artifact_id
              - issue_key
              - issue_number
              - issue_title
              - concern
              - role
            properties:
              artifact_id:
                type: string
                format: uuid
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
              concern:
                $ref: "#/components/schemas/Concern"
              role:
                type: string
        gaps:
          type: array
          items:
            $ref: "#/components/schemas/GapRow"
        code:
          type: array
          description: Issues con Deploy esperando la aprobación del código (hasta 100).
          items:
            type: object
            properties:
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
              task_id:
                type: string
                format: uuid
              commit:
                type: string
              can_approve:
                type: boolean
              needs_confirm:
                type: boolean
              missing:
                type: integer
                description: Archivos sin cubrir.
              important_open:
                type: integer
              reviewed:
                type: boolean
              local_only:
                type: boolean
              uninspected:
                type: integer
        no_four_eyes:
          type: array
          description: Aprobaciones de código sin cuatro ojos de los últimos 30 días (hasta 50).
          items:
            type: object
            properties:
              approver:
                type: string
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
              task_id:
                type: string
                format: uuid
              role:
                type: string
              at:
                type: string
                format: date-time
        no_four_eyes_30d:
          type: integer
        merged_outside:
          type: array
          description: PRs integrados en GitHub sin la aprobación de HQ Fabric (30 días, hasta 50).
          items:
            type: object
            properties:
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
              sha:
                type: string
                description: SHA corto.
              at:
                type: string
                format: date-time
        merged_outside_30d:
          type: integer
          description: Longitud de `merged_outside` (como mucho 50).
        local_only_approvals_30d:
          type: integer
        secret_incidents:
          type: array
          items:
            type: object
            properties:
              finding_id:
                type: string
                format: uuid
              task_id:
                type: string
                format: uuid
              path:
                type: string
              message:
                type: string
              at:
                type: string
                format: date-time
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
        teardown_pending:
          type: array
          description: Avisos de teardown sin descartar de tus runtimes. La tarea y el issue van vacíos si no ves el issue.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              runtime_id:
                type: string
                format: uuid
              runtime_name:
                type: string
              project_name:
                type: string
              worktree:
                type: string
              port:
                type: integer
              processes:
                description: "JSON: los procesos vivos, `[{pid, cmd}]`."
              at:
                type: string
                format: date-time
              task_id:
                type: string
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
        quota_notices:
          type: array
          description: Avisos de cuota sin descartar de tus runtimes. La tarea y el issue van vacíos si no ves el issue.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              runtime_id:
                type: string
                format: uuid
              runtime_name:
                type: string
              provider:
                type: string
              reason:
                type: string
              at:
                type: string
                format: date-time
              task_id:
                type: string
              issue_key:
                type: string
              issue_number:
                type: integer
        conflicts:
          type: array
          items:
            $ref: "#/components/schemas/ConflictNotice"
        publish_incidents:
          type: array
          items:
            $ref: "#/components/schemas/PublishIncident"
        questions:
          type: array
          items:
            $ref: "#/components/schemas/TaskQuestion"
        waiting_input:
          type: array
          description: Sesiones interactivas que lanzaste y esperan tu entrada.
          items:
            type: object
            properties:
              task_id:
                type: string
                format: uuid
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
              wait_since:
                type:
                  - string
                  - "null"
                format: date-time
              signal:
                type: string
                const: agent
        wall_time:
          type: array
          description: Tareas paradas por el tope de tiempo total, sin continuación.
          items:
            type: object
            properties:
              task_id:
                type: string
                format: uuid
              issue_key:
                type: string
              issue_number:
                type: integer
              issue_title:
                type: string
              limit_hours:
                type: integer
              started:
                type: boolean
              can_extend:
                type: boolean
              at:
                type:
                  - string
                  - "null"
                format: date-time
              quota_resets_at:
                type: string
                format: date-time
                description: Sólo si esperaba el reinicio de la cuota.
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/PermissionRequest"
        total:
          type: integer
    ApproveIn:
      type: object
      properties:
        merge:
          type: boolean
          description: Integrar la rama (o subirla y abrir el PR) también de aprobar.
        confirm_no_four_eyes:
          type: boolean
          description: Confirmas que apruebas sin cuatro ojos (eres la única persona elegible).
        confirm_redacted:
          type: boolean
          description: Confirmas que el commit conserva secretos que en pantalla salen redactados.
        confirm_publish:
          type: string
          description: En un issue high o marcado, el hash del manifiesto que viste (`hash` de `publish_confirm`).
    ArtifactConcern:
      description: Una preocupación con lo que puede hacer quien pide (`concernOut` en getArtifact).
      allOf:
        - $ref: "#/components/schemas/Concern"
        - type: object
          required:
            - can_resolve
            - resolver_role
          properties:
            can_resolve:
              type: boolean
              description: Tienes el rol, está abierta y el artefacto está en revisión.
            resolver_role:
              type: string
    ArtifactDetail:
      type: object
      description: Respuesta de leer un artefacto (mapa literal en getArtifact, también tras resolver, sincronizar o cambiar
        la sensibilidad).
      required:
        - artifact
        - concerns
      properties:
        artifact:
          $ref: "#/components/schemas/ArtifactRow"
        concerns:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactConcern"
    ArtifactRow:
      type: object
      description: Un artefacto versionado (`ArtifactRow`).
      required:
        - id
        - issue_id
        - issue_number
        - issue_key
        - issue_title
        - project_id
        - kind
        - version
        - path
        - branch
        - status
        - content_sha256
        - commit_sha
        - approved_commit_sha
        - concerns
        - created_at
        - sensitivity
        - external
        - can_approve
        - approver_role
      properties:
        id:
          type: string
          format: uuid
        issue_id:
          type: string
          format: uuid
        issue_number:
          type: integer
        issue_key:
          type: string
        issue_title:
          type: string
        project_id:
          type:
            - string
            - "null"
          format: uuid
        kind:
          type: string
          enum:
            - intent
            - spec
            - plan
            - postmortem
        version:
          type: integer
        path:
          type: string
        branch:
          type: string
        status:
          type: string
          enum:
            - draft
            - in_review
            - changes_requested
            - approved
            - superseded
            - rejected
        content:
          type: string
          description: El documento. Se omite en listas que lo vacían (vista SDLC, bandeja).
        content_sha256:
          type: string
        commit_sha:
          type: string
        approved_commit_sha:
          type: string
        requested_by_name:
          type:
            - string
            - "null"
        produced_by_agent:
          type:
            - string
            - "null"
          format: uuid
        produced_by_name:
          type:
            - string
            - "null"
        produced_by_task:
          type:
            - string
            - "null"
          format: uuid
        edited_by_name:
          type:
            - string
            - "null"
        approved_by_name:
          type:
            - string
            - "null"
        approved_at:
          type:
            - string
            - "null"
          format: date-time
        concerns:
          description: "JSON: la lista de preocupaciones (`Concern`) tal como se guarda."
        context_node_id:
          type:
            - string
            - "null"
          format: uuid
        created_at:
          type: string
          format: date-time
        sensitivity:
          type: string
          enum:
            - low
            - moderate
            - high
        external:
          description: JSON del estado de la sincronización con el sistema externo (`{}` si no hay).
        can_approve:
          type: boolean
        approve_reason:
          type: string
          description: Por qué no puedes aprobarlo (si no puedes).
        approver_role:
          type: string
    Assignee:
      type: object
      description: Una persona o un agente a quien asignar trabajo.
      required:
        - type
        - id
        - name
        - slug
        - color
        - provider
      properties:
        type:
          type: string
          enum:
            - user
            - agent
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
          description: El del agente o, en una persona, lo que va antes de la `@` de su correo.
        color:
          type: string
          description: El del agente o, en una persona, `#64748b`.
        provider:
          type: string
          description: El proveedor del agente; vacío en las personas.
    BudgetView:
      type: object
      description: Lo último que GitHub dijo del límite de peticiones de un token o una instalación.
      required:
        - remaining
        - limit
        - reset
        - low
      properties:
        remaining:
          type: integer
          description: Peticiones que quedan (el límite completo si ya pasó `reset`).
        limit:
          type: integer
        reset:
          type: string
          format: date-time
        low:
          type: boolean
          description: Si queda poco presupuesto.
    Bundle:
      type: object
      description: El paquete de contexto ensamblado para un agente (`contextmesh.Bundle`, internal/contextmesh/assemble.go:88).
      required:
        - budget_tokens
        - target_tokens
        - used_tokens
        - utilization
        - included
        - dropped
        - clashes
        - slots
        - static_prefix
        - issue_prefix
        - dynamic_part
        - prefix_hash
        - issue_prefix_hash
        - rendered
        - skills_mode
        - prefix_tokens
      properties:
        budget_tokens:
          type: integer
          description: Ventana nominal del agente (24000 si el agente no tiene una).
        target_tokens:
          type: integer
          description: Presupuesto × utilización objetivo (0.7 por defecto); tope duro de la selección.
        used_tokens:
          type: integer
        utilization:
          type: number
        included:
          type: array
          items:
            $ref: "#/components/schemas/Entry"
        dropped:
          type: array
          items:
            $ref: "#/components/schemas/Entry"
        clashes:
          type: array
          items:
            $ref: "#/components/schemas/Clash"
        slots:
          type: object
          description: Tokens por ranura (`instructions`, `knowledge`, `tools`, `memory`, `state`, `query`).
          additionalProperties:
            type: integer
        static_prefix:
          type: string
          description: Nivel 1 del prefijo, compartido entre los issues de un agente y proyecto.
        issue_prefix:
          type: string
          description: Nivel 2, los nodos fijados de la capa issue; va al principio de `dynamic_part`.
        dynamic_part:
          type: string
        prefix_hash:
          type: string
        issue_prefix_hash:
          type: string
        rendered:
          type: string
          description: El texto final que recibiría el agente.
        skills_mode:
          type: string
          description: Con qué modo se ensambló el protocolo de skills.
        prefix_tokens:
          type: integer
          description: Tokens del nivel 1.
    BundleRow:
      type: object
      required:
        - budget_tokens
        - used_tokens
        - utilization
        - included
        - dropped
        - clashes
        - slots
        - static_prefix
        - dynamic_part
        - prefix_hash
        - created_at
      properties:
        budget_tokens:
          type: integer
        used_tokens:
          type: integer
        utilization:
          type: number
        included:
          description: Lo que entró en el contexto (JSON tal cual).
        dropped:
          description: Lo que se quedó fuera (JSON tal cual).
        clashes:
          description: Choques detectados (JSON tal cual).
        slots:
          description: Huecos del contexto (JSON tal cual).
        static_prefix:
          type: string
        dynamic_part:
          type: string
        prefix_hash:
          type: string
        previous_prefix_hash:
          type:
            - string
            - "null"
          description: Hash del prefijo del paquete anterior del mismo agente.
        created_at:
          type: string
          format: date-time
    Checkpoint:
      type: object
      required:
        - id
        - task_id
        - step
        - next
        - blockers
        - created_at
      properties:
        id:
          type: integer
        task_id:
          type: string
          format: uuid
        step:
          type: string
        next:
          type: string
        blockers:
          type: string
        created_at:
          type: string
          format: date-time
    ClaimAgent:
      type: object
      required:
        - id
        - slug
        - name
        - provider
        - model
        - instructions
        - run_mode
        - autonomy
        - extra_args
        - command_template
        - context_budget_tokens
        - context_target_util
        - max_sensitivity
        - max_task_tokens
        - skills_mode
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        provider:
          type: string
        model:
          type: string
          description: En Claude Code, el de la receta de la jugada si la hay.
        instructions:
          type: string
        run_mode:
          type: string
        autonomy:
          type: string
        extra_args:
          type: array
          items:
            type: string
        command_template:
          type: string
        context_budget_tokens:
          type: integer
        context_target_util:
          type: number
        max_sensitivity:
          type: string
        max_task_tokens:
          type: integer
        skills_mode:
          type: string
          enum:
            - served
            - inline
          description: El modo efectivo de las skills.
    ClaimArtifact:
      type: object
      required:
        - kind
        - path
        - version
        - required_sections
        - front_matter
        - commit_message
      properties:
        kind:
          type: string
        path:
          type: string
        version:
          type: integer
        required_sections:
          type: array
          items:
            type: array
            items:
              type: string
        front_matter:
          type: object
          description: La procedencia que el daemon escribe al normalizar.
          additionalProperties:
            type: string
        commit_message:
          type: string
    ClaimContext:
      type: object
      required:
        - static_prefix
        - dynamic_part
        - rendered
        - prefix_hash
        - used_tokens
        - budget_tokens
        - utilization
      properties:
        static_prefix:
          type: string
        dynamic_part:
          type: string
        rendered:
          type: string
        prefix_hash:
          type: string
        used_tokens:
          type: integer
        budget_tokens:
          type: integer
        utilization:
          type: number
    ClaimContinue:
      type: object
      description: La rama del issue se trae de GitHub (relevo de runtime).
      required:
        - ref
        - sha
        - runtime
      properties:
        ref:
          type: string
        sha:
          type: string
        runtime:
          type: string
    ClaimEnv:
      type: object
      description: Lo que el daemon necesita para preparar el entorno del worktree (sólo con proyecto).
      required:
        - project_id
        - project_sdlc
        - host_exec
      properties:
        project_id:
          type: string
          format: uuid
        project_sdlc:
          type: boolean
          description: El proyecto tiene SDLC (entonces `link` no se permite).
        sensitivity_floor:
          type: string
          description: La rama ya recibió secretos (`copy_secrets`) en otra tarea.
        host_exec:
          type: string
          enum:
            - docker
            - full
            - host
            - ""
          description: Si en esta máquina puede ejecutarse código que escribió el agente.
    ClaimGitHub:
      type: object
      description: |
        Credencial de GitHub sólo para las operaciones de red de git (un token nuevo por claim, revocable). El daemon
        no la guarda en disco ni la pasa al agente.
      required:
        - repo
        - clone_url
        - token
      properties:
        repo:
          type: string
          description: "`owner/name`."
        clone_url:
          type: string
        token:
          type: string
          description: Vacío en un issue high o marcado sin la App (ver `no_token`).
        expires_at:
          type: string
          format: date-time
          description: Caducidad del token de instalación de la App (fecha cero con el PAT).
        revoke_url:
          type: string
          description: Con la App, adónde revocar el token en cuanto termina.
        no_token:
          type: string
          description: Por qué no lleva token (`restricted_without_app`).
    ClaimGuardrails:
      type: object
      required:
        - protected
        - play_scope
        - plan_drift
        - plan_drift_ignore
        - test_globs
        - locked_tests
      properties:
        protected:
          type: array
          items:
            type: string
        play_scope:
          type: array
          items:
            type: string
        plan_files:
          type:
            - array
            - "null"
          items:
            type: string
        plan_drift:
          type: string
        plan_drift_ignore:
          type: array
          items:
            type: string
        test_globs:
          type: array
          items:
            type: string
        locked_tests:
          type: array
          items:
            type: string
    ClaimIssue:
      type: object
      required:
        - id
        - number
        - key
        - title
        - description
        - restricted
      properties:
        id:
          type: string
          format: uuid
        number:
          type: integer
        key:
          type: string
        title:
          type: string
        description:
          type: string
        restricted:
          type: boolean
          description: El issue es high o está marcado (los commits del daemon llevan sólo la clave).
    ClaimProject:
      type: object
      required:
        - id
        - slug
        - name
        - repo_url
        - default_branch
        - local_path
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        repo_url:
          type: string
        default_branch:
          type: string
        local_path:
          type: string
          description: El repo vinculado en este runtime (vacío si no hay).
        github:
          $ref: "#/components/schemas/ClaimGitHub"
    ClaimPush:
      type: object
      description: Adónde empuja el daemon la rama del issue tras escribir en ella.
      required:
        - url
        - token
        - ref
        - hidden_ref
        - only_paths
      properties:
        url:
          type: string
        token:
          type: string
        expires_at:
          type: string
          format: date-time
          description: Caducidad del token de la App (fecha cero con el PAT).
        revoke_url:
          type: string
        ref:
          type: string
          description: Destino preferido.
        hidden_ref:
          type: string
          description: El destino si la rama ya lleva algo más que artefactos (vacío = no se empuja).
        only_paths:
          type: array
          description: Los únicos archivos que pueden diferir de la base para usar `ref` cuando es una rama.
          items:
            type: string
    ClaimRequester:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
    ClaimResponse:
      type: object
      required:
        - task
        - workspace
        - issue
        - project
        - agent
        - skills
        - context
      properties:
        server_caps:
          type: array
          description: Lo que sabe hacer el servidor (hoy `["pub2"]`).
          items:
            type: string
        task:
          $ref: "#/components/schemas/ClaimTask"
        sdlc:
          $ref: "#/components/schemas/ClaimSDLC"
        workspace:
          $ref: "#/components/schemas/ClaimWorkspace"
        issue:
          $ref: "#/components/schemas/ClaimIssue"
        project:
          description: El proyecto del issue, o `null` si no tiene.
          oneOf:
            - $ref: "#/components/schemas/ClaimProject"
            - type: "null"
        agent:
          $ref: "#/components/schemas/ClaimAgent"
        skills:
          type: array
          items:
            $ref: "#/components/schemas/ClaimSkill"
        env:
          $ref: "#/components/schemas/ClaimEnv"
        supervised:
          $ref: "#/components/schemas/ClaimSupervised"
        context:
          $ref: "#/components/schemas/ClaimContext"
    ClaimResume:
      type: object
      description: La sesión que el daemon reanuda (sólo la decide el servidor).
      required:
        - session_id
        - prior
      properties:
        session_id:
          type: string
        prior:
          $ref: "#/components/schemas/UsageIn"
        prompt:
          type: string
          description: La parte nueva del nivel 3 (la solicitud de la continuación).
    ClaimReview:
      type: object
      required:
        - commit_sha
        - of_task
        - round
        - max_nits
        - inputs
      properties:
        commit_sha:
          type: string
        of_task:
          type: string
        round:
          type: integer
        max_nits:
          type: integer
        inputs:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    ClaimSDLC:
      type: object
      description: Qué artefacto produce la jugada y qué hay que aplicar antes (sólo en el SDLC).
      required:
        - play
        - stage
        - issue_branch
        - pending_writes
        - protected_paths
      properties:
        play:
          type: string
        stage:
          type: string
        issue_branch:
          type: string
        artifact:
          $ref: "#/components/schemas/ClaimArtifact"
        pending_writes:
          type: array
          description: Commits humanos que aplicar antes.
          items:
            $ref: "#/components/schemas/ClaimWrite"
        requested_by:
          $ref: "#/components/schemas/ClaimRequester"
        protected_paths:
          type: array
          description: Artefactos aprobados que esta jugada no puede modificar.
          items:
            type: string
        push:
          $ref: "#/components/schemas/ClaimPush"
        continue_from:
          $ref: "#/components/schemas/ClaimContinue"
        verify:
          $ref: "#/components/schemas/ClaimVerify"
        guardrails:
          $ref: "#/components/schemas/ClaimGuardrails"
        review:
          $ref: "#/components/schemas/ClaimReview"
        prior_tokens:
          type: integer
          description: Tokens que ya gastó el barrido.
    ClaimSkill:
      type: object
      required:
        - slug
        - name
        - description
        - content
        - files
      properties:
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        content:
          type: string
        files:
          description: Los archivos de la skill (JSON tal cual).
    ClaimSupervised:
      type: object
      description: Lo que el daemon necesita para la puerta de permisos (sólo con autonomía `supervised`).
      required:
        - allow
        - timeout_sec
        - max_input_bytes
      properties:
        allow:
          type: array
          items:
            $ref: "#/components/schemas/AllowRule"
        timeout_sec:
          type: integer
        max_input_bytes:
          type: integer
    ClaimTask:
      type: object
      required:
        - id
        - attempt
        - trigger
        - prompt
        - branch
        - base_ref
        - play
      properties:
        id:
          type: string
          format: uuid
        attempt:
          type: integer
        trigger:
          type: string
        prompt:
          type: string
        branch:
          type: string
        base_ref:
          type: string
        worktree_path:
          type:
            - string
            - "null"
        continues:
          type:
            - string
            - "null"
          format: uuid
          description: La tarea cuyo worktree continúa.
        fanout_group_id:
          type:
            - string
            - "null"
          format: uuid
        agent_token:
          type: string
          description: Token de la tarea (`hqftk_`) para el agente, sólo mientras está en curso.
        play:
          type: string
        stage:
          type: string
        resume:
          $ref: "#/components/schemas/ClaimResume"
        live_steering:
          type: boolean
          description: Conducción en vivo activa (sólo Claude Code headless, fuera de la revisión y de una verificación sola).
        base_sha:
          type: string
          description: La base que registró el `/start` de la tarea que creó el worktree que ésta reutiliza.
        head_sha:
          type: string
          description: La cabeza de la rama del issue que juzgó el servidor.
    ClaimVerify:
      type: object
      required:
        - command
        - shell
        - timeout_sec
        - max_rounds
        - precommit
        - verifier
        - host_exec
        - expect_fail
        - expected_failure
        - verifier_prompt
        - only_verify
      properties:
        command:
          type: array
          items:
            type: string
        shell:
          type: boolean
        timeout_sec:
          type: integer
        max_rounds:
          type: integer
        precommit:
          type: string
        verifier:
          type: string
        host_exec:
          type: string
        expect_fail:
          type: boolean
        expected_failure:
          type: string
        verifier_prompt:
          type: string
        only_verify:
          type: boolean
    ClaimWorkspace:
      type: object
      required:
        - id
        - slug
        - locale
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        locale:
          type: string
    ClaimWrite:
      type: object
      required:
        - id
        - op
        - path
        - content
        - message
        - author_name
        - author_email
      properties:
        id:
          type: string
          format: uuid
        op:
          type: string
        path:
          type: string
        content:
          type: string
        message:
          type: string
          description: En un issue high o marcado, sólo la clave del issue.
        author_name:
          type: string
          description: Vacío en un issue high o marcado.
        author_email:
          type: string
          description: Vacío en un issue high o marcado.
    Clash:
      type: object
      description: Dos nodos que chocan; se queda uno (`contextmesh.Clash`, internal/contextmesh/assemble.go:82).
      required:
        - kept
        - dropped
        - relation
      properties:
        kept:
          type: string
          description: "`short_id` del nodo que se queda."
        dropped:
          type: string
          description: "`short_id` del nodo descartado."
        relation:
          type: string
    CodeDecision:
      type: object
      description: El resultado de la decisión de aprobación de código (sdlc.CodeDecision).
      required:
        - allowed
        - role
        - four_eyes
      properties:
        allowed:
          type: boolean
        code:
          type: string
          description: Código de rechazo (not_user, code_owner_required, four_eyes, four_eyes_required, confirm_no_four_eyes,
            nothing_left_to_cover, approval_role_required).
        role:
          type: string
          description: Rol con que se decide.
        fallback:
          type: boolean
          description: El rol no tiene miembros y decidió la política del proyecto.
        four_eyes:
          type: boolean
        reason:
          type: string
        covers:
          type: array
          description: Archivos que cubre esta aprobación.
          items:
            type: string
        missing:
          type: array
          description: Archivos que faltan tras esta aprobación.
          items:
            type: string
        others:
          type: array
          description: Quién más podría aprobar (ids).
          items:
            type: string
    Comment:
      type: object
      required:
        - id
        - issue_id
        - author_type
        - body
        - created_at
      properties:
        id:
          type: string
          format: uuid
        issue_id:
          type: string
          format: uuid
        author_type:
          type: string
          enum:
            - user
            - agent
            - system
        author_id:
          type:
            - string
            - "null"
          format: uuid
        author_name:
          type:
            - string
            - "null"
          description: Nombre del usuario o del agente; `HQ Fabric` si es el sistema.
        author_color:
          type:
            - string
            - "null"
          description: Color del agente (sólo agentes).
        body:
          type: string
        created_at:
          type: string
          format: date-time
    Commit:
      type: object
      required:
        - sha
        - author
        - committer
        - message
        - files
        - parents
      properties:
        sha:
          type: string
        author:
          type: string
        committer:
          type: string
        message:
          type: string
        files:
          type: array
          items:
            type: string
        parents:
          type: array
          items:
            type: string
        merge:
          type: boolean
    CompleteArtifact:
      type: object
      description: El artefacto que dejó una jugada del SDLC (ya commiteado).
      properties:
        kind:
          type: string
        path:
          type: string
        version:
          type: integer
        content:
          type: string
        commit_sha:
          type: string
    CompleteIn:
      type: object
      required:
        - status
      properties:
        protected_conflicts:
          type: array
          description: resolve-conflicts no lanzó al agente por conflictos en rutas protegidas.
          items:
            type: string
        status:
          type: string
          enum:
            - completed
            - failed
            - blocked
            - cancelled
            - pending_verification
            - quota
        summary:
          type: string
        error:
          type: string
        exit_code:
          type:
            - integer
            - "null"
        usage:
          type: object
          properties:
            tokens_in:
              type: integer
            tokens_out:
              type: integer
            cost_usd:
              type: number
        diff:
          type:
            - object
            - "null"
          properties:
            patch:
              type: string
            files:
              description: Los archivos del diff (JSON tal cual; el servidor lee `path` de cada uno).
            commit_sha:
              type: string
        lessons:
          type: string
          description: Lecciones y feedback para el curador.
        blocked:
          type: string
          description: Motivo de bloqueo; con `completed`, la tarea pasa a `blocked`.
        signals:
          type: object
          description: Señales para el curador (p. ej. `worktree_setup_failed`).
          additionalProperties: true
        worktree_path:
          type: string
        no_retry:
          type: boolean
          description: Reintentar no arregla el fallo.
        pr_body:
          type: string
          description: Descripción del PR escrita por el agente.
        artifact:
          $ref: "#/components/schemas/CompleteArtifact"
        pushed:
          $ref: "#/components/schemas/PushedIn"
        agent_alive:
          type: boolean
          description: El daemon no pudo matar todo lo del agente; no se da token de empuje.
        play_patch:
          type:
            - string
            - "null"
        play_base:
          type: string
        rounds:
          type: integer
        verify_status:
          type: string
        error_class:
          type: string
          description: Sin SDLC sólo se guarda en un fallo si es `guardrail`, `infra`, `agent`, `timeout` o `budget`.
        repro_auto_accepted:
          type: boolean
        verifications:
          type: array
          items:
            $ref: "#/components/schemas/VerificationIn"
        guardrail_findings:
          type: array
          items:
            $ref: "#/components/schemas/FindingIn"
        review:
          oneOf:
            - $ref: "#/components/schemas/ReviewIn"
            - type: "null"
        cumulative:
          oneOf:
            - $ref: "#/components/schemas/CumulativeIn"
            - type: "null"
        quota:
          $ref: "#/components/schemas/QuotaCompletionIn"
        quota_suspect:
          $ref: "#/components/schemas/QuotaSuspectIn"
    Concern:
      type: object
      description: Una fila de la tabla «Áreas de preocupación» de un spec (`sdlc.Concern`).
      required:
        - id
        - category
        - owner
        - status
        - text
      properties:
        id:
          type: string
        category:
          type: string
        owner:
          type: string
        status:
          type: string
          description: "`open` o `resolved`. Sólo se resuelve con `/resolve`."
        text:
          type: string
        proposal:
          type: string
        resolution:
          type: string
        resolved_by:
          type: string
          description: Nombre de quien la resolvió.
        resolved_at:
          type: string
          description: Fecha RFC 3339 en texto.
        source:
          type: string
          enum:
            - agent
            - server
        extra:
          type: object
          description: Columnas que no son del formato; `declared_status` guarda el estado que traía el documento.
          additionalProperties:
            type: string
    ConfirmGitHubCallbackRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: El valor de `gh_confirm` con el que la vuelta de GitHub redirigió a la web.
    ConflictNotice:
      type: object
      description: Un aviso de conflicto en ruta protegida (`conflictNotice`).
      required:
        - id
        - issue_key
        - issue_number
        - task_id
        - paths
        - created_at
      properties:
        id:
          type: string
          format: uuid
        issue_key:
          type: string
        issue_number:
          type: integer
        task_id:
          type:
            - string
            - "null"
          format: uuid
        paths:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    ConnectorRow:
      type: object
      description: Un conector con un sistema de work items (sin su token).
      required:
        - id
        - kind
        - name
        - base_url
        - project
        - api_version
        - username
        - token_hint
        - last_check_error
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - azure_devops
            - jira
        name:
          type: string
        base_url:
          type: string
        project:
          type: string
        api_version:
          type: string
        username:
          type: string
          description: En Jira, el correo de la cuenta del token.
        token_hint:
          type: string
          description: 4 primeros y 4 últimos caracteres del token (`…` si tiene 8 o menos).
        last_check_at:
          type:
            - string
            - "null"
          format: date-time
          description: La última prueba (`POST …/test`).
        last_check_error:
          type: string
          description: El error de la última prueba; vacío si fue bien.
        updated_at:
          type: string
          format: date-time
    ContainerInput:
      type: object
      description: Cuerpo para crear o reinstalar un runtime en Docker (tipo Go `containerIn`).
      properties:
        name:
          type: string
        cpus:
          type: number
          minimum: 0.5
        memory_mb:
          type: integer
          minimum: 512
        server_url:
          type: string
          description: "`http(s)://host[:puerto]`; vacío = el valor actual o el del servidor."
        harnesses:
          type: array
          description: CLIs que se preinstalan en el volumen (conocidos, instalables, no `custom`).
          items:
            type: string
    ContainerRuntime:
      type: object
      description: El detalle de un runtime en Docker (tipo Go `ContainerRuntime`).
      required:
        - runtime_id
        - container
        - volume
        - image
        - cpus
        - memory_mb
        - server_url
        - harnesses
        - state
        - error
        - error_code
        - log
        - updated_at
        - busy
        - running
      properties:
        runtime_id:
          type: string
          format: uuid
        container:
          type: string
        volume:
          type: string
        image:
          type: string
        cpus:
          type: number
        memory_mb:
          type: integer
        server_url:
          type: string
        harnesses:
          type: array
          items:
            type: string
        state:
          type: string
          description: "`installing`, `starting`, `stopping`, `ready`, `stopped` o `error`."
        error:
          type: string
        error_code:
          type: string
        log:
          type: string
          description: Log de la última operación.
        updated_at:
          type: string
          format: date-time
        busy:
          type: boolean
          description: Hay una operación en curso.
        running:
          type: boolean
          description: El contenedor corre (sólo se consulta si no hay operación en curso).
    ContextNode:
      type: object
      description: Un nodo de la Malla de Contexto (internal/api/context.go:15).
      required:
        - id
        - short_id
        - scope
        - slot
        - kind
        - section
        - slug
        - title
        - body
        - tags
        - weight
        - pinned
        - token_count
        - state
        - sensitivity
        - helpful_count
        - harmful_count
        - use_count
        - verified
        - source_type
        - metadata
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        short_id:
          type: string
          description: El identificador con el que lo citan los agentes, `ctx-` y los 8 primeros caracteres hexadecimales del id.
        scope:
          type: string
          enum:
            - workspace
            - project
            - agent
            - issue
        scope_id:
          type:
            - string
            - "null"
          format: uuid
          description: El proyecto, agente o issue de la capa; null en `workspace`.
        scope_name:
          type:
            - string
            - "null"
          description: El nombre del proyecto o del agente, o la clave del issue (`PREFIJO-n`); null en `workspace`.
        slot:
          type: string
          enum:
            - instructions
            - knowledge
            - tools
            - memory
            - state
            - query
        kind:
          type: string
          enum:
            - rule
            - convention
            - doc
            - adr
            - repo
            - skill
            - memory
            - artifact
            - glossary
            - plan
        section:
          type: string
        slug:
          type: string
        title:
          type: string
        body:
          type: string
        uri:
          type:
            - string
            - "null"
        tags:
          type: array
          items:
            type: string
        weight:
          type: number
        pinned:
          type: boolean
        token_count:
          type: integer
        state:
          type: string
          enum:
            - active
            - warm
            - cold
            - archived
        sensitivity:
          type: string
          enum:
            - low
            - moderate
            - high
        helpful_count:
          type: integer
        harmful_count:
          type: integer
        use_count:
          type: integer
        last_used_at:
          type:
            - string
            - "null"
          format: date-time
        verified:
          type: boolean
        source_type:
          type: string
          enum:
            - user
            - agent
            - system
        source_id:
          type:
            - string
            - "null"
          format: uuid
        source_name:
          type:
            - string
            - "null"
          description: El nombre del agente o de la persona que lo creó.
        source_task_id:
          type:
            - string
            - "null"
          format: uuid
        metadata:
          description: JSON libre del nodo (columna `metadata`, un objeto; `{}` por defecto).
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ContextNodeInput:
      type: object
      description: |
        Cuerpo de crear y de modificar un nodo (`nodeIn`, internal/api/context.go:119). Todos los campos son
        opcionales en el esquema; al crear, `title` es obligatorio. Un campo null cuenta como ausente.
      properties:
        scope:
          type: string
          enum:
            - workspace
            - project
            - agent
            - issue
          description: Sólo al crear.
        scope_id:
          type: string
          description: Uuid del proyecto, agente o issue de la capa (o vacío). Sólo al crear.
        slot:
          type: string
          enum:
            - instructions
            - knowledge
            - tools
            - memory
            - state
            - query
        kind:
          type: string
          enum:
            - rule
            - convention
            - doc
            - adr
            - repo
            - skill
            - memory
            - artifact
            - glossary
            - plan
        section:
          type: string
        slug:
          type: string
          description: Sólo al crear; se normaliza (minúsculas, sin acentos, guiones, hasta 48 caracteres).
        title:
          type: string
        body:
          type: string
        uri:
          type: string
        tags:
          type: array
          items:
            type: string
        weight:
          type: number
          minimum: 0
          maximum: 10
        pinned:
          type: boolean
        state:
          type: string
          enum:
            - active
            - warm
            - cold
            - archived
          description: Sólo al modificar (al crear se ignora).
        sensitivity:
          type: string
          enum:
            - low
            - moderate
            - high
        verified:
          type: boolean
          description: Sólo al modificar (al crear se ignora).
    ContextPreviewRequest:
      type: object
      description: Cuerpo de la vista previa del contexto (struct anónimo, internal/api/context.go:536).
      required:
        - issue_number
        - agent_id
      properties:
        issue_number:
          type: integer
          description: Número del issue en el workspace.
        agent_id:
          type: string
          format: uuid
        prompt:
          type: string
          description: La petición de la tarea (opcional).
    CountRow:
      type: object
      description: Un recuento por clave (`countRow`, internal/api/context.go:591).
      required:
        - key
        - count
      properties:
        key:
          type: string
        count:
          type: integer
    CreateContextEdgeRequest:
      type: object
      description: Cuerpo de crear una arista (struct anónimo, internal/api/context.go:436).
      required:
        - from_node
        - to_node
        - relation
      properties:
        from_node:
          type: string
          format: uuid
        to_node:
          type: string
          format: uuid
          description: Distinto de `from_node`.
        relation:
          type: string
          enum:
            - depends_on
            - refines
            - contradicts
            - derived_from
            - references
            - applies_to
            - supersedes
        weight:
          type: number
          description: Peso de la arista (1.0 si no se manda). No se valida el rango.
    CreateDelegationRequest:
      type: object
      description: Cuerpo de `POST /runtimes/{rid}/approval-delegations` (struct anónimo).
      required:
        - project_id
        - delegate_user_id
      properties:
        project_id:
          type: string
          format: uuid
        delegate_user_id:
          type: string
          format: uuid
        expires_days:
          type: integer
          minimum: 1
          maximum: 90
          description: 30 si no viene.
    CreateDiffCommentRequest:
      type: object
      required:
        - file_path
        - body
      properties:
        file_path:
          type: string
        line:
          type: integer
        side:
          type: string
          description: old; cualquier otro valor queda en new.
        body:
          type: string
    CreateGitHubAppManifestRequest:
      type: object
      properties:
        org:
          type: string
          description: Organización de GitHub donde crear la App; vacío = tu cuenta.
    CreateGitHubRepoRequest:
      type: object
      required:
        - name
      properties:
        owner:
          type: string
          description: Organización donde crearlo; vacío o igual a la cuenta del token = la cuenta.
        name:
          type: string
          maxLength: 100
          pattern: ^[A-Za-z0-9_.-]+$
          description: Ni `.` ni `..` ni acabado en `.git`.
        description:
          type: string
          description: Se juntan espacios y saltos de línea y se corta a 350 caracteres.
        private:
          type: boolean
          description: Por defecto `true`.
        token:
          type: string
          minLength: 20
          description: Token puntual sólo para crear este repo (no se guarda); sin espacios.
    CreateTokenRequest:
      type: object
      properties:
        name:
          type: string
          description: Nombre del token; vacío = `cli`.
        days:
          type: integer
          description: Días hasta que caduca; 0 o negativo, no caduca.
        scopes:
          type: array
          description: Vacío = `runtime` si el nombre empieza por `hqf@`, `api` si no.
          items:
            type: string
            enum:
              - api
              - runtime
    CreateWorkspaceRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Obligatorio (se recortan espacios).
        slug:
          type: string
          description: Vacío = el del nombre. Siempre se normaliza.
        issue_prefix:
          type: string
          description: Vacío = las 4 primeras letras del slug sin guiones. Se guarda en mayúsculas.
        locale:
          type: string
          description: Vacío = tu idioma. Normalizado a `es` o `en`.
    CumulativeIn:
      type: object
      description: El diff acumulado de la rama del issue (L4).
      properties:
        base:
          type: string
        head:
          type: string
        patch:
          type: string
        same_as_diff:
          type: boolean
    CuratorResult:
      type: object
      required:
        - added
        - merged
        - helpful
        - harmful
      properties:
        added:
          type: integer
        lowered:
          type: integer
          description: Lecciones que bajaron al issue de origen porque no cabían en su ámbito.
        merged:
          type: integer
        helpful:
          type: integer
        harmful:
          type: integer
    DaemonArtifactWriteAppliedRequest:
      type: object
      properties:
        ok:
          type: boolean
          description: Se aplicó el commit.
        commit_sha:
          type: string
        error:
          type: string
          description: Se guarda recortado a 2000 caracteres.
        pushed:
          $ref: "#/components/schemas/PushedIn"
    DaemonCheckpointRequest:
      type: object
      required:
        - step
      properties:
        step:
          type: string
          description: Qué hiciste (obligatorio). step + next + blockers, como mucho 2048 bytes.
        next:
          type: string
        blockers:
          type: string
    DaemonConsentCheckRequest:
      type: object
      required:
        - project_id
        - kind
        - subject_hash
      properties:
        project_id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - worktree.setup
            - copy_secrets
            - worktree.link
            - worktree.clone_exceptions
            - supervised.allow
        subject_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
        task_id:
          type: string
          format: uuid
          description: La última tarea del worktree; su autonomía decide `host_exec`.
    DaemonContextMetricsRequest:
      type: object
      properties:
        max_context_tokens:
          type: integer
          minimum: 0
          maximum: 10000000
        turns:
          type: integer
          minimum: 0
          maximum: 1000000
    DaemonHeartbeatRequest:
      type: object
      properties:
        providers:
          description: Los CLI de agentes que el daemon detecta (JSON tal cual; sin él, `[]`).
        repos:
          type: object
          description: Slug o id de un proyecto → ruta local del repo vinculado.
          additionalProperties:
            type: string
        running:
          type: array
          description: Ids de las tareas que el daemon tiene en marcha.
          items:
            type: string
            format: uuid
        version:
          type: string
          description: Versión del daemon (el handler no la usa).
        max_parallel:
          type: integer
          description: Tareas a la vez; 0 conserva el valor guardado.
        task_timeout:
          type: string
          description: Tope de tiempo por tarea; vacío conserva el valor guardado.
        supervised_profile:
          type:
            - object
            - "null"
          description: Si el perfil dedicado de `supervised` tiene sesión.
          properties:
            logged_in:
              type: boolean
            checked_at:
              type: string
              format: date-time
        quota:
          type: array
          description: La cuota vista por el daemon (de 1 a 256 ventanas; con más se ignora).
          items:
            $ref: "#/components/schemas/QuotaIn"
    DaemonOk:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
          const: true
    DaemonPermId:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
    DaemonSessionRequest:
      type: object
      required:
        - session_id
      properties:
        session_id:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        cwd:
          type: string
          description: Tiene que ser el worktree de la tarea.
        status:
          type: string
          enum:
            - active
            - resumable
            - closed
            - ""
        usage:
          $ref: "#/components/schemas/UsageIn"
        head_sha:
          type: string
          description: SHA de 40 hex (otro valor se ignora).
        fresh:
          type: boolean
          description: La reanudación concedida no arrancó y el daemon siguió con una sesión nueva.
    DaemonSessionsPurgedRequest:
      type: object
      properties:
        task_ids:
          type: array
          description: Como mucho se toman 500 uuid válidos.
          items:
            type: string
            format: uuid
    DaemonSubtaskRequest:
      type: object
      required:
        - title
        - prompt
      properties:
        title:
          type: string
          description: En una línea, hasta 200 bytes tras limpiarlo.
        prompt:
          type: string
          description: Hasta 16000 bytes tras limpiarlo.
    DaemonTaskAskRequest:
      type: object
      required:
        - questions
      properties:
        questions:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: string
            maxLength: 2000
        domain:
          type: string
          description: Dominio de las preguntas (se pasa a minúsculas y se corta a 80 bytes).
    DaemonTaskBlockRequest:
      type: object
      required:
        - reason
      properties:
        reason:
          type: string
          minLength: 1
    DaemonTaskCommentRequest:
      type: object
      required:
        - body
      properties:
        body:
          type: string
    DaemonTaskEventsRequest:
      type: object
      properties:
        events:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                description: P. ej. `tool_call`, `subagents` o `pty` (con `payload.data` en base64).
              payload:
                description: Los datos del evento (JSON; sin él, `{}`).
    DaemonTaskIssueRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
        description:
          type: string
        priority:
          type: string
          description: "`none`, `low`, `medium`, `high` o `urgent`; otro valor, `none`."
    DaemonTaskManifestRequest:
      type: object
      properties:
        request_id:
          type: string
          description: El del pedido `task.manifest`.
        manifest:
          oneOf:
            - $ref: "#/components/schemas/Manifest"
            - type: "null"
        error:
          type: string
          description: Por qué el daemon no pudo calcular el manifiesto.
    DaemonTaskMergedRequest:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: string
        base:
          type: string
        commit:
          type: string
          description: El handler no lo usa.
    DaemonTaskPushedRequest:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: string
        commit:
          type: string
          description: El commit empujado.
        manifest:
          description: En un issue high o marcado, el manifiesto con el que empujó.
          oneOf:
            - $ref: "#/components/schemas/Manifest"
            - type: "null"
    DaemonTaskQuestionsRequest:
      type: object
      required:
        - question
      properties:
        question:
          type: string
          maxLength: 2000
        options:
          type: array
          description: Ninguna o de 2 a 8, de hasta 200 caracteres, no vacías ni repetidas.
          maxItems: 8
          items:
            type: string
            maxLength: 200
        default:
          type: string
          description: Una de las opciones; exige `timeout_sec`.
        timeout_sec:
          type: integer
          description: De 60 a 604800 (7 días); 0 sin plazo.
        role:
          type: string
          enum:
            - product_owner
            - engineer
            - code_owner
            - context_owner
        domain:
          type: string
          description: También crea un hueco de conocimiento con este dominio.
    DaemonTaskStartRequest:
      type: object
      properties:
        worktree_path:
          type: string
        base_ref:
          type: string
        base_sha:
          type: string
          description: La base de la tarea (SHA de 40 hex; otro valor se ignora). Sólo cuenta la primera.
    DaemonTaskWaitRequest:
      type: object
      properties:
        state:
          type: string
          enum:
            - input
            - permission
            - quota
            - hibernated
            - ""
        until:
          type: string
          format: date-time
          description: RFC 3339, entre hace un minuto y dentro de 8 días.
        ref:
          type: string
          description: Referencia de la espera (una línea, hasta 200 bytes; no puede empezar por `question:`).
    DaemonTeardownSkippedRequest:
      type: object
      required:
        - project_id
        - worktree
      properties:
        project_id:
          type: string
          format: uuid
        task_id:
          type: string
          format: uuid
        worktree:
          type: string
          description: Ruta del worktree (una línea, hasta 1024 bytes).
        port:
          type: integer
          minimum: 0
          maximum: 65535
        processes:
          type: array
          description: Los procesos que seguían vivos (se guardan hasta 50 con pid positivo).
          items:
            $ref: "#/components/schemas/TeardownProc"
    DaemonUploadBinaryRequest:
      type: object
      required:
        - path
        - blob
        - data
      properties:
        path:
          type: string
        blob:
          type: string
          pattern: ^[0-9a-f]{40}([0-9a-f]{24})?$
          description: Id de git del blob (SHA-1 o SHA-256).
        data:
          type: string
          contentEncoding: base64
          description: El contenido en base64 (como mucho 8 MB decodificado).
    DaemonWorktreeProposalRequest:
      type: object
      required:
        - yaml
        - sources
      properties:
        yaml:
          type: string
          description: El worktree.yaml propuesto (hasta 64 KB tras limpiarlo).
        sources:
          type: array
          items:
            type: string
            enum:
              - .worktreeinclude
              - orca.yaml
              - conductor.json
    DaemonWorktreesStatusRequest:
      type: object
      properties:
        task_ids:
          type: array
          description: Como mucho se toman 500 uuid válidos.
          items:
            type: string
            format: uuid
    DecidePermissionRequest:
      type: object
      properties:
        input_sha256:
          type:
            - string
            - "null"
          description: Al aprobar, obligatorio y igual al `input_sha256` de la solicitud.
        reason:
          type: string
          description: Al denegar, el motivo (opcional; se le pasa al agente).
    DeltaRow:
      type: object
      required:
        - id
        - op
        - payload
        - created_at
      properties:
        id:
          type: string
          format: uuid
        node_id:
          type:
            - string
            - "null"
          format: uuid
          description: Null si no ves el nodo.
        node_title:
          type:
            - string
            - "null"
          description: Null si no ves el nodo.
        op:
          type: string
          description: add, helpful, harmful, update o archive.
        payload:
          description: Contenido del delta (JSON tal cual).
        merged_into:
          type:
            - string
            - "null"
          format: uuid
          description: Null si no ves el nodo.
        created_at:
          type: string
          format: date-time
    Detected:
      type: object
      description: Un CLI de agentes detectado en una máquina (tipo Go `agentcli.Detected`).
      required:
        - id
        - name
        - binary
        - path
        - version
      properties:
        id:
          type: string
        name:
          type: string
        binary:
          type: string
        path:
          type: string
        version:
          type: string
        auth:
          type: string
          description: "`ok` (sesión o API key), `missing` o `unknown`."
    Diff:
      type: object
      required:
        - patch
        - files
        - updated_at
      properties:
        patch:
          type: string
        files:
          description: Archivos del diff (JSON tal cual se guardó; cada elemento lleva al menos `additions` y `deletions`).
        commit_sha:
          type:
            - string
            - "null"
        pr_url:
          type:
            - string
            - "null"
        updated_at:
          type: string
          format: date-time
    DiffComment:
      type: object
      required:
        - id
        - file_path
        - line
        - side
        - body
        - status
        - created_at
        - author_type
      properties:
        id:
          type: string
          format: uuid
        file_path:
          type: string
        line:
          type: integer
        side:
          type: string
          description: old o new.
        body:
          type: string
        status:
          type: string
          description: open, sent o resolved.
        author_id:
          type:
            - string
            - "null"
          format: uuid
        author_name:
          type:
            - string
            - "null"
        created_at:
          type: string
          format: date-time
        author_type:
          type: string
          description: user o agent (hallazgo del revisor).
        agent_name:
          type:
            - string
            - "null"
        severity:
          type:
            - string
            - "null"
        pass:
          type:
            - string
            - "null"
        title:
          type:
            - string
            - "null"
        source_task_id:
          type:
            - string
            - "null"
          format: uuid
        dismissed_by_name:
          type:
            - string
            - "null"
        dismissed_at:
          type:
            - string
            - "null"
          format: date-time
        dismiss_reason:
          type:
            - string
            - "null"
    DismissReasonRequest:
      type: object
      required:
        - reason
      properties:
        reason:
          type: string
          description: Por qué se descarta.
    DockerSetup:
      type: object
      description: El estado de Docker en la máquina del servidor (tipo Go `DockerSetup`).
      required:
        - enabled
        - available
        - can_start
        - ncpu
        - memory_mb
        - server_url
      properties:
        enabled:
          type: boolean
          description: El servidor permite runtimes en Docker (`DOCKER_RUNTIME`).
        available:
          type: boolean
          description: Docker está instalado y corriendo.
        reason_code:
          type: string
          description: "`disabled`, `no_docker`, `not_running` o `unsupported`."
        reason:
          type: string
        can_start:
          type: boolean
          description: Se puede abrir Docker Desktop desde la web (macOS con Docker.app).
        version:
          type: string
        arch:
          type: string
        ncpu:
          type: integer
        memory_mb:
          type: integer
        server_url:
          type: string
          description: URL con la que los contenedores llegan al servidor (por defecto).
    EdgeRow:
      type: object
      description: Una arista de la malla con los títulos de sus nodos (internal/api/context.go:390).
      required:
        - id
        - from_node
        - to_node
        - from_title
        - to_title
        - relation
        - weight
        - created_at
      properties:
        id:
          type: string
          format: uuid
        from_node:
          type: string
          format: uuid
        to_node:
          type: string
          format: uuid
        from_title:
          type: string
        to_title:
          type: string
        relation:
          type: string
          enum:
            - depends_on
            - refines
            - contradicts
            - derived_from
            - references
            - applies_to
            - supersedes
        weight:
          type: number
        created_at:
          type: string
          format: date-time
    Entry:
      type: object
      description: Un nodo incluido o descartado del paquete (`contextmesh.Entry`, internal/contextmesh/assemble.go:70).
      required:
        - node_id
        - short_id
        - title
        - scope
        - slot
        - kind
        - tokens
        - score
        - reason
      properties:
        node_id:
          type: string
          format: uuid
        short_id:
          type: string
        title:
          type: string
        scope:
          type: string
        slot:
          type: string
        kind:
          type: string
        tokens:
          type: integer
        score:
          type: number
          description: Puntuación redondeada a 3 decimales.
        reason:
          type: string
          description: |
            En `included`: `pinned`, `scope`, `similar`, `graph` o vacío. En `dropped`: `sensitivity`, `clash`,
            `budget`, `irrelevant` o `top_k`.
    EnvConsentIn:
      type: object
      required:
        - kind
        - subject_hash
        - subject
      properties:
        kind:
          type: string
          enum:
            - worktree.setup
            - copy_secrets
            - worktree.link
            - worktree.clone_exceptions
            - supervised.allow
        subject_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: sha256 de lo que se consiente.
        subject:
          description: |
            Lo que verá el dueño (JSON, hasta 64 KB). Con `paths`, rutas relativas y literales dentro del repo; en
            `supervised.allow`, `{"allow": [AllowRule…]}`.
        yaml_hash:
          type: string
          description: sha256 del worktree.yaml de la base (auditoría).
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Código del error (p. ej. `unauthorized`, `forbidden`, `not_found`, `bad_json`).
        message:
          type: string
          description: Texto para personas, en el idioma del servidor.
    Finding:
      type: object
      required:
        - pass
        - severity
        - path
        - line
        - title
        - body
      properties:
        pass:
          type: string
        severity:
          type: string
        path:
          type: string
        line:
          type: integer
        title:
          type: string
        body:
          type: string
    FindingIn:
      type: object
      description: Un hallazgo de los guardarraíles del daemon.
      properties:
        rule:
          type: string
          description: "`protected_path`, `path_escape`, `symlink`, `secret`, `bug_test_lock`, `play_scope`, `plan_drift`…"
        path:
          type: string
        line:
          type: integer
        severity:
          type: string
          enum:
            - block
            - warn
        message:
          type: string
        how_to_fix:
          type: string
        hash_prefix:
          type: string
          description: Sólo en secretos.
        layer:
          type: string
        round:
          type: integer
    FindingRow:
      type: object
      required:
        - id
        - layer
        - rule
        - severity
        - message
      properties:
        id:
          type: integer
        layer:
          type: string
          description: L1, L2, L3 o L4.
        rule:
          type: string
        severity:
          type: string
          description: block o warn.
        path:
          type:
            - string
            - "null"
        line:
          type:
            - integer
            - "null"
        hash_prefix:
          type:
            - string
            - "null"
        message:
          type: string
        round:
          type:
            - integer
            - "null"
        expected:
          type:
            - boolean
            - "null"
        dismiss_reason:
          type:
            - string
            - "null"
        dismissed_by_name:
          type:
            - string
            - "null"
    GapRow:
      type: object
      description: Un hueco de conocimiento (`GapRow`).
      required:
        - id
        - issue_id
        - issue_number
        - issue_key
        - issue_title
        - task_id
        - agent_name
        - domain
        - question
        - answer
        - answered_by_name
        - answered_at
        - status
        - node_id
        - created_at
        - project_id
        - can_add_answerers
      properties:
        id:
          type: string
          format: uuid
        issue_id:
          type:
            - string
            - "null"
          format: uuid
        issue_number:
          type:
            - integer
            - "null"
        issue_key:
          type:
            - string
            - "null"
        issue_title:
          type:
            - string
            - "null"
        task_id:
          type:
            - string
            - "null"
          format: uuid
        agent_name:
          type:
            - string
            - "null"
        domain:
          type: string
        question:
          type: string
        answer:
          type: string
          description: La respuesta, o el motivo si se descartó.
        answered_by_name:
          type:
            - string
            - "null"
        answered_at:
          type:
            - string
            - "null"
          format: date-time
        status:
          type: string
          enum:
            - open
            - answered
            - converted
            - dismissed
        node_id:
          type:
            - string
            - "null"
          format: uuid
          description: El nodo de la malla si se convirtió.
        created_at:
          type: string
          format: date-time
        project_id:
          type:
            - string
            - "null"
          format: uuid
        can_add_answerers:
          type: boolean
          description: Quien pide es mantenedor del proyecto y el hueco está abierto (sólo se calcula en la lista del issue).
    GitHubCreatedRepo:
      description: El repo recién creado y, si el token del workspace no alcanza a usarlo, un aviso.
      allOf:
        - $ref: "#/components/schemas/GitHubRepo"
        - type: object
          properties:
            warning:
              type: string
              description: Aviso si el token del workspace no puede escribir en el repo o no tiene acceso a él.
    GitHubLoginOut:
      type: object
      description: Tu login de GitHub vinculado.
      required:
        - login
        - verified
        - oauth_available
      properties:
        login:
          type: string
        verified:
          type: boolean
          description: Si está comprobado (con el id numérico de la cuenta).
        verified_at:
          type:
            - string
            - "null"
          format: date-time
        code:
          type: string
          description: Mientras no esté comprobado, el código (`hqf-verify-…`) que tienes que poner en tu bio de GitHub.
        linked_via:
          type: string
          description: |
            Cómo se vinculó: `bio` u `oauth`. Una reserva sin comprobar conserva el valor que ya tenía tu fila
            (`bio` si es nueva).
        oauth_available:
          type: boolean
          description: Si el workspace tiene GitHub App legible (vinculación por OAuth).
    GitHubOwner:
      type: object
      description: Una cuenta u organización de GitHub donde crear repos (tipo Go `github.Owner`).
      required:
        - login
        - type
      properties:
        login:
          type: string
        type:
          type: string
          enum:
            - user
            - org
    GitHubRepo:
      type: object
      description: Un repo de GitHub.
      required:
        - full_name
        - owner
        - name
        - private
        - description
        - url
        - clone_url
        - default_branch
        - can_push
      properties:
        full_name:
          type: string
          description: "`owner/name`."
        owner:
          type: string
        name:
          type: string
        private:
          type: boolean
        description:
          type: string
        url:
          type: string
          description: La página del repo en GitHub.
        clone_url:
          type: string
        default_branch:
          type: string
        pushed_at:
          type:
            - string
            - "null"
          format: date-time
        can_push:
          type: boolean
          description: Si el token puede escribir en el repo.
    GitHubStatus:
      type: object
      description: El estado de la conexión del workspace con GitHub por token.
      required:
        - connected
      properties:
        connected:
          type: boolean
        login:
          type: string
          description: La cuenta de GitHub del token.
        token_hint:
          type: string
          description: 4 primeros y 4 últimos caracteres del token.
        scopes:
          type: string
          description: Los scopes del token (X-OAuth-Scopes, separados por comas); vacío con tokens fine-grained.
        connected_at:
          type: string
          format: date-time
        warning:
          type: string
          description: Aviso si un token clásico no tiene el scope `repo`.
        error:
          type: string
          description: Error si el token guardado no se puede descifrar.
        budget:
          $ref: "#/components/schemas/BudgetView"
    GrantRuntimeConsentRequest:
      type: object
      description: Cuerpo de `POST /runtimes/{rid}/consents/{cid}/grant` (struct anónimo).
      properties:
        expires_days:
          type: integer
          minimum: 0
          maximum: 90
          description: Días hasta que vence (de 1 a 90); 0 o ausente = 90.
    GrantVerifyRequest:
      type: object
      description: Cuerpo de `POST /runtimes/{rid}/verify-grants` (struct anónimo).
      properties:
        project_id:
          type:
            - string
            - "null"
          format: uuid
          description: Un proyecto; ausente, `null` o vacío = todos.
    Harness:
      type: object
      description: Un CLI de agentes y su estado en un runtime (tipo Go `Harness`).
      required:
        - id
        - name
        - color
        - installable
        - can_login
        - key_set
        - installed
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
        docs:
          type: string
        installable:
          type: boolean
          description: Se puede instalar desde la web.
        method:
          type: string
          description: "`npm` o `script`."
        package:
          type: string
          description: Paquete npm o URL del instalador.
        pinned:
          type: string
          description: Versión fijada que se instala.
        can_login:
          type: boolean
        login_hint:
          type: string
        key_env:
          type: string
          description: Variable de la API key, si el CLI la admite.
        key_set:
          type: boolean
          description: La máquina tiene guardada esa API key.
        installed:
          type: boolean
        version:
          type: string
        path:
          type: string
        auth:
          type: string
          description: "`ok`, `missing` o `unknown`."
    HarnessKeyRequest:
      type: object
      description: Cuerpo de `PUT /runtimes/{rid}/harnesses/{hid}/key` (struct anónimo).
      required:
        - value
      properties:
        value:
          type: string
          minLength: 8
          description: La API key; sin espacios, tabuladores ni saltos de línea.
    HostRuntimeStatus:
      type: object
      description: El estado del runtime de la máquina del servidor (tipo Go `HostRuntimeStatus`).
      required:
        - available
        - hostname
        - os
        - arch
        - providers
        - home
        - enabled
        - running
      properties:
        available:
          type: boolean
          description: El servidor permite usar su máquina (`HOST_RUNTIME`).
        reason:
          type: string
          description: Por qué no está disponible.
        hostname:
          type: string
        os:
          type: string
        arch:
          type: string
        providers:
          type: array
          description: CLIs detectados en la máquina del servidor (vacío si no está disponible).
          items:
            $ref: "#/components/schemas/Detected"
        home:
          type: string
          description: Carpeta del runtime del workspace en la máquina del servidor.
        runtime_id:
          type:
            - string
            - "null"
          format: uuid
          description: El runtime del workspace, si ya existe.
        enabled:
          type: boolean
        running:
          type: boolean
          description: Su proceso corre ahora.
        error:
          type: string
    Issue:
      type: object
      required:
        - id
        - number
        - key
        - title
        - description
        - status
        - priority
        - creator_type
        - labels
        - created_at
        - updated_at
        - comment_count
        - last_checkpoint
      properties:
        id:
          type: string
          format: uuid
        number:
          type: integer
          description: Número del issue en el workspace.
        key:
          type: string
          description: Prefijo del workspace y número (p. ej. `HQF-12`).
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - backlog
            - todo
            - in_progress
            - in_review
            - done
            - cancelled
        priority:
          type: string
          enum:
            - none
            - low
            - medium
            - high
            - urgent
        project_id:
          type:
            - string
            - "null"
          format: uuid
        project_name:
          type:
            - string
            - "null"
        assignee_type:
          type:
            - string
            - "null"
          enum:
            - user
            - agent
            - system
            - null
        assignee_id:
          type:
            - string
            - "null"
          format: uuid
        assignee_name:
          type:
            - string
            - "null"
          description: Nombre del usuario o del agente asignado.
        creator_type:
          type: string
          enum:
            - user
            - agent
            - system
        creator_id:
          type:
            - string
            - "null"
          format: uuid
        creator_name:
          type:
            - string
            - "null"
        labels:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        task_status:
          type:
            - string
            - "null"
          enum:
            - queued
            - claimed
            - running
            - blocked
            - completed
            - failed
            - cancelled
            - null
          description: Estado de la tarea más reciente del issue.
        comment_count:
          type: integer
        sdlc_track:
          type:
            - string
            - "null"
          enum:
            - feature
            - bug
            - chore
            - incident
            - null
          description: Pista del pipeline SDLC (null = sin pipeline).
        sdlc_branch:
          type:
            - string
            - "null"
          description: Rama del issue en el pipeline.
        sdlc_stage:
          type:
            - string
            - "null"
          enum:
            - plan
            - design
            - build
            - test
            - deploy
            - maintain
            - null
          description: Etapa actual (la primera, en el orden del bucle, que está active, awaiting_approval o blocked).
        sdlc_stage_state:
          type:
            - string
            - "null"
          enum:
            - active
            - awaiting_approval
            - blocked
            - null
        last_checkpoint:
          description: El último checkpoint de cualquier tarea del issue (`step`, `created_at`, `task_id`), o `null` (JSON tal
            cual).
    IssueAudienceSelfLoss:
      type: object
      description: Respuesta cuando quien crea o modifica el issue no lo ve (mapa literal en createIssue y patchIssue).
      required:
        - id
        - audience_self_loss
        - notice
      properties:
        id:
          type: string
          format: uuid
        audience_self_loss:
          type: boolean
          const: true
        notice:
          type: string
          description: Aviso en el idioma de quien pide.
    IssueExternal:
      type: object
      description: El work item enlazado al issue (`IssueExternal`).
      required:
        - connector
        - system
        - id
        - url
        - title
      properties:
        connector:
          type: string
          description: Nombre del conector.
        system:
          type: string
          description: Tipo de conector (p. ej. `azure_devops`, `jira`).
        id:
          type: string
        url:
          type: string
        title:
          type: string
    IssueInput:
      type: object
      description: |
        Cuerpo de `POST /issues` y `PATCH /issues/{num}` (`issueIn`). Al crear, `title` es obligatorio salvo
        que importes con `external`. En PATCH sólo cambian los campos presentes; `project_id` y `assignee_id`
        cuentan si la clave está, aunque sea null o vacía.
      properties:
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - backlog
            - todo
            - in_progress
            - in_review
            - done
            - cancelled
        priority:
          type: string
          enum:
            - none
            - low
            - medium
            - high
            - urgent
        project_id:
          type:
            - string
            - "null"
          format: uuid
          description: Vacío o null = sin proyecto.
        assignee_type:
          type:
            - string
            - "null"
          enum:
            - user
            - agent
            - ""
            - null
          description: Sólo cuenta junto a `assignee_id`.
        assignee_id:
          type:
            - string
            - "null"
          format: uuid
          description: Vacío o null = sin asignar. Si falta `assignee_type` o `assignee_id`, el issue queda sin asignar.
        labels:
          type: array
          items:
            type: string
        confirm_audience:
          type: boolean
          description: Confirmas que más personas verán el issue al moverlo o reasignarlo.
        confirm_self_loss:
          type: boolean
          description: Confirmas que dejarás de ver el issue (o que no verás el que creas).
        external:
          type: object
          description: Sólo al crear. Importa un work item del conector.
          properties:
            connector:
              type: string
              description: Nombre del conector del workspace.
            id:
              type: string
              description: Id del work item. Vacío = no se importa.
    IssueSDLCView:
      type: object
      description: La vista SDLC de un issue (mapa literal de `sdlcView`).
      required:
        - issue_number
        - enabled
        - project_mode
        - track
        - branch
        - stages
        - artifacts
        - busy
        - next
        - gaps_open
        - source_of_truth
        - external
        - can_link
        - pushed
        - waiting_runtime
        - repro_pending
        - locked_tests
        - can_accept_repro
        - can_unlock_tests
      properties:
        issue_number:
          type: integer
        enabled:
          type: boolean
          description: El issue sigue el pipeline y su proyecto tiene el SDLC activado.
        project_mode:
          type: string
          enum:
            - off
            - manual
            - semi
            - auto
        track:
          type:
            - string
            - "null"
        branch:
          type:
            - string
            - "null"
        stages:
          type: array
          items:
            $ref: "#/components/schemas/StageRow"
        artifacts:
          type: array
          description: La última versión de cada tipo, sin `content`.
          items:
            $ref: "#/components/schemas/ArtifactRow"
        busy:
          type: boolean
          description: Hay una jugada en curso.
        next:
          type:
            - object
            - "null"
          description: La siguiente jugada que lanzaría «Siguiente jugada» (sólo con el pipeline activo).
          properties:
            play:
              type: string
            stage:
              type: string
            can_launch:
              type: boolean
            role:
              type: string
        gaps_open:
          type: integer
        source_of_truth:
          type: string
          description: repo, link o external ("" si el issue no sigue el pipeline).
        external:
          oneOf:
            - $ref: "#/components/schemas/IssueExternal"
            - type: "null"
        can_link:
          $ref: "#/components/schemas/SDLCDecision"
        pushed:
          type:
            - object
            - "null"
          description: Lo último que se empujó de la rama del issue.
          properties:
            ref:
              type: string
            sha:
              type: string
            at:
              type:
                - string
                - "null"
              format: date-time
        waiting_runtime:
          oneOf:
            - $ref: "#/components/schemas/WaitingRuntime"
            - type: "null"
        repro_pending:
          type: boolean
          description: Un repro que falla espera que un engineer lo confirme.
        locked_tests:
          type: integer
          description: Tests bloqueados sin desbloquear.
        can_accept_repro:
          type: boolean
        can_unlock_tests:
          type: boolean
        review:
          $ref: "#/components/schemas/ReviewView"
    Lesson:
      type: object
      required:
        - body
      properties:
        section:
          type: string
        body:
          type: string
          minLength: 12
        scope:
          type: string
          description: "`workspace`, `project` o `agent` (por defecto, el proyecto si lo hay)."
    LinkRuntimeRepoRequest:
      type: object
      description: Cuerpo de `PUT /runtimes/{rid}/repos/{pid}` (struct anónimo).
      properties:
        path:
          type: string
          description: Carpeta del repo en la máquina del runtime.
    LinkRuntimeRepoResponse:
      type: object
      description: Respuesta de `PUT /runtimes/{rid}/repos/{pid}` (struct anónimo).
      required:
        - repo
        - config
      properties:
        repo:
          oneOf:
            - $ref: "#/components/schemas/RuntimeRepoInfo"
            - type: "null"
        warning:
          type: string
          description: El `origin` de la carpeta no coincide con el repo del proyecto.
        config:
          $ref: "#/components/schemas/RuntimeConfig"
    LockedTest:
      type: object
      description: Un test bloqueado del issue (`LockedTest`). Las fechas, como texto de PostgreSQL.
      required:
        - path
        - blob_sha
        - locked_at
        - unlocked_at
        - unlocked_by_name
      properties:
        path:
          type: string
        blob_sha:
          type: string
        locked_at:
          type: string
          description: Texto de `timestamptz` (p. ej. `2026-11-15 10:00:00.123+00`).
        unlocked_at:
          type:
            - string
            - "null"
          description: Igual que `locked_at`.
        unlocked_by_name:
          type:
            - string
            - "null"
    Manifest:
      type: object
      description: Todo lo que sale a GitHub al empujar la rama de un issue high o marcado.
      required:
        - repo_id
        - repo_url
        - branch
        - base
        - sha
        - commits
        - frontier
        - pr_title
        - pr_body
        - check
      properties:
        repo_id:
          type: integer
        repo_url:
          type: string
        branch:
          type: string
        base:
          type: string
        sha:
          type: string
        commits:
          type: array
          items:
            $ref: "#/components/schemas/Commit"
        frontier:
          type: array
          description: Los padres de los commits que no están en `commits` (sin commits nuevos, `[sha]`), ordenados.
          items:
            type: string
        pr_title:
          type: string
        pr_body:
          type: string
        check:
          type: string
    MarkFindingExpectedRequest:
      type: object
      required:
        - finding_id
      properties:
        finding_id:
          type: integer
        expected:
          type: boolean
          description: true para marcarlo esperado, false para desmarcarlo.
    MeResponse:
      type: object
      description: Tu usuario y si eres administrador de la instancia (respuesta de `GET /api/me`).
      required:
        - id
        - email
        - name
        - locale
        - instance_admin
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        name:
          type: string
        locale:
          type: string
          description: Idioma (`es` o `en`).
        instance_admin:
          type: boolean
          description: Si puedes usar runtimes en la máquina del servidor (INSTANCE_ADMINS o la primera cuenta).
    MemberRow:
      type: object
      description: Un miembro del workspace.
      required:
        - user_id
        - email
        - name
        - role
        - created_at
      properties:
        user_id:
          type: string
          format: uuid
        email:
          type: string
        name:
          type: string
        role:
          type: string
          enum:
            - owner
            - admin
            - member
        created_at:
          type: string
          format: date-time
          description: Cuándo entró en el workspace.
    NotificationPref:
      type: object
      description: |
        La preferencia de notificación de una categoría. Al guardarla, un booleano que no venga cuenta como
        `false`.
      required:
        - category
        - in_app
        - browser
      properties:
        category:
          type: string
          enum:
            - questions
            - permissions
            - gates
            - quota
            - ci
            - teardown
        in_app:
          type: boolean
          description: Avisar en la app.
        browser:
          type: boolean
          description: Avisar con notificaciones del navegador.
    OpenTerminalRequest:
      type: object
      description: Cuerpo de `POST /terminals` (struct anónimo).
      properties:
        runtime_id:
          type: string
          format: uuid
          description: Obligatorio si no das un `task_id` válido.
        task_id:
          type: string
          format: uuid
          description: Abre la shell en el worktree de la tarea; su runtime manda sobre `runtime_id`.
        cols:
          type: integer
        rows:
          type: integer
        command:
          type: string
          description: Atajo que la terminal escribe al abrirse (`harness-install:<id>`, `harness-upgrade:<id>`,
            `harness-login:<id>`, `claude-login`) o vacío.
    PatchDiffCommentRequest:
      type: object
      properties:
        body:
          type:
            - string
            - "null"
        status:
          type:
            - string
            - "null"
          enum:
            - open
            - resolved
            - null
    PatchMeRequest:
      type: object
      properties:
        name:
          type: string
          description: Tu nombre (no se valida).
        locale:
          type: string
          description: Tu idioma; lo que empieza por `en` es `en`, cualquier otro valor `es`.
    PatchMemberRequest:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - owner
            - admin
            - member
          description: No puede ser superior al tuyo.
    PatchRuntimeRequest:
      type: object
      description: Cuerpo de `PATCH /runtimes/{rid}` (struct anónimo). Al menos un campo.
      properties:
        name:
          type: string
          description: De 1 a 64 caracteres (sin espacios alrededor).
        max_parallel:
          type: integer
          description: El daemon admite de 1 a 32.
        task_timeout:
          type: string
          description: Duración; el daemon admite de `1m` a `72h`.
    PatchWorkspaceRequest:
      type: object
      properties:
        name:
          type: string
        issue_prefix:
          type: string
          description: Se guarda en mayúsculas.
        locale:
          type: string
          description: Normalizado a `es` o `en`.
        monthly_budget_usd:
          type: number
          minimum: 0
          maximum: 1000000
          description: Tope de gasto de agentes al mes en USD; 0 lo quita.
        quota_hold_threshold:
          type: number
          minimum: 0.5
          maximum: 1
          description: Umbral de retención por cuota proactiva. Sólo con la sesión del navegador.
        search_audit_days:
          type: integer
          minimum: 1
          maximum: 365
          description: Días de retención de la auditoría de búsquedas. Sólo con la sesión del navegador.
    PermCreateIn:
      type: object
      required:
        - run_id
        - tool_use_id
        - tool_name
      properties:
        run_id:
          type: string
          maxLength: 100
        tool_use_id:
          type: string
          maxLength: 200
        tool_name:
          type: string
          pattern: ^[A-Za-z0-9_.:\-]{1,200}$
        input:
          description: La entrada de la herramienta (un objeto JSON). Sin ella con `auto` `denied`.
        description:
          type: string
          description: Se guarda limpia y recortada a 4 KB.
        auto:
          type: string
          enum:
            - allowed
            - denied
            - ""
          description: Lo que ya decidió el daemon (vacío = a la bandeja).
        argv:
          type: array
          description: Con `auto` `allowed`, el argv que aprobó la lista permitida en el daemon.
          items:
            type: string
        reason:
          type: string
          description: Con `auto` `denied`, `too_large` o `l1`.
        input_bytes:
          type: integer
          description: Con `auto` `denied` y `too_large`, el tamaño de la entrada (sólo auditoría).
    PermOut:
      type: object
      required:
        - id
        - status
        - input_sha256
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - approved
            - denied
        input_sha256:
          type: string
          description: Hash canónico de la entrada (vacío si el daemon la negó sin mandarla).
        reason:
          type: string
          description: |
            Por qué se negó sola: `too_large`, `l1`, `secret_unreviewable`, `timeout_sticky`, `too_many` o
            `one_pending`.
    PermissionRequest:
      type: object
      description: Una solicitud de permiso de un agente supervisado (`PermissionRequest`).
      required:
        - id
        - task_id
        - issue_key
        - issue_number
        - issue_title
        - agent_name
        - tool_name
        - input_redacted
        - input_sha256
        - status
        - host_exec
        - requested_at
        - hidden_chars
        - argv
        - can_decide
      properties:
        id:
          type: string
          format: uuid
        task_id:
          type: string
          format: uuid
        issue_key:
          type: string
        issue_number:
          type: integer
        issue_title:
          type: string
          description: Vacío si `limited`.
        agent_name:
          type: string
          description: Vacío si `limited`.
        project_id:
          type:
            - string
            - "null"
          format: uuid
        project_name:
          type:
            - string
            - "null"
        tool_name:
          type: string
        input_redacted:
          type: string
          description: La entrada de la herramienta, redactada.
        description:
          type:
            - string
            - "null"
        input_sha256:
          type: string
          description: Hash de la entrada sin redactar; hay que mandarlo al aprobar.
        status:
          type: string
          description: pending, approved, denied, expired o cancelled.
        host_exec:
          type: boolean
          description: Se ejecuta en la máquina del dueño del runtime, sin sandbox.
        runtime_name:
          type:
            - string
            - "null"
        runtime_owner_name:
          type:
            - string
            - "null"
        requested_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - "null"
          format: date-time
        expired_at:
          type:
            - string
            - "null"
          format: date-time
        decided_by_name:
          type:
            - string
            - "null"
        decided_via:
          type:
            - string
            - "null"
          description: owner, delegate o eligible.
        decided_at:
          type:
            - string
            - "null"
          format: date-time
        reason:
          type:
            - string
            - "null"
        hidden_chars:
          type: integer
          description: Caracteres invisibles quitados de la entrada.
        auto:
          type:
            - string
            - "null"
          description: allowed o denied si se decidió sola.
        argv:
          type:
            - array
            - "null"
          items:
            type: string
        can_decide:
          type: boolean
        cannot_decide_reason:
          type: string
          description: Por qué no puedes decidir (sale si no está vacío).
        limited:
          type: boolean
          description: Quien la lee no ve su tarea (dueño del runtime o delegado).
    Project:
      type: object
      description: Un proyecto del workspace (`Project`).
      required:
        - id
        - slug
        - name
        - description
        - repo_url
        - default_branch
        - require_review
        - approval_role
        - auto_open_pr
        - created_at
        - open_issues
        - github_repo
        - max_task_wall_time_hours
        - live_steering
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        repo_url:
          type: string
        default_branch:
          type: string
        require_review:
          type: boolean
        approval_role:
          type: string
          enum:
            - auto
            - member
            - admin
          description: Quién aprueba tareas (auto = admins si el repo es de GitHub, members si no).
        auto_open_pr:
          type: boolean
          description: Al completar una tarea (SDLC apagado) se sube la rama y se abre el PR; nunca se integra.
        created_at:
          type: string
          format: date-time
        open_issues:
          type: integer
          description: Issues abiertos (ni done ni cancelled) que ve quien pide.
        github_repo:
          type:
            - string
            - "null"
          description: "`owner/name` si `repo_url` es de GitHub."
        max_task_wall_time_hours:
          type: integer
          description: Tope de tiempo total por tarea, con las esperas (horas).
        live_steering:
          type:
            - boolean
            - "null"
          description: Conducción en vivo (null = por defecto, activa con SDLC).
    ProjectInput:
      type: object
      description: Cuerpo de `POST /projects` y `PATCH /projects/{pid}` (`projectIn`). Todo opcional salvo `name` al crear.
      properties:
        name:
          type: string
        slug:
          type: string
          description: Sólo al crear. Si no viene, sale del nombre.
        description:
          type: string
        repo_url:
          type: string
          description: Se recortan los espacios.
        default_branch:
          type: string
        require_review:
          type: boolean
          description: "Deprecado: `false` se guarda como `true`."
        approval_role:
          type: string
          enum:
            - auto
            - member
            - admin
          description: Admin y sesión del navegador.
        auto_open_pr:
          type: boolean
          description: Admin y sesión del navegador.
        max_task_wall_time_hours:
          type: integer
          minimum: 1
          maximum: 168
          description: Sólo en PATCH.
        live_steering:
          type:
            - boolean
            - "null"
          description: Sólo en PATCH. null = vuelve al valor por defecto.
    ProjectRef:
      type: object
      required:
        - id
        - slug
        - name
        - repo_url
        - default_branch
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        repo_url:
          type: string
        default_branch:
          type: string
    ProjectRolesView:
      type: object
      description: Respuesta de los roles del proyecto (mapa literal en getProjectRoles).
      required:
        - roles
        - available
        - can_edit
      properties:
        roles:
          type: array
          items:
            $ref: "#/components/schemas/RoleRow"
        available:
          type: array
          description: Los roles de proyecto que existen.
          items:
            type: string
        can_edit:
          type: boolean
          description: Eres admin del workspace u owner de la organización.
    Provider:
      type: object
      description: Un CLI de agentes del catálogo del servidor (tipo Go `agentcli.Provider`).
      required:
        - id
        - name
        - binaries
        - stream
        - color
        - docs
        - setup
      properties:
        id:
          type: string
        name:
          type: string
        binaries:
          type:
            - array
            - "null"
          description: Ejecutables que se buscan en el PATH; `null` en `custom`.
          items:
            type: string
        stream:
          type: string
          description: Dialecto de la salida estructurada en headless (`claude`, `codex`, `cursor` o `text`).
        color:
          type: string
        docs:
          type: string
        setup:
          $ref: "#/components/schemas/Setup"
    PublishIncident:
      type: object
      description: Lo que GitHub tiene distinto de lo confirmado al publicar (`publishIncident`).
      required:
        - id
        - issue_key
        - issue_number
        - task_id
        - manifest_hash
        - kind
        - detail
        - created_at
      properties:
        id:
          type: string
          format: uuid
        issue_key:
          type: string
        issue_number:
          type: integer
        task_id:
          type:
            - string
            - "null"
          format: uuid
        manifest_hash:
          type: string
        kind:
          type: string
          enum:
            - mismatch
            - unverifiable
        detail:
          description: JSON con el detalle del incidente.
        created_at:
          type: string
          format: date-time
    PublishRequest:
      type: object
      properties:
        confirm_publish:
          type: string
          description: El hash del manifiesto que viste (`hash` de `publish_confirm`).
        confirm_redacted:
          type: boolean
          description: Confirmas que los commits llevan secretos que aquí salen redactados.
    PushedIn:
      type: object
      description: Lo que el daemon cuenta de un empuje de la rama del issue.
      properties:
        ref:
          type: string
        sha:
          type: string
        head:
          type: string
          description: HEAD de la rama del issue (se guarda en el issue).
        error:
          type: string
        reason:
          type: string
          description: Por qué no se empujó (p. ej. `skipped_code`).
        revoke_error:
          type: string
          description: Se empujó pero el token no se pudo revocar.
    PutConnectorRequest:
      type: object
      required:
        - kind
        - base_url
      properties:
        kind:
          type: string
          enum:
            - azure_devops
            - jira
        base_url:
          type: string
          description: "`https://…` sin credenciales, query ni fragmento (`http://` sólo con CONNECTORS_ALLOW_HTTP=true)."
        project:
          type: string
        api_version:
          type: string
          description: Azure DevOps; por defecto `7.0`.
        username:
          type: string
          description: Jira (obligatorio); el correo de la cuenta del token.
        token:
          type: string
          description: El PAT. Obligatorio al crear; vacío al editar conserva el guardado.
    PutGitHubRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: Token de GitHub (se recortan espacios).
    PutHostRuntimeRequest:
      type: object
      description: Cuerpo de `PUT /host-runtime` (struct anónimo).
      properties:
        enabled:
          type: boolean
    PutMyGitHubLoginRequest:
      type: object
      required:
        - login
      properties:
        login:
          type: string
          maxLength: 39
          description: Tu login de GitHub (se admite con `@` delante).
    PutNotificationPrefsRequest:
      type: object
      properties:
        prefs:
          type: array
          maxItems: 6
          items:
            $ref: "#/components/schemas/NotificationPref"
    PutOrganizationPolicyRequest:
      type: object
      description: Tiene que venir al menos uno de los dos campos.
      properties:
        require_four_eyes:
          type: boolean
        forbid_host_approval_delegation:
          type: boolean
    PutOrganizationRolesRequest:
      type: object
      properties:
        roles:
          type: array
          maxItems: 500
          items:
            $ref: "#/components/schemas/RoleIn"
    QuotaCompletionIn:
      type: object
      description: Con `status` `quota`, el límite que cortó la ejecución.
      properties:
        provider:
          type: string
          description: Si llega, tiene que ser el del agente de la tarea.
        window:
          type: string
        resets_at:
          type:
            - string
            - "null"
          format: date-time
    QuotaHold:
      type: object
      description: Una tarea en cola retenida por cuota (`quotaHold`).
      required:
        - provider
      properties:
        provider:
          type: string
        until:
          type: string
          format: date-time
        detail:
          type: string
          description: Sólo para el dueño del runtime y los admins.
        runtime:
          type: string
    QuotaIn:
      type: object
      description: Una ventana de cuota de un proveedor, según el daemon.
      properties:
        provider:
          type: string
        window:
          type: string
          description: Nombre de la ventana (`^[a-z0-9_-]{1,40}$`).
        used_fraction:
          type:
            - number
            - "null"
        resets_at:
          type:
            - string
            - "null"
          format: date-time
        credits_remaining:
          type:
            - number
            - "null"
        status:
          type: string
        using_overage:
          type: boolean
        source:
          type: string
        observed_at:
          type: string
          format: date-time
    QuotaSuspectIn:
      type: object
      description: La tarea falló con algo que parece un límite no reconocido (nunca el texto del error).
      properties:
        provider:
          type: string
        reason:
          type: string
          enum:
            - rejected_without_limit
            - limit_error
    QuotaWindow:
      type: object
      description: Una ventana de cuota leída del proveedor (tipo Go `quotaWindow`).
      required:
        - window
        - source
        - observed_at
      properties:
        window:
          type: string
        used_fraction:
          type:
            - number
            - "null"
        resets_at:
          type:
            - string
            - "null"
          format: date-time
        credits_remaining:
          type: number
        status:
          type: string
        using_overage:
          type: boolean
        source:
          type: string
          description: "`reactive` o `proactive`."
        observed_at:
          type: string
          format: date-time
    ReauthRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: El código que acabas de pedir con `POST /api/auth/request-code`.
    Recipe:
      type: object
      description: La receta de una jugada en un proyecto (`Recipe`).
      required:
        - play
        - agent_id
        - model
        - effort
        - template
        - updated_by
        - updated_at
      properties:
        play:
          type: string
          enum:
            - resolve-conflicts
            - fix-ci
        agent_id:
          type:
            - string
            - "null"
          format: uuid
        model:
          type: string
        effort:
          type: string
        template:
          type: string
        updated_by:
          type:
            - string
            - "null"
          format: uuid
        updated_at:
          type:
            - string
            - "null"
          format: date-time
    RegisterRuntimeRequest:
      type: object
      description: Cuerpo de `POST /runtimes/register` (struct anónimo).
      properties:
        name:
          type: string
        hostname:
          type: string
        os:
          type: string
        arch:
          type: string
        providers:
          description: JSON con los CLIs detectados (`json.RawMessage`); se guarda tal cual (vacío = `[]`).
        runtime_id:
          type: string
          description: Para volver a registrar un runtime tuyo (rota el token).
    RemoteInput:
      type: object
      description: Cuerpo para conectar o reinstalar una máquina por SSH (tipo Go `remoteIn`).
      properties:
        name:
          type: string
        kind:
          type: string
          enum:
            - vps
            - ec2
        host:
          type: string
          description: IP o nombre DNS; acepta `ssh://`, `usuario@host` y `host:puerto`.
        port:
          type: integer
          minimum: 1
          maximum: 65535
        user:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_.-]{0,31}$
        auth:
          type: string
          enum:
            - workspace_key
            - private_key
            - password
        private_key:
          type: string
          description: Clave privada (PEM) para `auth` `private_key`.
        passphrase:
          type: string
          description: Contraseña de la clave privada, si está cifrada.
        password:
          type: string
          description: Contraseña SSH para `auth` `password`.
        server_url:
          type: string
          description: "`http(s)://host[:puerto]` con la que la máquina llega al servidor."
        trust_host_key:
          type: boolean
          description: Olvida la clave del host fijada y acepta la nueva.
        allow_insecure:
          type: boolean
          description: Aceptas una `server_url` `http://` pública.
    RemoteRuntime:
      type: object
      description: El detalle de la conexión SSH de un runtime remoto (tipo Go `RemoteRuntime`).
      required:
        - runtime_id
        - kind
        - host
        - port
        - user
        - auth
        - host_key_fingerprint
        - server_url
        - state
        - error
        - error_code
        - log
        - service
        - remote_home
        - os_name
        - updated_at
        - busy
      properties:
        runtime_id:
          type: string
          format: uuid
        kind:
          type: string
          description: "`vps` o `ec2`."
        host:
          type: string
        port:
          type: integer
        user:
          type: string
        auth:
          type: string
          description: "`workspace_key`, `private_key` o `password`."
        host_key_fingerprint:
          type: string
          description: Huella de la clave del host fijada en la primera conexión.
        server_url:
          type: string
        state:
          type: string
          description: "`installing`, `starting`, `stopping`, `ready`, `stopped` o `error`."
        error:
          type: string
        error_code:
          type: string
        log:
          type: string
          description: Log de la última operación.
        service:
          type: string
          description: "`systemd`, `background` o vacío (nunca se instaló)."
        remote_home:
          type: string
        os_name:
          type: string
        updated_at:
          type: string
          format: date-time
        busy:
          type: boolean
          description: Hay una operación en curso.
    RequestCodeRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          maxLength: 254
          description: Tu correo; se normaliza a minúsculas sin espacios y tiene que llevar `@`.
        locale:
          type: string
          description: Idioma del correo (`en…` inglés; cualquier otro, español).
    ResumeMetrics:
      type: object
      description: Métrica de reanudación de sesiones del proyecto en los últimos 30 días (`ResumeMetrics`).
      required:
        - days
        - continuations
        - resumed
        - resume_pct
        - refused
        - no_session
      properties:
        days:
          type: integer
          description: La ventana (30).
        continuations:
          type: integer
          description: Continuaciones reclamadas en la ventana.
        resumed:
          type: integer
        resume_pct:
          type: number
          description: Porcentaje reanudado, con un decimal.
        refused:
          type: object
          description: Motivo de rechazo (`not_isolated`, `play`, `status_*`, `audience`… u `other`) → número.
          additionalProperties:
            type: integer
        no_session:
          type: integer
          description: Continuaciones sin sesión que reanudar (nunca negativo).
    ReviewIn:
      type: object
      properties:
        commit_sha:
          type: string
        findings:
          type: array
          items:
            $ref: "#/components/schemas/Finding"
        stats:
          $ref: "#/components/schemas/ReviewStats"
        passes:
          type: array
          items:
            type: string
        from_file:
          type: boolean
        invalid:
          type: string
    ReviewStats:
      type: object
      required:
        - important
        - nits
        - ignored
        - general
        - over_cap
        - duplicate
        - redacted
      properties:
        important:
          type: integer
        nits:
          type: integer
        ignored:
          type: integer
        general:
          type: integer
        over_cap:
          type: integer
        duplicate:
          type: integer
        redacted:
          type: integer
    ReviewView:
      type: object
      description: |
        Lo que la web necesita de Deploy (mapa literal de `reviewView`). Si quien pide no ve el issue, `{}`.
        Las claves desde `head_task_id` sólo salen si hay tarea de código de cabeza.
      properties:
        review_enabled:
          type: boolean
        sweep:
          oneOf:
            - $ref: "#/components/schemas/Sweep"
            - type: "null"
          description: El último barrido del issue.
        wip:
          type:
            - object
            - "null"
          description: Límite WIP del proyecto (null si no hay).
          properties:
            limit:
              type: integer
            held:
              type: boolean
            in_review:
              type: integer
              description: Sólo si no está retenido.
        can_sweep:
          type: boolean
        max_rounds:
          type: integer
        head_task_id:
          type: string
          format: uuid
        commit:
          type: string
        verify:
          type:
            - string
            - "null"
        reviewed_sha:
          type: string
        reviewed:
          type: boolean
        reviewer_available:
          type: boolean
        required:
          type: boolean
          description: La revisión es obligatoria (activa y con revisor).
        l4:
          type: object
          properties:
            status:
              type: string
              description: passed, blocked, missing o mismatch.
            blocking:
              type: integer
            reason:
              type: string
            excluded:
              type:
                - array
                - "null"
              items:
                type: string
            files:
              type: integer
        pr:
          type: object
          properties:
            url:
              type:
                - string
                - "null"
            state:
              type:
                - string
                - "null"
            checks:
              description: JSON de los checks del PR.
        important_open:
          type: integer
        nits_open:
          type: integer
        approvals:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              role:
                type: string
              four_eyes:
                type: boolean
              files:
                type: array
                items:
                  type: string
              at:
                type: string
                format: date-time
        missing:
          type: array
          items:
            type: string
          description: Archivos que ninguna aprobación cubre.
        can_approve:
          type: boolean
        needs_confirm:
          type: boolean
          description: Aprobar exige confirmar que no hay cuatro ojos.
        approve_code:
          type: string
        approve_reason:
          type: string
        covers:
          type:
            - array
            - "null"
          items:
            type: string
        others:
          type: array
          items:
            type: string
          description: Nombres de quién más podría aprobar.
        require_four_eyes:
          type: boolean
        verification:
          type: string
          enum:
            - ci
            - local
        required_checks:
          type:
            - array
            - "null"
          items:
            type: string
        uninspected:
          type: integer
        redacted:
          type: integer
        github_mode:
          type: string
          enum:
            - none
            - pat
            - app
            - app_error
            - app_unverified
    RevisionRow:
      type: object
      description: Una revisión inmutable de la configuración (`RevisionRow`).
      required:
        - id
        - version
        - content
        - sha256
        - status
        - author_name
        - note
        - created_at
      properties:
        id:
          type: string
          format: uuid
        version:
          type: integer
        content:
          description: "JSON guardado: `{mode, config}` de la configuración SDLC."
        sha256:
          type: string
        status:
          type: string
          enum:
            - proposed
            - approved
            - rejected
        author_name:
          type:
            - string
            - "null"
        note:
          type: string
        created_at:
          type: string
          format: date-time
    RoleIn:
      type: object
      description: Un rol a asignar.
      required:
        - role
        - user_id
      properties:
        role:
          type: string
          description: El rol (en la organización, `owner`, `platform_engineer` o `context_owner`).
        scope:
          type: string
          maxLength: 120
          description: Alcance; vacío = todo. Se recortan espacios.
        user_id:
          type: string
          format: uuid
          description: Un miembro del workspace.
    RoleInput:
      type: object
      description: Un rol que asignas (`roleIn`).
      required:
        - role
        - user_id
      properties:
        role:
          type: string
          enum:
            - product_owner
            - engineer
            - code_owner
            - policy_owner
            - context_owner
            - platform_engineer
            - release_manager
            - on_call
        scope:
          type: string
          maxLength: 120
          description: Se recortan los espacios.
        user_id:
          type: string
          format: uuid
          description: Un miembro del workspace.
    RoleRow:
      type: object
      description: Un rol asignado a una persona, con su alcance.
      required:
        - role
        - scope
        - user_id
        - name
        - email
      properties:
        role:
          type: string
          enum:
            - product_owner
            - engineer
            - code_owner
            - policy_owner
            - context_owner
            - platform_engineer
            - release_manager
            - on_call
        scope:
          type: string
          description: Alcance del rol; vacío = todo.
        user_id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
    Runtime:
      type: object
      description: Un runtime (máquina con daemon) del workspace (tipo Go `Runtime`).
      required:
        - id
        - name
        - hostname
        - os
        - arch
        - status
        - providers
        - repo_paths
        - max_parallel
        - task_timeout
        - host_managed
        - host_enabled
        - remote
        - container
        - created_at
        - owner_name
        - owner_id
        - running
        - live
        - pending_consents
        - waiting
        - quota
        - supervised_profile
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        hostname:
          type: string
        os:
          type: string
        arch:
          type: string
        status:
          type: string
          enum:
            - online
            - offline
        providers:
          description: JSON con los CLIs que declaró o detectó el daemon (`json.RawMessage`), p. ej. una lista de `Detected`.
        repo_paths:
          description: JSON con las carpetas de los repos en la máquina por id de proyecto (`json.RawMessage`), p. ej.
            `{"<project_id>":"/home/u/repo"}`.
        max_parallel:
          type: integer
        task_timeout:
          type: string
          description: Tiempo máximo por tarea (duración, p. ej. `30m`); vacío = el del daemon.
        host_managed:
          type: boolean
          description: Lo lanza y supervisa el servidor en su propia máquina.
        host_enabled:
          type: boolean
        host_error:
          type: string
          description: Último error del proceso, sólo en el runtime de la máquina del servidor.
        remote:
          description: |
            JSON de la conexión SSH (`json.RawMessage`) o `null`: `{kind, host, port, user, auth, state, error,
            error_code, service, os_name}`.
        container:
          description: |
            JSON del contenedor Docker (`json.RawMessage`) o `null`: `{container, cpus, memory_mb, state, error,
            error_code, harnesses, image}`.
        last_seen_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
        owner_name:
          type: string
        owner_id:
          type: string
          format: uuid
        running:
          type: integer
          description: Tareas del runtime en `claimed` o `running`.
        live:
          type: boolean
          description: El daemon está conectado ahora por WebSocket.
        outdated:
          type: boolean
          description: El contenedor lleva un `hqf` distinto al de este servidor.
        pending_consents:
          type: integer
          description: Consentimientos pendientes; sólo para su dueño (0 para los demás).
        waiting:
          description: |
            JSON con las tareas en espera del runtime (`json.RawMessage`): una lista de
            `{task_id, issue_key, issue_number, wait_state, wait_until}` para quien ve el issue, o `{occupied: true}`.
        quota:
          type:
            - array
            - "null"
          description: La cuota por proveedor. `null` en las respuestas de crear un runtime (Docker o SSH).
          items:
            $ref: "#/components/schemas/RuntimeQuotaView"
        supervised_profile:
          description: JSON del perfil dedicado de `supervised` (`json.RawMessage`), `{logged_in, checked_at}`, o `null`.
    RuntimeConfig:
      type: object
      description: La configuración del daemon de una máquina (tipo Go `RuntimeConfig`).
      required:
        - name
        - max_parallel
        - task_timeout
        - repos
        - repos_dir
        - worktrees_dir
        - config_path
        - env_keys
      properties:
        name:
          type: string
        max_parallel:
          type: integer
        task_timeout:
          type: string
        repos:
          type:
            - object
            - "null"
          description: Carpeta de cada repo vinculado, por slug o id de proyecto.
          additionalProperties:
            type: string
        repos_dir:
          type: string
        worktrees_dir:
          type: string
        config_path:
          type: string
        env_keys:
          type:
            - array
            - "null"
          description: Nombres de las API keys guardadas en la máquina (nunca sus valores).
          items:
            type: string
        providers:
          type: array
          description: CLIs detectados (cuando se pidió detectar).
          items:
            $ref: "#/components/schemas/Detected"
    RuntimeConsent:
      type: object
      description: Un consentimiento del dueño de un runtime para lo que pide `worktree.yaml` (tipo Go `RuntimeConsent`).
      required:
        - id
        - project_id
        - project_name
        - kind
        - subject_hash
        - subject
        - status
        - requested_at
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        project_name:
          type: string
        kind:
          type: string
          description: "`worktree.setup`, `copy_secrets`, `worktree.link`, `worktree.clone_exceptions` o `supervised.allow`."
        subject_hash:
          type: string
          description: sha256 (hex) de lo que se consiente.
        subject:
          description: JSON con lo que se consiente (`json.RawMessage`).
        status:
          type: string
          enum:
            - pending
            - granted
            - expired
            - revoked
        requested_at:
          type: string
          format: date-time
        requested_task_id:
          type:
            - string
            - "null"
          format: uuid
          description: La tarea que lo pidió, sólo si ves su issue.
        granted_at:
          type:
            - string
            - "null"
          format: date-time
        expires_at:
          type:
            - string
            - "null"
          format: date-time
        revoked_at:
          type:
            - string
            - "null"
          format: date-time
    RuntimeQuotaView:
      type: object
      description: La cuota de un proveedor en un runtime, con lo que ve quien pide (tipo Go `runtimeQuotaView`).
      required:
        - provider
        - held
        - no_data
        - untrusted
        - detail
      properties:
        provider:
          type: string
        held:
          type: boolean
          description: La cuota retiene el claim (límite activo o uso por encima del umbral).
        no_data:
          type: boolean
        untrusted:
          type: boolean
          description: El servidor no se fía de la cuota que informa el runtime.
        limited_until:
          type: string
          format: date-time
          description: Sólo con el detalle.
        limited_window:
          type: string
          description: Sólo con el detalle.
        untrusted_since:
          type: string
          format: date-time
          description: Sólo con el detalle.
        windows:
          type: array
          description: Las ventanas vigentes; sólo con el detalle.
          items:
            $ref: "#/components/schemas/QuotaWindow"
        detail:
          type: boolean
          description: Quien pide ve el detalle (dueño del runtime o admin).
        using_overage:
          type: boolean
          description: La cuenta usa overage (sólo con el detalle).
        can_release:
          type: boolean
          description: Hay un límite activo y quien mira es el dueño del runtime.
    RuntimeRepoInfo:
      type: object
      description: Un repo local inspeccionado por el daemon (tipo Go `RuntimeRepoInfo`).
      required:
        - path
      properties:
        path:
          type: string
        remote:
          type: string
        branch:
          type: string
    SDLCConfig:
      type: object
      description: |
        Configuración SDLC de un proyecto (`sdlc.Config`). En las respuestas sale con los valores por defecto
        completados (pistas, rutas, `source_of_truth: repo`); `plays` y `stages` se omiten si están vacíos.
        Al guardar, un campo desconocido da 400.
      properties:
        mode:
          type: string
          enum:
            - off
            - manual
            - semi
            - auto
        tracks:
          type: object
          description: Pista (feature, bug, chore, incident) → etapas en orden, sin repetir. Una pista con jugadas de código
            necesita deploy después de ellas.
          additionalProperties:
            type: array
            items:
              type: string
              enum:
                - plan
                - design
                - build
                - test
                - deploy
                - maintain
        paths:
          type: object
          description: Tipo de artefacto (intent, spec, plan, postmortem) → ruta relativa al repo en Markdown con `{key}` (p. ej.
            `specs/{key}.md`).
          additionalProperties:
            type: string
        plays:
          type: object
          description: Jugada → qué agente la ejecuta (slug; vacío = el asignado) y qué skills extra carga.
          additionalProperties:
            type: object
            properties:
              agent:
                type: string
              skills:
                type: array
                items:
                  type: string
        stages:
          type: object
          description: Etapa → si sus jugadas se lanzan solas.
          additionalProperties:
            type: object
            properties:
              auto:
                type: boolean
        source_of_truth:
          type: string
          enum:
            - repo
            - link
            - external
          description: "`link` y `external` necesitan `external.connector`."
        external:
          type: object
          properties:
            connector:
              type: string
              description: Nombre de un conector del workspace.
        affinity:
          type: object
          properties:
            offline_takeover_minutes:
              type: integer
              minimum: 0
              maximum: 10080
              description: Minutos offline del runtime afín antes del relevo (0 = 15).
            hidden_refs:
              type: boolean
              description: Empujar el código sin aprobar a `refs/hqf/<key>`.
        verify:
          type: object
          properties:
            command:
              type: array
              maxItems: 32
              description: argv del comando de verificación (sin shell salvo `shell`).
              items:
                type: string
                maxLength: 4096
            shell:
              type: boolean
              description: "`command` es un único script de `sh -c`."
            timeout:
              type: string
              description: Duración de Go entre 1s y 2h (20m por defecto).
            max_rounds:
              type: integer
              minimum: 0
              maximum: 10
            verifier:
              type: string
              enum:
                - ""
                - off
                - advisory
                - required
            precommit:
              type: string
              enum:
                - ""
                - auto
                - off
        guardrails:
          type: object
          properties:
            plan_drift:
              type: string
              enum:
                - ""
                - warn
                - block
                - off
            plan_drift_ignore:
              type: array
              maxItems: 200
              items:
                type: string
            toolchain_paths:
              type: array
              maxItems: 200
              items:
                type: string
            protected:
              type: array
              maxItems: 200
              items:
                type: string
        test_globs:
          type: array
          maxItems: 200
          description: Dónde viven los tests (vacío = los globs por defecto). Globs relativos al repo, sin `..`.
          items:
            type: string
            maxLength: 300
        review:
          type: object
          properties:
            enabled:
              type: boolean
              description: Revisión agéntica antes de aprobar el código (sí por defecto).
            max_nits:
              type: integer
              minimum: 0
              maximum: 50
            max_awaiting_review:
              type: integer
              minimum: 0
              maximum: 100
              description: Límite WIP (0 = sin límite).
        sweep:
          type: object
          properties:
            max_rounds:
              type: integer
              minimum: 0
              maximum: 10
              description: Rondas del barrido (0 = 3).
        ci:
          type: object
          properties:
            required_checks:
              type: array
              maxItems: 50
              description: Checks de CI exigidos para aprobar el código (no puede ser `hqf/approval`).
              items:
                type: string
                maxLength: 200
            app:
              type: string
              description: Slug de la app cuyos check runs cuentan (`github-actions` por defecto).
        supervised:
          type: object
          description: Lista permitida y topes de la bandeja de permisos (vale también con el modo off).
          properties:
            allow:
              type: array
              maxItems: 100
              items:
                type: object
                required:
                  - argv
                properties:
                  argv:
                    type: array
                    minItems: 1
                    maxItems: 32
                    items:
                      type: string
                  vars:
                    type: array
                    items:
                      type: string
                  opts:
                    type: array
                    maxItems: 64
                    items:
                      type: string
            timeout_min:
              type: integer
              description: 1 a 60 (15 por defecto).
            max_requests:
              type: integer
              description: Por tarea, 1 a 200 (30 por defecto).
            max_input_bytes:
              type: integer
              description: 1024 a 262144 (65536 por defecto).
    SDLCDecision:
      type: object
      description: Por qué sí o por qué no puede actuar el usuario (`sdlc.Decision`).
      required:
        - allowed
        - role
      properties:
        allowed:
          type: boolean
        role:
          type: string
          description: Rol con el que se decide.
        fallback:
          type: boolean
          description: El rol no tiene miembros y decidió `approval_role`.
        reason:
          type: string
          description: Por qué no (si no puede).
    SearchIn:
      type: object
      required:
        - q
        - from
        - to
      properties:
        q:
          type: string
          description: Texto a buscar (2–200 caracteres tras limpiarlo).
        from:
          type: string
          format: date-time
          description: Desde (RFC 3339).
        to:
          type: string
          format: date-time
          description: Hasta (RFC 3339), como mucho 90 días después de `from`.
        project_id:
          type:
            - string
            - "null"
          format: uuid
          description: Sólo los issues de este proyecto (el actual del issue).
    SearchResult:
      type: object
      required:
        - task_id
        - issue_number
        - issue_key
        - issue_title
        - kind
        - at
        - snippet
      properties:
        task_id:
          type: string
          format: uuid
        issue_number:
          type: integer
        issue_key:
          type: string
        issue_title:
          type: string
        project_id:
          type:
            - string
            - "null"
          format: uuid
        project_name:
          type:
            - string
            - "null"
        kind:
          type: string
          description: message, tool_call, tool_result, error, steer o question.
        at:
          type: string
          format: date-time
        snippet:
          type: array
          items:
            $ref: "#/components/schemas/SnippetSeg"
        hidden:
          type: boolean
          description: Se quitaron caracteres invisibles del fragmento (sale si es true).
    SecurityAlert:
      type: object
      description: Una alerta de seguridad para los administradores de la instancia.
      required:
        - id
        - kind
        - subject
        - detail
        - created_at
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          description: "`login_email_ceiling`, `login_codes_instance_cap` o `task_token_while_waiting`."
        subject:
          type: string
          description: El sujeto de la alerta (un correo, un hash opaco o vacío, según el tipo).
        detail:
          description: Objeto JSON con el detalle; sus claves dependen de `kind`.
        created_at:
          type: string
          format: date-time
    SendReviewRequest:
      type: object
      properties:
        summary:
          type: string
          description: Resumen que va detrás de los comentarios.
    SessionInfo:
      type: object
      description: Una sesión de terminal abierta (tipo Go `realtime.SessionInfo`).
      required:
        - id
        - runtime_id
        - kind
        - title
        - started_at
        - closed
      properties:
        id:
          type: string
          format: uuid
        runtime_id:
          type: string
          format: uuid
        task_id:
          type: string
        kind:
          type: string
          enum:
            - agent
            - shell
        title:
          type: string
        started_at:
          type: string
          format: date-time
        closed:
          type: boolean
    SetAgentSkillsRequest:
      type: object
      description: Cuerpo de `PUT /agents/{aid}/skills` (struct anónimo).
      properties:
        skill_ids:
          type: array
          items:
            type: string
            format: uuid
    Setup:
      type: object
      description: Cómo instalar y autenticar un CLI desde la terminal del runtime (tipo Go `agentcli.Setup`).
      properties:
        npm:
          type: string
          description: Paquete npm.
        version:
          type: string
          description: Versión fijada que se instala.
        script:
          type: string
          description: URL del instalador oficial.
        login:
          type: array
          description: Orden para iniciar sesión.
          items:
            type: string
        login_hint:
          type: string
        key_env:
          type: string
          description: Variable de la API key, si el CLI la admite.
    Skill:
      type: object
      description: Una skill del workspace (tipo Go `Skill`).
      required:
        - id
        - slug
        - name
        - description
        - version
        - content
        - files
        - updated_at
        - agent_count
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        version:
          type: string
        content:
          type: string
          description: El SKILL.md.
        files:
          description: JSON con los archivos de la skill (`json.RawMessage`), p. ej. `[{"path":"schema.sql","content":"…"}]`.
        updated_at:
          type: string
          format: date-time
        agent_count:
          type: integer
          description: Agentes que usan la skill.
    SkillInput:
      type: object
      description: Cuerpo para crear o cambiar una skill (tipo Go `skillIn`).
      properties:
        name:
          type: string
        slug:
          type: string
          description: Se normaliza; sólo al crear.
        description:
          type: string
        version:
          type: string
        content:
          type: string
        files:
          description: JSON con los archivos (`json.RawMessage`); se guarda tal cual.
    SnippetSeg:
      type: object
      required:
        - text
        - hit
      properties:
        text:
          type: string
        hit:
          type: boolean
          description: El segmento es una palabra que casa.
    StageRow:
      type: object
      description: Una etapa del pipeline de un issue (`StageRow`).
      required:
        - stage
        - state
        - note
        - started_at
        - approved_at
        - approved_by_name
      properties:
        stage:
          type: string
          enum:
            - plan
            - design
            - build
            - test
            - deploy
            - maintain
        state:
          type: string
          enum:
            - pending
            - active
            - awaiting_approval
            - approved
            - skipped
            - blocked
        note:
          type: string
        started_at:
          type:
            - string
            - "null"
          format: date-time
        approved_at:
          type:
            - string
            - "null"
          format: date-time
        approved_by_name:
          type:
            - string
            - "null"
    SteerRequest:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          maxLength: 4096
          description: Hasta 4096 bytes.
    Sweep:
      type: object
      description: Un barrido «hasta verde» (`Sweep`).
      required:
        - id
        - status
        - round
        - max_rounds
        - tokens
        - max_tokens
        - stop_reason
        - started_at
        - finished_at
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - running
            - waiting_checks
            - done
            - stopped
        round:
          type: integer
        max_rounds:
          type: integer
        tokens:
          type: integer
          format: int64
        max_tokens:
          type: integer
          format: int64
        stop_reason:
          type:
            - string
            - "null"
        started_at:
          type: string
          format: date-time
        finished_at:
          type:
            - string
            - "null"
          format: date-time
    Task:
      type: object
      description: Una tarea de un agente (`Task`, `taskSelect` en internal/api/tasks.go).
      required:
        - id
        - issue_id
        - issue_number
        - issue_key
        - issue_title
        - agent_id
        - agent_name
        - agent_slug
        - agent_color
        - provider
        - run_mode
        - status
        - attempt
        - max_attempts
        - trigger
        - prompt
        - tokens_in
        - tokens_out
        - cost_usd
        - tool_calls
        - created_at
        - diff_files
        - additions
        - deletions
        - github_pr
        - play
        - rounds
        - review_stats
        - pr_checks
        - l4
        - redacted_in_diff
        - last_checkpoint
        - consent_required
        - awaiting_answer
        - issue_restricted
        - branch_published
        - publish_retry
      properties:
        id:
          type: string
          format: uuid
        issue_id:
          type: string
          format: uuid
        issue_number:
          type: integer
        issue_key:
          type: string
          description: Prefijo del workspace y número del issue (p. ej. `HQ-12`).
        issue_title:
          type: string
        agent_id:
          type: string
          format: uuid
        agent_name:
          type: string
        agent_slug:
          type: string
        agent_color:
          type: string
        provider:
          type: string
          description: Proveedor del agente.
        run_mode:
          type: string
          description: Modo de ejecución del agente.
        runtime_id:
          type:
            - string
            - "null"
          format: uuid
        runtime_name:
          type:
            - string
            - "null"
        runtime_owner_id:
          type:
            - string
            - "null"
          format: uuid
        status:
          type: string
          enum:
            - queued
            - claimed
            - running
            - blocked
            - completed
            - failed
            - cancelled
          description: queued, claimed, running, blocked, completed, failed, cancelled o pending_verification.
        attempt:
          type: integer
        max_attempts:
          type: integer
        trigger:
          type: string
          description: Qué la lanzó (p. ej. manual, assign, mention, comment, fanout, review, verify, extend, ci, conflicts).
        prompt:
          type: string
          description: El encargo.
        branch:
          type:
            - string
            - "null"
        worktree_path:
          type:
            - string
            - "null"
        base_ref:
          type:
            - string
            - "null"
        fanout_group_id:
          type:
            - string
            - "null"
          format: uuid
        continues:
          type:
            - string
            - "null"
          format: uuid
          description: La tarea que continúa.
        retry_of:
          type:
            - string
            - "null"
          format: uuid
          description: La tarea que reintenta.
        result_summary:
          type:
            - string
            - "null"
        error:
          type:
            - string
            - "null"
        blocker:
          type:
            - string
            - "null"
        tokens_in:
          type: integer
          format: int64
        tokens_out:
          type: integer
          format: int64
        cost_usd:
          type: number
        tool_calls:
          type: integer
        exit_code:
          type:
            - integer
            - "null"
        created_at:
          type: string
          format: date-time
        claimed_at:
          type:
            - string
            - "null"
          format: date-time
        started_at:
          type:
            - string
            - "null"
          format: date-time
        finished_at:
          type:
            - string
            - "null"
          format: date-time
        approved_at:
          type:
            - string
            - "null"
          format: date-time
        merged_at:
          type:
            - string
            - "null"
          format: date-time
        diff_files:
          type: integer
          description: Archivos del diff guardado (0 si no hay).
        additions:
          type: integer
        deletions:
          type: integer
        context_utilization:
          type:
            - number
            - "null"
          description: Fracción del presupuesto de contexto usada.
        context_tokens:
          type:
            - integer
            - "null"
        github_pr:
          type: boolean
          description: El workspace tiene GitHub y el repo del proyecto es de GitHub.
        pushed_at:
          type:
            - string
            - "null"
          format: date-time
        pr_number:
          type:
            - integer
            - "null"
        pr_url:
          type:
            - string
            - "null"
        pr_state:
          type:
            - string
            - "null"
        pr_error:
          type:
            - string
            - "null"
        play:
          type: string
          description: Jugada (las tareas sin SDLC son `build` sin etapa).
        stage:
          type:
            - string
            - "null"
          description: Etapa SDLC (null sin SDLC).
        requested_by:
          type:
            - string
            - "null"
          format: uuid
          description: Quién lanzó la jugada.
        responsible_id:
          type:
            - string
            - "null"
          format: uuid
          description: La persona responsable de la tarea.
        queue_reason:
          type:
            - string
            - "null"
          description: Por qué sigue en cola.
        verify_status:
          type:
            - string
            - "null"
          description: passed, failed, unconfigured, not_permitted, reproduced o not_reproduced.
        error_class:
          type:
            - string
            - "null"
          description: guardrail, verify, verifier, agent, timeout, budget o infra.
        rounds:
          type: integer
          description: Rondas del bucle agente, L2 y verificación.
        review_of:
          type:
            - string
            - "null"
          format: uuid
          description: La tarea de código que revisa.
        reviewed_sha:
          type:
            - string
            - "null"
        review_stats:
          description: JSON de las estadísticas de la revisión, o null.
        sweep_id:
          type:
            - string
            - "null"
          format: uuid
        pr_checks:
          description: JSON de los checks del PR, o null.
        l4:
          description: JSON del veredicto L4, o null.
        commit_sha:
          type:
            - string
            - "null"
        redacted_in_diff:
          type: integer
          description: Secretos redactados en el diff guardado (el commit los conserva).
        last_checkpoint:
          description: JSON `{step, next, created_at}` del último checkpoint de la tarea, o null.
        sensitivity_floor:
          type:
            - string
            - "null"
        consent_required:
          type: boolean
          description: Espera un consentimiento del dueño del runtime.
        wait_state:
          type:
            - string
            - "null"
          description: Subestado de una tarea running (p. ej. quota, input, permission, hibernated).
        wait_since:
          type:
            - string
            - "null"
          format: date-time
        wait_until:
          type:
            - string
            - "null"
          format: date-time
        block_reason:
          type:
            - string
            - "null"
          description: Motivo con que quedó blocked (p. ej. wall_time).
        awaiting_answer:
          type: boolean
          description: Está en blocked, running o claimed con una pregunta o un hueco abiertos.
        defaulted_questions:
          type: array
          description: Sólo en `GET /tasks/{tid}`.
          items:
            type: object
            required:
              - id
              - question
              - default_option
            properties:
              id:
                type: string
                format: uuid
              question:
                type: string
              default_option:
                type: string
        can_extend_wall_time:
          type: boolean
          description: Sólo en `GET /tasks/{tid}`; sale sólo si es true.
        can_retry:
          type: boolean
          description: Sólo en `GET /tasks/{tid}` con sesión del navegador; sale sólo si es true.
        quota_hold:
          $ref: "#/components/schemas/QuotaHold"
        queued_inputs:
          type: integer
          description: Sólo en `GET /tasks/{tid}`; menciones en cola para la siguiente ejecución (sale si no es 0).
        issue_restricted:
          type: boolean
          description: El issue es high o está marcado.
        branch_published:
          type: boolean
          description: La rama de la tarea tiene una publicación confirmada en el issue.
        publish_retry:
          type: boolean
          description: Aprobada en un issue restringido, su empuje no salió y se puede reintentar.
        pr_conflicts:
          type: boolean
          description: Sólo en `GET /tasks/{tid}`; el PR tiene conflictos (sale si es true).
        can_resolve_conflicts:
          type: boolean
          description: Sólo en `GET /tasks/{tid}`; sale si es true.
        can_fix_ci:
          type: boolean
          description: Sólo en `GET /tasks/{tid}`; sale si es true.
    TaskEvent:
      type: object
      required:
        - seq
        - kind
        - payload
        - created_at
      properties:
        seq:
          type: integer
        kind:
          type: string
        payload:
          description: Contenido del evento (JSON tal cual lo guardó el daemon).
        created_at:
          type: string
          format: date-time
    TaskQuestion:
      type: object
      description: Una pregunta estructurada de un agente (`TaskQuestion`).
      required:
        - id
        - task_id
        - issue_id
        - issue_key
        - issue_number
        - issue_title
        - agent_name
        - question
        - options
        - status
        - created_at
        - can_answer
        - can_add_answerers
      properties:
        id:
          type: string
          format: uuid
        task_id:
          type: string
          format: uuid
        issue_id:
          type: string
          format: uuid
        issue_key:
          type: string
        issue_number:
          type: integer
        issue_title:
          type: string
        project_id:
          type:
            - string
            - "null"
          format: uuid
        project_name:
          type:
            - string
            - "null"
        agent_name:
          type: string
        question:
          type: string
        options:
          type: array
          items:
            type: string
          description: Opciones (vacía o entre 2 y 8).
        default_option:
          type:
            - string
            - "null"
        timeout_at:
          type:
            - string
            - "null"
          format: date-time
        restricted_role:
          type:
            - string
            - "null"
          description: product_owner, engineer, code_owner o context_owner.
        status:
          type: string
          description: open, answered, defaulted, expired o cancelled.
        answer:
          type:
            - string
            - "null"
        answered_by_name:
          type:
            - string
            - "null"
        answered_via:
          type:
            - string
            - "null"
          description: web, api, comment, timeout o system.
        answered_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
        gap_id:
          type:
            - string
            - "null"
          format: uuid
        can_answer:
          type: boolean
          description: Sólo se calcula en las abiertas.
        cannot_answer_reason:
          type: string
          description: Por qué no puedes responder (sale si no está vacío).
        can_add_answerers:
          type: boolean
          description: Quien pide es mantenedor del proyecto (sólo en las abiertas).
    TaskSteer:
      type: object
      description: Un mensaje de conducción (o una mención entregada en vivo).
      required:
        - id
        - author
        - source
        - text
        - created_at
      properties:
        id:
          type: string
          format: uuid
        author:
          type: string
          description: Nombre del autor (`?` si ya no existe).
        source:
          type: string
          description: steer o mention.
        text:
          type: string
        created_at:
          type: string
          format: date-time
        delivered_at:
          type:
            - string
            - "null"
          format: date-time
    TeardownProc:
      type: object
      properties:
        pid:
          type: integer
        cmd:
          type: string
          description: Una línea, hasta 200 bytes.
    TokenRow:
      type: object
      description: Un token personal de API (sin su valor).
      required:
        - id
        - name
        - created_at
        - scopes
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        last_used_at:
          type:
            - string
            - "null"
          format: date-time
        expires_at:
          type:
            - string
            - "null"
          format: date-time
          description: "`null` si no caduca."
        created_at:
          type: string
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - api
              - runtime
    UsageIn:
      type: object
      description: Los acumulados del CLI de una sesión.
      properties:
        cost_usd:
          type: number
        tokens_in:
          type: integer
        tokens_out:
          type: integer
        cache_read:
          type: integer
    UsageRow:
      type: object
      description: El uso de un agente en un día (`usageRow`, internal/api/tasks.go:1263).
      required:
        - day
        - agent_id
        - agent_name
        - tasks
        - completed
        - failed
        - tokens_in
        - tokens_out
        - cost_usd
      properties:
        day:
          type: string
          format: date-time
          description: El día, truncado a medianoche.
        agent_id:
          type: string
          format: uuid
        agent_name:
          type: string
        tasks:
          type: integer
        completed:
          type: integer
        failed:
          type: integer
        tokens_in:
          type: integer
          format: int64
        tokens_out:
          type: integer
          format: int64
        cost_usd:
          type: number
        avg_context_utilization:
          type:
            - number
            - "null"
          description: Utilización media del contexto de los paquetes de esas tareas; null si ninguna tiene paquete.
    User:
      type: object
      description: Una persona usuaria.
      required:
        - id
        - email
        - name
        - locale
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        name:
          type: string
        locale:
          type: string
          description: Idioma (`es` o `en`).
    VerificationIn:
      type: object
      properties:
        round:
          type: integer
        kind:
          type: string
        status:
          type: string
        command:
          type: array
          items:
            type: string
        exit_code:
          type:
            - integer
            - "null"
        duration_ms:
          type: integer
        output_tail:
          type: string
        commit_sha:
          type: string
        executor:
          type: string
        verdict:
          description: El veredicto del verificador (JSON tal cual).
    VerificationRow:
      type: object
      required:
        - id
        - round
        - kind
        - status
        - command
        - output_tail
        - verdict
        - created_at
      properties:
        id:
          type: integer
        round:
          type: integer
        kind:
          type: string
          description: command, precommit o verifier.
        status:
          type: string
          description: passed, failed, timeout, error o invalid.
        command:
          description: El comando (JSON tal cual).
        exit_code:
          type:
            - integer
            - "null"
        duration_ms:
          type:
            - integer
            - "null"
        output_tail:
          type: string
          description: Los últimos 64 KB de la salida, redactados.
        commit_sha:
          type:
            - string
            - "null"
        executor:
          type:
            - string
            - "null"
          description: docker, host o full.
        verdict:
          description: 'Veredicto del verifier (`{"verdict": "pass|fail|unsure", "unmet": [...]}`), o null.'
        created_at:
          type: string
          description: Fecha en el formato de texto de PostgreSQL (no RFC 3339).
    VerifyCodeRequest:
      type: object
      required:
        - email
        - code
      properties:
        email:
          type: string
          description: El correo al que se envió el código (se normaliza).
        code:
          type: string
          description: El código de 6 dígitos (se recortan espacios).
        name:
          type: string
          description: Tu nombre, sólo si se crea la cuenta; vacío = lo que va antes de la `@`.
        locale:
          type: string
          description: Tu idioma, sólo si se crea la cuenta (normalizado a `es` o `en`); vacío = DEFAULT_LOCALE.
    VerifyGrant:
      type: object
      description: Un permiso del dueño de un runtime para ejecutar la verificación en su máquina (tipo Go `VerifyGrant`).
      required:
        - id
        - granted_at
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type:
            - string
            - "null"
          format: uuid
          description: "`null` = todos los proyectos."
        project_name:
          type:
            - string
            - "null"
        granted_at:
          type: string
          description: Fecha en el formato de texto de PostgreSQL (`granted_at::text`, p. ej. `2026-11-15 23:11:00.123+00`), no
            RFC 3339.
    WaitingRuntime:
      type: object
      description: La jugada en cola espera al runtime afín, que está offline (`waitingRuntime`).
      required:
        - name
        - offline_since
        - takeover_minutes
        - takeover_possible
        - restricted
      properties:
        name:
          type: string
        offline_since:
          type: string
          format: date-time
        takeover_minutes:
          type: integer
        takeover_possible:
          type: boolean
          description: Proyecto de GitHub con la rama empujada al día, en un issue que no es high ni está marcado.
        restricted:
          type: boolean
          description: Issue high o marcado; sólo ese runtime puede continuar.
    Workspace:
      type: object
      description: Un workspace, con el rol de quien lo pide.
      required:
        - id
        - slug
        - name
        - issue_prefix
        - locale
        - settings
        - created_at
        - role
        - quota_hold_threshold
        - search_audit_days
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        issue_prefix:
          type: string
          description: Prefijo de los issues (en mayúsculas).
        locale:
          type: string
          description: Idioma del workspace (`es` o `en`).
        settings:
          description: Objeto JSON de ajustes del workspace (p. ej. `monthly_budget_usd`, el tope de gasto mensual).
        created_at:
          type: string
          format: date-time
        role:
          type: string
          enum:
            - owner
            - admin
            - member
          description: Tu rol en el workspace.
        quota_hold_threshold:
          type: number
          description: Umbral de retención por cuota proactiva (por defecto 0,9).
        search_audit_days:
          type: integer
          description: Días que se guarda la auditoría de búsquedas (por defecto 30).
  parameters:
    ws:
      name: ws
      in: path
      required: true
      description: Slug del workspace. Hay que ser miembro (si no, 404 `workspace_not_found`).
      schema:
        type: string
    daemonTid:
      name: tid
      in: path
      required: true
      description: |
        Id de la tarea. Tiene que ser un uuid (si no, 400 `invalid_id`) y estar asignada a tu runtime (si no, 404
        `not_found`).
      schema:
        type: string
        format: uuid
    daemonSid:
      name: sid
      in: path
      required: true
      description: Id del mensaje de conducción en vivo (uuid; si no, 400 `invalid_id`).
      schema:
        type: string
        format: uuid
    daemonPrid:
      name: prid
      in: path
      required: true
      description: Id de la solicitud de permiso (si no es un uuid o no es de tu runtime, 404 `not_found`).
      schema:
        type: string
        format: uuid
    daemonWid:
      name: wid
      in: path
      required: true
      description: Id de la escritura de artefacto pendiente (uuid; si no, 400 `invalid_id`).
      schema:
        type: string
        format: uuid
  responses:
    BadRequest:
      description: Petición inválida (`bad_json`, `invalid` u otro código de validación).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Sin credencial válida (`unauthorized`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: |
        Sin permiso: `forbidden` (rol insuficiente), `session_required` (exige la sesión del navegador),
        `token_scope` (alcance del token) o `instance_admin_required`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: No existe o no lo puedes ver (`not_found`, `workspace_not_found`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: Conflicto con el estado actual (`conflict` u otro código).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Internal:
      description: Error interno (`internal`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    DaemonTaskScope:
      description: |
        `task_scope`: llegó un token de tarea (`hqftk_`) válido en una ruta que no es suya (sólo sirve para
        `comment`, `block`, `remember`, `issue`, `ask`, `status`, `checkpoint`, `questions` y `subtask` de su propia
        tarea). Si esa tarea espera con el proceso detenido, la respuesta es 409 `waiting`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    DaemonTaskWaiting:
      description: |
        `waiting`: el token de tarea está suspendido porque la tarea espera con el proceso detenido (cuota, sesión
        hibernada o una pregunta con reanudación). El uso queda como evento de seguridad.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
