[ADR-0012] Hot Reload Dinâmico de Ambientes de IA (Sandboxes) via Polling OTP

• *Status:* Aceito
• *Data:* 17 de Maio, 2026

*Contexto:*

Atualmente (Fase Alpha), as regras de Sandboxing (allowed_root, protected_files) e a personalidade da IA (system_prompt) são carregadas na inicialização do sistema através dos arquivos em .gbr_envs/. Se um desenvolvedor perceber que a IA está se comportando mal ou bloqueando um arquivo que deveria ser permitido, ele é forçado a encerrar a aplicação (perdendo todo o histórico de contexto em memória), editar o arquivo e reiniciar o Agente. Esta fricção degrada a Experiência do Desenvolvedor (DX). Inicialmente, cogitou-se o uso de ganchos nativos do SO (via pacote fs em C), porém, para o escopo restrito de monitorar apenas configurações, introduzir uma dependência de toolchain C/C++ foi considerado um risco desnecessário de portabilidade e estabilidade.

*Decisão:*

Implementaremos a funcionalidade de Hot Reload utilizando *Polling Assíncrono Leve e 100% nativo em Gleam/OTP.*

1. **O Ator de Monitoramento (env_watcher.gleam):** Criaremos um processo OTP leve e isolado cuja única função é inspecionar metadados de arquivos.
2. *Ciclo de Active Wait:* O Ator utilizará process.send_after para se auto-despertar a cada 2000ms (2 segundos).
3. **Verificação de Metadados (mtime):** Ao acordar, ele executará simplifile.file_info nos arquivos ativos do perfil atual (ex: .gbr_envs/default.json). Ele comparará a propriedade mtime (Tempo de Modificação) com o carimbo de tempo salvo no seu Estado Interno. Se não houver alteração, ele volta a dormir (consumo ~0% de CPU).
4. *Broadcast de Atualização:* Se o mtime for mais recente, o watcher disparará uma mensagem assíncrona (UpdateEnv) para o Ator Maestro (ai.gleam). - O filesystem.gleam receberá as novas regras de Chroot instantaneamente. - O session.gleam fará a mutação cirúrgica do seu histórico em memória, trocando apenas a mensagem com a role: System pelo novo prompt lido do arquivo.

*Consequências:*

• *Positivas:* - DX "Mágica": o usuário reprograma o agente no editor de texto e a IA assume a nova personalidade ou permissão instantaneamente. - *Zero dependências externas:* O projeto permanece puramente Gleam/Erlang, compilando facilmente em qualquer sistema (Windows, Linux, Mac) sem exigir bibliotecas C instaladas. - Imunidade a falhas ("Crash"): o env_watcher valida o JSON antes de propagar. Se o usuário salvar um arquivo corrompido, o watcher apenas avisa no terminal e descarta o erro.
• *Negativas:* Existe um pequeno atraso (latência máxima de 2 segundos) entre o momento em que o usuário salva o arquivo no VSCode e o momento em que a CLI reconhece a mudança, o que é um trade-off irrelevante para a experiência de uso contínuo.

Depreciada - # [ADR-0012] Hot Reload Dinâmico de Ambientes de IA (Sandboxes)

• *Status:* Proposto
• *Data:* 17 de Maio, 2026

*Contexto:*

Atualmente (Fase Alpha), as regras de Sandboxing (allowed_root, protected_files) e a personalidade da IA (system_prompt) são carregadas na inicialização do sistema através dos arquivos em .gbr_envs/. Se um desenvolvedor perceber que a IA está se comportando mal ou bloqueando um arquivo que deveria ser permitido, ele é forçado a encerrar a aplicação (perdendo todo o histórico de contexto e raciocínio em memória da Sessão), editar o arquivo de configuração e reiniciar o Agente. Esta fricção (interrupção do estado de fluxo) degrada a Experiência do Desenvolvedor (DX) e contraria a filosofia de "agente pareador" contínuo.

*Decisão:*

Implementaremos a funcionalidade de Hot Reload utilizando monitoramento assíncrono do Sistema Operacional.

1. *Monitor de Diretório:* Utilizaremos a biblioteca filespy (um wrapper Gleam seguro sobre a biblioteca nativa Erlang fs, que utiliza inotify, fsevents ou ReadDirectoryChangesW) para monitorar exclusivamente o diretório .gbr_envs/.
2. *Ator Orquestrador:* O Ator principal (ai.gleam ou um novo env_manager.gleam) instanciará o filespy. Quando um evento do tipo Event.Modified for detectado no arquivo de configuração atual, o orquestrador fará a leitura e o parse do novo conteúdo.
3. *Broadcast de Atualização:* Se o arquivo for válido, o orquestrador disparará mensagens assíncronas de atualização de estado (UpdateEnv) para os Atores dependentes: - O filesystem.gleam (Braços) atualizará suas regras de Chroot e Lista de Proteção em tempo real. - O session.gleam (Cérebro) substituirá sua primeira mensagem do histórico (O System Prompt) pelas novas diretrizes, mantendo o restante da conversa intacto.
4. *Resiliência a Erros Humanos:* Se o arquivo modificado contiver erros de sintaxe (ex: JSON/TOML quebrado), o orquestrador registrará um erro no terminal (via gbr_log), descartará a alteração e manterá a configuração anterior funcionando perfeitamente, sem causar "Crash" no Agente.

*Consequências:*

• *Positivas:* DX incomparável — os usuários podem "reprogramar" a mente e os limites do Agente em tempo real usando seus editores de texto (VSCode, Neovim) enquanto conversam com a IA no terminal adjacente. Zero perda de contexto.
• *Negativas:* Adição de uma dependência nativa pesada (fs) que requer compilação de código C (C/C++ toolchain) na máquina hospedeira ou no processo de build cruzado; necessidade de lidar com a debouncing de eventos (editores de texto costumam disparar múltiplos eventos Modified rápidos ao salvar um único arquivo).