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

| Componente | Normal | Safe Mode | Motivo |

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

| Router | Roteamento Total | Roteamento Read-Only | Evitar que agentes planejem escritas. |

| Executor R2+ | Executa e Valida | Bloqueia e Notifica | Prevenir alterações de estado. |

| Executor R3/R4 | Aprovação + Execução | Bloqueio Total | Risco inaceitável em incidente. |

| WebSocket | Bidirecional Total | Bidirecional (Log Only) | Manter dashboard vivo para diagnóstico. |

| Health Endpoints | Retorna Status | Retorna Status + Mode | Informar monitoramento externo. |

| Logs | Gravação Normal | Gravação Normal | Essencial para auditoria e diagnóstico de incidente. |

| Observabilidade | Append/Consulta JSONL | Consulta + Append de eventos de bloqueio | Registrar tentativas negadas em Safe Mode sem liberar execução R2+. |

| LLMs Integration | Chamada Total | Chamada Limitada (Analista) | IA atua apenas como consultora. |

| Aprovações (R2+) | Fluxo normal (quando existir) | Fluxo visual pode existir, mas execução permanece bloqueada | Evitar falsa sensação de liberação durante incidente. |

| Studio UI | Operação Total | Visualização/Diagnóstico | UI bloqueia botões de ação. |

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

1. Ativação Env: Setar CEREBRO_SAFE_MODE=true e validar log de boot.
2. Ativação Flag: Rodar node index.js --safe e validar retorno de /status.
3. Precedência: Setar env false + flag --safe e garantir modo seguro ativo.
4. Bloqueio R2+: Simular comando replace no router e validar Error: Safe Mode.
5. 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.