GTI_GERENCIADOR_FISCAL/fiscal/docs/AGENT2_UPGRADE_RUNBOOK_V1.md

Agent 2 — Roteiro de upgrade manual 1.3.7 → 1.3.8

Self-update: NÃO EXISTE

Evidência no código:

• deploy/agent-windows/gti-agent.ps1 só aceita install | install-auto | configure | preflight | start | stop | restart | status | uninstall (ValidateSet na linha 20). Não há verbo update/upgrade.
• install-auto é idempotente e recusa fazer qualquer coisa se .env já tem AGENT_TOKEN e o serviço já existe ("Already enrolled and installed... Nothing to do.") — não reenrola, não atualiza arquivos.
• O painel do Hub (central/app/control_plane.py:140, compute_version_drift) só calcula e exibe o rótulo "Desatualizada" (version_drift); não existe nenhum código que baixe pacote, copie arquivo ou reinicie o serviço a partir do Hub. O botão "Atualização disponível" é só informativo — não há ação de clique associada.
• docs/PILOT_DEPLOYMENT.md:367 já documenta isso: "There is no auto-update mechanism yet (deliberately out of scope)".

Conclusão: o upgrade é sempre manual, feito por humano na máquina do cliente.

Roteiro (operador, elevado)

1. Backup antes de tocar em qualquer arquivo
   • Copie <pasta_instalação>\agent\agent_state.sqlite para um local seguro (ex.: agent_state.sqlite.bak-2026-09-28).
   • Copie também <pasta_instalação>\.env (tem o AGENT_TOKEN permanente — nunca gerar um novo).
2. gti-agent.ps1 stop (para o serviço GTIFiscalAgent).
3. Extraia o pacote 1.3.8 publicado sobre a mesma pasta de instalação (sobrescrever arquivos de código), sem apagar a pasta antes e:
   • não sobrescrever .env;
   • não sobrescrever/apagar agent\agent_state.sqlite;
   • não copiar/usar enrollment.json do pacote novo (ele é só para instalação nova; reenrollar geraria outro installation_id/token).
4. gti-agent.ps1 install (elevado) — reinstala dependências no venv existente e re-registra o serviço com o novo código. Não toca .env nem o SQLite.
5. Confira que .env continua com o mesmo AGENT_TOKEN/AGENT_ID de antes.
6. gti-agent.ps1 preflight — deve passar (mesmas credenciais Firebird de antes).
7. gti-agent.ps1 start.
8. Verificar (ainda na máquina): gti-agent.ps1 status mostra o serviço rodando.
9. Confirmar sozinho ou pedir para eu confirmar (somente leitura, pelo Hub): heartbeat com agent_version=1.3.8, installation_id inalterado (bb50884a-5e78-4f26-8cac-804932dae8de), horário do heartbeat novo.

Se algo falhar depois do passo 3, restaurar o backup do agent_state.sqlite e do .env resolve qualquer estado inconsistente sem precisar reenrolar.