@diegosouzacdv/jev-browser-mcp 0.1.0

package/README.md

@@ -0,0 +1,1728 @@
+# Orquestrador Multi-Agente Corporativo
+
+Orquestrador de desenvolvimento de software com LangGraph, LangChain, MCP,
+persistência SQLite, revisão multiagente, gates determinísticos, HITL e
+artefatos versionados por manifesto.
+
+O provedor LLM padrão do código é a Groq quando nenhuma variável é definida.
+O modelo padrão do perfil operacional deste projeto é
+`deepseek/deepseek-v4-flash-0731`, usado via OpenRouter.
+A chave nunca deve ser gravada no código, no `.env.example`, em checkpoints,
+logs ou relatórios.
+
+As configurações operacionais dos agentes ficam centralizadas em
+`config/agent-policy.json` (modelo, limite, timeout, retry, contrato, contexto,
+skills, MCP e ownership). Valide ou projete as variáveis de um workflow com:
+
+```bash
+python scripts/validate_agent_policy.py validate
+python scripts/render_agent_policy.py show
+python scripts/render_agent_policy.py --github-env
+```
+
+`ORQUESTRADOR_AGENT_RUNTIME_JSON` e demais variáveis legadas existem apenas
+para compatibilidade explícita; os workflows canônicos derivam a configuração
+do arquivo central.
+
+## 1. Pré-requisitos
+
+- Python 3.12+;
+- Git;
+- Docker Desktop/Engine para o sandbox estrito e para o Gitea local;
+- Node.js/npm somente quando houver validação TypeScript;
+- uma chave Groq criada no [console de API da Groq](https://console.groq.com/keys)
+  ou uma chave OpenRouter criada em [OpenRouter Keys](https://openrouter.ai/settings/keys);
+- OpenSSH no Windows para o acesso ao Gitea;
+- portas locais `3000` (HTTP) e `2222` (SSH) livres.
+
+Se uma chave foi publicada em chat, commit ou log, revogue-a e crie outra antes
+de continuar.
+
+## 2. Instalação local
+
+Windows PowerShell:
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+Copy-Item .env.example .env
+```
+
+Linux/macOS:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edite `.env` localmente. O arquivo `.env.example` é o catálogo versionado das
+variáveis suportadas; o `.env` é ignorado pelo Git e contém os valores
+específicos da máquina. Para o perfil local deste projeto:
+
+```dotenv
+ORQUESTRADOR_LLM_PROVIDER=openrouter
+OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
+ORQUESTRADOR_AGENT_MODEL=deepseek/deepseek-v4-flash-0731
+MCP_FILESYSTEM_ROOTS=.
+ORQUESTRADOR_SANDBOX_MODE=docker
+```
+
+Quando a chave estiver cadastrada no ambiente de usuário do Windows, use a
+expansão `${OPENROUTER_API_KEY}` acima; não copie o segredo para o `.env`. Para
+CI e produção, use secrets/variáveis do ambiente; não publique o arquivo `.env`.
+
+### Conferir a integridade da `.venv`
+
+A `.venv` é ignorada pelo Git: se algo reescrever um arquivo dela, nada o traz de
+volta. Em 2026-08-28 um script de tradução reescreveu 23 pacotes (`resolver` →
+`resolve`), e isso só apareceu semanas depois, como erros sem relação aparente.
+Cada pacote instalado guarda o sha256 de cada arquivo no próprio `RECORD`, e o
+script abaixo confere tudo contra ele:
+
+```powershell
+.venv\Scripts\python.exe scripts\venv_integrity.py
+```
+
+```bash
+.venv/bin/python scripts/venv_integrity.py
+```
+
+Sai `0` com `"clean": true`; sai `1` nomeando pacote e arquivo em `mismatched`
+(conteúdo diferente), `missing` (arquivo apagado) ou `unverifiable` (pacote sem
+`RECORD`, que não dá para conferir e por isso não conta como limpo). Rode com o
+interpretador da `.venv` que quer conferir. Leva de 1 a 11 s, conforme o cache de
+disco. Para reparar um pacote apontado:
+`pip install --force-reinstall --no-deps <pacote>==<versão>`.
+
+Na agenda do Hermes, uma vez por semana, pela skill
+`.hermes/skills/orquestrador-venv-integrity/`, que só reporta e nunca repara; o
+comando `hermes cron create` está no `SKILL.md` dela.
+
+## 2.1. Gitea local para Actions e espelhamento do GitHub
+
+O GitHub é a origem canônica deste projeto. O Gitea é uma cópia local usada para
+executar os workflows self-hosted; portanto, o fluxo normal é publicar primeiro
+em `origin` (GitHub) e depois atualizar o remote `gitea`. Não trate o clone local
+do Gitea como fonte de verdade.
+
+| Componente | Caminho/URL nesta máquina |
+|---|---|
+| Checkout de desenvolvimento | `C:\orquestrador` |
+| Servidor Gitea, compose e dados persistentes | `C:\gitea` |
+| Runner Linux/Docker | `C:\gitea-runner` |
+| Runner Windows/host | `C:\gitea-runner-win` |
+| URL configurada no compose | `http://192.168.1.3:3000` |
+| SSH do Gitea | `ssh://gitea-local/...` na porta `2222` |
+
+O `docker-compose.yml` atual usa `192.168.1.3`. Se o endereço da máquina mudar, atualize
+`ROOT_URL`, `DOMAIN` e `SSH_DOMAIN` no compose antes de registrar novos runners.
+Não misture `localhost`, o IP da LAN e outro hostname no mesmo registro: o endereço usado
+pelo runner precisa ser alcançável por ele.
+
+Referências oficiais: [instalação com Docker](https://docs.gitea.com/next/installation/install-with-docker/),
+[Gitea Actions](https://docs.gitea.com/usage/actions/overview/) e
+[Gitea Runner](https://docs.gitea.com/usage/actions/act-runner/).
+
+### Subir o servidor Gitea
+
+Inicie o Docker Desktop com o engine Linux e confirme que ele está saudável:
+
+~~~powershell
+docker info
+docker compose version
+~~~
+
+Suba a instância já configurada em `C:\gitea`; não recrie o volume de dados:
+
+~~~powershell
+Set-Location C:\gitea
+docker compose pull
+docker compose up -d
+docker compose ps
+docker compose logs --tail 100 server
+Invoke-WebRequest http://192.168.1.3:3000/api/v1/version -TimeoutSec 10
+~~~
+
+Na primeira instalação, acesse <http://192.168.1.3:3000>, crie o usuário
+administrador, ative Actions e confirme que o repositório
+`admin/projeto-global` existe. Os dados ficam em `C:\gitea\gitea`; não use
+`docker compose down -v`, pois isso remove o armazenamento persistente.
+
+Para parar temporariamente sem apagar dados:
+
+~~~powershell
+Set-Location C:\gitea
+docker compose stop
+~~~
+
+### GitHub como origem e Gitea como espelho
+
+No checkout principal, preserve `origin` apontando para o GitHub e mantenha o
+Gitea em um segundo remote:
+
+~~~powershell
+Set-Location C:\orquestrador
+git remote -v
+git remote set-url origin https://github.com/diegosouzacdv/orquestrador.git
+git remote set-url gitea ssh://gitea-local/admin/projeto-global.git
+git fetch origin --prune
+~~~
+
+Se `gitea` ainda não existir, use `git remote add gitea ...` em vez de
+`set-url`. A chave SSH do Gitea pode ser criada assim:
+
+~~~powershell
+$sshDir = Join-Path $env:USERPROFILE ".ssh"
+New-Item -ItemType Directory -Force $sshDir | Out-Null
+ssh-keygen -t ed25519 -C "gitea-local" -f (Join-Path $sshDir "gitea_local")
+Get-Content (Join-Path $sshDir "gitea_local.pub")
+~~~
+
+Adicione a chave pública em **Gitea → Settings → SSH / GPG Keys** e crie
+`C:\Users\<usuario>\.ssh\config`:
+
+~~~sshconfig
+Host gitea-local
+  HostName 192.168.1.3
+  Port 2222
+  User git
+  IdentityFile ~/.ssh/gitea_local
+  IdentitiesOnly yes
+~~~
+
+Valide a autenticação e publique o mesmo commit nos dois destinos:
+
+~~~powershell
+ssh -T gitea-local
+git pull --ff-only origin master
+git push origin master
+git push gitea master:master
+git push gitea --tags
+git ls-remote origin refs/heads/master
+git ls-remote gitea refs/heads/master
+~~~
+
+O `ssh -T` pode responder que não existe shell interativo; isso é esperado se a
+autenticação funcionar. O último bloco deve mostrar o mesmo SHA no GitHub e
+no Gitea. O clone atual em `C:\gitea-runner\repositorio` é apenas um bootstrap
+antigo e não deve ser usado como origem do espelho sem antes conferir seus
+remotes e seu estado:
+
+~~~powershell
+git -C C:\gitea-runner\repositorio remote -v
+git -C C:\gitea-runner\repositorio status --short --branch
+~~~
+
+Para espelhar também branches e tags removidas, use um clone bare dedicado.
+O comando `git push --mirror` substitui todas as refs do repositório de destino;
+confirme o destino antes de executá-lo e não aponte para um repositório com
+trabalho independente:
+
+~~~powershell
+$mirror = "C:\gitea-runner\github-mirror.git"
+if (Test-Path $mirror) { throw "O mirror já existe; valide-o manualmente antes de reutilizar o caminho." }
+git clone --mirror https://github.com/diegosouzacdv/orquestrador.git $mirror
+Set-Location $mirror
+git remote add gitea ssh://gitea-local/admin/projeto-global.git
+git fetch origin --prune
+git push --mirror gitea
+~~~
+
+### Runner Linux/Docker — `C:\gitea-runner`
+
+Este é o runner usado pelos workflows com `runs-on: ubuntu-latest`, como
+`.gitea/workflows/agentic-graph-e2e.yml` e
+`.gitea/workflows/mcp-integration-smoke.yml`. Ele usa Docker Desktop e o
+socket `/var/run/docker.sock` dentro dos jobs. O socket dá ao job controle do
+Docker do host; aceite jobs somente do repositório confiável.
+
+O binário e a configuração já ficam em `C:\gitea-runner`. Se for necessário
+registrar novamente, gere o arquivo uma única vez, solicite um token novo na
+interface do Gitea e não salve o token em arquivo, histórico ou Git:
+
+~~~powershell
+Set-Location C:\gitea-runner
+if (!(Test-Path .\config.yaml)) {
+  .\act_runner.exe config generate | Out-File -Encoding utf8 .\config.yaml
+}
+$runnerToken = Read-Host "Token do runner Gitea"
+.\act_runner.exe register --no-interactive --instance "http://192.168.1.3:3000" --token $runnerToken --name "orquestrador-local" --labels "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04,ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04"
+Remove-Variable runnerToken
+~~~
+
+Na configuração, preserve pelo menos estas opções para os workflows Docker:
+
+~~~yaml
+container:
+  options: --volume /var/run/docker.sock:/var/run/docker.sock --add-host=host.docker.internal:host-gateway
+  valid_volumes:
+    - '**'
+  require_docker: true
+  docker_timeout: 60s
+  bind_workdir: true
+~~~
+
+Teste em primeiro plano antes de depender do serviço do Windows:
+
+~~~powershell
+docker info
+Set-Location C:\gitea-runner
+.\act_runner.exe daemon --config C:\gitea-runner\config.yaml
+~~~
+
+Nesta máquina, o serviço `GiteaActRunner` já está configurado para executar
+`C:\gitea-runner\act_runner.exe daemon --config C:\gitea-runner\config.yaml`.
+Depois que o Docker Desktop estiver pronto, reinicie-o e confira o log:
+
+~~~powershell
+Get-Service GiteaActRunner
+Restart-Service GiteaActRunner
+Get-Content C:\gitea-runner\service.err.log -Tail 80
+~~~
+
+O serviço deve aparecer como `Running` e o runner deve ficar online em
+**Gitea → Actions → Runners**. Se `docker info` falhar ou o log mencionar
+`Docker Engine socket not found`, corrija o Docker Desktop primeiro; reiniciar
+o runner sozinho não resolve essa causa.
+
+Estado verificado em 2026-09-13: serviço `Running`, runner `orquestrador-local`
+(id 3) em `v3.3.1`, com as três labels `ubuntu-*` e `last_online` corrente. O
+log de sucesso tem exatamente três linhas — `Starting runner daemon`,
+`Docker is ready` e `declare successfully`. A ausência de `Docker is ready`
+neste runner é defeito; no runner Windows, não.
+
+Uma enxurrada de `failed to fetch task ... target machine actively refused it`
+**não** é defeito do runner: é o container do Gitea parado. O runner fica em
+retry e volta sozinho quando o servidor sobe — foi o que ocorreu entre 07:41 e
+07:55 de 2026-09-13, com recuperação às 07:59 sem nenhuma intervenção no
+runner. Antes de mexer no runner, confira `docker compose ps` em `C:\gitea`.
+
+### Runner Windows/host — `C:\gitea-runner-win`
+
+Este é um segundo runner, independente do runner Docker, registrado como
+`orquestrador-windows` (id 4) com a label `windows-latest:host`. Ele é usado
+pelos jobs Windows da matriz `os: [ubuntu-latest, windows-latest]` de
+`.gitea/workflows/antigravity-sdk-homologation.yml` — hoje o único workflow
+Gitea que não é só `ubuntu-latest`. Sem este runner, a perna `windows-latest`
+dessa matriz fica enfileirada para sempre em vez de falhar, que é o sintoma
+pelo qual essa ausência costuma ser percebida.
+
+**O serviço `GiteaActRunnerWindows` já existe nesta máquina** e está correto:
+NSSM, `AUTO_START`, `Application=C:\gitea-runner-win\act_runner.exe`,
+`AppDirectory=C:\gitea-runner-win`,
+`AppParameters=daemon --config C:\gitea-runner-win\config.yaml`. Confira antes
+de tentar criá-lo de novo — `nssm install` sobre um serviço existente não é o
+caminho:
+
+~~~powershell
+sc.exe query GiteaActRunnerWindows
+reg query "HKLM\SYSTEM\CurrentControlSet\Services\GiteaActRunnerWindows\Parameters"
+~~~
+
+#### As duas causas que mantiveram este runner parado
+
+Diagnosticadas em 2026-09-13, com o serviço existente e bem configurado:
+
+1. **O binário não estava lá.** `C:\gitea-runner-win\` tinha `.runner` e
+   `config.yaml`, mas não `act_runner.exe`. O serviço sobe, não acha o
+   executável e morre com `ESTADO: STOPPED`, `WIN32_EXIT_CODE: 1066 (0x42a)` e
+   `SERVICE_EXIT_CODE: 3` — `ERROR_PATH_NOT_FOUND`. O 1066 é genérico
+   ("erro específico do serviço") e não aponta o arquivo; quem lê só o 1066
+   procura defeito de registro e não encontra nada.
+2. **`require_docker: true` herdado do runner Docker.** O `config.yaml` deste
+   diretório é cópia do config do runner Linux, inclusive do bloco
+   `container:`. A opção está documentada no próprio arquivo como *"Always
+   require a reachable docker daemon, **even if not required by runner**"* —
+   ou seja, ela amarra a subida deste runner ao Docker Desktop, que um runner
+   `host` não usa. Com o Docker parado, o runner Windows recusa subir sem ter
+   motivo próprio para isso.
+
+Correção das duas, na ordem:
+
+~~~powershell
+Set-Location C:\gitea-runner-win
+if (!(Test-Path .\act_runner.exe)) {
+  Copy-Item C:\gitea-runner\act_runner.exe .\act_runner.exe
+}
+.\act_runner.exe --version   # precisa casar com o runner Docker: v3.3.1
+~~~
+
+No `config.yaml` deste runner, e **somente** neste, deixe:
+
+~~~yaml
+container:
+  require_docker: false
+~~~
+
+O resto do bloco `container:` (socket Docker, `valid_volumes`, `bind_workdir`)
+é inerte aqui, porque um runner `host` não cria container — mas mantê-lo copiado
+é o que faz `require_docker` voltar despercebido na próxima cópia do arquivo.
+
+Valide em foreground antes de depender do serviço:
+
+~~~powershell
+Set-Location C:\gitea-runner-win
+.\act_runner.exe daemon --config C:\gitea-runner-win\config.yaml
+~~~
+
+O sucesso são **duas** linhas, sem `Docker is ready`:
+
+~~~text
+level=info msg="Starting runner daemon"
+level=info msg="runner: orquestrador-windows, with version: v3.3.1, with labels: [windows-latest], declare successfully"
+~~~
+
+`Docker is ready` aqui significa que `require_docker` voltou a `true`. A label
+sai como `windows-latest` porque o `:host` é o modo de execução do lado do
+runner, não parte do nome da label — `runs-on: windows-latest` no workflow é o
+que casa.
+
+O `config.yaml` desse runner aponta
+`ORQUESTRADOR_WINDOWS_PYTHON` para
+`C:\orquestrador\.venv\Scripts\python.exe`. Confira que o ambiente virtual
+existe e tem as dependências do projeto antes de iniciar o serviço.
+
+Encerre o foreground com `Ctrl+C` antes de subir o serviço: os dois usam o
+mesmo `.runner.lock` e a mesma identidade registrada.
+
+#### Subir o serviço — exige PowerShell elevado
+
+`sc.exe start` sem elevação falha com `OpenService FALHA 5: Acesso negado`, e
+esse 5 é do controle do serviço, não do runner. Em PowerShell **como
+administrador**:
+
+~~~powershell
+Start-Service GiteaActRunnerWindows
+Get-Service GiteaActRunner, GiteaActRunnerWindows
+~~~
+
+Executado pelo operador em 2026-09-13: o serviço ficou `RUNNING` e os **dois**
+runners passaram a reportar `last_online` no mesmo minuto — id 3
+(`orquestrador-local`) e id 4 (`orquestrador-windows`), com 12 segundos de
+diferença. É essa a evidência que fecha a subida dos dois runners; serviço
+`RUNNING` sozinho não prova conexão com o Gitea.
+
+Só crie o serviço com NSSM se `sc.exe query` disser que ele não existe. Ele
+precisa de diretório de trabalho próprio e não pode reutilizar o registro do
+runner Docker:
+
+~~~powershell
+$nssm = (Get-Command nssm.exe).Source
+& $nssm install GiteaActRunnerWindows C:\gitea-runner-win\act_runner.exe
+& $nssm set GiteaActRunnerWindows AppDirectory C:\gitea-runner-win
+& $nssm set GiteaActRunnerWindows AppParameters 'daemon --config C:\gitea-runner-win\config.yaml'
+& $nssm set GiteaActRunnerWindows Start SERVICE_AUTO_START
+Start-Service GiteaActRunnerWindows
+~~~
+
+O modo `host` expõe o ambiente Windows, ferramentas e credenciais da máquina
+ao job. Use-o apenas para workflows confiáveis.
+
+### Secrets e workflows
+
+Secrets do GitHub não são copiados automaticamente para o Gitea. Cadastre no
+repositório Gitea, em **Settings → Actions → Secrets**, os valores exigidos
+pelos workflows, como `OPENROUTER_API_KEY`, `CONTEXT7_API_KEY`,
+`TWENTY_FIRST_API_KEY` e `GEMINI_API_KEY` quando aplicável. Tokens de clone e
+tokens de registro de runner devem ser tratados separadamente e nunca entrar
+no repositório.
+
+Os arquivos em `.gitea/workflows/` são executados pelo Gitea. Os arquivos em
+`.github/workflows/` continuam sendo executados pelo GitHub Actions; o fato de
+o conteúdo ser espelhado não faz o Gitea executar workflows do GitHub. Dentro
+de um job Docker, use `http://host.docker.internal:3000` para acessar o Gitea;
+`localhost` aponta para o próprio container.
+
+### Diagnóstico e manutenção
+
+~~~powershell
+Set-Location C:\gitea
+docker compose ps
+docker compose logs --tail 100 server
+Get-Service GiteaActRunner
+Get-Content C:\gitea-runner\service.err.log -Tail 80
+Get-Service GiteaActRunnerWindows -ErrorAction SilentlyContinue
+Get-Content C:\gitea-runner-win\service.err.log -Tail 80 -ErrorAction SilentlyContinue
+~~~
+
+Serviço `Running` prova que o processo existe, não que o runner está falando
+com o Gitea. Quem responde isso é o `last_online` do servidor, e ele é
+consultável sem abrir a interface e sem autenticar:
+
+~~~powershell
+docker exec gitea sqlite3 /data/gitea/gitea.db "select id, name, version, agent_labels, datetime(last_online,'unixepoch','localtime') from action_runner where deleted is null;"
+~~~
+
+**O `where deleted is null` não é opcional.** O Gitea apaga runner por *soft
+delete*: a linha permanece em `action_runner` com a coluna `deleted`
+preenchida, e a interface e a API deixam de listá-la. Uma consulta sem esse
+filtro mostra registros já removidos como se estivessem ativos — foi o que
+aconteceu em 2026-09-13, quando os ids 1 e 2 foram lidos como "órfãos
+aparecendo offline na interface" e na verdade já tinham sido excluídos em
+2026-08-30, minutos depois de criados e antes do id 3 existir.
+
+Um `last_online` recente é o runner online agora. Os registros vivos nesta
+máquina são o id 3 (`orquestrador-local`, labels `ubuntu-*`) e o id 4
+(`orquestrador-windows`, label `windows-latest`). Para conferir o que a
+interface de fato mostra, sem depender da leitura do banco:
+
+~~~powershell
+docker exec gitea sqlite3 /data/gitea/gitea.db "select id, datetime(deleted,'unixepoch','localtime') from action_runner;"
+~~~
+
+Nunca apague linha de `action_runner` por SQL: remover runner é operação de
+interface, e o soft delete existe para preservar a trilha dos jobs que aquele
+runner atendeu.
+
+Se um runner for removido pela interface do Gitea, pare o daemon e remova
+somente `.runner` e `.runner.lock` no diretório daquele runner; preserve
+`config.yaml`, registre um novo token e valide novamente. Nunca remova
+`C:\gitea\gitea` para corrigir um problema de runner.
+
+No diagnóstico desta máquina, em 2026-09-11, o endpoint do Gitea recusou
+conexão porque o container estava parado e `C:\gitea-runner\service.err.log`
+registrou `Docker Engine socket not found`. A sequência de recuperação é:
+
+~~~powershell
+Set-Location C:\gitea
+docker compose up -d
+docker info
+Restart-Service GiteaActRunner
+Get-Content C:\gitea-runner\service.err.log -Tail 80
+~~~
+
+Em 2026-09-13 o Gitea (`1.27.3`) e o runner Docker estavam saudáveis, e só o
+runner Windows estava parado: binário ausente e `require_docker: true` herdado.
+A lição de diagnóstico é que os dois runners falham por causas **disjuntas** —
+o Docker depende do Docker Desktop e do container do Gitea; o Windows/host não
+depende de nenhum dos dois. Tratar "os runners não sobem" como um problema só
+faz procurar causa comum onde não há.
+
+## 2.2. Variáveis de ambiente
+
+O arquivo [`.env.example`](.env.example) é o catálogo versionado das variáveis
+suportadas. O `.env` local é ignorado pelo Git e não deve ser publicado.
+Para as credenciais cadastradas no ambiente de usuário do Windows, use referências
+sem copiar os valores:
+
+```dotenv
+OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
+CONTEXT7_API_KEY=${CONTEXT7_API_KEY}
+TWENTY_FIRST_API_KEY=${TWENTY_FIRST_API_KEY}
+```
+
+Abra um novo PowerShell depois de alterar variáveis no Windows. Confira somente
+a presença das credenciais:
+
+```powershell
+python -c "import os; from dotenv import load_dotenv; load_dotenv('.env', override=False); names=['OPENROUTER_API_KEY','CONTEXT7_API_KEY','TWENTY_FIRST_API_KEY']; print({n:bool(os.environ.get(n)) for n in names})"
+git check-ignore -v .env
+python scripts/validate_agent_policy.py validate
+python scripts/plan_status.py validate
+```
+
+As variáveis estão organizadas no `.env.example` por provider LLM, OpenRouter,
+MCP, Gitea/Git, sandbox, retry, kernel, orçamento, observabilidade, skills,
+HITL, identidade e mídia. O modelo padrão operacional é
+`deepseek/deepseek-v4-flash-0731`; o Backend usa `reasoning_effort=max` na
+política central `config/agent-policy.json`. Não habilite overrides legados.
+
+## 2.3. Supermemory local (memória entre sessões)
+
+Desde 2026-09-23, por decisão do operador, a memória entre sessões mora no
+`supermemory-server` rodando no **WSL Ubuntu** da máquina do operador. O plano da
+nuvem chegou ao limite e passou a recusar gravações, e o conector da nuvem foi
+**desativado** no mesmo dia (claude.ai → Settings → Connectors → Supermemory). As
+regras de uso estão no `AGENTS.md`, subseção "Supermemory: o servidor local do
+operador".
+
+Tudo abaixo roda **dentro do Ubuntu** (`wsl -d Ubuntu`), a partir de `~`, nunca
+de `/mnt/c/...`: a pasta de dados segue o diretório atual quando não é fixada, e
+`/mnt/c` é o disco do Windows, mais lento.
+
+### Instalar (uma vez)
+
+```bash
+sudo apt update && sudo apt install -y curl
+cd ~ && curl -fsSL https://supermemory.ai/install | bash
+echo 'export PATH="$HOME/.supermemory/bin:$PATH"' >> ~/.bashrc
+```
+
+### Configuração fixa (uma vez)
+
+Embedding multilíngue e local, com a pasta de dados fixada. Nada disso é
+segredo. O `embedding-plan.json` que o assistente grava **não** é o que o
+servidor carrega; sem estas variáveis ele sobe com o modelo inglês de 768
+dimensões, que não combina com as tabelas de 1024 (medido em 2026-09-23).
+
+```bash
+cat >> ~/.bashrc <<'EOF'
+export SUPERMEMORY_EMBEDDING_PROVIDER=local
+export SUPERMEMORY_EMBEDDING_MODEL=Xenova/bge-m3
+export SUPERMEMORY_EMBEDDING_DIMENSIONS=1024
+export SUPERMEMORY_DATA_DIR="$HOME/.supermemory"
+EOF
+source ~/.bashrc
+```
+
+Chave do LLM que extrai as memórias (GLM, pela API compatível com OpenAI da
+Z.ai). A chave vai para um arquivo **fora** de `~/.supermemory`, porque o
+servidor lê o `~/.supermemory/env`, cifra o conteúdo em `env.enc` e apaga o
+original; e a extração roda num processo que só enxerga variáveis exportadas.
+
+```bash
+mkdir -p ~/.config/glm && chmod 700 ~/.config/glm
+read -rsp "Chave GLM: " K; echo; printf '%s' "$K" > ~/.config/glm/key; unset K
+chmod 600 ~/.config/glm/key
+
+cat >> ~/.bashrc <<'EOF'
+sm() { ( export OPENAI_API_KEY="$(cat "$HOME/.config/glm/key")" \
+  OPENAI_BASE_URL=https://api.z.ai/api/coding/paas/v4 \
+  OPENAI_MODEL=glm-4.6 OPENAI_FAST_MODEL=glm-4.5-air
+  exec supermemory-server "$@" ); }
+EOF
+source ~/.bashrc
+```
+
+`OPENAI_BASE_URL` depende do plano da Z.ai: com a assinatura de código use a URL
+`coding` acima; com saldo pré-pago, `https://api.z.ai/api/paas/v4`. A URL errada
+responde `Insufficient balance or no resource package`.
+
+### Subir e conferir
+
+```bash
+cd ~ && sm                      # sobe em http://localhost:6767 e fica em primeiro plano
+supermemory-server doctor       # noutro terminal: provedor, embedding, pasta de dados
+```
+
+O quadro `supermemory ready` precisa mostrar `database /home/<você>/.supermemory` e
+`embeddings local · Xenova/bge-m3 · 1024d`. **Não compartilhe prints desse quadro:
+a linha `api key` traz a chave inteira.**
+
+### Testar
+
+```bash
+# grava um documento; no terminal do servidor a linha final deve terminar em "N memories"
+curl -s http://localhost:6767/v3/documents -H "Content-Type: application/json" \
+  -d '{"content":"Teste do Supermemory local.","containerTag":"orquestrador"}'; echo
+
+# busca: containerTags é LISTA. Sem ela, ou com containerTag no singular, a
+# resposta é 200 com resultado vazio -- parece "nada gravado" e não é.
+curl -s http://localhost:6767/v4/search -H "Content-Type: application/json" \
+  -d '{"q":"supermemory local","containerTags":["orquestrador"],"searchMode":"memories","threshold":0}'; echo
+```
+
+Mande sempre `threshold`. Sem ele o servidor aplica um limiar próprio e descarta
+memória relevante: medido em 2026-09-23, "Hermes cron workdir" devolveu 1 memória
+sem `threshold` e as do mesmo assunto com `threshold: 0`. Com 0, a busca devolve
+as mais próximas até o `limit`, cada uma com a `similarity` ao lado. O cliente do
+orquestrador manda o valor de `config/durable-stores.json`,
+`memory_store.search_threshold`.
+
+Teste de ponta a ponta de **todas** as chamadas que o orquestrador faz (gravar,
+buscar, editar, grafo, ler, esquecer, apagar), num espaço descartável
+`orquestrador-smoke`, que ele limpa no fim. Cada linha diz `OK` ou `FAIL` com o
+motivo que o servidor deu:
+
+```bash
+PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_local_smoke.py
+```
+
+No **Windows**, que é onde a `.venv` do projeto mora, rode pelo PowerShell a
+partir do checkout — o Windows alcança o servidor do WSL por `127.0.0.1:6767`.
+Os scripts abaixo (migração e sync) seguem a mesma forma:
+
+```powershell
+cd C:\orquestrador            # ou a worktree da branch que tem os scripts
+$env:PYTHONPATH = (Get-Location).Path
+$env:PYTHONUTF8 = "1"          # o console cp1252 quebra no ✅ das memórias
+$py = "C:\orquestrador\.venv\Scripts\python.exe"
+& $py scripts\supermemory_local_smoke.py
+```
+
+A busca do smoke tenta de novo por até 30 s antes de reprovar: o servidor indexa
+a memória nova na própria fila, e uma espera fixa confundia "ainda não indexou"
+com "a busca não funciona".
+
+### Listar as memórias
+
+```bash
+# documentos do espaço, paginados
+curl -s http://localhost:6767/v3/documents/list -H "Content-Type: application/json" \
+  -d '{"containerTags":["orquestrador"],"page":1,"limit":50}'; echo
+
+# um documento com as memórias extraídas dele
+curl -s http://localhost:6767/v3/documents/<documentId>; echo
+```
+
+Pelo orquestrador, o grafo inteiro (todos os documentos com as memórias de cada
+um) sai de `GET /memory/graph` da API HTTP (seção 7), autenticado como as outras
+rotas.
+
+### Migrar as memórias da nuvem (uma vez)
+
+Com o servidor de pé, a partir do checkout do orquestrador:
+
+```bash
+PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_migrate_to_local.py --dry-run
+PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_migrate_to_local.py
+```
+
+São as 33 memórias de `docs/supermemory/cloud-export-2026-09-23.json`, já
+normalizadas para o padrão de gravação, escritas com o texto exato, sem reprocessar
+no LLM. O script confere o export inteiro contra o padrão **antes** da primeira
+gravação — `--dry-run` lista em `invalid` o que seria recusado — e guarda em
+`data/supermemory-migration.json` o que já foi aceito: rodar de novo não duplica.
+
+### Padrão de gravação (aplicado pelo código)
+
+Toda gravação — MCP, tela, migração, inbox — passa por `src/memory/standard.py`,
+que recusa e nomeia cada violação. O formato que passa:
+
+```text
+TEC-002 was delivered on 2026-09-22 in commit 93bbf57.
+STK-004 was marked ✅, meaning developed and validated within the scope of the cited evidence, not approved by the operator, on 2026-09-22 in commit d2ab40d.
+```
+
+Uma frase, em inglês, com data ISO e âncora (SHA, id de item ou `session <id>`),
+ícone com o sentido escrito, sem estado volátil ("still pending", "in progress")
+e sem segredo. Os valores estão em `config/durable-stores.json`,
+`memory_store.standard`.
+
+### Sincronizar com as sessões da nuvem
+
+Sessões na nuvem não alcançam este servidor. Elas leem
+`docs/supermemory/snapshot.json` e gravam em `docs/supermemory/inbox/`, que chegam
+aqui pelo git. Depois de trazer as branches mescladas para o checkout:
+
+```bash
+PYTHONPATH=$PWD .venv/bin/python scripts/supermemory_sync.py
+git add docs/supermemory/snapshot.json
+git commit -m "memory: snapshot do servidor local" -- docs/supermemory/snapshot.json
+```
+
+O script aplica cada operação do inbox uma vez (o registro fica em
+`data/supermemory-sync.json`) e reescreve o snapshot a partir do servidor. Rode-o
+depois da migração, para o snapshot passar a vir do servidor, e sempre que um
+inbox novo chegar. O Hermes pode rodá-lo na mesma agenda do laço do plano.
+
+As memórias seguidas de uma mesma sessão vão numa chamada só, e o servidor faz um
+documento por chamada: no grafo, cada sessão aparece como um documento com os
+fatos em volta. Até 2026-09-23 cada memória ia sozinha, e o grafo mostrava um par
+documento-memória para cada uma.
+
+### Reagrupar as memórias gravadas uma por documento (uma vez)
+
+As 42 memórias gravadas antes dessa mudança continuam uma por documento. O
+reagrupamento junta cada lote de gravação da nuvem e cada sessão do inbox num
+documento só. Ele só apaga um documento antigo **depois** de conferir que cada
+memória dele está no documento novo, e no fim confere que o conjunto de memórias
+é o mesmo de antes, sem perda e sem duplicata. Memória que o repositório não
+conhece (gravada pela tela, por exemplo) fica onde está.
+
+```powershell
+git fetch origin claude/nifty-knuth-27gns3
+git checkout origin/claude/nifty-knuth-27gns3
+& $py scripts\supermemory_sync.py                  # aplica o que estiver no inbox
+& $py scripts\supermemory_regroup.py               # só o plano, não toca em nada
+& $py scripts\supermemory_regroup.py --apply       # "verified": true no fim
+& $py scripts\supermemory_sync.py                  # snapshot a partir do servidor
+git add docs/supermemory/snapshot.json
+git commit -m "memory: snapshot reagrupado" -- docs/supermemory/snapshot.json
+```
+
+`--apply` sai `0` só com `"verified": true`. Se sair `1`, nada foi apagado antes
+do problema: o relatório nomeia o grupo que o servidor não confirmou. Rodar de
+novo é seguro.
+
+### Sessões e Hermes: o MCP `supermemory-local`
+
+O `.mcp.json` declara `supermemory-local`, um MCP `stdio` que chama o servidor
+local. Ferramentas: `search_memory`, `add_memory` (`action` `save`/`forget`),
+`list_memories`, `get_document`, `update_memory`, `delete_document`. O
+interpretador vem de `ORQUESTRADOR_PYTHON`:
+
+```powershell
+# Windows (checkout em C:\orquestrador)
+[System.Environment]::SetEnvironmentVariable("ORQUESTRADOR_PYTHON", "C:\orquestrador\.venv\Scripts\python.exe", "User")
+```
+
+```bash
+# Linux/WSL
+echo "export ORQUESTRADOR_PYTHON=$PWD/.venv/bin/python" >> ~/.bashrc
+```
+
+Depois, em uma sessão nova, `/mcp` deve listar `supermemory-local` conectado.
+Se o interpretador escolhido não tiver o pacote `mcp`, o servidor se entrega ao
+`python` da `.venv` do projeto. Sessões na nuvem (claude.ai/code) **não** alcançam
+o `localhost` do operador: o mesmo MCP responde a elas pelo snapshot e grava no
+inbox, com o erro do servidor ao lado para ninguém confundir espelho com servidor.
+Para o MCP subir num container da nuvem, o ambiente precisa da `.venv` com
+`requirements.txt` instalado — o script de setup do ambiente é o lugar.
+
+Hermes, em `~/.hermes/config.yaml`. O nome `supermemory` mantém as ferramentas
+`mcp_supermemory_search_memory` e `mcp_supermemory_add_memory` que a skill
+`orquestrador-plan-loop` já chama:
+
+```yaml
+mcp_servers:
+  supermemory:
+    command: /caminho/do/orquestrador/.venv/bin/python
+    args: ["/caminho/do/orquestrador/mcp_servers/supermemory_local_server.py"]
+```
+
+### Espaço de desenvolvimento e despacho contínuo pelo Hermes
+
+Desde 2026-09-24 a memória tem dois espaços. O geral (`orquestrador`) guarda
+decisões e achados; o de desenvolvimento (`orquestrador-dev`) guarda só os
+registros `[dispatch]`, `[result]`, `[blocked]` e `[compact]` do despacho. O mesmo
+servidor MCP atende os dois: `supermemory-dev` é ele com
+`SUPERMEMORY_LOCAL_SPACE=dev`, já declarado no `.mcp.json`. O espaço dev não tem
+espelho versionado; sem o servidor, ele responde com o erro e nada mais.
+
+O Hermes despacha cada task do plano para a sessão Claude Code persistente do
+papel dela (`backend`, `frontend`, `docs`, `dba`), um turno por task com
+`claude -p --resume`, até o plano acabar. Política em `config/dev-dispatch.json`;
+instalação, pré-requisitos (login do Claude Code, uma worktree e uma sessão por
+papel, o campo `role` nos itens) e operação em
+[`.hermes/skills/orquestrador-dev-dispatcher/SKILL.md`](.hermes/skills/orquestrador-dev-dispatcher/SKILL.md).
+Para ver o que ele faria sem lançar nada:
+
+```powershell
+$env:HERMES_HOME = "$env:LOCALAPPDATA\hermes"
+C:\orquestrador\.venv\Scripts\python.exe .hermes\skills\orquestrador-dev-dispatcher\scripts\dispatch_tick.py --repo C:\orquestrador --dry-run
+```
+
+### Segurança da porta 6767
+
+O servidor escuta em `0.0.0.0:6767` (`ss -ltn | grep 6767`), e não há opção
+documentada para prendê-lo ao `localhost`. No WSL2 em modo NAT, o padrão, só o
+próprio Windows o alcança. Se o `.wslconfig` usa `networkingMode=mirrored`, ou se
+houver `portproxy`, a rede local também alcança. Bloqueie a entrada vinda da rede
+no firewall do Windows (PowerShell como administrador). O tráfego de loopback
+não passa por essa regra:
+
+```powershell
+New-NetFirewallRule -DisplayName "Supermemory local - bloqueia rede" -Direction Inbound `
+  -Protocol TCP -LocalPort 6767 -RemoteAddress LocalSubnet,Internet -Action Block
+```
+
+## 3. Modelos Groq
+
+Os perfis podem ser alterados sem modificar código:
+
+```dotenv
+ORQUESTRADOR_MODEL_STRUCTURED=openai/gpt-oss-20b
+ORQUESTRADOR_MODEL_CODING=openai/gpt-oss-120b
+ORQUESTRADOR_MODEL_REASONING=openai/gpt-oss-120b
+ORQUESTRADOR_MODEL_RESEARCH=groq/compound
+ORQUESTRADOR_MODEL_RESEARCH_FAST=groq/compound-mini
+ORQUESTRADOR_MODEL_INPUT_GUARD=meta-llama/llama-prompt-guard-2-86m
+ORQUESTRADOR_MODEL_OUTPUT_GUARD=openai/gpt-oss-safeguard-20b
+```
+
+Mapa recomendado, conforme a documentação oficial da Groq:
+
+| Perfil/modelo | Janela | Máx. saída | Uso |
+|---|---:|---:|---|
+| `openai/gpt-oss-20b` | 131.072 | 65.536 | router, classificações e JSON estruturado rápido |
+| `openai/gpt-oss-120b` | 131.072 | 65.536 | código, arquitetura, review, compliance e DBA |
+| `groq/compound` | 131.072 | 8.192 | pesquisa/agentes com ferramentas Groq |
+| `groq/compound-mini` | 131.072 | 8.192 | pesquisa rápida e sumarização |
+| `meta-llama/llama-prompt-guard-2-86m` | 512 | 512 | classificação de prompt de entrada |
+| `openai/gpt-oss-safeguard-20b` | 131.072 | 65.536 | inspeção de saída/safety |
+| `qwen/qwen3.6-27b` | 131.072 | 16.384 | alternativa experimental; modelo preview e mais caro |
+
+O perfil estruturado usa `json_schema` nos GPT-OSS; o perfil de
+código/raciocínio usa o GPT-OSS 120B. Compound fica reservado para pesquisa
+com ferramentas. Prompt Guard e Safeguard permanecem nos portões de segurança
+e foram validados pelo smoke real do workflow Groq.
+
+Os números da tabela são capacidades máximas dos modelos, não a quota da
+conta. No tier on-demand com 8.000 TPM, configure limites conservadores para
+que entrada mais saída solicitada caibam na quota:
+
+```dotenv
+ORQUESTRADOR_LLM_MAX_INPUT_CHARS=12000
+ORQUESTRADOR_GROQ_MAX_COMPLETION_TOKENS=2048
+```
+
+Ao migrar para um tier superior, esses dois valores podem ser aumentados sem
+alterar o código.
+
+Para OpenRouter, os limites não ficam presos aos valores conservadores da
+Groq. O catálogo operacional por modelo está centralizado em
+[`src/llm/llm_model_config.py`](src/llm/llm_model_config.py). A troca global do modelo
+é feita em um único ponto:
+
+| Modelo agentic | Contexto | Máx. saída | Input / 1M | Output / 1M |
+|---|---:|---:|---:|---:|
+| `deepseek/deepseek-v4-flash-0731` | 1.310.720 | 943.718 | US$ 0,04 | US$ 0,08 |
+| `minimax/minimax-m3` (fallback produção) | 1.048.576 | 512.000 | US$ 0,30 | US$ 1,20 |
+| `moonshotai/kimi-k2.7-code` (fallback produção) | 262.144 | 235.929 | US$ 0,67 | US$ 3,40 |
+
+Os valores são snapshot do catálogo e não substituem o preço efetivo da
+resposta. O adapter registra usage/custo retornados pelo OpenRouter.
+
+```dotenv
+ORQUESTRADOR_LLM_PROVIDER=openrouter
+ORQUESTRADOR_AGENT_MODEL=deepseek/deepseek-v4-flash-0731
+```
+
+O `DeepSeek V4 Flash 0731` está registrado com contexto de 1.310.720 tokens e
+até 943.718 tokens de saída. O limite de entrada operacional é de 1.000.000
+de caracteres para evitar enviar acidentalmente o repositório inteiro em uma
+única chamada. Esses valores podem ser sobrescritos temporariamente com
+`ORQUESTRADOR_MODEL_CONFIG_JSON`, sem editar agentes. Um teto operacional por
+ambiente (`ORQUESTRADOR_OPENROUTER_MAX_COMPLETION_TOKENS` ou
+`ORQUESTRADOR_LLM_MAX_INPUT_CHARS`) continua disponível e tem precedência.
+
+Referências oficiais: [Quickstart Groq](https://console.groq.com/docs/quickstart),
+[modelos](https://console.groq.com/docs/models), [API compatível com OpenAI](https://console.groq.com/docs/openai),
+[Structured Outputs](https://console.groq.com/docs/structured-outputs),
+[LangChain + Groq](https://console.groq.com/docs/langchain),
+[Prompt Caching](https://console.groq.com/docs/prompt-caching) e
+[limites](https://console.groq.com/docs/rate-limits).
+Páginas dos modelos: [Compound](https://console.groq.com/docs/compound),
+[Compound mini](https://console.groq.com/docs/compound/systems/compound-mini),
+[GPT-OSS 120B](https://console.groq.com/docs/model/openai/gpt-oss-120b),
+[GPT-OSS 20B](https://console.groq.com/docs/model/openai/gpt-oss-20b),
+[Qwen 3.6 27B](https://console.groq.com/docs/model/qwen/qwen3.6-27b),
+[Prompt Guard 86M](https://console.groq.com/docs/model/meta-llama/llama-prompt-guard-2-86m) e
+[Safeguard 20B](https://console.groq.com/docs/model/openai/gpt-oss-safeguard-20b).
+
+## 4. Roteamento multi-provedor
+
+Os agentes usam uma fábrica única (`src/llm/llm_provider.py`) e podem ser
+direcionados individualmente, por perfil ou globalmente. O comportamento
+legado continua sendo Groq por padrão. As credenciais são sempre lidas de
+variáveis de ambiente:
+
+```dotenv
+# Provedor único para todos os agentes
+ORQUESTRADOR_LLM_PROVIDER=groq
+GROQ_API_KEY=...
+
+# Alternativas suportadas pelo adapter
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+GEMINI_API_KEY=...
+```
+
+Para escolher provedor e modelo por agente, use JSON no secret/variável
+`ORQUESTRADOR_LLM_ROUTING_JSON` (não coloque chaves dentro do JSON):
+
+```json
+{
+  "default": {"provider": "groq", "model": "openai/gpt-oss-20b"},
+  "profiles": {
+    "reasoning": {"provider": "anthropic", "model": "claude-sonnet-4-5"},
+    "coding": {"provider": "openai", "model": "gpt-4o-mini"}
+  },
+  "agents": {
+    "agent_architect": {"provider": "anthropic", "model": "claude-opus-4-1"},
+    "agent_backend": {"provider": "openai", "model": "gpt-4o"},
+    "agent_code_review": {"provider": "groq", "model": "openai/gpt-oss-120b"}
+  }
+}
+```
+
+Precedência: `agents` > `profiles` > `default` > variáveis legadas de
+provedor/perfil. Assim, o futuro frontend poderá salvar uma política de
+execução sem alterar o código dos agentes. Para trocar tudo de uma vez,
+defina apenas `ORQUESTRADOR_LLM_PROVIDER`, a chave correspondente e os
+modelos `ORQUESTRADOR_MODEL_*`.
+
+## 5. Executar o orquestrador
+
+Modo automático para CI/local:
+
+```bash
+python main.py --auto-aprovar --tipo new --prazo "2 semanas" \
+  "Criar um sistema de controle de tarefas"
+```
+
+Opções importantes:
+
+```bash
+python main.py --projeto-id meu-projeto --documentacao docs/requisitos.md pedido
+python main.py --no-cache --auto-aprovar pedido
+python main.py --resume --thread-id minha-thread
+python main.py --devops --auto-aprovar pedido
+```
+
+O resultado só é considerado entrega aprovada quando `compliance_status=approved`.
+No modo sem chave LLM, o fluxo pode terminar com artefato fallback rejeitado.
+
+## 6. Sandbox e gates D2
+
+Construa a imagem segura:
+
+```bash
+docker build -f docker/Dockerfile.sandbox -t orquestrador-sandbox:py312 .
+```
+
+Execute gates em container:
+
+```bash
+ORQUESTRADOR_SANDBOX_MODE=docker \
+ORQUESTRADOR_SANDBOX_IMAGE=orquestrador-sandbox:py312 \
+python -m pytest -q
+```
+
+O container usa rede desabilitada, filesystem read-only, usuário não-root,
+limites de CPU/memória/PIDs, timeout e ambiente sem credenciais. O contrato
+`config/frontend-validation.json` fixa a versão do TypeScript usada pelo
+validador e pelo `docker/Dockerfile.sandbox`; o workflow instala essa mesma versão
+antes do graph. ESLint e Playwright continuam pertencendo ao projeto gerado e
+só são executados quando sua configuração e dependências versionadas existem.
+O modo
+`subprocess` é apenas uma opção local de desenvolvimento.
+
+Os gates executam compilação Python, Ruff, mypy, pytest, TypeScript e EXPLAIN
+SQL quando o artefato e o ambiente suportam cada verificação.
+
+## 7. HITL HTTP
+
+`HITL_API_TOKEN` é um token interno criado pelo operador para proteger a API
+HTTP local. Ele não é fornecido pelo Google, não é `GEMINI_API_KEY`, não é uma
+credencial OAuth do Antigravity e não é um token do Gitea. Mantenha-o fora do
+repositório, prompts, argumentos de processo, logs e artefatos.
+
+Em Windows PowerShell, gere um token aleatório sem colar o valor literal no
+histórico. Esta forma funciona também no Windows PowerShell antigo; não troque
+por uma expressão com parênteses ou barras invertidas:
+
+~~~powershell
+$bytes = New-Object byte[] 32
+$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
+
+try {
+    $rng.GetBytes($bytes)
+}
+finally {
+    $rng.Dispose()
+}
+
+$env:HITL_API_TOKEN = [Convert]::ToBase64String($bytes)
+Remove-Variable bytes, rng
+~~~
+
+A variável vale para a janela/processo atual. Inicie a API na mesma janela,
+preferencialmente a partir do checkout:
+
+~~~powershell
+Set-Location C:\orquestrador
+& 'C:\orquestrador\.venv\Scripts\python.exe' -m uvicorn server.app:app --host 127.0.0.1 --port 8000
+~~~
+
+Se a API rodar como serviço, carregue o mesmo token pelo cofre de segredos do
+serviço; não coloque o valor diretamente no comando, no arquivo versionado ou
+em `setx` compartilhado. Para chamar a API em outro terminal, forneça o mesmo
+valor ao ambiente desse cliente e use apenas o cabeçalho Bearer:
+
+~~~powershell
+$headers = @{ Authorization = "Bearer $env:HITL_API_TOKEN" }
+~~~
+
+Não execute `$env:HITL_API_TOKEN` sozinho, pois isso imprime o segredo. Ao
+terminar a sessão, limpe a variável se ela não for mais necessária:
+
+~~~powershell
+Remove-Item Env:HITL_API_TOKEN -ErrorAction SilentlyContinue
+~~~
+
+Verifique saúde:
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+Consulte ou retome uma thread usando `Authorization: Bearer ...`:
+
+```bash
+curl -H "Authorization: Bearer $HITL_API_TOKEN" \
+  http://127.0.0.1:8000/threads/minha-thread/state
+
+curl -X POST -H "Authorization: Bearer $HITL_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"resume_data":{"aprovado":true}}' \
+  http://127.0.0.1:8000/threads/minha-thread/resume
+```
+
+### 7.1. Antigravity OAuth: state dir, host e container
+
+`ORQUESTRADOR_ANTIGRAVITY_STATE_DIR` é o diretório privado onde a API mantém o
+estado protegido do login Antigravity. Ele não é uma API key, não é o
+`client_id`, não é o `client_secret` e não deve apontar para o checkout. O
+diretório pode conter o refresh token; por isso, copiar seus arquivos para
+prompt, log, issue, artefato ou workspace é uma violação da fronteira de
+credenciais.
+
+Há duas visões do mesmo diretório no ambiente local:
+
+| Onde | Caminho | Uso |
+|---|---|---|
+| API no host Windows | `C:\orquestrador-secrets\antigravity-state` | persistência do login e do refresh |
+| job Linux do runner Docker | `/var/lib/orquestrador/antigravity-state` | caminho usado pelo workflow |
+| secret do Gitea | `/var/lib/orquestrador/antigravity-state` | valor que o job recebe; não use o caminho Windows |
+
+O secret do Gitea configura somente o processo do job. Ele não configura uma
+API que já esteja rodando no host. A API precisa receber o caminho Windows em
+seu próprio ambiente; o runner precisa montar o mesmo diretório no caminho
+Linux antes de executar o workflow.
+
+O diretório deve ser criado e protegido pelo administrador do host, fora de
+`C:\orquestrador`, com ACL/DACL privada e sem junction, symlink ou reparse
+point. Para o job Linux, o runner autorizado deve montar esse mesmo diretório
+como `/var/lib/orquestrador/antigravity-state`; o valor salvo no Gitea é sempre
+o caminho Linux, nunca o caminho Windows. Não liste nem copie os arquivos de
+estado OAuth.
+
+#### 1. Cadastrar o caminho no Gitea
+
+Em `admin/projeto-global`, abra **Settings → Actions → Secrets** e cadastre
+somente o par abaixo:
+
+~~~text
+Nome:  ORQUESTRADOR_ANTIGRAVITY_STATE_DIR
+Valor: /var/lib/orquestrador/antigravity-state
+~~~
+
+Não coloque o caminho Windows nesse secret: o job é Linux dentro do Docker.
+Não tente ler o valor de volta pela interface e não registre secrets em
+artefatos. Os secrets `ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_ID` e
+`ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET` continuam necessários nos
+passos Kernel/Claude: a conta persistida contém um `refreshToken`, e o proxy
+precisa desses dois valores para convertê-lo em um access token antes da probe.
+Eles não são necessários para SDK ou Pi e não devem ser injetados nesses jobs.
+
+**Não crie um cliente OAuth próprio para esta rota.** Esta instrução existiu
+aqui até 2026-09-14 e estava errada; ela custou três runs e duas sessões de
+diagnóstico, e o sintoma não apontava para ela.
+
+Um cliente criado no seu projeto do Google Cloud **autentica com sucesso** — o
+login abre, o consentimento passa, o `refresh_token` é emitido e renovado — e
+mesmo assim toda chamada morre em `UPSTREAM_HTTP_403`. O Google emite token
+para qualquer cliente válido; o backend do Antigravity só aceita token cunhado
+pelo cliente em que ele confia. A falha aparece apenas na chamada real, muito
+depois do login, e se parece com um problema de conta ou de modelo.
+
+O par que a rota exige é o que o snapshot upstream traz embutido, visível nas
+linhas removidas de `antigravity_proxy/patches/003-account-boundary.patch`. O
+patch o tirou do **default de runtime** para que uma cópia do sidecar não fosse
+fonte de credencial; o valor continua no repositório, dentro do patch, e é dali
+que ele deve ser lido para preencher as duas variáveis:
+
+~~~text
+ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_ID
+ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET
+~~~
+
+Isso vale para o ambiente da API **e** para os secrets do Gitea: os dois lados
+precisam do mesmo cliente, porque o refresh token fica preso ao cliente que o
+emitiu. Trocar o cliente invalida a conta persistida — é obrigatório
+`logout` seguido de `auto --force-login` depois de mudar esses valores.
+
+Como confirmar em segundos, sem gastar uma corrida da matriz:
+
+~~~powershell
+Set-Location C:\orquestrador
+$env:PYTHONPATH = "."
+& '.\.venv\Scripts\python.exe' scripts\list_antigravity_models.py
+~~~
+
+Com o cliente certo, isso lista os modelos que a conta anuncia — em 2026-09-14,
+onze, incluindo `gemini-3.8-flash-tiered`, que é o default do workflow. Com o
+cliente errado, responde `500 ... UPSTREAM_HTTP_403`, e nenhuma troca de conta
+ou de modelo muda esse resultado.
+
+#### 2. Login automático
+
+Depois de configurar no ambiente da API `ORQUESTRADOR_ANTIGRAVITY_STATE_DIR`,
+`ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_ID` e
+`ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET`, execute somente o helper abaixo
+no host autorizado:
+
+~~~powershell
+Set-Location C:\orquestrador
+& 'C:\orquestrador\.venv\Scripts\python.exe' scripts\antigravity_auth.py auto
+~~~
+
+O helper valida o ambiente, abre o navegador, recebe o callback loopback sem
+clipboard ou impressão de código e executa `refresh`. Se já houver uma conta,
+ele não abre novo login. O resultado esperado é `ready`; a API grava o estado
+protegido somente no state dir. Não execute outro fluxo OAuth em paralelo.
+
+O valor produzido depois do login é estado protegido da conta, não deve ser
+usado como `ORQUESTRADOR_ANTIGRAVITY_OAUTH_CLIENT_SECRET` nem copiado para
+prompt, log, issue ou artefato.
+
+Somente depois de `status` pronto, refresh aprovado, DACL/reparse verificados e
+mount confirmado deve ser disparada a matriz real. O procedimento detalhado de
+AGS-004/ACP está em
+[`docs/ags004-acp-live-runbook.md`](docs/ags004-acp-live-runbook.md).
+
+## 8. Testes locais
+
+```bash
+pytest -q
+ruff check .
+mypy agents src server main.py scripts pi_harness mcp_servers
+python scripts/smoke/mcp_tools_binding.py
+python scripts/smoke/full_orchestrator_e2e.py
+```
+
+Smoke real Groq, com limite baixo de tokens:
+
+```bash
+GROQ_API_KEY="$GROQ_API_KEY" ORQUESTRADOR_SMOKE_MAX_TOKENS=512 \
+  ORQUESTRADOR_SMOKE_RUN_GRAPH=false \
+  python scripts/smoke_groq.py
+```
+
+O smoke não imprime a chave. O prompt caching é automático na Groq; o teste
+registra `cached_tokens`, mas um cache miss não é tratado como falha porque a
+Groq não garante hit em toda chamada. O workflow manual aprovado percorre
+Compound, Compound Mini, Prompt Guard, GPT-OSS 20B, GPT-OSS 120B, Qwen 27B e
+Safeguard 20B; todas as chamadas retornaram `OK`. O grafo fica desativado nesse
+workflow para separar smoke de modelos de gates HITL/Compliance.
+
+## 9. Batch API
+
+Ative somente para workloads assíncronos:
+
+```dotenv
+ORQUESTRADOR_BATCH_ENABLED=true
+ORQUESTRADOR_USE_BATCH=true
+```
+
+O adapter usa JSONL e a API Groq Batch. A janela é assíncrona; acompanhe o
+`batch_id` e não coloque prompts completos no `GraphState`.
+
+O Batch depende de habilitação do plano Groq. Se a API responder
+`403 not_available_for_plan`, a credencial está válida, mas a conta ainda não
+possui esse recurso; o adapter registra a situação e usa uma simulação offline
+correlacionável para testes locais. A execução real exige habilitar o Batch no
+plano Groq e usar um modelo elegível.
+
+Documentação: [Groq Batch API](https://console.groq.com/docs/batch) e
+[referência de batches](https://console.groq.com/docs/api-reference).
+
+## 10. Git remoto e GitHub Checks
+
+Em GitHub Actions, configure secrets/variáveis:
+
+```dotenv
+GITHUB_TOKEN=provided-by-github-actions
+GITHUB_REPOSITORY=owner/repository
+GITHUB_SHA=commit-sha
+ORQUESTRADOR_GIT_REMOTE=https://github.com/owner/repository.git
+```
+
+O workflow cria branch por thread, publica commit, abre PR draft e publica
+GitHub Check. Sem credencial explícita, o sistema mantém apenas branch/commit
+local e não inventa URL de PR.
+
+## 11. CI
+
+O workflow `quality.yml` é o portão determinístico: instalação, Ruff, mypy,
+pytest, os smokes e o build do sandbox. Ele é **dividido em dois jobs** —
+`quality` roda `-m 'not slow and not quarantine'` e `slow-e2e` roda o
+complemento —, e os dois somados são `pytest -q`.
+
+**Quando ele roda está nos próprios arquivos, e as duas superfícies diferem de
+propósito.** No GitHub, `pull_request` e disparo manual; no Gitea, disparo
+manual apenas, porque enfileirar um check obrigatório contra um runner local
+que nem sempre está ligado seria pior que não ter. Esta frase dizia "em todo
+push/PR" até 2026-09-15, o que estava errado nas duas — e é o tipo de cópia em
+prosa que `tests/guards/test_governance_document_truth_guard.py` passou a
+conferir contra o YAML.
+
+Ele **não bloqueia merge** em nenhuma das duas: o `master` do Gitea não tem
+regra de proteção, e a do GitHub é recurso pago em repositório privado. O que
+segura a qualidade antes do push é a regra de trabalho do `AGENTS.md`, aplicada
+pelo hook de pre-commit; o workflow é a repetição disso num Linux, que é o
+ambiente que a máquina do operador não tem.
+
+O workflow `groq-smoke.yml` é manual (`workflow_dispatch`) e exige o secret
+`GROQ_API_KEY` em um GitHub Environment protegido. Ele não deve ser executado
+em PRs de forks.
+
+Para executar o E2E do grafo com LLM real, use o workflow manual
+`.github/workflows/groq-graph-e2e.yml`. Ele usa o mesmo Environment protegido,
+executa as trilhas `new`, `feature` e `fix` com Groq e mantém os limites do tier
+on-demand. O workflow define `ORQUESTRADOR_REQUIRE_REAL_LLM=true`, portanto
+fallback offline faz o job falhar. A execução pode terminar com
+`compliance_status=rejected` por
+pendências legítimas; o objetivo desse workflow é comprovar o caminho real do
+grafo, não forçar aprovação de uma entrega sem evidência.
+
+No GitHub: **Actions → groq-graph-e2e → Run workflow → master**. Se o
+Environment exigir aprovação, aprove o job antes que os secrets sejam
+liberados.
+
+Permissões mínimas recomendadas:
+
+```yaml
+permissions:
+  contents: read
+  checks: write
+```
+
+Para PR remoto, conceda `contents: write` e `pull-requests: write` apenas no
+workflow manual protegido.
+
+## 12. Observabilidade
+
+Para exportar spans via OTLP:
+
+```dotenv
+OTEL_SERVICE_NAME=orquestrador
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+```
+
+Sem endpoint, o sistema registra apenas eventos técnicos locais. Prompts,
+código, tokens de autenticação e conteúdo de documentação não entram nos
+traces.
+
+## 13. Artefatos e D5
+
+O código gerado é salvo em `workspace/<thread-id>/`; o estado carrega hashes e
+referências do manifesto. Checkpoints legados ainda podem ser lidos durante a
+migração, mas novas execuções não precisam persistir blobs completos quando
+`ORQUESTRADOR_LEGACY_CODE_STATE=false`.
+
+## 14. Documentação do projeto
+
+- [Trilha de sessões e status](docs/plano-agentic-skills-status.md) (append-only, com índice em `docs/plano-status.json`)
+- [Estrutura de pastas e nomenclatura](docs/planos/auditoria/estrutura-pastas-e-nomenclatura.md)
+- [Fluxo de agentes, documentação e execução](docs/fluxo-agentes-documentacao-e-execucao.md)
+- [Guia de atualização dos validadores](docs/planos/auditoria/guia-atualizacao-versoes-validadores.md)
+
+## 15. Time travel, retenção e governança
+
+Forks são não destrutivos: o checkpoint pai permanece na thread original e o
+fork recebe novo `thread_id`, workspace independente e branch local.
+
+```bash
+python scripts/time_travel.py list --thread-id <id>
+python scripts/time_travel.py fork --thread-id <id> --checkpoint-id <cp> \
+  --field prazo_entrega --value "2026-09-15"
+python scripts/time_travel.py retention --days 30       # dry-run
+python scripts/time_travel.py retention --days 30 --purge --legal-hold <id>
+```
+
+Objetos D5 são endereçados por SHA-256 e o modo legado permanece opt-in:
+`ORQUESTRADOR_LEGACY_CODE_STATE=true`.
+
+## 16. Web escopada, qualidade e Batch
+
+Configure `ORQUESTRADOR_WEB_ALLOWLIST` antes de habilitar o MCP web; sem
+allowlist, HTTPS, resolução pública e aprovação humana, o conteúdo é
+bloqueado. Para quality gates completos, use `docker/Dockerfile.quality`, que instala
+Playwright/Lighthouse e grava `data/quality-evidence.json`.
+
+Submissão/consulta Batch:
+
+```bash
+python scripts/batch_cli.py submit --prompt "health" --model deepseek/deepseek-v4-flash-0731
+python scripts/batch_cli.py status <batch-id>
+```
+
+O workflow `.github/workflows/batch-submit.yml` usa somente modelos Groq Batch
+elegíveis e um GitHub Environment protegido.
+
+## 17. OpenRouter opcional (multi-provedor e multimodal)
+
+Groq continua sendo o padrão. Para habilitar OpenRouter, configure a chave
+somente no ambiente de execução (nunca em `GraphState`, registry ou logs):
+
+```dotenv
+ORQUESTRADOR_LLM_PROVIDER=openrouter
+OPENROUTER_API_KEY=...
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# opcional: OPENROUTER_HTTP_REFERER=https://seu-dominio
+# opcional: OPENROUTER_TITLE=Orquestrador
+# opcional: ORQUESTRADOR_OPENROUTER_TIMEOUT_SECONDS=90
+# compatibilidade legada, somente com ORQUESTRADOR_POLICY_LEGACY_OVERRIDES=true
+# ORQUESTRADOR_OPENROUTER_REASONING_EFFORT=low
+# ORQUESTRADOR_OPENROUTER_STRUCTURED_METHOD=json_schema
+# ORQUESTRADOR_OPENROUTER_REQUIRE_PARAMETERS=true
+# ORQUESTRADOR_OPENROUTER_STRUCTURED_RETRIES=1
+# opcional: ORQUESTRADOR_SMOKE_MAX_COMPLETION_TOKENS=16
+# opcional: ORQUESTRADOR_LLM_LOG_PREVIEW_CHARS=120 (0 desabilita previews)
+```
+
+Para modelos marcados no catálogo local como compatíveis, o padrão é
+`json_schema` com `strict=true`. No E2E canônico,
+`ORQUESTRADOR_OPENROUTER_REQUIRE_PARAMETERS=true` também restringe o
+roteamento a endpoints que aceitem os parâmetros enviados. Use `json_mode`
+somente como override para um modelo/endpoint sem structured outputs nativos.
+
+As chamadas diretas de OpenRouter (catálogo, mídia, TTS/STT, vídeo e smoke)
+usam o pacote oficial `openrouter==1.1.81`, com respostas tipadas e clientes
+síncrono/assíncrono. O LangGraph permanece sobre LangChain para preservar
+`Runnable`, saída estruturada, callbacks, ferramentas e o roteamento entre
+Groq, OpenRouter e demais provedores. O Batch é a única exceção: nessa versão
+do SDK o endpoint `/beta/batches` ainda não está exposto, portanto fica em um
+transporte HTTP privado e isolado.
+
+O SDK não realiza novas tentativas por conta própria. Backoff, circuit breaker,
+limite de quatro tentativas e fallback continuam centralizados no orquestrador.
+O adapter aceita `max_tokens` apenas por compatibilidade e o converte para
+`max_completion_tokens`; código novo deve usar o segundo nome.
+
+Cada chamada OpenRouter também emite logs reduzidos `[OPENROUTER] REQUEST`,
+`RESPONSE` e `ERROR`, com agente, modelo, tentativa, duração, hashes,
+tamanhos, tokens/cache, generation ID e erro sanitizado. Prompts e respostas
+completos não são gravados; o preview é limitado por
+`ORQUESTRADOR_LLM_LOG_PREVIEW_CHARS` (defina `0` em ambientes sensíveis).
+
+Os limites físicos de cada modelo permanecem em `src/llm/llm_model_config.py`. Já
+os orçamentos operacionais por agente ficam em um único JSON:
+
+```dotenv
+# Somente para migração de ambientes antigos; a fonte normal é
+# config/agent-policy.json e o mapa é ignorado sem opt-in explícito.
+ORQUESTRADOR_POLICY_LEGACY_OVERRIDES=true
+ORQUESTRADOR_AGENT_RUNTIME_JSON={"agent_clean_code":{"max_completion_tokens":8192,"reasoning_effort":"minimal","timeout_seconds":180,"structured_retries":1},"agent_code_review":{"max_completion_tokens":8192,"reasoning_effort":"minimal","timeout_seconds":180,"structured_retries":0}}
+ORQUESTRADOR_REVIEW_MAX_INPUT_CHARS=30000
+ORQUESTRADOR_RED_TEAM_MAX_INPUT_CHARS=30000
+```
+
+Falhas do Planejador ou de Requisitos são bloqueantes. Primeiro,
+`structured_retries` repete apenas a chamada do agente. Se todas as tentativas
+falharem, o portão `critical_failure_gate` permite repetir somente esse nó a
+partir do checkpoint ou encerrar. `ORQUESTRADOR_CRITICAL_NODE_RETRIES` limita
+essas repetições manuais (padrão: `1`). Em CI, `auto_aprovar` escolhe encerrar;
+documentação ausente nunca é transformada em fallback aprovado.
+
+Planejador e Consultor persistem seus resultados antes dos nós de aprovação.
+Assim, retomar um HITL não repete a chamada LLM. Clean Code, Code Review, Red
+Team e Compliance usam contratos compactos; fallback de um quality gate é
+registrado em `validacoes_fallback`, reprova o Compliance e faz o E2E real
+falhar explicitamente.
+
+O dispatcher é orientado por fases: o roadmap normalizado atribui os agentes
+de implementação e o grafo executa `agent_dba` (persistência/contrato),
+`agent_backend` (API) e `agent_frontend` (interface) em etapas separadas,
+com fan-in e aprovação HITL entre elas. Code Review e Red Team só começam após
+a última fase; threads antigas sem a atribuição `agentes` mantêm o fan-out
+legado para compatibilidade.
+
+O workflow `openrouter-graph-e2e.yml` define
+`ORQUESTRADOR_ITERATIVE_REPAIR=false`: ele valida uma rodada completa e
+encaminha achados ao Compliance sem repetir três ciclos de geração, que
+custariam três vezes mais para dizer a mesma coisa. O padrão está em
+`defaults.iterative_repair` e a variável o sobrepõe para uma corrida.
+
+Antes isso era `ORQUESTRADOR_E2E_NO_REPAIR`, lida com literal dentro de
+`src/state/graph.py`. É deliberadamente independente de
+`ORQUESTRADOR_RUN_MODE`: amarrar as duas faria quem quer uma corrida mais
+barata pinar o provedor sem pedir, e tornaria impossível medir o próprio laço
+de reparação.
+
+Rotas podem ser escolhidas por agente/perfil/thread em
+`ORQUESTRADOR_LLM_ROUTING_JSON`; `fallback_models` usa a cascata nativa do
+OpenRouter e `external_routes` define a cascata entre provedores. O limite é
+de quatro tentativas e erros de autenticação, payload, orçamento e segurança
+não fazem fallback.
+
+A precedência é `thread/agente > thread/perfil > projeto/agente >
+projeto/perfil > defaults do projeto > ambiente`. O registry persiste apenas
+JSON de política; chaves permanecem exclusivamente em variáveis de ambiente.
+
+### Claude Code como harness opcional
+
+É possível adicionar o Claude Code/Anthropic Agent SDK como backend de
+execução dos agentes de código, mantendo a OpenRouter como gateway. A
+arquitetura recomendada é preservar o LangGraph como plano de controle
+(roteamento, HITL, orçamento, checkpoints, Compliance e D5) e delegar apenas
+uma tarefa de implementação isolada ao harness Claude Code, com workspace e
+tools permitidas explicitamente.
+
+O processo filho receberá as credenciais somente em memória:
+
+```dotenv
+ANTHROPIC_BASE_URL=https://openrouter.ai/api
+ANTHROPIC_AUTH_TOKEN=<valor de OPENROUTER_API_KEY injetado no processo>
+ANTHROPIC_API_KEY=
+```
+
+O executor está disponível por política explícita. O workflow canônico usa
+`deepseek/deepseek-v4-flash-0731` através do protocolo Anthropic Skin. A
+documentação da OpenRouter garante formalmente o Claude Code apenas com
+modelos Anthropic first-party; DeepSeek, MiniMax e Kimi são portanto uma rota
+experimental do projeto e precisam de E2E próprio. A política de produção é:
+
+```json
+{"agents":{"agent_backend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"]},"agent_frontend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"]}}}
+```
+
+MiniMax M3 custa US$ 0,30/M de input e US$ 1,20/M de output; Kimi K2.7
+Code custa US$ 0,67/M de input e US$ 3,40/M de output (valores de catálogo,
+o custo efetivo vem do usage). Esses fallbacks só são habilitados quando
+`ORQUESTRADOR_EXECUTOR_FALLBACK_MODE=production`; workflows usam
+`disabled`, DeepSeek exclusivamente e no máximo três tentativas. Erros de
+payload, autenticação, orçamento, segurança e ownership nunca fazem fallback.
+
+Documentação oficial: [Quickstart](https://openrouter.ai/docs/quickstart),
+[Client SDKs](https://openrouter.ai/docs/client-sdks/overview),
+[SDK Python](https://openrouter.ai/docs/client-sdks/python/overview),
+[model fallbacks](https://openrouter.ai/docs/guides/routing/model-fallbacks),
+[multimodal](https://openrouter.ai/docs/guides/overview/multimodal/overview),
+[Batch](https://openrouter.ai/docs/batch-quickstart),
+[prompt caching](https://openrouter.ai/docs/guides/best-practices/prompt-caching#caching-in-the-batch-api)
+e [MCP administrativo](https://openrouter.ai/docs/guides/overview/mcp-server).
+Para o harness, consulte [Claude Code com OpenRouter](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration)
+e [Anthropic Agent SDK com OpenRouter](https://openrouter.ai/docs/guides/community/anthropic-agent-sdk).
+
+Workflows manuais separados:
+
+```text
+.github/workflows/openrouter-smoke.yml
+.github/workflows/openrouter-graph-e2e.yml
+.github/workflows/openrouter-batch-submit.yml
+.github/workflows/openrouter-batch-status.yml
+```
+
+Configuração no GitHub:
+
+1. Crie uma chave em [OpenRouter Keys](https://openrouter.ai/settings/keys).
+2. Em **Settings → Environments**, crie exatamente `openrouter-smoke`,
+   `openrouter-graph-e2e` e `openrouter-batch`.
+3. Em cada Environment, adicione o secret **`OPENROUTER_API_KEY`**. Não use
+   Repository variable nem coloque a chave no YAML. Se o Environment exigir
+   aprovação, aprove a implantação antes da execução.
+4. Opcionalmente adicione as variables `OPENROUTER_HTTP_REFERER` e
+   `OPENROUTER_TITLE` para identificação da aplicação.
+5. Em **Actions → workflow → Run workflow**, execute primeiro o smoke. Depois
+   use o graph E2E. Batch exige quota/plano habilitado; submeta o lote e copie
+   o `batch_id` impresso para o workflow de status.
+
+Pela CLI do GitHub:
+
+```bash
+gh secret set OPENROUTER_API_KEY --env openrouter-smoke --repo OWNER/REPO
+gh secret set OPENROUTER_API_KEY --env openrouter-graph-e2e --repo OWNER/REPO
+gh secret set OPENROUTER_API_KEY --env openrouter-batch --repo OWNER/REPO
+  gh workflow run openrouter-smoke.yml --ref master -f model=deepseek/deepseek-v4-flash-0731
+gh run watch --exit-status
+```
+
+O grafo E2E executa uma trilha por vez por padrão, reduzindo rate limit e
+duração. Escolha a trilha assim:
+
+A trilha `new` do workflow usa deliberadamente o pedido fixo e pequeno
+`CRUD simples de produtos (código identificador e nome)`, para validar o
+fluxo do grafo e o Compliance sem transformar o teste em uma geração de
+produto grande. Ele pode ser sobrescrito apenas por `ORQUESTRADOR_E2E_CLIENT_INPUT`
+em execuções controladas.
+
+Quando a trilha `new` não recebe `projeto_id` nem `mcp_roots`, o Arquiteto usa
+um contexto **greenfield** determinístico e não indexa o código-fonte do
+próprio orquestrador. Para evoluir um código existente desde o início, registre
+o projeto/base ou forneça um root MCP explícito; nesse caso a análise detalhada
+do repositório continua habilitada.
+
+```bash
+gh workflow run openrouter-graph-e2e.yml --ref master \
+  -f model=deepseek/deepseek-v4-flash-0731 -f tracks=new
+# Para executar todas: -f tracks=new,feature,fix
+```
+
+O primeiro passo de cada workflow executa `test -n "$OPENROUTER_API_KEY"`; se
+falhar, o secret está no Environment errado, o Environment não foi aprovado ou
+o nome está diferente. A API usa `https://openrouter.ai/api/v1`, conforme o
+[Quickstart oficial](https://openrouter.ai/docs/quickstart), e os modelos
+devem ser IDs publicados no [catálogo](https://openrouter.ai/models).
+Para contas com crédito limitado, reduza opcionalmente
+`ORQUESTRADOR_OPENROUTER_MAX_COMPLETION_TOKENS`; quando ausente, cada modelo
+usa o limite registrado em `src/llm/llm_model_config.py`. Os workflows OpenRouter
+usam uma cascata paga de DeepSeek V4 Flash e Solar Pro4, evitando as cotas
+instáveis dos endpoints gratuitos.
+
+O smoke registra modelo efetivo, generation ID, tokens, cache, custo e BYOK.
+O smoke usa `ORQUESTRADOR_SMOKE_MAX_COMPLETION_TOKENS` (16 por padrão, apenas
+para manter a chamada curta); `ORQUESTRADOR_SMOKE_MAX_TOKENS` continua aceito
+temporariamente. Ele não limita as execuções do grafo. No Batch, `max_tokens`
+é opcional por item: se omitido, o adapter não injeta um teto artificial do
+OpenRouter; informe-o somente quando quiser limitar aquele item.
+Batch OpenRouter aceita apenas texto, um modelo por lote e janela de 24 horas;
+simulação offline só é permitida com
+`ORQUESTRADOR_BATCH_OFFLINE_SIMULATION=true`.
+
+Uploads multimodais são armazenados localmente por SHA-256 em D5. Imagem,
+PDF, áudio e vídeo são convertidos para as partes da API apenas durante a
+requisição; base64 e binários não entram em checkpoints. As APIs prontas para
+frontend são `/llm/*`, `/integrations/openrouter/mcp/*`, `/media/*`,
+`/batches` e `POST /threads`. Para OAuth administrativo por usuário configure
+`OIDC_ISSUER_URL`, `OIDC_AUDIENCE`, `OIDC_JWKS_URL` e
+`ORQUESTRADOR_CREDENTIAL_ENCRYPTION_KEY`.
+
+## Planejamento especializado e executores agentic
+
+O grafo separa planejamento e execução: requisitos, arquitetura e Clean Code
+alimentam os planos DBA, Backend e Frontend; uma validação determinística
+confere cobertura/propriedade; uma única aprovação HITL libera a ordem DBA →
+Backend → Frontend. Backend não pode possuir migrations e Frontend não pode
+inventar endpoint, SQL ou regra de negócio. Migrations que falham no banco
+efêmero não entram no manifesto D5.
+
+O executor padrão é o **`kernel`**, declarado em `config/agent-policy.json`
+(`defaults.executor`). Os executores selecionáveis são `kernel`, `claude_code`,
+`pi` e `antigravity_sdk` (`defaults.selectable.executor`); `legacy` (o adapter
+LangChain) e `deepseek_harness` permanecem apenas como compatibilidade, em
+`COMPATIBILITY_EXECUTOR_NAMES` de `src/execution/executors.py`, e não são o
+padrão de nada. Claude Code pode ser ativado por política para Backend/Frontend
+e usa o SDK `claude-agent-sdk` com OpenRouter/Anthropic Skin. DeepSeek Harness é
+somente shadow/piloto em Linux, workspace isolado e sem aplicar artefatos ao
+workspace canônico. Se um executor explicitamente solicitado não estiver
+disponível, a execução é bloqueada; não há fallback silencioso.
+
+Cada executor externo trabalha numa cópia descartável do workspace. Apenas
+arquivos textuais permitidos pela task card, pertencentes ao agente e dentro do
+orçamento são promovidos ao armazenamento D5. Remoções, binários, paths fora do
+plano e violações de propriedade bloqueiam a fase. Claude Code não recebe Bash,
+WebFetch, WebSearch ou NotebookEdit; os limites de contexto/conclusão do
+DeepSeek vêm de `src/llm/llm_model_config.py`, e não do arquivo Cordis.
+
+O executor `pi` roda o loop do harness Pi (`@earendil-works/pi-agent-core` +
+`pi-ai`) num sidecar Node privado em `pi_harness/worker/`. Ele vem **desligado** em
+`config/agent-policy.json` (`pi_harness.enabled=false`) e, quando ligado,
+atende só os owners listados em `pi_harness.agents`. O sidecar não recebe
+credencial, Git, shell nem o workspace canônico: cada inferência volta para a
+fachada central em `src/llm/llm_provider.py` e cada ferramenta é revalidada contra
+o WorkPacket em `pi_harness/tools.py`. Instale o worker com
+`npm ci --ignore-scripts --prefix pi_harness/worker` e verifique o runtime com
+`python -m pi_harness.bridge`. Detalhes de operação em
+[`docs/planos/auditoria/operacao-pi-harness.md`](docs/planos/auditoria/operacao-pi-harness.md).
+
+Instale os SDKs opcionais em Linux/Docker com
+`pip install -r requirements-agentic.txt`; a instalação padrão não os exige.
+As versões testadas são `claude-agent-sdk==0.2.128` e
+`deepseek-harness-sdk==0.1.1rc2`. O DeepSeek Harness não possui wheel do runtime
+para Windows e, por isso, seu piloto roda apenas em Linux.
+
+Exemplo de política (sem credenciais; fallbacks somente em produção):
+
+```json
+{"default":{"executor":"kernel"},"fallback_mode":"disabled","agents":{"agent_backend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"],"shadow_executor":"pi"},"agent_frontend":{"executor":"claude_code","model":"deepseek/deepseek-v4-flash-0731","fallback_models":["minimax/minimax-m3","moonshotai/kimi-k2.7-code"],"shadow_executor":"pi"},"agent_dba":{"executor":"kernel"}}}
+```
+
+MCPs são registrados por especialidade: Context7 (`resolve-library-id` e
+`query-docs`) para planejamento/desenvolvimento, 21st somente para Frontend e
+PostgreSQL somente leitura para o DBA. Configure `CONTEXT7_API_KEY`,
+`TWENTY_FIRST_API_KEY` e `MCP_POSTGRES_DSN` apenas no secret manager; o estado
+guarda somente hashes de evidência e capacidades liberadas.
+
+O cliente MCP aplica a allowlist antes de cada chamada, protege conteúdo
+externo contra prompt injection e limita o texto retornado. No PostgreSQL, o
+modelo não recebe a ferramenta `connect` nem o DSN: o orquestrador conecta com
+um usuário read-only, entrega somente schema/query/EXPLAIN e desconecta. A
+validação de migrations usa separadamente `MCP_POSTGRES_VALIDATION_DSN`, que é
+aceito apenas para hosts allowlisted e bancos efêmeros. Para inspecionar a
+conectividade real use `GET /mcp/capabilities?probe=true`.
+
+Claude Code recebe proxies MCP locais, não os servidores remotos brutos. Esses
+proxies publicam exclusivamente a allowlist read-only e reaplicam sanitização e
+Prompt Guard em cada resultado. Portanto, ferramentas novas ou mutantes que o
+21st venha a publicar não ficam automaticamente acessíveis ao executor.
+
+Para testes de tela conduzidos por Jev e Playwright, inclusive a instalação do
+MCP Node via GitHub em outros harnesses, consulte
+[`docs/jev-browser-mcp.md`](docs/jev-browser-mcp.md). A escolha entre o browser
+headless do harness e Chrome/Edge visível fica em `config/ui-testing.json`; a
+chave do OpenRouter fica no ambiente do processo.
+
+O sidecar PostgreSQL de teste pode ser validado localmente com:
+
+```bash
+docker compose -f docker-compose.agentic.yml up -d --build
+python scripts/smoke_mcp.py postgres --rows
+python scripts/smoke_postgres_discovery.py --seed tests/fixtures/postgres_existing_schema.sql
+docker compose -f docker-compose.agentic.yml down -v
+```
+
+`smoke_mcp.py postgres` lista as ferramentas publicadas; `--rows` chama
+`pg_query`/`pg_explain` de verdade e exige que o gate recuse a leitura de linhas
+sem consent `read_only_data`. Listar ferramenta não é exercitá-la: foi por isso
+que um nome de argumento errado sobreviveu a probes verdes.
+
+`smoke_postgres_discovery.py` homologa AUD-034-DISCOVERY ponta a ponta —
+introspecta o schema físico por MCP, aplica `UP`/`DOWN` no banco efêmero,
+reintrospecta e compara os três snapshots. Sai com 0 somente quando a migration
+reversível é verificada **e** a irreversível é bloqueada. As duas DSNs são
+deliberadamente diferentes: `MCP_POSTGRES_DSN` é read-only e é a que a sessão
+MCP usa, `MCP_POSTGRES_VALIDATION_DSN` é a única que aplica migration e só é
+aceita para host allowlisted e banco efêmero.
+
+Novas APIs autenticadas: `GET/PUT /execution/policies`,
+`GET /execution/executors` e `GET /mcp/capabilities`. `POST /threads` aceita
+`execution_policy` por thread. Workflows de rollout:
+
+```text
+.github/workflows/agentic-offline.yml
+.github/workflows/mcp-integration-smoke.yml
+.github/workflows/agentic-graph-e2e.yml
+.github/workflows/deepseek-harness-eval.yml
+.github/workflows/executor-benchmark.yml
+.github/workflows/skills-offline.yml
+```
+
+### Skills por agente
+
+O catálogo canônico fica em `.agents/skills`. A descoberta retorna apenas
+nome, descrição, origem e hash; corpo e referências são carregados somente
+quando a política do agente autoriza a skill e a stack é compatível. O estado,
+relatório e logs recebem somente `skill_catalog_digest` e hashes de evidência.
+Campos `model`, `provider`, `tools`, credenciais e orçamento encontrados em
+frontmatter são inertes: a rota continua sendo resolvida exclusivamente pela
+política LLM/execution policy.
+
+Exemplo para ativar `frontend-design` no Designer UI e Remotion no Frontend/Code Review:
+
+```json
+{
+  "default": {"executor": "kernel", "skills": [], "skill_mode": "disabled"},
+  "agents": {
+    "agent_ui_designer": {"skills": ["frontend-design"], "skill_mode": "required"},
+    "agent_frontend": {"skills": ["frontend-design", "remotion-best-practices"], "skill_mode": "auto"},
+    "agent_code_review": {"skills": ["remotion-best-practices"], "skill_mode": "auto"}
+  }
+}
+```
+
+Valide o bundle e seu lockfile sem rede:
+
+```bash
+python scripts/validate_skills.py
+python -m pytest -q tests/test_skill_registry.py
+```
+
+As APIs autenticadas `GET /skills`, `GET /skills/{name}`,
+`GET /skills/capabilities`, `GET/PUT /skills/policies` e
+`POST /skills/validate` nunca retornam o corpo da skill. Instalação remota fica
+desabilitada até existir preview/diff, scanner, aprovação HITL e atualização
+atômica do lockfile. `find-skills` é reservado ao futuro curador administrativo
+e não é liberado aos desenvolvedores.
+
+Crie o Environment protegido `agentic-e2e`, exija aprovação manual e cadastre
+`OPENROUTER_API_KEY`, `CONTEXT7_API_KEY` e uma `TWENTY_FIRST_API_KEY` nova. A
+ordem de rollout é: `agentic-offline`, `mcp-integration-smoke`,
+`agentic-graph-e2e`, `deepseek-harness-eval` e, por fim,
+`executor-benchmark`. Os três últimos são validações reais/manuais: não devem
+ser tratados como aprovados somente porque a suíte offline passou. Consulte os
+guias oficiais:
+[Claude Code com OpenRouter](https://openrouter.ai/docs/guides/coding-agents/claude-code-integration),
+[Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python),
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md),
+[Context7](https://github.com/upstash/context7),
+[21st MCP](https://github.com/21st-dev/magic-mcp) e
+[pg-mcp-server](https://github.com/stuzero/pg-mcp-server).