SPEC: BK-45 Safe Mode (Modo de Segurança)

1. Objetivo

O Safe Mode visa garantir que o ecossistema Cérebro (Kernel + Studio) possa subir em um estado funcional mínimo mesmo durante incidentes críticos (ex: falha de banco de dados, erros de rede, conflitos de porta EADDRINUSE ou comportamentos anômalos de LLMs). Ele permite o diagnóstico e a leitura de logs sem o risco de execução de ações que alterem o estado da VPS ou dos projetos.

2. Gatilho de Ativação

A ativação é definida no momento do boot (bootstrap) através de:

Variável de Ambiente: CEREBRO_SAFE_MODE=true (no .env ou export global).
Flag de CLI: --safe (passada ao processo Node).
Precedência: A flag --safe tem precedência absoluta sobre a variável de ambiente.
Valores Inválidos: Qualquer valor diferente de true (case-insensitive) ou 1 na env var será tratado como false. Se a flag --safe estiver presente, o valor é ignorado e o modo é ativado.
Verificação: O check ocorre no arquivo kernel/index.js antes da inicialização de sockets e roteadores. No Studio (studio/server.js), o modo deve refletir o estado reportado pelo Kernel ou sua própria env var de segurança.

3. Comportamento Mínimo

Em Safe Mode, o sistema deve:

Subir em Modo Degradado: O sistema deve permitir operação mínima de diagnóstico. O comportamento exato por componente (Kernel/Studio) segue a matriz abaixo, incluindo cenário com Studio ativo e Kernel indisponível.
Bloqueio de Escrita (R2+): Qualquer tentativa de executar comandos write, replace, rm, mv, git commit, git push ou alterações em banco de dados deve ser abortada com um erro explícito: ⛔ BLOQUEADO: Safe Mode ativo.
Serviços Disponíveis:
Diagnóstico de sistema (df, free, ps, ls).
Leitura de arquivos e documentação.
Endpoints de /health e /status.
Streaming de logs existentes.
Observabilidade (consulta dos logs JSONL + registro de eventos de bloqueio em Safe Mode, sem executar ações de escrita R2+).
Sinalização no Boot (Log Mock):

```text

[BOOT] 🚀 ClawCerebro V8.2 iniciando...

[SAFE MODE] 🛡️ ALERTA: Modo de Segurança ATIVO.

[SAFE MODE] ⛔ Ações R2, R3 e R4 estão BLOQUEADAS.

[SAFE MODE] ✅ Leitura, Logs e Diagnóstico estão LIBERADOS.

[EVENT] kernel_ready | mode: safe | port: 18790

```

Payload /health / /status (JSON):

```json

{

"status": "ok",

"mode": "safe",

"timestamp": "2026-02-26T18:00:00Z",

"restrictions": ["no_write", "no_git_push", "no_db_alter"]

}

```

4. Matriz de Componentes

| :--- | :--- | :--- | :--- |

5. Critérios de Aceite

[ ] O Kernel reporta mode: "safe" no log de boot quando --safe é passado. (sim/não)
[ ] O endpoint /status retorna o JSON com o campo mode correto. (sim/não)
[ ] Tentativas de git push via Skill Git-Guardian retornam erro de Safe Mode. (sim/não)
[ ] Tentativas de rm via DevOps Agent retornam erro de Safe Mode. (sim/não)
[ ] A flag --safe anula CEREBRO_SAFE_MODE=false. (sim/não)
[ ] O Studio UI exibe um banner visual de "SAFE MODE" no topo. (sim/não)

6. Testes Planejados

Ativação Env: Setar CEREBRO_SAFE_MODE=true e validar log de boot.
Ativação Flag: Rodar node index.js --safe e validar retorno de /status.
Precedência: Setar env false + flag --safe e garantir modo seguro ativo.
Bloqueio R2+: Simular comando replace no router e validar Error: Safe Mode.
Integridade JSON: Validar que o payload de /health é um JSON parseável com mode: "safe".

7. Riscos e Decisões em Aberto

Tarefas em Execução: DECISAO EM ABERTO - Devemos matar tarefas R2+ em andamento se o modo mudar em runtime (hot-reload) ou apenas no próximo boot?
Escopo do Bloqueio: DECISAO EM ABERTO - Bloqueamos R2 (mudanças simples) ou apenas R3/R4? (Sugestão inicial: R2+).
Studio Isolado: DECISAO EM ABERTO - Se o Kernel estiver offline, o Studio deve subir em modo diagnóstico local e sinalizar mode: "safe" automaticamente?
Auditoria: Como registrar no execution-observability.jsonl que um evento foi negado pelo Safe Mode (novo campo rejected_by: "safe_mode").

8. Impacto Esperado no Checklist de Migração

Bloqueador Alvo: "Modo incidente / safe mode definido" (removido somente apos implementacao + validacao em runtime).
Evolução de Status: Item 8 (Alertas operacionais) e Item 1 (Observabilidade) ganham robustez.
Bloqueio Remanescente: A migração ainda dependerá de "Rollback claro para R3/R4" [BK-47] e da implementação/validação de aprovações R2+ no Studio (BK a definir/confirmar no backlog).

9. Status Atual (MVP Passo 2 + Delta UX, auditado em 2026-02-26)

9.1 MVP Safe Mode (Kernel + Router + Studio)

Status: Implementado e validado em smoke local (sem PM2 / sem produção).
Kernel: Ativação por CEREBRO_SAFE_MODE=true|1 e --safe (precedência da flag), sinalização de boot em Safe Mode, bloqueio de fluxos de execução (!cerebro, startExecution, execution_ready no Studio WS) e propagação de estado Safe Mode no WebSocket (init/status).
Router: Bloqueio defensivo em checkSafety(...) para comandos R2+ com erro ⛔ BLOQUEADO: Safe Mode ativo e registro de observabilidade com rejected_by: "safe_mode".
Studio API: Endpoints GET /health e GET /status retornando mode, restrictions e payload safeMode; /healthz mantido compatível.
Testes/Evidências: Suite do Kernel verde (6 suites, 50 testes) e smoke local do Studio com mode: "safe" confirmado em /health e /status.

9.2 Delta de UX do Studio (acabamento)

Arquivo alterado (delta): studio/server.js (sem alteração de lógica do Kernel neste delta).
Banner SAFE MODE: Implementado no topo do Studio com maior visibilidade e texto de estado/ restrições.
Ações bloqueadas (UI): Execução pronta, Executar Plano Colado e Aprovar (marcar OK) ficam desabilitadas/bloqueadas em Safe Mode, com feedback claro via toast e/ou status da página.
Consumo de estado: Studio usa estado vindo do Kernel (WS init/status) com fallback por env local para Safe Mode.

9.3 Observações de Precisão (auditoria)

As restrições no banner são exibidas como texto/lista inline (não chips visuais individuais).
O motivo do bloqueio é exibido via toast/status e desabilitação de controles; não há tooltip/title dedicado implementado em todos os botões.

9.4 Validação R3 em Produção (domínio real, temporária + rollback)

Status: Validado em produção controlada no domínio https://cerebro.seuimovel.rio.br/ com ativação temporária via PM2 (--update-env) e rollback na mesma sessão.
Ativação temporária: CEREBRO_SAFE_MODE=true pm2 restart cerebro-kernel --update-env seguido de CEREBRO_SAFE_MODE=true pm2 restart cerebro-studio --update-env.
Evidência de runtime em Safe Mode: /status e /health retornando mode: "safe" com restrictions preenchido; banner SAFE MODE visível no Studio (validação manual); bloqueio manual confirmado ao tentar selecionar Execução pronta no Terminal (toast/feedback de bloqueio).
Rollback temporário: CEREBRO_SAFE_MODE=false pm2 restart ... --update-env em Kernel + Studio, com /status retornando mode: "normal" após reinício.
Observação operacional: ocorreu 502 Bad Gateway transitório durante a janela de restart (curl executado imediatamente após reiniciar), sem persistência; PM2 e endpoints estabilizaram em seguida.
Pendências de validação funcional complementar (não bloqueiam a conclusão do R3):
teste manual do botão Executar Plano Colado em Safe Mode;
teste do botão Aprovar (marcar OK) em página de BK com fixture/backlog disponível (nesta sessão o ambiente retornou "BACKLOG.md não encontrado").

Documento gerado em 26/02/2026 para BK-45 Fase 1.