Traza persistente del ciclo de swap del auto-update (Agent 2.13.1)

Resumen

Tras el auto-update 2.12.0 → 2.13.0 del 03-07-2026, no quedó rastro de si el watchdog post-swap (F2, vigilante de robustez) llegó a lanzarse. Root cause: agent.log se trunca en cada arranque (FileHandler(mode="w")), y quien logueaba el lanzamiento era el proceso VIEJO, cuyo log muere con el os._exit(0) del swap.

Fix en Agent 2.13.1: traza persistente en update_watchdog.log (append-only, sobrevive a relevos de proceso) + robustez del script PowerShell del watchdog.

Problema

El ciclo de auto-update de CreaRack Local Agent consta de 4 fases:

1. Descargar el ejecutable nuevo
2. Verificar self-test en destino (el binario debe arrancar)
3. Aplicar el swap (renombrar archivos, relanzar la versión nueva)
4. Lanzar el watchdog post-swap desacoplado (F2): comprueba cada 30 s que la versión nueva responde; relanza si el AV la mató; restaura la anterior si no hay manera

El problema: la fase 4 jamás dejaba rastro de si se ejecutaba o qué le pasaba. agent.log se borra en cada arranque, así que cuando el proceso nuevo empieza, el “watchdog lanzado” del viejo ya desapareció. No hay forma de saber tras 24 h si se ejecutó o falló silenciosamente.

Solución

Traza persistente del updater

Nuevo helper _wlog() → escribe en update_watchdog.log (mismo fichero que el watchdog, append-only):

def _wlog(msg: str) -> None:
    """Traza persistente del ciclo de swap (mismo fichero que escribe el watchdog)."""
    try:
        with open(WATCHDOG_LOG, "a", encoding="utf-8") as fh:
            fh.write(f"{datetime.now().isoformat(timespec='seconds')} [agent] {msg}\n")
    except OSError:
        pass  # nunca debe tumbar el updater

Puntos de escritura:

Robustez del watchdog PowerShell

1. Loguea al arrancar (antes del sleep de 30 s): distingue “no se lanzó” de “se lanzó y murió a medias”

   L 'watchdog started (swap to v2.13.0); waiting 30s for health'

2. PowerShell por ruta absoluta (System32), con fallback a PATH:

   ps_exe = os.path.join(
       os.environ.get("SYSTEMROOT", r"C:\Windows"), 
       "System32", "WindowsPowerShell", "v1.0", "powershell.exe"
   )
   if not os.path.exists(ps_exe):
       ps_exe = "powershell"  # fallback

   Motivo: el PATH heredado por un proceso frozen relanzado no está garantizado (candidato a causa raíz del silencio del 03-07).

Cobertura de tests

Nuevo suite tests/agent/test_agent_updater_trace.py (4 tests):

• test_wlog_appends_lines_with_agent_tag: la traza append-only funciona
• test_wlog_never_raises_on_unwritable_path: la primitiva jamás tumba el updater
• test_cleanup_old_exe_deja_traza_de_arranque_post_swap: se registra “arranque OK tras swap”
• test_cleanup_old_exe_silencioso_en_arranque_normal: no ensucia la traza en arranques normales

Validación

• Próximo auto-update (2.13.0 → 2.13.1): el Agente de Edu (único en flota) se actualizará y debe generar update_watchdog.log con la traza del swap aplicado + watchdog lanzado.

Cambios sin impacto visible

• Bump de versión: AGENT_VERSION 2.13.0 → 2.13.1 (v1.45.7 en el SaaS)
• Operaciones: borrados de app_media/downloads en Hetzner los binarios muertos CreaRackAgent.exe.BROKEN_2_11_1 y .HOLD_2_11_2 (la 2.13.0 está asentada hace un día; autorizado por Edu)
• No hay cambios de comportamiento del swap en el camino feliz; solo observabilidad + robustez.

Véase también

• [[local-agent-auto-update-tech]]
• [[entity—terminal—model—agent-instance]]
• [[concept—saas—local-agent]]
• [[incident—20260703—auto-update-swap-2-13-0]]
• [[decision—agent-watchdog-f2]]