Appendix
Appendix D: Failure Catalog
Los known failure modes del lab. Cada entry tiene un ID, una description, una detection rule, una recovery procedure y una severity.
Propósito
Este appendix es la referencia canónica para los known failure modes del lab. Cada failure mode tiene un ID (F-NNN), una description, una detection rule, una recovery procedure y una severity.
El catalog es la source del runbook (Runbook) y de los audit findings (Audit Model).
How to use this catalog
Cuando ocurre un incident:
- Encontrar el matching failure mode en este catalog.
- Seguir la recovery procedure.
- Si el failure no está en el catalog, documentarlo y añadirlo al catalog.
El catalog es un living document. Se añaden new failure modes según se descubren.
Failure modes
F-001: Coordinator gateway is unreachable
| Field | Value |
|---|---|
| ID | F-001 |
| Severity | Critical |
| Detection | curl -s http://localhost:18789/health devuelve un connection error. |
| Description | El Coordinator gateway no responde. |
| Recovery | Aplicar Runbook → Worker recovery. |
| Prevention | Monitorear el heartbeat; setear un watchdog. |
F-002: Scout gateway is unreachable
| Field | Value |
|---|---|
| ID | F-002 |
| Severity | High |
| Detection | curl -s http://localhost:18790/health devuelve un connection error. |
| Description | El Scout gateway no responde. |
| Recovery | Aplicar Runbook → Worker recovery. |
| Prevention | Monitorear el heartbeat; setear un watchdog. |
F-003: Coding sub-agent is killed by the OS
| Field | Value |
|---|---|
| ID | F-003 |
| Severity | High |
| Detection | El sub-agent sale con code 137; el log muestra Killed. |
| Description | El sub-agent fue killed por el OS (típicamente SIGKILL) porque su task era demasiado grande. |
| Recovery | Aplicar Runbook → Coding Assistant killed by timeout. |
| Prevention | Splittear las tasks en prompts más pequeños; usar progressive prompts. |
F-004: Model quota is exhausted
| Field | Value |
|---|---|
| ID | F-004 |
| Severity | High |
| Detection | El model devuelve 429 o quota_exceeded; el health probe del Coordinator reporta quota_exhausted: true. |
| Description | La quota del model está exhausted. |
| Recovery | Aplicar Runbook → Model quota exhausted. |
| Prevention | Trackear la quota; avisar antes de que se agote. |
F-005: Token pool is exhausted
| Field | Value |
|---|---|
| ID | F-005 |
| Severity | High |
| Detection | Todos los tokens en token_pool_state.json están quota_exhausted; la P3 phase es failed_terminal. |
| Description | Todos los tokens del Perplexity token pool están exhausted. |
| Recovery | Aplicar Runbook → Token pool exhausted. |
| Prevention | Trackear la per-token quota; rotar tokens antes de que se agoten. |
F-006: Browser CDP target is detached
| Field | Value |
|---|---|
| ID | F-006 |
| Severity | High |
| Detection | Las browser actions devuelven connection refused o Target.detached; el CDP port no está listening. |
| Description | Se perdió la connection del browser's DevTools Protocol. |
| Recovery | Aplicar Runbook → Browser CDP target detached. |
| Prevention | Monitorear el browser; reiniciar ante repeated detach. |
F-007: Media Lab Server is not responding
| Field | Value |
|---|---|
| ID | F-007 |
| Severity | Medium |
| Detection | curl -s http://127.0.0.1:8765/api/status devuelve un connection error. |
| Description | El Media Lab Server no responde. |
| Recovery | Aplicar Runbook → Media Lab Server not responding. |
| Prevention | Monitorear el server; reiniciar ante repeated failures. |
F-008: Mission is stuck in a non-terminal state
| Field | Value |
|---|---|
| ID | F-008 |
| Severity | High |
| Detection | El phase.json de una mission lleva en non-terminal state más del timeout. |
| Description | Una mission está stuck; el orchestrator no está progresando. |
| Recovery | Inspeccionar el state; identificar la stuck phase; resumir o cancelar la mission. |
| Prevention | Setear una maximum mission duration; alert ante overrun. |
F-009: Phase fails with failed_terminal
| Field | Value |
|---|---|
| ID | F-009 |
| Severity | High |
| Detection | El status de la phase en phase.json es failed_terminal. |
| Description | Una phase falló de una forma que no se puede reintentar. |
| Recovery | Inspeccionar el error; identificar la cause; reintentar la mission o aceptar el failure. |
| Prevention | Añadir unit tests para la phase; revisar el error message antes de declararlo terminal. |
F-010: External API returns 4xx
| Field | Value |
|---|---|
| ID | F-010 |
| Severity | Medium |
| Detection | El adapter devuelve 4xx. |
| Description | Una external API devolvió un 4xx error (distinto de 429). |
| Recovery | Inspeccionar el error; arreglar la request; reintentar. |
| Prevention | Validar la request antes de enviar; usar un schema validator. |
F-011: External API returns 5xx
| Field | Value |
|---|---|
| ID | F-011 |
| Severity | Medium |
| Detection | El adapter devuelve 5xx. |
| Description | Una external API devolvió un 5xx error. |
| Recovery | Reintentar con exponential backoff; si todos los retries fallan, caer a otro adapter. |
| Prevention | Usar el request journal para detectar patterns; alertar ante 5xx sostenidos. |
F-012: External API rate limit
| Field | Value |
|---|---|
| ID | F-012 |
| Severity | Medium |
| Detection | El adapter devuelve 429. |
| Description | Se hit el rate limit de la external API. |
| Recovery | Esperar a que el rate limit se resetee; reducir la request rate. |
| Prevention | Trackear el per-adapter rate limit; usar el per-minute cap. |
F-013: Artifact validation failure
| Field | Value |
|---|---|
| ID | F-013 |
| Severity | High |
| Detection | El ArtifactStore lanza un Pydantic validation error. |
| Description | Un artifact no matchea su schema. |
| Recovery | Inspeccionar el artifact; arreglar el producer; regenerar el artifact. |
| Prevention | Añadir unit tests para el schema; usar el schema en los tests del producer. |
F-014: File permission is too permissive
| Field | Value |
|---|---|
| ID | F-014 |
| Severity | Low |
| Detection | ls -l muestra permissions más amplias que 0600 en un sensitive file. |
| Description | Un sensitive file es readable o writable por un grupo más amplio de lo necesario. |
| Recovery | chmod 600 <file>; arreglar el producer para que setee los permissions correctos. |
| Prevention | Añadir un check en el CI que falle cuando los permissions sean demasiado permisivos. |
F-015: Outdated documentation
| Field | Value |
|---|---|
| ID | F-015 |
| Severity | Low |
| Detection | La documentation describe un sistema que ha cambiado. |
| Description | La documentation está out of sync con el sistema. |
| Recovery | Actualizar la documentation para que matchee el sistema. |
| Prevention | Actualizar la documentation con cada commit que cambie el sistema. |
F-016: Missing dependency
| Field | Value |
|---|---|
| ID | F-016 |
| Severity | Medium |
| Detection | Un import falla; una tool reporta un missing binary. |
| Description | Un required package o binary no está instalado. |
| Recovery | Instalar la dependency; documentar el install en el README. |
| Prevention | Añadir un dependency check en el CI; documentar dependencies en el README. |
F-017: Configuration drift
| Field | Value |
|---|---|
| ID | F-017 |
| Severity | Medium |
| Detection | La actual configuration difiere de la documented. |
| Description | La configuration ha drifted de la documentation. |
| Recovery | Actualizar la documentation para que matchee la configuration, o actualizar la configuration para que matchee la documentation. |
| Prevention | Añadir un check en el CI que compare la live configuration con la documented. |
F-018: Memory layer is full
| Field | Value |
|---|---|
| ID | F-018 |
| Severity | Medium |
| Detection | El disk usage de la memory layer supera el threshold. |
| Description | La memory layer está usando demasiado disk space. |
| Recovery | Aplicar la retention policy; archivar daily logs antiguos. |
| Prevention | Añadir un disk usage check a las daily tasks. |
F-019: Audit log is growing too fast
| Field | Value |
|---|---|
| ID | F-019 |
| Severity | Low |
| Detection | El growth rate del audit log supera el expected rate. |
| Description | El audit log está creciendo más rápido de lo expected, lo que puede indicar un logging bug. |
| Recovery | Inspeccionar el log; identificar la source del growth; arreglar el bug. |
| Prevention | Añadir un growth-rate check a las weekly tasks. |
F-020: Provider returns unexpected response
| Field | Value |
|---|---|
| ID | F-020 |
| Severity | Medium |
| Detection | El adapter devuelve una response que no matchea el expected schema. |
| Description | Un external provider devolvió una response en un formato inesperado. |
| Recovery | Loguear la unexpected response; caer a otro adapter; reportar al provider. |
| Prevention | Añadir un schema check en el adapter; alertar ante schema violations. |
Severity summary
| Severity | Count |
|---|---|
| Critical | 1 |
| High | 6 |
| Medium | 9 |
| Low | 4 |
| Total | 20 |
Adding a new failure mode
Cuando se descubre un new failure mode:
- Añadir un entry a este catalog con el siguiente ID.
- Actualizar el runbook si el failure necesita un new procedure.
- Actualizar el audit report template si el failure afecta al audit.
- Actualizar la telemetry si el failure tiene una metric.
El new entry debe tener:
- Un unique ID (F-NNN).
- Una clear description.
- Una reliable detection rule.
- Una tested recovery procedure.
- Una severity.