pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.11

package/README.pt-BR.md

@@ -53,6 +53,10 @@ Com o OpenCode em execução, descreva o resultado que você quer:
 ```
 
 O Pantheon ajuda a transformar esse pedido em um plano e em etapas revisadas.
+Quando você pede um plano ou inicia `/pantheon-deepwork`, Athena devolve o plano
+completo para Zeus, que o apresenta na conversa principal antes de pedir
+aprovação. O pedido de aprovação não ficará separado de um plano escondido na
+conversa de um subagente.
 
 ## Para quem é?
 
@@ -122,16 +126,137 @@ registrados juntos.
 |---|---|---|
 | Chave de config do OpenCode | `plugin` singular | `plugins` plural |
 | Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | `pantheon-opencode/plugin-v2` (`src/plugin-v2.ts`) |
-| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 6 ferramentas de orquestração, 4 assinaturas de eventos, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), além de transforms de configuração |
+| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 3 ferramentas de orquestração mais `vision_describe` quando o catálogo de modelos está disponível, 5 assinaturas de eventos, session hooks (`prompt`, `context`), um hook `execute.before` que impõe sessões somente-leitura, além de transforms de configuração |
 | APIs V1 | Registradas | Definições próprias de ferramentas via `ctx.tool.transform()` — não pelo caminho do plugin V1 |
 
-O plugin V2 fornece 6 ferramentas de orquestração (`hashline_edit`,
-`pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
+O plugin V2 fornece 3 ferramentas de orquestração (`hashline_edit`,
 `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
 `session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
-`context`) e tool hooks (`execute.before`, `execute.after`). Os recursos V2 sem
-suporte são `legacy-hooks` (a superfície de hooks específica do V1),
-`catalog-transform`, `integration-transform` e `skill-transform`.
+`context`) e um hook de ferramenta `execute.before` que impõe sessões
+somente-leitura. As 3 ferramentas de goal **não** são
+registradas no V2: o goal loop precisa de um `GoalStore`, de um
+`GoalLoopClient` e de um `BackgroundJobBoard`, nenhum dos quais o
+`PluginContext` do V2 expõe, então a lacuna é reportada como o marcador de
+recurso sem suporte `goal-tools`. Use o contrato V1 se precisar do goal loop.
+
+O V2 também registra `vision_describe` quando `ctx.model.list()` está
+disponível. A ferramenta verifica a entrada de imagem no catálogo atual,
+prioriza o modelo pago `opencode-go/mimo-v2.6-flash` (modelos free-tier são
+excluídos da seleção automática — o gateway direto os rejeita com HTTP 403, só
+funcionam de dentro do OpenCode; um pin explícito em
+`PANTHEON_VISION_MODEL`/config/preset continua sendo honrado, então seu 403 vira
+um erro acionável em vez de uma troca silenciosa) e envia a imagem
+diretamente ao endpoint autenticado do OpenCode Zen. A requisição carrega o
+session id vivo no header Zen-only `x-opencode-session` exigido pelo gateway
+(nunca enviado a um provider não-Zen, e nunca logado). As credenciais vêm de
+`opencode auth login` ou `PANTHEON_OPENCODE_API_KEY`; sem modelo compatível ou
+credenciais, a ferramenta retorna um erro explícito em vez de inventar uma
+descrição. Esse caminho funciona sem a ponte V1 opcional.
+O hook de prompt V2 também preserva as referências dos anexos e orienta Zeus a
+inspecionar imagens relevantes e repassar a referência e observações concisas a
+Aphrodite. Bytes inline não são copiados para o texto persistido do prompt, e a
+imagem não autoriza apagar nem reverter alterações fora do escopo.
+
+O caminho nativo do turno de chat escolhe o modelo de visão numa precedência
+fixa: a variável `PANTHEON_VISION_MODEL`, depois `visionModel` em
+`opencode-vision.json`, depois `vision.model` do preset ativo, depois descoberta
+automática no catálogo de providers do host (`GET /config/providers`) e, por
+fim, o padrão embutido. A descoberta é conservadora e somente paga: mantém
+apenas entradas com imagem (`capabilities.input.image`) cujo provider é Zen
+confiável ou cujo pacote `npm` é OpenAI-compatível (`@ai-sdk/openai-compatible` /
+`@ai-sdk/openai`), EXCLUI entradas free-tier (`-free` ou `cost.input <= 0` — o
+gateway direto as rejeita com HTTP 403), escolhe a entrada mais barata restante
+e faz cache do catálogo por 60
+segundos por processo; um modelo incompatível simplesmente cai no fallback da
+tool MCP de visão. A base URL vem do `api.url` da entrada do catálogo, e os
+endpoints Zen legados permanecem como fallback quando não há catálogo. As
+credenciais seguem o endpoint: para um endpoint Zen, as variáveis compartilhadas
+`PANTHEON_OPENCODE_API_KEY` / `OPENCODE_API_KEY` são tentadas primeiro e depois o
+auth store do OpenCode (o provider resolvido primeiro, depois as entradas legadas
+`opencode-go` / `opencode`); para um endpoint não-Zen, apenas a entrada do próprio
+provider no auth store é usada — as variáveis compartilhadas e as entradas Zen
+legadas nunca são anexadas a uma base URL não-Zen. Um modelo de visão
+configurado explicitamente e qualificado sempre vence a descoberta — um pin que
+não qualifica (não-Zen, text-only ou fora do catálogo) é descartado e a seleção
+automática assume. O `pantheon-opencode init` oferece um
+passo opcional de vision em sessões TTY interativas — a descoberta automática é
+o default e não grava nada; pinar faz merge de `visionModel` no
+`opencode-vision.json` global; fluxos não-interativos nunca perguntam nem gravam.
+
+A pergunta do usuário é injetada no prompt de visão nos caminhos nativo e V2,
+aparada e limitada a 2000 caracteres; a mesma imagem com uma pergunta diferente
+gera nova descrição, enquanto uma repetição idêntica dentro do TTL de cache
+reutiliza o texto guardado. O describe nativo é robusto por construção: o
+timeout escala de uma base de 20 segundos a cerca de 10 segundos por MB de
+payload até um teto de 300 segundos, e uma checagem de orientação EXIF sem
+dependências (JPEG) adiciona uma dica textual para o vision model descrever a
+imagem rotacionada ou espelhada na posição correta — só detecção, os pixels
+nunca são reescritos, e a orientação entra na chave do cache.
+
+A visão degrada numa cadeia explícita — nativa → tool MCP de visão → local.
+Quando a nativa está indisponível e a tool MCP de visão não está presente, a
+imagem é substituída por extração local determinística: dimensões, formato e
+tamanho do header PNG/JPEG/GIF/WebP, cores dominantes para PNG RGB/RGBA e OCR
+somente quando o binário `tesseract` está no `PATH`. Nunca fabrica conteúdo — a
+degradação é declarada explicitamente. As tools `vision_describe` e `vision_ocr`
+do MCP degradam para esse modo local quando não há credencial de gateway, sem
+dependências novas. (A `vision_analyze` exige credencial de gateway e retorna um
+erro explícito.) Trade-offs deliberados, registrados para não serem
+revertidos por acidente: o Pantheon descreve cada imagem uma vez e mantém o
+texto no histórico (council 2026-08-03) em vez de preservar a imagem original
+para re-observação a cada turno; o describe-always prioriza latência zero em vez
+de uma tool `describe_image` sob demanda. A sanitização multi-turno
+(`experimental.chat.messages.transform`) é invariante obrigatória — garante que
+`image_url` / `FilePart` nunca cheguem a um provider textual e não é
+configurável. O Bifrost permanece opt-in, nunca padrão, conforme o incidente de
+credencial em [SECURITY.md](SECURITY.md).
+
+O hook `execute.before` do V2 é o ponto de imposição de sessões somente-leitura
+dessa superfície: o host inclui o agente ativo no evento, um agente somente-leitura
+(`apollo`, `gaia`) registra sua sessão, e o `createEnforcementGuard`
+compartilhado lança para negar `edit`, `write`, `bash`, `task`,
+`hashline_edit` e `pantheon_model`. Ele **não** depende do hook
+`tool.execute.before` do V1, que vive em `src/plugin.ts` e não é carregado
+quando apenas `plugin-v2` está configurado. Quando o host registra o hook
+`permission.evaluate`, ele aplica no V2 a matriz caller/target a todos os itens
+do array `resources` do host para destinos gerenciados pelo Pantheon. Sem o
+registro do hook, a matriz não fica disponível e o host mantém o controle.
+Recursos exclusivamente nativos são repassados sem alteração à política de
+permissões do OpenCode; pedidos mistos (nativos/Pantheon) ou com vários destinos
+são negados.
+Para destinos Pantheon, a política exige uma chamada nativa `subagent` cujo
+session ID, message ID e tool-call ID no `source` coincidam com o evento do host
+`tool.execute.before`; também confirma que a sessão não tem `parentID`. O campo
+`permission.evaluate.agent`, sozinho, não identifica o chamador. Origins
+ausentes, expirados, repetidos ou incompatíveis são negados. A canary no
+OpenCode v2.0.29 admite Zeus→Apollo na raiz e nega dispatches inválidos ou
+originados em uma filha; veja o [relatório de F4A](bench/results/f4a-v229-admission-identity-2026-10-14.md).
+Uma negação explícita do host é final, e dados de recursos ausentes ou
+desconhecidos são negados por padrão. O `execute.after` do
+V2 executa a cadeia de resultados concluídos `task-result-guard` →
+`context-sandbox` → `read-enhancer`; eventos de erro permanecem inalterados.
+
+#### Leitura bounded do workspace (F3b)
+
+No OpenCode v2.0.29, o plugin V2 pode registrar `pantheon_bounded_read` quando
+o host oferece as APIs nativas de permissão e sessão. Só uma sessão root do
+Zeus pode usá-la. Cada chamada pede ao host permissão `read` para um arquivo
+relativo exato do workspace, com escopo de persistência vazio; o conteúdo só é
+lido após aprovação e passa pelo scanner de segredos fail-closed existente.
+Os limites são duas chamadas e dois arquivos distintos, 400 linhas e 32 KiB
+por mensagem do assistant. Travessia de diretórios, symlinks, diretórios,
+escopos sensíveis, formatos binários/mídia reconhecidos e falhas do scanner são
+negados. O escopo suportado é um workspace local sem escritores concorrentes;
+isso não promete isolamento contra filesystem adversarial nem classificação
+binária do arquivo inteiro. Evidência host-backed:
+[`bench/results/f3b-v229-bounded-read-2026-10-15.md`](bench/results/f3b-v229-bounded-read-2026-10-15.md).
+
+Toda ferramenta V2 declara um schema `output`. O OpenCode 2.0.x exige que a
+declaração e o resultado resolvido concordem nos dois sentidos, então uma
+ferramenta sem declaração — ou que retorne `output` sem declará-lo — falha em
+toda chamada. Os recursos V2 sem suporte são `legacy-hooks` (a superfície de
+hooks específica do V1), `catalog-transform`, `integration-transform`,
+`skill-transform` e `goal-tools`.
 
 O pacote expõe os dois contratos como exports importáveis:
 `pantheon-opencode/plugin` (V1), `pantheon-opencode/plugin-v2` (V2) e
@@ -151,26 +276,68 @@ npx pantheon-opencode init --opencode-version v2
 npx pantheon-opencode init --opencode-version auto
 ```
 
-`--version v1|v2|auto` é aceito como a grafia antiga do seletor quando usado
-depois de `init`. `auto` é conservador, não uma autodetecção geral de
-plataforma: `OPENCODE_VERSION=v1|v2` vence; caso contrário, um `OPENCODE_BIN`
-terminando em `opencode2` seleciona V2; qualquer outro caso seleciona V1. O
-instalador remove referências Pantheon das duas formas de config antes de
+`auto` é o padrão. `--version v1|v2|auto` é aceito como a grafia antiga do seletor
+quando usado depois de `init`. `auto` resolve a geração a partir do host nesta
+ordem: um `OPENCODE_VERSION=v1|v2` explícito vence; caso contrário, um
+`OPENCODE_BIN` terminando em `opencode2` seleciona V2; caso contrário o binário
+do host é consultado com `--version` e uma major >= 2 seleciona V2. Qualquer
+outro caso — uma sonda ilegível, um banner não interpretável, ou um banner
+cujos tokens de versão se contradizem sem um nome de ferramenta que desfaça o
+empate — avisa uma vez e volta para V1, porque uma entrada de diretório em
+`plugins` plural em um host 1.x desconhecido perde o plugin inteiro.
+
+A sonda prefere o token que vem logo após o nome da ferramenta, então um token
+de runtime antes dele (`node v22.1.0 (opencode 1.18.33)`) ou uma data de build
+no final (`opencode v1.18.33 built 2026.10.04`) não conseguem virar a geração.
+O instalador remove referências Pantheon das duas formas de config antes de
 gravar apenas o registro Pantheon selecionado. Entradas de terceiros não são
 convertidas nem reivindicadas por essa regra.
 
-O relatório `pantheon_cost`, disponível nos plugins V1 e V2, pode selecionar o banco com
-`PANTHEON_OPENCODE_VERSION=v1` ou `v2` (`opencode.db` ou `opencode-v2.db`).
-`PANTHEON_COST_DB=/caminho/absoluto/para/opencode.db` tem precedência sobre o
-seletor de versão, e um `dbPath` explícito fornecido pelo chamador da
-ferramenta tem precedência sobre ambos. O resolver nunca consulta o banco da
-outra versão e reporta um erro acionável quando o banco selecionado está
-ausente ou com schema incompatível.
+O relatório `pantheon_cost`, disponível nos plugins V1 e V2, resolve o banco por
+CAMINHO, nesta ordem: um `dbPath` explícito fornecido pelo chamador da
+ferramenta, depois `PANTHEON_COST_DB=/caminho/absoluto/para/opencode.db`,
+depois `OPENCODE_DB`, e por fim o padrão do XDG `opencode.db`. Não há nome de
+arquivo por versão nessa cadeia: `opencode-v2.db` não é um banco de um host 2.x
+— é o nome que um sandbox dá ao próprio banco de estado via `OPENCODE_DB`.
+
+A distinção v1/v2 é o SCHEMA DETECTADO, não o nome do arquivo. O relatório
+procura as tabelas `message` e `session_message` e lê aquele que o banco aberto
+realmente tiver, porque um banco migrado carrega as duas famílias ao mesmo
+tempo. `PANTHEON_OPENCODE_VERSION=v1|v2` não seleciona arquivo nenhum: apenas
+estreita um conjunto já detectado para uma família de tabelas, e falha rápido
+quando o valor não é `v1` nem `v2` ou quando a família pedida não existe lá.
+Sem a variável, todas as famílias detectadas são lidas. Um banco sem nenhuma
+das duas tabelas volta como erro acionável (`CORRUPT_DATA`), e um ledger que
+existe mas não produz tokens legíveis como `UNSUPPORTED` — nunca como um
+relatório vazio com sucesso.
 
 O instalador continua gravando as configurações de compatibilidade exigidas
 pelo host OpenCode selecionado, como `experimental.subagent_depth`; isso não
 converte um plugin V1 em V2 nem dá hooks V1 ao V2.
 
+O Pantheon não define mais um teto de passos para os agentes. No OpenCode 2 o
+campo `steps` é opcional e não tem default: ausente significa que o host não
+aplica nenhum limite nativo. Uma config escrita antes dessa mudança ainda
+carrega o valor antigo, e o caminho de instalação v2 o remove de todos os
+agentes que o Pantheon gerencia — um agente definido por você nunca é tocado,
+e o bloco V1 singular `agent`, em retirada, é deixado intacto. Rode o
+instalador uma vez para limpar um valor antigo de uma config existente:
+
+```bash
+npx pantheon-opencode init --opencode-version=v2
+```
+
+O controle de contexto não é uma configuração do Pantheon. Qualquer orçamento
+que um agente terá vem das settings de compactação do próprio host OpenCode,
+e o Pantheon não as define.
+
+Quando um bloco V1 `agent` e um bloco V2 `agents` coexistem — o que acontece
+em qualquer `opencode.json` já instalado — a conversão V1→V2 mescla os dois em
+vez de deixar um substituir o outro. O bloco V2 é a base, os campos
+gerenciados que vêm do V1 sobrescrevem, e os seus próprios campos são
+preservados, com a mesma precedência que o instalador já aplica em outros
+pontos. A ordem das chaves não muda o resultado.
+
 ## Atualizando entre releases (beta.5+)
 
 Um comando mantém uma instalação existente em dia:
@@ -193,7 +360,15 @@ pacote. Duas garantias de freshness sustentam isso:
 - **Sync de artifacts no postinstall** — depois de qualquer `npm install`, os
   artefatos de cópia (agents, skills, AGENTS.md, commands, scripts MCP,
   payload code-mode) são atualizados automaticamente no config dir existente;
-  você nunca precisa re-rodar `init` só para atualizar arquivos.
+  você nunca precisa re-rodar `init` só para atualizar arquivos. O config dir
+  global recebe o **artefato global** agnóstico de repositório
+  (`AGENTS.global.md`: tabela de agentes + regras compartilhadas), enquanto o
+  `AGENTS.md` de cada projeto carrega apenas o setup específico do projeto —
+  os dois são esculpidos para serem disjuntos (trabalho de latência beta-10),
+  então nenhuma regra é paga duas vezes por sessão. A instalação é
+  conservadora: conteúdo fora da região gerenciada (regras próprias do
+  usuário) é preservado verbatim, um `AGENTS.md` legado totalmente gerado é
+  atualizado in place, e qualquer merge é reportado com um aviso.
 - **Detecção de drift** — o instalador grava a versão instalada em
   `.pantheon/install-state.json` e o `doctor` avisa quando o pacote é mais
   novo que o último sync, apontando para o `update`.
@@ -213,6 +388,10 @@ de PR, push, merge e tag nunca publicam nada, e todos os gates de validação s
 fail-closed: somente um PASS explícito autoriza release evidence. Consulte
 [docs/RELEASING.md](docs/RELEASING.md) para detalhes de validação e recuperação.
 
+Se a seção de uma versão candidata já existir, atualize as notas com
+`node scripts/versioning.mjs changelog <versão>`; o comando mescla `[Unreleased]`
+na versão indicada sem avançar o número do pacote.
+
 A validação mantém cada manifest junto do seu lockfile: o root
 `package.json` + `package-lock.json` e o TUI
 `src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Ambos usam
@@ -267,6 +446,92 @@ de testar silenciosamente a instalação do host.
 Isso valida somente o sandbox isolado e preparado. Um PASS não prova suporte
 para todo host real nem para configurações de host que não foram exercitadas.
 
+## Benchmark de latência (bench/)
+
+O `bench/` mede a latência de sessão de ponta a ponta do CLI `opencode`
+instalado com o plugin V2 do repositório — o baseline contra o qual toda
+mudança de performance de uma release deve ser comparada. Executa dois
+cenários N vezes cada, intercalados (não-interativo, um diretório de sandbox
+novo por run), coleta métricas por run do `opencode.db` em modo READ-ONLY
+(tokens root + sessões filhas sem dupla contagem, tool calls por nome, número
+de sessões filhas) e tempos de hook das linhas `[bench]` que o plugin anexa ao
+`hooks.log`:
+
+```bash
+node bench/bin/bench.mjs            # 5 runs por cenário (A e B), ~1h
+BENCH_MODEL=opencode-go/glm-5.3-flash node bench/bin/bench.mjs   # fixar modelo
+node bench/bin/bench.mjs --runs 1   # smoke: um run por cenário
+```
+
+Os resultados vão para `bench/results/<label>-<git-sha>.json` (mediana +
+p80 + falhas por cenário); o label padrão é `baseline` e o harness recusa
+sobrescrever um resultado existente, então a identidade do run fica no nome do
+arquivo. O cenário A faz pesquisa web real, então a variância de rede é
+registrada por run.
+
+### Perfis de medição (explícitos, nunca inferidos)
+
+As instruções são injetadas por duas superfícies: o diretório de config global
+e o diretório do projeto. O harness declara qual delas exercita, porque um
+resultado só significa algo no perfil onde a mudança atua:
+
+| `--profile` | `AGENTS.md` global | `AGENTS.md` de projeto | Uso |
+|---|---|---|---|
+| `host` (padrão) | diretório de config do host (ou `--global-agents`) | nenhum — run dirs ficam vazios | a injeção real do host, sem alteração |
+| `double-injection` | diretório de config do host (ou `--global-agents`) | `--project-agents`, escrito em cada run dir | o perfil no repo onde global+projeto se sobrepõem |
+
+O padrão mede os cenários A e B. Use `--scenarios B` para isolar o claim
+one-shot de F1; o cenário selecionado ainda roda N vezes (`--runs 5` por
+padrão).
+
+```bash
+# braço candidato: artefato global carveado + artefato de projeto carveado
+node bench/bin/bench.mjs --runs 5 --scenarios B --profile double-injection \
+  --global-agents AGENTS.global.md --project-agents AGENTS.md --label f1-candidate
+```
+
+Cada braço registra, por run e lido do banco, a identidade (caminho, bytes,
+sha256) de cada arquivo de instrução que a sessão de fato carregou
+(`instruction_state` + `instruction_blob`) — a prova de fidelidade de que o
+que foi medido é o que foi gerado. Um claim só pode se apoiar num run cuja
+provenance mostre que os artefatos global **e** de projeto pretendidos foram
+carregados.
+
+### Sinal vs ruído
+
+Wall time é pista, não critério: o spread same-day chega a ~8× no cenário A e
+~13× no B. Um efeito só é **confirmado** quando excede o spread same-day (ou
+exige N maior); caso contrário é registrado como **inconclusivo**. Prefira
+medianas de tokens, bem mais estáveis. O wall do cenário A não é métrica de
+claim — ele faz pesquisa web real, então a variância de rede domina.
+
+### Proxy do 1º request e evidência de F1
+
+O payload de instruções injetado só incide no primeiro request, então o
+`tokens.input` total da árvore (somado em todo turno) é dominado pela variância
+de duração da sessão. Cada run também registra `firstRequest` — o
+`tokens.input` + `tokens.cache.read` da primeira linha assistant — o proxy que
+isola o payload.
+
+Uma rodada intercalada no OpenCode v2.0.29 (C1/K1…C5/K5, N=5/braço) mediu o
+contexto do 1º request em 17555 tokens no controle e 15489 na candidata
+(**−2066, −11,8%**; spread intra-braço de 14 tokens em cada braço). D4 confirmou
+22350 B carregados no controle e 13400 B na candidata (−8950 B, −40,0%); o
+oráculo pré-registrado passou em 5/5 nos dois braços. O efeito no primeiro
+request está confirmado contra o spread intra-braço; a aceitação final de F1
+aguarda revisão do Themis. O input total da árvore caiu da mediana de 47594 para
+38253 tokens, mas os ranges se sobrepõem e a hipótese de ≤30k não foi atingida.
+As medianas de wall foram 30,078 s e 24,130 s, com spread alto; input total e
+wall permanecem **inconclusivos**. Não há claim de ganho de wall ou custo
+monetário. Detalhes e artefatos por run:
+`bench/results/f1-di-v229-interleaved-2026-10-14.md`. O par sequencial anterior
+permanece somente como evidência de apoio em
+`bench/results/f1-di-v229-clean-2026-10-14.md`. As rodadas exploratórias
+anteriores foram preservadas separadamente em
+`bench/results/f1-double-injection.md` e
+`bench/results/f1-di-v229-preliminary-2026-10-14.md`.
+
+
 ## Cobertura TypeScript do Plugin V2
 
 `npm run coverage:plugin-v2` executa a suíte `tests/pantheon/*.test.ts` com a
@@ -291,7 +556,7 @@ preparado.
 
 ### Divergência intencional do memory MCP
 
-`scripts/memory_mcp_server.py` e `src/mcp/memory_mcp_server.py` são
+`scripts/memory_mcp.py` e `src/mcp/memory_mcp.py` são
 intencionalmente diferentes. A cópia independente em `scripts/` mantém o
 contrato leve de `memory_*`; a cópia instalada em `src/mcp/` também expõe o
 schema opcional de codemap e `code_index`, `code_query` e `code_neighbors`. As

package/bin/pantheon-init.mjs

@@ -8,8 +8,10 @@
  * installOpenCode() from scripts/install/opencode.mjs.
  *
  * Dual-version install (Phase 3): the generated config is V1-shaped and valid
- * under BOTH OpenCode V1 (`opencode` 1.18.x) and V2 (`opencode2`
- * v0.0.0-next-17444). V2 reads the same config locations and normalizes V1
+ * under BOTH OpenCode V1 (`opencode` 1.18.x) and V2 (`opencode2`, OpenCode 2.x —
+ * `opencode2 --version` prints "opencode v2.0.22"; an early 2.x prerelease
+ * printed "0.0.0-next-17444", which is history and not a host observation).
+ * V2 reads the same config locations and normalizes V1
  * fields in memory — no native V2 conversion. `--version v2` labels the
  * install for the operator; state isolation is a runtime concern
  * (OPENCODE_DB ~/.local/share/opencode/opencode-v2.db, service port 49375).
@@ -19,6 +21,8 @@ import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { resolveInstallExitCode } from '../scripts/install/exit-codes.mjs'
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ROOT = path.resolve(__dirname, '..')
 
@@ -54,6 +58,9 @@ function printUsage() {
   console.log('  npx pantheon-opencode init --components agents,skills,instructions')
   console.log('  npx pantheon-opencode init --opencode-version v1|v2|auto')
   console.log('  npx pantheon-opencode init --preset <name> # Install and activate model preset')
+  console.log(
+    '  npx pantheon-opencode init --merge-dev-config <path> # Merge a dev config (off by default)',
+  )
   console.log('  npx pantheon-opencode set-tier <name>      # Set active model preset (global)')
   console.log(
     '  npx pantheon-opencode update [--stable]    # Update package + re-run init (default: beta channel)',
@@ -64,10 +71,24 @@ function printUsage() {
   console.log('  npx pantheon-opencode prune               # List legacy artifacts (dry-run)')
   console.log('  npx pantheon-opencode prune --apply       # Remove stale backups')
   console.log('  npx pantheon-opencode doctor [--profile]  # Run health check')
+  console.log(
+    '  npx pantheon-opencode restore [--project] [--yes]  # Restore an exact installer backup',
+  )
   console.log('  npx pantheon-opencode uninstall --project   # Remove project artifacts safely')
   console.log('  npx pantheon-opencode uninstall --global    # Remove global artifacts safely')
   console.log('  npx pantheon-opencode --version, -v       # Print version and exit')
   console.log('  npx pantheon-opencode --help              # Show this help')
+  console.log('')
+  console.log('Apply authorization:')
+  console.log('  A non-interactive run without --yes prints the plan and applies NOTHING.')
+  console.log('  Re-run with --yes to apply; an interactive TTY run prompts (default: no).')
+  console.log('')
+  console.log('Exit codes:')
+  console.log('  0   success, or plan/no-apply (declined)')
+  console.log('  1   failure')
+  console.log('  2   apply was requested without authorization (non-interactive, no --yes)')
+  console.log('  3   drift detected (a planned file changed after the plan)')
+  console.log('  130 canceled')
 }
 
 async function main() {
@@ -104,6 +125,17 @@ async function main() {
     process.exit(result.status ?? 1)
   }
 
+  // restore delegates to scripts/restore.mjs (same spawnSync pattern as prune).
+  if (command === 'restore') {
+    const { spawnSync } = await import('node:child_process')
+    const restoreScript = path.join(ROOT, 'scripts', 'restore.mjs')
+    const result = spawnSync(process.execPath, [restoreScript, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    })
+    process.exit(result.status ?? 1)
+  }
+
   // doctor delegates to scripts/doctor.mjs (same spawnSync pattern as prune).
   // Forwarding the FULL args (profile, target, --fix, ...) keeps the packaged
   // CLI a thin wrapper; the doctor banner reports the resolved profile.
@@ -287,6 +319,7 @@ async function main() {
       '--version',
       '--opencode-version',
       '--components',
+      '--merge-dev-config',
     ])
     for (let i = 1; i < args.length; i++) {
       const arg = args[i]
@@ -368,6 +401,22 @@ async function main() {
       }
     }
 
+    // --merge-dev-config <path> opts IN to merging a contributor's personal
+    // OpenCode config into the generated one. Only third-party plugin/provider/
+    // compaction entries are merged; Pantheon-owned entries are always stripped.
+    // Absent this flag no repository-root config is read (product defaults come
+    // from the installer code, never from a dev checkout).
+    const mergeDevConfigIndex = args.indexOf('--merge-dev-config')
+    const inlineMergeDevConfig = args.find((arg) => arg.startsWith('--merge-dev-config='))
+    const mergeDevConfigOpt =
+      mergeDevConfigIndex >= 0
+        ? (args[mergeDevConfigIndex + 1] ?? null)
+        : (inlineMergeDevConfig?.split('=', 2)[1] ?? null)
+    if (mergeDevConfigIndex >= 0 && mergeDevConfigOpt === null) {
+      console.error('❌ --merge-dev-config requires a file path')
+      process.exit(1)
+    }
+
     const components = requestedComponents ?? [
       'agents',
       'skills',
@@ -392,17 +441,19 @@ async function main() {
       console.log('')
     }
 
+    let result
     try {
       const { installOpenCode } = await import('../scripts/install/opencode.mjs')
       const target = isProject ? process.cwd() : undefined
-      await installOpenCode(target, isDryRun, forceReinstall, components, {
+      result = await installOpenCode(target, isDryRun, forceReinstall, components, {
         interactive: forceInteractive,
         headless: forceHeadless,
         yes: autoYes,
         model: modelOpt,
         smallModel: smallModelOpt,
         preset: presetOpt,
-        version: versionOpt ?? 'v1',
+        version: versionOpt ?? 'auto',
+        mergeDevConfig: mergeDevConfigOpt,
       })
     } catch (err) {
       if (err?.message === 'Canceled') {
@@ -413,6 +464,21 @@ async function main() {
       process.exit(1)
     }
 
+    // Beta 11 Setup phases 3-4: a run that did NOT apply (declined /
+    // unauthorized / drift) must never print a success banner. Exit codes:
+    //   0 ok / no-apply · 2 apply-requested-without-authorization · 3 drift
+    //   130 canceled · 1 failure (thrown above).
+    if (result?.applied === false) {
+      if (!isDryRun) {
+        if (result.reason === 'canceled') console.error(S.canceled)
+        process.exit(resolveInstallExitCode(result, isDryRun))
+      }
+      // Dry-run preview: report honestly instead of the "installed!" banner.
+      console.log('')
+      console.log(`  ${S.dryRunNothingWritten}`)
+      return
+    }
+
     if (runDoctor && !isDryRun) {
       console.log('')
       console.log(`  ${S.runningHealthCheck}`)

package/commands/pantheon-audit.md

@@ -15,7 +15,13 @@ agent: "zeus"
 ## Layers
 
 ### Layer 1 — Heuristic Scan
-`python3 scripts/themis_heuristic_scan.py [--path=<dir>]`
+Resolve the installed helper first (do not assume the current project contains
+Pantheon source). Check, in order: `$OPENCODE_CONFIG_DIR/.opencode/scripts/`,
+`$OPENCODE_CONFIG_DIR/scripts/`, `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/scripts/`,
+`$HOME/.opencode/scripts/`, `.opencode/scripts/`, then
+`$(npm root -g)/pantheon-opencode/scripts/`. Resolve the first existing file to
+an absolute path and run `python3 "$helper" --path="$PWD"`; if none exists,
+report the helper as missing and stop Layer 1 rather than claiming it passed.
 Zero tokens, <2s. Checks: ruff, biome, anti-pattern slop, anti-overengineering (YAGNI), hash-anchored edits. Returns score 0-100 + APPROVED/BLOCKING.
 
 ### Layer 2 — Themis Deep Review

package/commands/pantheon-consolidate.md

@@ -1,6 +1,6 @@
 ---
 description: "Merge and consolidate memory entries"
-agent: zeus
+agent: mnemosyne
 ---
 
 Merge related memory entries and consolidate duplicates:

package/commands/pantheon-deepwork.md

@@ -15,8 +15,15 @@ Structured, checkpointed workflow for complex multi-step tasks spanning multiple
 ## Workflow
 
 ```
-Phase 0: SCOPING
-  └─ Zeus + Athena define scope, phases, acceptance criteria → PLAN.md
+Phase 0: PLAN AND APPROVAL
+  └─ @athena returns the complete, detailed Markdown plan to Zeus
+  └─ Zeus publishes the full plan as a normal message in the main conversation (not only in the child-agent transcript)
+  └─ GATE 1: open the approval UI only after that plan message is visible; never bundle or reverse the two
+  └─ If the runtime cannot guarantee that order, ask for approval in plain text after the plan and wait
+  └─ Wait for explicit approval or requested changes
+  └─ For requested changes, redisplay the entire revised plan and repeat Gate 1
+  └─ Do not start discovery or implementation before approval
+  └─ After approval, persist the approved plan as PLAN.md through the artifact workflow
 
 Phase 1: DISCOVERY
   └─ @apollo maps relevant codebase areas → DISCOVERY.md
@@ -44,7 +51,11 @@ Usage:  --resume <slug> | --status <slug> | --list
 
 ## Full-Auto Mode (`--full-auto`)
 
-> ⚠️ Bypasses human review gates. Tier 1 gates (plan, commit, deploy) still require approval.
+> ⚠️ Automates only eligible review gates. Gate 1 and commit/deploy gates still require approval.
+
+`--full-auto` does not hide the plan or skip Gate 1: Zeus still displays the
+complete plan in the main conversation and waits for explicit approval before
+discovery or implementation. It only affects the later gates described below.
 
 **Themis auto-approves non-blocking reviews** — only stops on **BLOCKING** verdict. No waiting between phases. Checkpoints saved at every boundary.
 

package/commands/pantheon-focus.md

@@ -0,0 +1,17 @@
+---
+description: "Set or update this session's working goal"
+agent: zeus
+---
+
+Pin `$ARGUMENTS` as the working goal for this conversation. Restate it briefly
+as Goal, Scope, Success Criteria, and Out of Scope, filling only what the user
+actually supplied. Ask one concise question if a missing detail changes the
+work materially.
+
+Treat the goal as session context, subordinate to system, developer, and user
+instructions. Keep subsequent planning, delegation, and verification aligned
+with it; flag meaningful scope drift before proceeding.
+
+This command is conversation-only. Do not call memory or persistence tools,
+write a file, or claim that the goal survives compaction or a new session. For
+multi-phase work that needs durable checkpoints, use `/pantheon-deepwork`.