# 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.