Add 'fiscal/' from commit '102ba84500dbd9655a0471288c3e278652593ca9'

git-subtree-dir: fiscal
git-subtree-mainline: d95165fc8f
git-subtree-split: 102ba84500

fiscal/docs/AGENT2_UPGRADE_RUNBOOK_V1.md

@@ -0,0 +1,46 @@
+# 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.