npm - @diegosouzacdv/jev-browser-mcp - Versions diffs - 0.3.0 → 0.3.1 - Mend

@diegosouzacdv/jev-browser-mcp 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,1818 +1,354 @@
-# Orquestrador Multi-Agente Corporativo
+# Automação de tela com Jev e Playwright
-Orquestrador de desenvolvimento de software com LangGraph, LangChain, MCP,
-persistência SQLite, revisão multiagente, gates determinísticos, HITL e
-artefatos versionados por manifesto.
+## Instalar em outros harnesses com npm/npx
-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.
+O repositório também contém um pacote Node independente do harness. Ele fala
+MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
+qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
+usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
+Python do orquestrador. As opções específicas do pacote ficam isoladas no
+bloco `jev_browser_mcp` para preservar o contrato do servidor Python.
-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):
+Instale a versão publicada do npm diretamente no harness. Para fixar uma
+versão em produção, use o número explícito no argumento do pacote:
 ```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"}
+  "mcpServers": {
+    "jev-browser": {
+      "command": "npx",
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.3.1"],
+      "env": {
+        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
+        "JEV_BROWSER_MODE": "harness"
+      }
+    }
   }
 }
 ```
-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:
+O formato de interpolação de variáveis varia por harness. Injete a chave por
+um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
+de configuração. Para instalar no projeto Node do próprio harness:
-```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
+```sh
+npm install @diegosouzacdv/jev-browser-mcp
+npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
 ```
-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.
+No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
+controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
+perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
+as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
+`JEV_BROWSER_PROFILE`. O browser permanece aquecido enquanto o processo MCP
+estiver ativo e fecha quando o harness encerra o processo. `JEV_PROVIDER_URL`
+e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
+nome de variável declarado em `jev.credential_env`.
+Uma aplicação Node também pode importar `createJevBrowserServer` por
+`@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
+que ela já utiliza.
+O pacote é montado em uma pasta temporária isolada: o publicador usa o campo
+`files` do `package.json` para copiar somente o código Node, a configuração
+compartilhada e esta documentação, que também vira o `README.md` da raiz do
+pacote. Assim, o npm não inclui o README geral do orquestrador na página do MCP.
+Para gerar e conferir o pacote antes de publicar, execute
+`npm run pack:jev-browser-mcp`; para publicar uma versão já autenticada no npm, execute
+`npm run publish:jev-browser-mcp`. A instalação por npm é a recomendada; use a
+referência GitHub somente quando precisar experimentar uma revisão ainda não
+publicada.
+### Contrato do pacote
+O executável oferece `choose_next_action` e `run_browser_flow`, mantém uma
+sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
+passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
+hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
+raiz local configurada e reações idempotentes a um comentário único. Também
+aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
+JavaScript enviado pelo harness, seletores livres nem coordenadas. Ele usa a
+biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
+Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
+`stderr` para não misturar com JSON-RPC.
+O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
+página pode conter instruções maliciosas. O Jev recebe a captura acessível com
+uma instrução para tratar esse conteúdo como dado não confiável; não inclua
+segredos no fluxo, no resultado esperado ou nas descrições dos planos.
+Para um fluxo conhecido, o LLM do harness procura o cenário e os critérios de
+aceitação no projeto e chama `jev_browser.run_browser_flow` com planos
+candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
+a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
+plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
+resultado esperado na tela.
+Cada plano pode usar:
+- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
+- `wait_for_text` e `wait_for_condition` (`network_idle`, limitado pelo timeout
+  de ação configurado);
+- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
+  `Enter`, `Escape` ou `Tab`;
+- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`;
+- `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
+  dropzone;
+- `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
+- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
+  não repetem uma reação já no estado pedido e distinguem `Curtir` de
+  `Descurtir`.
+Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
+container acessível único, como uma linha ou card. `index` escolhe uma ocorrência
+zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
-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()
+```json
+{
+  "action": "click",
+  "role": "button",
+  "name": "Add to cart",
+  "within": {"role": "group", "name": "Sauce Labs Backpack"}
 }
-$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
+{"action":"click","role":"button","name":"Add to cart","index":0}
 ```
-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.
+### Captura de downloads
-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):
+Marque o clique que deve iniciar um download com `expect_download: true`. O
+Playwright começa a aguardar o evento antes do clique; após a transferência
+terminar, o MCP verifica o tamanho, sanitiza o nome sugerido e copia o arquivo
+para `JEV_BROWSER_ARTIFACT_DIR` (ou para o diretório de artefatos configurado).
+O resultado inclui a lista `downloaded_files`, com nome, caminho local e bytes;
+cada passo também contém o arquivo capturado. Os limites contam arquivos e bytes
+por fluxo. A checagem de tamanho acontece depois da transferência do navegador,
+antes de copiar para a pasta de artefatos.
 ```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"}}}
+{"action":"click","role":"button","name":"Export report","expect_download":true}
 ```
-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`.
+`jev_browser_mcp.browser.max_download_files`, `max_download_file_bytes`,
+`max_download_total_bytes` e `max_download_timeout_seconds` definem os limites.
+O diretório de artefatos deve ser local e protegido: arquivos baixados podem
+conter dados da aplicação.
-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.
+### Auditoria automatizada de acessibilidade
-### MCP de navegador com Jev e Playwright
+Use `audit_accessibility` depois de colocar a página no estado que deseja
+verificar:
-O pacote independente `@diegosouzacdv/jev-browser-mcp` conecta qualquer harness
-compatível com MCP por `stdio` ao Jev e ao Playwright. Requer Node.js 22 ou mais
-recente. Instale o navegador do Playwright uma vez para execuções no modo
-`harness`:
+```json
+{"action":"audit_accessibility","standard":"wcag2aa"}
+```
+O MCP usa `@axe-core/playwright` com as tags WCAG 2.0 e 2.1 A/AA. O retorno
+resume as violações por regra, impacto e quantidade de nós, sem copiar HTML ou
+trechos da página. Qualquer violação reprova esse fluxo. A auditoria automática
+encontra problemas comuns, mas não comprova conformidade WCAG completa; combine-a
+com revisão manual e testes com usuários assistivos.
+Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
+corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
+conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
+configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
+próximos quando o snapshot os encontrar. O plano não aceita JavaScript enviado
+pelo harness, coordenadas ou seletores livres.
+Os aliases `value` → `text` em `type`/`wait_for_text` e `value` → `expected` em
+asserções são aceitos. `comment` também é aceito em planos e passos, mas é
+ignorado e não é enviado ao Jev. Campos fora do contrato continuam sendo
+recusados.
+### Upload de arquivos
+Defina `JEV_BROWSER_UPLOAD_ROOT` como uma pasta absoluta que contenha os arquivos
+de fixture. Cada caminho passado ao fluxo também precisa ser absoluto; o MCP
+resolve links simbólicos e recusa qualquer arquivo fora dessa raiz. Só aceita
+arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e 25 MiB no
+total do passo, conforme `jev_browser_mcp.browser` em `config/ui-testing.json`.
+Os bytes são lidos e validados no processo local antes de serem entregues ao
+Playwright. O MCP não envia esses bytes ao Jev nem os inclui diretamente na
+resposta; texto que o próprio site exibir na interface ainda pode aparecer no
+snapshot devolvido ao harness.
-```sh
-npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
+```json
+{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/fixtures/nota.pdf"}
 ```
-Registre o servidor MCP no formato aceito pelo seu harness. Exemplo de
-configuração comum:
+Para uma área de arrastar, use o papel e o nome acessível da dropzone. Para um
+botão que abre a janela nativa, use `target: "button"`; sem `target`, a presença
+de `label` seleciona o input e `role`/`name` seleciona esse botão.
 ```json
-{
-  "mcpServers": {
-    "jev-browser": {
-      "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp"],
-      "env": {
-        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
-        "JEV_BROWSER_MODE": "harness"
-      }
-    }
-  }
-}
+{"action":"upload_file","target":"dropzone","role":"region","name":"Anexos","file_paths":["/fixtures/a.pdf","/fixtures/b.png"]}
 ```
-Configure `OPENROUTER_API_KEY` no secret manager ou no ambiente do processo
-que inicia o harness. Não coloque a chave no JSON. O endpoint e o modelo
-Decisions têm valores padrão no pacote; `JEV_PROVIDER_URL` e `JEV_MODEL` podem
-substituí-los.
-Escolha o navegador por variáveis de ambiente:
+Se `JEV_BROWSER_UPLOAD_ROOT` não estiver definido, a ação recusa a execução. O
+limite evita que um plano transforme o MCP em leitor arbitrário de arquivos do
+computador.
-- `JEV_BROWSER_MODE=harness` inicia um navegador isolado e sem interface,
-  adequado para testes automatizados e CI.
-- `JEV_BROWSER_MODE=computer` abre o Chrome ou Edge instalado. O MCP usa um
-  perfil persistente próprio; faça login nele uma vez. Não configure o perfil
-  pessoal que já está aberto no computador.
-- `JEV_BROWSER_CHANNEL=chrome` ou `msedge` escolhe o navegador.
-- `JEV_BROWSER_PROFILE` define o caminho absoluto do perfil persistente no
-  modo `computer`.
-Para um fluxo conhecido, o agente do harness consulta o cenário e os critérios
-de aceitação no projeto e chama `run_browser_flow` uma vez. Informe o objetivo,
-a URL inicial, o resultado esperado e planos candidatos declarativos. O Jev
-escolhe um dos planos com base no snapshot acessível da página; o MCP executa
-os passos e confere se o resultado esperado apareceu. Exemplo resumido:
+Exemplo de chamada:
 ```json
 {
-  "flow": "Adicionar o produto ao carrinho",
+  "flow": "Adicionar o produto ao carrinho e confirmar o resumo",
   "initial_url": "http://127.0.0.1:4173/products/coffee",
   "expected_outcome": "Coffee added to cart",
+  "options": {
+    "fast_path": true,
+    "snapshot_scope": "main",
+    "capture_network_errors": true,
+    "screenshot_on_failure": true
+  },
   "candidate_plans": {
-    "add_product": {
-      "description": "Adicionar o produto visível ao carrinho",
+    "add_and_confirm": {
+      "description": "Adicionar o produto visível ao carrinho e abrir o resumo",
       "steps": [
         {"action": "click", "role": "button", "name": "Add to cart"},
-        {"action": "wait_for_text", "text": "Coffee added to cart"}
+        {"action": "wait_for_text", "text": "Coffee added to cart"},
+        {"action": "click", "role": "link", "name": "View cart"},
+        {"action": "assert_text", "role": "heading", "name": "Order summary", "expected": "Coffee"}
       ]
     }
   }
 }
 ```
-O servidor também oferece `choose_next_action` para exploração passo a passo;
-esse modo exige chamadas separadas do harness e costuma ser mais lento. Os
-planos aceitam ações limitadas como clique por papel e nome acessível,
-preenchimento, espera por texto, rolagem e reação idempotente a um comentário
-único. Não aceitam JavaScript arbitrário, coordenadas nem seletores livres.
-Valores digitados ficam no Playwright e são removidos do conteúdo enviado ao
-Jev. Não coloque senhas, tokens ou outros segredos na descrição do fluxo ou
-nos critérios.
-O contrato também oferece `select_option`, `hover`, teclas `Enter`/`Escape`/`Tab`,
-asserções por elemento (`assert_text`, `assert_value`, `assert_visible`,
-`assert_hidden`), escopo de alvo por `within` e índice zero-based com `index`,
-além de alvos nomeados em iframes. `upload_file` aceita inputs, botões que abrem
-o seletor nativo e dropzones; configure `JEV_BROWSER_UPLOAD_ROOT` para limitar
-os arquivos locais que o MCP pode ler. `click` com `expect_download: true`
-captura arquivos na pasta de artefatos dentro dos limites configurados, e
-`audit_accessibility` roda axe nas tags WCAG 2.0/2.1 A/AA. A análise automatizada
-não substitui auditoria manual. Um único plano usa o fast-path por padrão e não
-chama a API Decisions. `options` pode limitar o
-snapshot a `main` ou `dialog`, bloquear rastreadores, capturar erros de console
-e rede e salvar screenshot/trace local em falhas. Os caminhos e limites estão
-descritos no [guia completo](docs/jev-browser-mcp.md).
-A resposta informa o status, o plano escolhido, as ações executadas, a captura
-final e se o resultado esperado foi confirmado. Consulte o [guia completo do
-MCP Jev Browser](docs/jev-browser-mcp.md) para schemas, limites, tempos e
-detalhes de segurança.
-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).
+O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
+deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
+de controles ou valores de formulário. Valores de `type` são usados localmente
+pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
+retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
+configurado.
+O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
+harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
+mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
+ação; prefira `run_browser_flow` quando os passos esperados puderem ser
+descritos antes da execução.
+## Configuração
+Edite `config/ui-testing.json`. URL, modelo do provedor, variável de credencial
+e limites compartilhados ficam nos blocos `browser` e `jev`. As opções próprias
+do pacote Node ficam no bloco opcional `jev_browser_mcp`, que não altera o
+contrato lido pelo servidor Python. Preserve a estrutura completa exigida pelos
+validadores.
+`browser.mode` aceita `harness` ou `computer`:
+- `harness` usa Chrome headless e perfil isolado, adequado a execuções do
+  harness e CI; o estado de autenticação é descartado ao final da chamada.
+- `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
+  persistente `browser.computer_user_data_dir`, separado por navegador. Não
+  reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
+  cookies permanecem nele entre chamadas.
+`browser.max_flow_steps` limita a soma de passos declarados entre os planos e
+`browser.max_text_entry_chars` limita cada valor digitado. O resultado contém
+`status`, o plano escolhido, as ações executadas, a última captura acessível e
+se o critério esperado apareceu. Quando existem asserções explícitas, `status`
+também pode ser `passed` com todas elas satisfeitas; `assertions_passed` registra
+esse resultado e `expected_outcome_visible` continua descrevendo somente o
+texto global. `incomplete` significa que nenhum critério foi comprovado;
+confiança do Jev não substitui essa verificação.
+`jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
+seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro
+de uma pasta absoluta escolhida pelo operador.
+`jev_browser_mcp.browser.max_upload_files`, `max_upload_path_chars`,
+`max_upload_file_bytes` e `max_upload_total_bytes` limitam quantidade e tamanho.
+Não configure a raiz como o disco inteiro ou a pasta home: use uma pasta de
+fixtures dedicada.
+Os limites de download ficam no mesmo bloco: `max_download_files`,
+`max_download_file_bytes`, `max_download_total_bytes` e
+`max_download_timeout_seconds`. `jev_browser_mcp.jev.max_accessibility_violations`
+limita quantas descrições de violações axe entram no resultado; a contagem total
+continua informada mesmo quando a lista é truncada.
+O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
+`block_trackers`, `capture_console_errors`, `capture_network_errors`,
+`screenshot_on_failure` e `trace_on_failure`. Sem override, os padrões são lidos
+de `jev_browser_mcp` em `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
+captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
+de recursos ficam desligados. `snapshot_scope` aceita `body`, `main` ou `dialog`.
+`block_trackers: true` bloqueia os domínios e tipos de recurso listados na
+configuração (analytics, Hotjar, fontes externas e mídia). Isso pode alterar o
+layout ou o comportamento do site, então a opção é desligada por padrão.
+Com `capture_console_errors` e `capture_network_errors`, o retorno traz
+`console_errors` e `network_failures`, limitados em quantidade e tamanho.
+Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
+fragmentos, valores de formulário e nomes de arquivo são removidos ou
+sanitizados. Em falhas, `screenshot_on_failure` salva screenshot local e retorna
+`screenshot_path`. `trace_on_failure: true` também grava um `.zip` compatível
+com o Trace Viewer do Playwright e retorna `trace_path`. O diretório padrão é
+`~/.cache/orquestrador/jev-browser-artifacts`; `JEV_BROWSER_ARTIFACT_DIR` pode
+substituí-lo por uma pasta absoluta fora do pacote. Screenshots e traces podem
+conter dados visíveis da aplicação: mantenha o diretório local protegido e
+compartilhe os arquivos somente se o teste permitir.
+`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
+`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;
+o diretório persistente armazena dados de login e é resolvido sob a pasta home
+do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
+`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
+Defina o valor secreto na variável indicada por `jev.credential_env`, usando o
+secret manager ou ambiente do processo que inicia o harness. Não grave a chave
+em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
+Decisions. O cliente não
+segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
+fica indisponível quando a política de MCP está em modo offline.
+Na primeira execução, aqueça uma vez o cache local do pacote declarado em
+`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
+depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
+Quando a versão configurada mudar, aqueça o novo pacote uma vez.
+## Desempenho e evidência
+O pacote Node usa a decisão remota do Jev para escolher entre múltiplos planos.
+Com exatamente um plano e `fast_path` ligado (padrão), executa esse plano sem
+chamar a API Decisions; `jev_decisions` fica em zero. Inclua o fluxo completo em
+um plano candidato para evitar chamadas separadas ao harness; seleção,
+navegação, ações e asserções ficam em uma chamada MCP. O servidor Python
+`mcp_servers/jev_browser_server.py` mantém seu fluxo próprio e usa uma decisão
+remota do Jev por chamada. A sessão Playwright fecha antes de o MCP Python
+retornar. O perfil do modo `computer` preserva o login para chamadas seguintes;
+nesse servidor o processo e a janela não são reutilizados. O pacote Node mantém
+o browser aquecido até o harness encerrar o processo. O snapshot enviado ao Jev
+e devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
+início e o fim da captura com um marcador de truncamento. `snapshot_scope` pode
+limitar a captura a `main` ou `dialog`; iframes nomeados contidos nesse escopo
+também podem ser incluídos.
+A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
+que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
+sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
+`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_ms`
+para localizar o custo. O teto observado em um fluxo sintético local anterior
+foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
+O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
+são enviados ao endpoint Decisions quando há mais de uma opção. Com fast-path,
+um plano não gera chamada remota. Os passos, valores digitados, valores
+esperados pelas asserções, caminhos e conteúdo dos arquivos não são enviados.
+Não inclua segredos em `flow`, `expected_outcome` ou nas descrições. A resposta
+retorna o plano escolhido quando houver decisão, custo/confiança do provedor
+quando disponíveis e o snapshot final sanitizado. O fluxo passa quando o texto
+esperado aparece no snapshot ou quando todas as asserções declaradas passam.
+`network_idle` é uma espera limitada e opcional; páginas com polling ou conexões
+contínuas podem atingir o timeout. Prefira `wait_for_text` e asserções de
+elemento quando houver um sinal de interface específico.
+Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
+[tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)
+para os tipos de resposta e autenticação.