Concepto: Resiliencia del auto-update silencioso (Agent Full-Local)

Definición

Auto-update resilience es la capacidad del Agente Local de descargarse, validarse, reemplazarse y recuperarse de fallos de forma silenciosa sin intervención del usuario, garantizando que siempre hay una versión funcional en ejecución.

El mecanismo abarca:

1. Descarga y verificación: El SaaS publica versión+SHA-256; el Agente verifica integridad.
2. Staged deployment: El nuevo binary se descarga a .new.exe antes de hacer swap.
3. Self-test en destino: El nuevo binary arranca con --selftest ANTES del swap → aborta si falla.
4. Watchdog post-swap: Tras el reemplazo, un vigilante desacoplado monitorea y recupera.
5. Rollback en dos capas: Si falla el swap a nivel de filesystem, revierte; si falla el arranque, el watchdog revierte la versión.

Motivación

Antes de 2.9.0, los Agentes se actualizaban manualmente o se quedaban obsoletos. El auto-update silencioso (2.9.0) resolvió eso, pero dejó un riesgo: si algo salía mal en el swap, el Agente quedaba muerto sin avisar.

Cimientos sucesivos corrigieron capas de riesgo:

• 2.11.2 (2.11.2): Self-test en destino (verifica que el binary nuevo arranca antes de reemplazar el viejo).
• 2.11.4 (2.11.4): Watchdog post-swap (si el AV mata el arranque, relanza o revierte).
• 2.13.1 (2.13.1): Traza persistente (evidencia del ciclo de swap en update_watchdog.log).
• 2.13.2 (2.13.2): Kill de instancias duplicadas (psutil empaquetado).
• 2.13.3 (2.13.3): Watchdog funcional (fix de flags de Windows que lo mataban silenciosamente).

Capas de defensa

┌─────────────────────────────────────────────────────────────────┐
│ 1. DESCARGA & VERIFICACIÓN (2.9.0)                              │
│    - SHA-256 verificado contra el SaaS                          │
│    - Si falla → aborta, Agente sigue en versión actual          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. SELF-TEST EN DESTINO (2.11.2)                                │
│    - NEW_EXE --selftest ejecutado                               │
│    - Importa terceros lazy (psutil, pysnmp)                     │
│    - Si falla → aborta, no toca el binary viejo                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. SWAP BLINDADO CON ROLLBACK (2.11.4)                          │
│    - Rename atomic si es posible; rollback si AV bloquea        │
│    - Si falla el rename → revierte, Agente sigue vivo           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. WATCHDOG POST-SWAP (2.11.4+)                                 │
│    - Proceso hijo desacoplado que sobrevive al padre            │
│    - Monitorea /health cada 30 segundos                         │
│    - Si OK → misión cumplida                                    │
│    - Si falla → relanza (--swap-retry) o revierte               │
│    ⚠️  BUG HASTA 2.13.2: Flags de Windows mataban el watchdog   │
│    ✅ CORREGIDO EN 2.13.3: CREATE_NO_WINDOW + DEVNULL           │
└─────────────────────────────────────────────────────────────────┘

Estados y transiciones

                         ┌─────────────────┐
                         │  VERSIÓN ACTUAL │  (ej. 2.13.2)
                         │   EN EJECUCIÓN  │
                         └────────┬────────┘
                                  │
                    [SaaS publica 2.13.3]
                                  │
                         ┌────────▼────────┐
                         │   DESCARGANDO   │
                         │  (verificando)  │
                         └────────┬────────┘
                                  │
                    [SHA-256 OK, staged en .new.exe]
                                  │
                         ┌────────▼────────┐
                         │   AUTOTEST      │
                         │  (2.13.3 antes  │
                         │   del swap)     │
                         └────────┬────────┘
                                  │
                    [--selftest OK]
                                  │
                         ┌────────▼────────┐
                         │    SWAP         │  (rename, os._exit)
                         │    APLICADO     │
                         └────────┬────────┘
                                  │
           ┌──────────────────────┼──────────────────────┐
           │                      │                      │
     ❌ Fallo         ✅ Éxito     │              ⚠️  AV bloquea
     (rollback)      (vivo)        │                (watchdog actúa)
           │                      │                      │
     ┌─────▼────┐          ┌──────▼──────┐        ┌──────▼───────┐
     │ REVERTIDO │          │   2.13.3    │        │ WATCHDOG: 1s │
     │ (2.13.2)  │          │   VIVO      │        │ reintento    │
     └───────────┘          └─────────────┘        └──────┬───────┘
                                                           │
                                        ┌──────────────────┼──────┐
                                        │                  │      │
                                     OK │           ❌ Falla│      │
                                        │                  │      │
                                   ┌────▼─────┐      ┌──────▼──┐  │
                                   │ 2.13.3    │      │ Revert  │  │
                                   │ VIVO      │      │ 2.13.2  │  │
                                   └───────────┘      └─────────┘  │
                                                                    └─(N reintentos)

Verificación en la flota

Desde el SaaS

• Endpoint GET /api/agent/versions → lista de Agentes con su versión actual.
• Webhook/polling: “¿Versión X está en al menos el 95% de la flota?”
• Alertas: Si una versión se queda en <5% tras 24h, posible rollback masivo.

Desde el Agente

• Archivo update_watchdog.log:

  [2026-07-05 12:00:00] Swap a v2.13.3: descargado, SHA verificado
  [2026-07-05 12:05:00] Self-test ejecutado (2.13.3 --selftest): OK
  [2026-07-05 12:05:01] Swap aplicado
  [2026-07-05 12:05:30] Watchdog lanzado (pid 5432, powershell)
  [2026-07-05 12:05:31] [watchdog] Iniciado
  [2026-07-05 12:06:00] [watchdog] Healthcheck OK
  [2026-07-05 12:06:00] [watchdog] Misión cumplida

• Log apto para auditoría y debugging post-incident.

Invariantes garantizados

Incidentes históricos y lecciones

Véase también

• [[incident—20260705—watchdog-auto-update-mudo]]
• [[feature—terminal—watchdog-recovery-fix-v2-13-3]]
• [[entity—terminal—service—updater-swap-watchdog]]
• [[decision—20260705—flags-createprocess-windows-watchdog]]