# Contrato — Watchman status snapshot (Spec 035)

**Ficheiro:** `/var/lib/ligbox-watchman/status.json`  
**Actualização:** a cada ciclo completo do scheduler (máx. 30 s para tier critical)

---

## Schema JSON

```json
{
  "watchman_version": "1.0.0",
  "generated_at": "2026-06-22T11:30:00+00:00",
  "hostname": "ligbox-ops",
  "summary": {
    "total": 24,
    "ok": 22,
    "degraded": 2,
    "open_incidents": 1
  },
  "last_alert_at": "2026-06-22T11:25:10+00:00",
  "services": [
    {
      "id": "vm122-desk-ui",
      "vm": "122",
      "title": "Desk Frontend",
      "tier": "critical",
      "ok": false,
      "status": "down",
      "consecutive_failures": 3,
      "last_ok_at": "2026-06-21T16:47:00+00:00",
      "last_check_at": "2026-06-22T11:30:00+00:00",
      "detail": "Connection refused",
      "http_status": null,
      "incident_open": true
    }
  ]
}
```

---

## Campos

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `ok` | bool | Resultado último probe |
| `status` | string | `online` \| `down` \| `check` |
| `consecutive_failures` | int | Falhas seguidas (reset em OK) |
| `incident_open` | bool | Alerta DOWN enviado, ainda não RESOLVED |
| `detail` | string | Erro ou HTTP status humanizado |

---

## Consumo Desk (Fase 2)

`GET /api/v1/watchman/status` lê este ficheiro (ou cache 5 s) — **sem auth pública**; RBAC `super_admin`, `ops_lead`, `technician`, `noc`.