Runbook: Diagnosticar y recuperarse de fallos de auto-update del Agente

Objetivo

Guía rápida para operadores de flota que detectan un Agente Local muerto o en versión antiga tras un intento de auto-update.

Síntomas típicos:

Agente no reporta métricas al SaaS (desaparece de la flota).
O reporta versión antigua (2.13.1) aunque hace días que el SaaS publica 2.13.3.
Or el servidor ve “pending update” en la ficha del Agente pero no progresa.

Diagnóstico rápido (< 2 min)

Paso 1: ¿El Agente está vivo?

En el equipo (RDP/SSH a la máquina del Agente):

# Windows
Get-Process agent -ErrorAction SilentlyContinue
# Si hay resultado → el Agente está corriendo

# Alternativa: por puerto
netstat -ano | findstr "9999"
# Si ve LISTENING en 127.0.0.1:9999 → Agente vivo

Si está vivo: Ve a Paso 3 (chequea logs y versión).
Si está muerto: Ve a Paso 2 (busca causa raíz).

Paso 2: ¿Por qué está muerto?

Abre el log de actualizaciones:

# Ruta típica:
cat "$env:APPDATA\CreaRack Pro\agent\update_watchdog.log"

# O si prefieres seguir en tiempo real (reciente):
Get-Content "$env:APPDATA\CreaRack Pro\agent\update_watchdog.log" -Tail 50

Patrones a buscar:

Patrón en log	Interpretación	Acción
`Swap a v2.13.3: descargado, SHA verificado` + nada más	Swap aplicado pero Agente muerto al arrancar (AV probablemente).	Ver Paso 4.
`watchdog lanzado (pid 5432)` + línea siguiente del `.ps1` jamás aparece (hasta 2.13.2)	Watchdog lanzado pero muerto antes de escribir. Causa: flags DETACHED_PROCESS (bug fijo en 2.13.3).	Relanzar Agente manualmente (una sola vez).
`Self-test ejecutado: FALLÓ`	Nuevo binary falla al importar (ej. módulo corrupto).	Relanzar el swap (`agent.exe --swap-retry`).
No hay línea de watchdog en el log	Algo falló antes de lanzar el watchdog (excepción en Python).	Ver `agent.log` (logs generales).

Paso 3: Chequea el status actual

# Consulta endpoint /info del Agente
$response = Invoke-WebRequest -Uri "http://localhost:9999/info" -UseBasicParsing
$response.Content | ConvertFrom-Json | select version, status

# Salida esperada:
# version : 2.13.3
# status  : running

Si versión es antigua (ej. 2.13.1 cuando debería ser 2.13.3):

El auto-update falló en algún punto.
Ve a Paso 4 para intento de recuperación manual.

Si versión es correcta:

Agente vivo y actualizado ✅. La crisis pasó (probablemente el watchdog lo recuperó).
Documenta el incident (Ver Paso 6).

Paso 4: Recuperación manual

Caso A: Agente muerto

# 1. Relanzar el Agente (debería descargar el binario si lo necesita)
Start-Process -FilePath "C:\Program Files\CreaRack Pro\agent\agent.exe"

# 2. Esperar 30 segundos y chequear
Start-Sleep -Seconds 30
curl http://localhost:9999/info

# 3. Si sigue muerto, ver en qué versión quedó el binary
dir "C:\Program Files\CreaRack Pro\agent\agent.*.exe"
# Debería haber agent.exe y posiblemente agent.new.exe o agent.old.exe

# 4. Si agent.new.exe existe (swap a medias), intentar revertir manualmente
if (Test-Path "C:\Program Files\CreaRack Pro\agent\agent.old.exe") {
    Remove-Item "C:\Program Files\CreaRack Pro\agent\agent.exe" -Force
    Rename-Item "C:\Program Files\CreaRack Pro\agent\agent.old.exe" -NewName "agent.exe"
    Start-Process -FilePath "C:\Program Files\CreaRack Pro\agent\agent.exe"
}

Caso B: Agente vivo pero versión antigua

# 1. Ejecutar self-test para verificar el binary nuevo (si existe)
if (Test-Path "C:\Program Files\CreaRack Pro\agent\agent.new.exe") {
    & "C:\Program Files\CreaRack Pro\agent\agent.new.exe" --selftest
    # Si sale sin error, el binary nuevo es funcional
    
    # 2. Aplicar swap manualmente
    Stop-Process -Name agent -Force -ErrorAction SilentlyContinue
    Rename-Item -Path "C:\Program Files\CreaRack Pro\agent\agent.exe" -NewName "agent.old.exe" -Force
    Rename-Item -Path "C:\Program Files\CreaRack Pro\agent\agent.new.exe" -NewName "agent.exe" -Force
    
    # 3. Relanzar
    Start-Process -FilePath "C:\Program Files\CreaRack Pro\agent\agent.exe"
    Start-Sleep -Seconds 30
    curl http://localhost:9999/info
}

Caso C: Watchdog mudo (hasta 2.13.2)

# Si el log dice "watchdog lanzado (pid XXX)" pero nada más:
# El watchdog nació y murió en 2 ms por bug de flags Windows (corregido en 2.13.3)
# Workaround: relanzar el Agente (una vez)
Stop-Process -Name agent -Force
Start-Process -FilePath "C:\Program Files\CreaRack Pro\agent\agent.exe"
# No necesita swap manual; el Agente ya está en la versión nueva

Paso 5: Verificación post-recuperación

# 1. Agente vivo y con versión correcta
curl http://localhost:9999/info

# 2. Logs sin errores
Get-Content "$env:APPDATA\CreaRack Pro\agent\agent.log" -Tail 20 | Select-String "ERROR|WARN" -Context 2

# 3. Métricas fluyendo al SaaS
# → Chequea el SaaS en 1-2 minutos: el Agente debería reapararecer en la flota
#   y empezar a reportar dispositivos y métricas

Paso 6: Reportar el incidente

Información a recopilar:

# Copiar los 2 logs a un lugar seguro para análisis
Copy-Item "$env:APPDATA\CreaRack Pro\agent\agent.log" -Destination "C:\temp\agent-debug-log.txt"
Copy-Item "$env:APPDATA\CreaRack Pro\agent\update_watchdog.log" -Destination "C:\temp\update-watchdog-log.txt"

# Metadatos de la máquina
systeminfo > "C:\temp\systeminfo.txt"

# Process list en el momento (si es un incidente activo)
Get-Process | Where-Object {$_.Name -match "agent|powershell"} | Out-File "C:\temp\processes.txt"

Crear un ticket con:

Rango horario del incidente.
Versión del Agente antes y después.
Logs recolectados.
Síntoma observado (ej. “Agente desapareció de flota por 2 horas”).
Acción de recuperación tomada.

Escenarios comunes

Escenario 1: Antivirus bloquea actualización

Síntoma:

watchdog lanzado (pid 5432)
[watchdog] Healthcheck FALLÓ (¿AV bloqueó el arranque?), reintentando...
[watchdog] Reintento 1: ejecutando agent.exe --swap-retry
[watchdog] Reintento 2: FALLÓ
[watchdog] Swap revertido a v2.13.1

Qué pasó: El AV mató el binary nuevo en su primer arranque (congelado, sin reputación). El watchdog intentó relanzarlo 2 veces y revirtió.

Solución:

El Agente está vivo (en v2.13.1) pero antiguo.
Whitelistear el path del Agente en el AV: C:\Program Files\CreaRack Pro\agent\*
El próximo swap (horas después, cuando el SaaS lo intente) debería tener éxito.

Escenario 2: Binary corrupto (import error)

Síntoma:

Self-test ejecutado (2.13.3 --selftest): FALLÓ
  Error: ModuleNotFoundError: No module named 'pysnmp'

Qué pasó: El binary nuevo se corrompió al descargar (conexión interrumpida, disk full, etc.). Le faltan módulos.

Solución:

Eliminar agent.new.exe para forzar re-descarga:

Remove-Item "C:\Program Files\CreaRack Pro\agent\agent.new.exe" -Force
# El próximo swap re-descargará desde cero

O relanzar el Agente y esperar a que el SaaS lo intente de nuevo.

Escenario 3: Watchdog mudo (2.13.2 o anterior)

Síntoma:

Swap a v2.13.3: watchdog lanzado (pid 20072, powershell)
[log silencio total hasta el próximo arranque del Agente]

Qué pasó: Bug en Agent 2.13.2: flags DETACHED_PROCESS mataban PowerShell. Watchdog nació y murió al instante.

Solución:

Relanzar el Agente manualmente (una sola vez).
El Agente ya arrancará en v2.13.3 (el swap ya está aplicado).
Próximos swaps (desde 2.13.3+) usarán el watchdog funcional.

Escalada

Si tras seguir este runbook:

✅ Agente se recuperó solo (watchdog funcional) → Documentar incidente, no es crítico.
✅ Agente se recuperó con intervención manual → Buscar la causa raíz (AV, disk full, etc.).
❌ Agente sigue muerto tras relanzar 3 veces → Escalada a Soporte (verificar instalación, posible re-instalación).

Véase también

[[incident—20260705—watchdog-auto-update-mudo]]
[[entity—terminal—service—updater-swap-watchdog]]
[[feature—terminal—watchdog-recovery-fix-v2-13-3]]
[[concept—infra—auto-update-resilience]]