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:

Descarga y verificación: El SaaS publica versión+SHA-256; el Agente verifica integridad.
Staged deployment: El nuevo binary se descarga a .new.exe antes de hacer swap.
Self-test en destino: El nuevo binary arranca con --selftest ANTES del swap → aborta si falla.
Watchdog post-swap: Tras el reemplazo, un vigilante desacoplado monitorea y recupera.
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

Invariante	Cobertura
Siempre hay un binary ejecutable	Rollback en filesystem (2.11.4) + watchdog (2.11.4)
SHA-256 verificado antes de usar	Descarga (2.9.0)
Nuevo binary probado antes de reemplazar viejo	Self-test (2.11.2)
Watchdog sobrevive al proceso padre	CREATE_NEW_PROCESS_GROUP (2.13.3)
Watchdog tiene logs para auditoría	update_watchdog.log (2.13.1)

Incidentes históricos y lecciones

Versión	Incidente	Causa	Solución
2.11.0	Binario muerto tras swap si AV mata el arranque	No hay watchdog	Introducir watchdog (2.11.4)
2.11.2	Watchdog no sabe si el nuevo binary arranca	No hay self-test antes del swap	Self-test en destino (2.11.2)
2.13.0	Swap silencioso sin evidencia (no sabemos si watchdog corrió)	Logs se pierden en arranque	Traza persistente (2.13.1)
2.13.2	Reinstalar .exe a mano deja duplicados	psutil no empaquetado	Empaquetar psutil, kill por path (2.13.2)
2.13.2–3 (03-07, 05-07)	Watchdog lanzado pero muere al instante (flags Windows)	DETACHED_PROCESS anula CREATE_NO_WINDOW	Eliminar DETACHED_PROCESS (2.13.3)

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]]