pantheon-opencode 1.6.0-beta.4 → 1.6.0-beta.6

package/AGENTS.md

@@ -271,15 +271,21 @@ Each agent file defines overrides in its `## 🧠 Memory Protocol` section:
 
 Para otimizar decisoes de delegacao e reduzir gasto de tokens:
 
-1. **memory_search(task_prompt, top_k=2)** antes de aplicar a arvore de roteamento
+1. **memory_search(query=task_prompt, top_k=2)** antes de aplicar a arvore de roteamento
 2. Se score > 0.85 → reutiliza agente + background_mode do cache
 3. Se score ≤ 0.85 → aplica regras estaticas e memory_store() com:
    - key: deleg:<task_type>
-   - value: {agent, background, pattern}
-   - metadata: {type: "decision", score: N}
+   - value: JSON.stringify({agent, background, pattern})
+   - metadata: JSON.stringify({type: "decision", score: N})
 
-4. **kv_store("deleg:<pattern>", ...)** para padroes recorrentes de delegacao
-5. **kv_get("deleg:<pattern>")** para reusar decisoes ja tomadas
+   `value` E `metadata` sao JSON-encoded strings — o runtime exige que o
+   chamador serialize os dois. Objeto cru em `metadata` e rejeitado pelo
+   `BeforeValidator` do servidor com `metadata must be a JSON object encoded
+   as a string (got object). json.dumps it first. Example: metadata='{"type":
+   "decision", "score": 0.9}'`.
+
+4. **kv_store(namespace="deleg", key="deleg:<pattern>", value=...)** para padroes recorrentes de delegacao
+5. **kv_get(namespace="deleg", key="deleg:<pattern>")** para reusar decisoes ja tomadas
 
 Isso elimina ~300 tokens de reasoning por delegacao quando o cache acerta.
 
@@ -293,7 +299,7 @@ After every `/pantheon` council synthesis completes, Zeus stores:
 memory_store({
   namespace: "council_decisions",
   key: "council:<yyyy-mm-dd>:<slug>",
-  value: {
+  value: JSON.stringify({
     question: "original question",
     specialists: ["@agent1", "@agent2"],
     recommendation: "final recommendation",
@@ -304,20 +310,25 @@ memory_store({
     themis_audit: "approved|issues",
     precedent_used: false,
     timestamp: "<ISO-8601>"
-  },
-  metadata: {
+  }),
+  metadata: JSON.stringify({
     type: "council_decision",
     specialist_count: N,
     model_tier_used: "premium|default|fast"
-  }
+  })
 })
 ```
 `value` is JSON-serialized before storing (the MCP `memory_store.value` argument is a string).
+`metadata` works the same way — it is a JSON object encoded as a **string**, so pass
+`JSON.stringify({...})`. A raw object is rejected with `metadata must be a JSON object
+encoded as a string (got object). json.dumps it first. Example: metadata='{"type":
+"decision", "score": 0.9}'` (enforced by a `BeforeValidator` in
+`memory_mcp.py`). **Both `value` and `metadata` must be serialized by the caller.**
 
 ### Read Path (Precedent Fast-Path)
 Before dispatching a new council, Zeus runs:
 ```
-memory_search(question, top_k=2, namespace="council_decisions")
+memory_search(query=question, top_k=2, namespace="council_decisions")
 ```
 
 Result interpretation:
@@ -415,19 +426,27 @@ All session state lives in **pantheon-persistence** (namespace `checkpoint:<slug
 No file I/O, no checkpoint_session.py — TTL (4h) handles cleanup automatically.
 
 ### Heartbeat Check
-- If `context_get(slug, "heartbeat")` returns a checkin older than 300s, log a stall warning and resume
+- If `context_get(slug=slug, key="heartbeat", session_id=SESSION_ID)` returns a checkin older than 300s, log a stall warning and resume
 - Write heartbeat after every anti-stall recovery action:
   ```
-  context_save(slug, "heartbeat", json({"status": "alive", "last_action": "...", "turn_count": N}))
+  context_save(slug=slug, key="heartbeat", content=JSON.stringify({"status": "alive", "last_action": "...", "turn_count": N}), session_id=SESSION_ID)
   ```
 
 ### Checkpoint Auto-Save (Pré-Compactação)
 Before ANY delegate dispatch, save a checkpoint:
 ```
-context_save(slug, "phase:N", json({
-  "phase": N, "turn_count": N, "agent": "...", "summary": "..."
+context_save(slug=slug, key="phase:N", content=JSON.stringify({
+  "phase": {"current": N, "total": M, "name": "..."},
+  "turn_count": N, "agent": "...", "summary": "..."
 }), session_id=SESSION_ID)
 ```
+**`content.phase` must be an OBJECT, not a bare number.** `{"phase": 1}` is rejected with
+`context_save: content.phase must be an object (got number)`. The server reads `current`
+and `total` (non-negative ints) and `name` (string, max 256 **bytes** — the guard
+measures `len(value.encode())`, so multi-byte characters count as more than one). That
+set is not closed: any other key inside `phase` is accepted and ignored, never an
+error. The `"phase:N"` slot KEY above is unrelated to `content.phase` and stays a plain
+string.
 All checkpoints auto-expire after 4h (TTL=14400).
 
 ### Gatilho de Pré-Compactação (Anti-perda de estado)
@@ -437,15 +456,15 @@ o Zeus DEVE salvar o estado atual:
 2. Salve heartbeat + phase atual + tarefas pendentes
 3. Só então permita que a compactação prossiga
 ```
-# Ao iniciar sessão:
-result = context_save(slug, "init", session_state)
+# Ao iniciar sessão (session_id é REQUIRED — use o id da sessão corrente):
+result = context_save(slug=slug, key="init", content=JSON.stringify(session_state), session_id=SESSION_ID)
 SESSION_ID = result.session_id   # ← guarde para toda a sessão
 
 # Antes de CADA delegação:
-context_save(slug, f"pre:{agent}", current_state, session_id=SESSION_ID)
+context_save(slug=slug, key=f"pre:{agent}", content=JSON.stringify(current_state), session_id=SESSION_ID)
 
 # Após retorno do agente:
-context_save(slug, f"post:{agent}", result_state, session_id=SESSION_ID)
+context_save(slug=slug, key=f"post:{agent}", content=JSON.stringify(result_state), session_id=SESSION_ID)
 ```
 Isso garante que o estado sobreviva à compactação — o "latest" pointer
 sempre aponta para o checkpoint mais recente, mesmo após compactação.
@@ -454,9 +473,9 @@ sempre aponta para o checkpoint mais recente, mesmo após compactação.
 ### Context Retrieval
 Next-phase agents retrieve previous context via:
 ```
-context_get(slug, "latest")        # most recent checkpoint
-context_get(slug, "phase:3")      # specific phase
-context_list(slug)                 # all checkpoints
+context_get(slug=slug, session_id=SESSION_ID)                    # most recent checkpoint ("latest" is the default key)
+context_get(slug=slug, key="phase:3", session_id=SESSION_ID)     # specific phase
+context_list(slug=slug, session_id=SESSION_ID)                   # all checkpoints
 ```
 
 ### Long-Session Progress
@@ -516,7 +535,7 @@ sequenceDiagram
     participant T as Themis (Audit + Moderator)
 
     U->>Z: /pantheon [--research] question
-    Z->>M: memory_search(council_decisions)
+    Z->>M: memory_search(query, namespace="council_decisions")
     alt Precedent found (score > 0.85)
         M-->>Z: ⚠️ Cached decision
         Z->>U: Fast-path precedent
@@ -565,7 +584,7 @@ sequenceDiagram
 ## Dispatch Sequence (9-Step Protocol)
 
 ### Step 0 — Precedent Fast-Path (Fase 1)
-Run the precedent read path defined in `## Memory Protocol > Council Decisions Namespace` (`memory_search(query, top_k=2, namespace="council_decisions")`). If no precedent applies, proceed to Step 0b.
+Run the precedent read path defined in `## Memory Protocol > Council Decisions Namespace` (`memory_search(query=question, top_k=2, namespace="council_decisions")`). If no precedent applies, proceed to Step 0b.
 
 ### Step 0b — Apollo Pre-Scan (Fase 2, --research flag)
 If `/pantheon --research <question>`: dispatch @apollo with 30s timeout. Inject findings as `shared_context` into ALL specialist prompts. Skip if flag absent.

package/CHANGELOG.md

@@ -18,6 +18,47 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.6.0-beta.6] - 2026-10-05
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🆕 What's New
+
+- **Política de suporte documentada: a linha 1.6.x é a ÚLTIMA compatível com OpenCode 1.X.** A partir de **1.7, toda release é breaking change com alvo em OpenCode 2.** O limite está escrito no `README.md` (seção "Compatibility and support policy", com matriz de suporte) e em `docs/INSTALLATION.md` (seção "OpenCode V1/V2 — contrato de plugin"), não duplicado em um documento novo: os dois arquivos já eram o ponto de entrada do contrato de plugin, e um terceiro documento seria um terceiro lugar para divergir. O texto distingue as duas células da linha 1.6.x — a célula 1.X é o contrato V1 (6 tools, lifecycle do board, hooks V1, compaction V1) e a célula OpenCode 2 é o contrato V2, que é real porém **menor**: 3 tools, sem as `pantheon_goal_*` e sem a matriz de delegação caller→target. **O suporte a OpenCode 2 na linha 1.6 é documentado como parcial, e não como completo**, por duas razões verificadas: (a) o canário de ferramentas V2 foi escrito contra `opencode 2.0.22`, host que não é publicado em nenhum canal npm — contra o `@opencode-ai/cli` instalável o mesmo canário falha 12/12, porque `/api/experimental/session/{id}/wait` foi promovido para `/api/session/{id}/wait` (404 no caminho antigo) e `ctx.tool.list` não existe mais; corrigindo apenas a rota, 10/12 passam no mesmo host, o que caracteriza descasamento canário/host e não regressão medida do plugin (issue #216, PR #213); (b) não existe perna V1 de validação end-to-end — `scripts/test-opencode-v2-sandbox.sh` é V2-only e rejeita `--run v1` — portanto a versão exata de host 1.X exercitada end-to-end pela linha 1.6 fica registrada como **não verificada**, e o caminho 1.X é sustentado pelo pin de dependência (`@opencode-ai/plugin` / `@opencode-ai/sdk` `1.18.33`), pelos testes unitários do gate de geração e pelos testes end-to-end do installer sobre a config emitida.
+
+## 🐞 Fixed
+
+- **Os exemplos de chamada MCP nos arquivos de prompt ensinavam um contrato que não existe no schema real.** Um `pantheon-persistence.kv_get` ao vivo foi rejeitado com `namespace: Missing key`; a linha que o produziu foi `src/agents/zeus.md:189` (`depth = kv_get("deleg:depth") ?? 0`), cuja cópia instalada em `~/.config/opencode/agents/zeus.md` é a que executou. A causa não era o servidor MCP: os arquivos de agente e de instrução ensinavam chamadas posicionais sem `namespace`, enquanto o schema real é `kv_get({ namespace /* obrigatório, sem default */, key, scope? })` — `kv_store.namespace` é igualmente obrigatório e `kv_store.value` é `str`. **A correção está nos docs, e não em adicionar um `namespace` default:** um default escreveria estado de coordenação no namespace errado silenciosamente, então *obrigatório* é o desenho correto. A mesma classe de defeito foi corrigida em `context_save` (posicional, com um helper `json()` inexistente e sem o `session_id` obrigatório → forma por palavra-chave com `content=JSON.stringify(...)`), em `memory_store` (`value` precisa ser uma string JSON codificada → agora iguala o padrão já correto de `metadata`, o que resolveu uma aut contradição no mesmo arquivo), na aritmética de profundidade (envolvida em `String(...)`, porque `kv_store.value` é `str` e não `int`) e em `memory_search(query, ...)` → `query=` em todas as instâncias. `AGENTS.md` é artefato gerado e foi reconstruído, nunca editado à mão.
+- **Um bypass de permissão vivo: `edit: deny` não cobria `hashline_edit`.** A regra `edit: deny` é avaliada por nome de ferramenta, e `hashline_edit` não é `edit` — então os agentes restritos a `edit: deny` (`zeus`, `athena`, `iris`, `nyx`, `themis`) podiam editar arquivos assim mesmo, escrevendo no disco por um caminho que a negação não cobria. `hashline_edit: deny` foi adicionado a esses cinco agentes. **Não era uma condição de corrida nem um erro de configuração: era uma tabela de permissões incompleta**, o que significa que a negação nunca esteve de fato aplicada a quem só deveria ler.
+- **`test:node` reportava sucesso tendo coletado zero testes.** `node --test <glob>` sai com 0 quando o glob não expande (Node >= 22), e foi exatamente o que aconteceu: um glob que nunca expandiu produziu um gate verde que não executou nada. Pior, `tests/` estava ausente da allow-list `files` do pacote, então um consumidor que rodasse `npm test` recebia esse verde. Agora os scripts de teste falham em voz alta quando a coleta é zero, e a guarda tem teste próprio (`tests/run-node-tests.test.mjs`) que a dirige como subprocesso — o contrato é o código de saída, então testá-la em processo não provaria nada.
+## [v1.6.0-beta.5] - 2026-10-05
+
+&lt;!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. --&gt;
+
+## 🆕 What's New
+
+- **O gate de geração do plugin passa a ler a versão do host — e a superfície de ferramentas deixa de desaparecer num host OpenCode 2.x.** O seletor de geração tinha três defaults `'v1'` (`bin/pantheon-init.mjs`, `scripts/install/opencode.mjs` e a assinatura do resolver em `scripts/install/opencode-version.mjs`). Nesse ramo, o installer grava caminhos de arquivo `.ts` na chave singular `plugin`; um host 2.x rejeita caminhos de arquivo ali (`configured plugin path must be a directory`), **descarta** as entradas e, ao fazer isso, **remove** a entrada de diretório V2 que já estava registrada e funcionando. O sintoma era um host aparentemente saudável — a frota MCP subia normalmente — com um único WARN no log e **nenhuma** ferramenta do plugin no catálogo: sem `pantheon_cost`, sem `hashline_edit`, sem `pantheon_model`, sem BackgroundJobBoard e sem hooks. Os três defaults passam a `'auto'`, e `auto` consulta a versão do host. Precedência: flag explícita > `OPENCODE_VERSION` > basename `opencode2` > probe de `--version` > aviso e fallback `v1`. Isto restaura as **3** ferramentas que o contrato V2 registra (`hashline_edit`, `pantheon_cost`, `pantheon_model`); não é paridade com o V1 — ver **Issues Conhecidas**.
+- **Uma instalação na geração V2 e o `doctor` agora declaram a superfície reduzida em vez de deixá-la ser descoberta.** A lista de recursos não suportados no V2 (`getUnsupportedFeatures()`) não tinha nenhum consumidor em produção — só testes a liam. O installer passa a imprimi-la ao lado do aviso de destino V2, e o `doctor` a reporta como um achado próprio, sem alterar o código de saída (uma instalação V2 é uma configuração suportada, não quebrada). A V2 registra 3 ferramentas, não 6, e não tem BackgroundJobBoard; as 3 ferramentas de goal não são registradas na V2 por desenho. O texto agora é único, vindo de `src/pantheon/v2-unsupported.mjs`.
+- **Renomeação dos entrypoints MCP (issue #198).** Os cinco entrypoints Python deixaram de compartilhar o token `server.py`, então um `pkill -f server.py` amplo não derruba mais a frota inteira como efeito colateral. Inclui uma migração em tempo de instalação para que as instalações existentes não fiquem órfãs.
+- **O pacote npm deixou de versionar e distribuir a configuração pessoal de desenvolvimento do OpenCode.** `opencode.json` e `.opencode/` (comandos, plugins e skills) saíram do controle de versão: a config carregava um endpoint MCP privado e overrides de permissão por desenvolvedor, e o harness V1 de comandos/plugins foi substituído por `src/plugin-v2.ts`. O `init` continua gerando a config do projeto do usuário, então instalações não são afetadas; para contribuidores, um `opencode.json` pessoal deve ir em `.git/info/exclude`.
+- **Documentação: `ROADMAP.md` reescrito e um novo documento de fronteira.** O roadmap foi reescrito com as causas-raiz verificadas, e um novo documento — `docs/PERMISSIONS-QUALITY-DELEGATION.md` — mapeia os gates de qualidade, as quatro camadas de permissão e a delegação num só lugar, marcando explicitamente o que ainda não foi verificado.
+
+## 🐞 Fixed
+
+- **A leitura do banner de versão do host era quadrática.** Um banner longo custava **11,1 s** para ser interpretado, contra o timeout de **5 s** do spawn de `--version`; o timeout guarda o processo, não a leitura, então um host verboso conseguia estourá-lo. A interpretação passou a ser **linear**.
+- **O `readOnlyRegistry` do V2 não era podado no `session.deleted`.** O registro é global ao processo e nunca era limpo quando uma sessão do V2 terminava, então entradas de sessões encerradas acumulavam. O `session.deleted` do V2 passa a podar o registro, como a V1 já fazia.
+
+## ⚠️ Known Issues
+
+- **Ação necessária: re-executar o `init` numa instalação afetada.** O `postinstall` **não** roda o `init`. Quem teve a configuração corrompida por uma instalação `v1` anterior **não** é auto-corrigido apenas por atualizar o pacote — é preciso rodar o installer de novo (`npx pantheon-opencode init`). Uma escolha correta de geração **auto-corrige** a configuração (o ramo V2 já remove as referências `.ts` do V1), mas só quando o installer roda. O mesmo vale para a renomeação dos entrypoints: instalações existentes continuam funcionando porque os arquivos antigos são mantidos, mas os caminhos só são corrigidos numa nova execução do installer; até lá, esses usuários permanecem nos entrypoints antigos e sujeitos ao efeito colateral do `server.py`.
+- **A superfície V2 é menor que a V1 por desenho.** A V2 registra 3 ferramentas (`hashline_edit`, `pantheon_cost`, `pantheon_model`), não 6, e não tem BackgroundJobBoard; as 3 `pantheon_goal_*` são V1-only e a matriz de delegação caller→target não é replicada. O installer e o `doctor` agora **dizem** isso (ver What's New), mas a funcionalidade ausente não é restaurada.
+- **O fallback continua a ser `v1`.** Quando o probe do host falha, não consegue ser interpretado, ou traz versões contraditórias, o resolver avisa **uma vez** e cai para `v1`, em vez de arriscar um host 1.x com uma entrada `plugins` que ele ignoraria. É um erro alto e visível, mas ainda é uma queda para a configuração V1.
+
+## ✅ Closed Issues
+
+- **A justificativa da matriz de delegação V1→V2 foi corrigida.** O texto dizia que o V2 "não expõe esse caminho de semeadura"; os tipos do SDK refutam isso. A causa real da matriz não replicada não é a ausência de um caminho de semeadura (`session.created` do V2 traz `properties.info: Session` com `parentID?`, o mesmo campo que a V1 semeia), mas a *segunda* fonte da V1 — o seed de `client.session.list()` para sessões anteriores ao carregamento do plugin — porque o `PluginContext` do V2 não expõe `client`. Se um host 2.0.22 ao vivo popula `info.parentID` nesse evento continua **não verificado** (nenhum canário lê payload de evento). A linha publicada em `v1.6.0-beta.4` fica como registro.
 ## [v1.6.0-beta.4] - 2026-10-03
 
 &lt;!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -31,7 +31,9 @@ way to plan work, make progress, check results, and keep useful project context.
 ## Start in 2 minutes
 
 Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js
-22.22.2+ (or 24.15.0+ / 26+).
+22.22.2+ (or 24.15.0+ / 26+). For which OpenCode generation each Pantheon
+release line supports, see
+[Compatibility and support policy](#compatibility-and-support-policy).
 
 Pantheon declares `engines.node` as `^22.22.2 || ^24.15.0 || >=26.0.0`. The
 floor reflects what the dependency tree actually needs — the transitive
@@ -89,6 +91,81 @@ services you choose to use. Check the
 [releases](https://github.com/ils15/pantheon-opencode/releases) and
 [changelog](CHANGELOG.md) for the latest published changes.
 
+## Compatibility and support policy
+
+> ### ⚠️ 1.6.x is the LAST line that supports OpenCode 1.X
+>
+> **OpenCode 1.X support ends after the 1.6 line.** From **1.7 onward, every
+> release is a breaking change targeting OpenCode 2.** A 1.6.x install is the
+> last one that runs on an OpenCode 1.X host; do not plan an upgrade across the
+> 1.6 → 1.7 boundary while your host is still on OpenCode 1.X.
+
+| Pantheon line | OpenCode 1.X host | OpenCode 2 host |
+|---|---|---|
+| **1.6.x** (current line) | **Supported.** V1 plugin contract | Supported, reduced surface — V2 contract |
+| **1.7 and later** | **Not supported.** Breaking change | Target of the 1.7+ work |
+
+Both columns of the 1.6.x row are real, and they are not the same claim. Read
+[the plugin contract](#opencode-v1v2--dual-version-160-beta1) for what each
+generation actually registers.
+
+### What "supported on OpenCode 1.X" concretely means
+
+On the 1.6 line, an OpenCode 1.X host gets the **V1 plugin**:
+`src/plugin.ts` plus `src/plugins/pantheon-hooks.ts`, registered under the
+singular `plugin` config key. That surface registers 6 tools
+(`hashline_edit`, the 3 `pantheon_goal_*` tools, `pantheon_cost`,
+`pantheon_model`), the BackgroundJobBoard lifecycle, the V1 event/tool hooks and
+the V1 compaction path. It is selected automatically: the generation gate
+(`--opencode-version`, else `OPENCODE_VERSION`, else a `OPENCODE_BIN` basename of
+`opencode2`, else a `--version` probe where major ≥ 2 selects V2) resolves a 1.X
+host to V1.
+
+The two generations are exclusive. The installer strips Pantheon references from
+both config shapes and registers only the selected one, so a 1.X host never
+loads the V2 plugin and a V2 host never loads the V1 plugin. Forcing V2 on a 1.X
+host is an unsupported mixed/wrong-generation configuration, not a supported mode.
+
+### What the OpenCode 2 path is — and is not
+
+**Not inert.** The V2 path (`src/plugin-v2`, registered as a directory because
+the V2 loader rejects bare file paths) registers real tools with real
+`input`/`output` schemas via `ctx.tool.transform()`, 5 event subscriptions,
+session hooks and a tool `execute.before` hook that enforces read-only sessions.
+It is a smaller surface than V1 by design, not a stub: the 3 goal tools and the
+V1 caller→target delegation matrix are absent, and `getUnsupportedFeatures()`
+reports that as `goal-tools` and `delegation-matrix`.
+
+**Not complete either, and the V2 support claim is currently narrowed.** Two
+facts, both recorded in this repository rather than smoothed over:
+
+- **The host-backed V2 gate is red on the installable OpenCode CLI.** The V2 tool
+  canary (`tests/canary/plugin-v2-tool-canary.test.mjs`) was written against
+  `opencode 2.0.22`, which no npm channel publishes. Against the installable
+  `@opencode-ai/cli` host, `/api/experimental/session/{id}/wait` has been
+  promoted to `/api/session/{id}/wait` (the old path 404s) and `ctx.tool.list`
+  is absent, so the canary fails 12/12 there. That is a canary/host-generation
+  mismatch, not a measured plugin regression — with only the route renamed, 10/12
+  pass on the same host, including the edit being applied and the mutant still
+  caught. Tracked as [issue
+  #216](https://github.com/ils15/pantheon-opencode/issues/216); the fail-closed
+  CI change is [PR #213](https://github.com/ils15/pantheon-opencode/pull/213).
+- **The 2.x host claims in `src/plugin-v2.ts` are measured against `2.0.22`
+  specifically**, not against the current installable CLI. Re-measurement
+  against the current host is outstanding and is tracked in the same issue.
+
+Treat the 1.6 line's OpenCode 2 support as **real but partial**, and do not read
+the 1.6.x row as "OpenCode 2 is finished".
+
+### Verified against which OpenCode versions
+
+| What | Verified against | How |
+|---|---|---|
+| V1 plugin + generation gate | The OpenCode 1.18.x line. This package pins `@opencode-ai/plugin` and `@opencode-ai/sdk` to `1.18.33`; the highest published `opencode-ai` host package (the one shipping the `opencode` binary) is `1.18.34` | Dependency pin (`package.json`); generation-gate unit tests over injected host banners; installer end-to-end tests asserting the emitted `opencode.json` shape |
+| V2 plugin tool surface | `opencode 2.0.22` (the host the canary was written against) | `tests/canary/plugin-v2-tool-canary.test.mjs`, driving `hashline_edit` through a real `opencode serve` |
+| V2 against the current installable CLI | **Not verified.** Canary fails 12/12; see issue #216 | — |
+| Exact 1.X host version the 1.6 line is exercised against end-to-end | **Unverified.** No V1 host leg exists: the sandbox runner is V2-only and `--run v1` is rejected | — |
+
 ## Delegation (native `task()`)
 
 Pantheon delegates exclusively through OpenCode's native `task()` child-session
@@ -188,12 +265,13 @@ per installation; V1 and V2 Pantheon plugins must never be registered together.
 |---|---|---|
 | OpenCode config key | singular `plugin` | plural `plugins` |
 | Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
-| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 3 tools (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 4 event subscriptions, session hooks (`prompt`, `context`), a read-only-enforcing tool `execute.before` hook, plus configuration transforms |
+| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 3 tools (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 5 event subscriptions, session hooks (`prompt`, `context`), a read-only-enforcing tool `execute.before` hook, plus configuration transforms |
 | V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
 
 The V2 plugin provides 3 orchestration tools (`hashline_edit`, `pantheon_cost`,
-`pantheon_model`), 4 event subscriptions (`session.created`, `session.idle`,
-`session.error`, `session.compacted`), session hooks (`prompt`, `context`),
+`pantheon_model`), 5 event subscriptions (`session.created`, `session.idle`,
+`session.deleted`, `session.error`, `session.compacted`), session hooks
+(`prompt`, `context`),
 and a tool `execute.before` hook that enforces read-only sessions. The 3 goal
 tools are **not**
 registered on V2: the goal loop needs a `GoalStore`, a `GoalLoopClient` and a
@@ -236,13 +314,22 @@ npx pantheon-opencode init --opencode-version v2
 npx pantheon-opencode init --opencode-version auto
 ```
 
-`--version v1|v2|auto` is accepted as the older selector spelling when used
-after `init`. `auto` is conservative, not general platform autodetection:
-`OPENCODE_VERSION=v1|v2` wins; otherwise an `OPENCODE_BIN` ending in
-`opencode2` selects V2; every other case selects V1. The installer removes
-Pantheon references from both config shapes before writing only the selected
-Pantheon registration. Third-party entries are not converted or claimed by
-this rule.
+`auto` is the default. `--version v1|v2|auto` is accepted as the older
+selector spelling when used after `init`. `auto` resolves the generation from
+the host in this order: an explicit `OPENCODE_VERSION=v1|v2` wins; otherwise an
+`OPENCODE_BIN` path ending in `opencode2` selects V2; otherwise the host
+binary is asked for its `--version` and a major of 2 or more selects V2. Every
+other case — an unreadable probe, an unparseable banner, or a banner whose
+version-like tokens contradict each other with no tool name to break the tie —
+warns once and falls back to V1, because a plural `plugins` directory entry on
+an unknown 1.x host loses the plugin entirely.
+
+The probe prefers the token that follows the tool name, so a runtime token
+ahead of it (`node v22.1.0 (opencode 1.18.33)`) or a trailing build date
+(`opencode v1.18.33 built 2026.10.04`) cannot flip the generation. The
+installer removes Pantheon references from both config shapes before writing
+only the selected Pantheon registration. Third-party entries are not converted
+or claimed by this rule.
 
 The `pantheon_cost` report resolves its database by PATH, in this order: an
 explicit `dbPath` supplied by the tool caller, then
@@ -291,6 +378,11 @@ Key order does not matter.
 
 ## Updating between releases (beta.5+)
 
+> **Read [Compatibility and support policy](#compatibility-and-support-policy)
+> before upgrading across a line boundary.** 1.6.x is the last line that
+> supports an OpenCode 1.X host; 1.7+ is breaking-change territory targeting
+> OpenCode 2. Within the 1.6 line, `update` is the supported path.
+
 One command keeps an existing installation current:
 
 ```bash
@@ -450,7 +542,7 @@ in the sandbox root) · `2` usage error · `3` sandbox not prepared.
 
 ### Intentional memory MCP divergence
 
-`scripts/memory_mcp_server.py` and `src/mcp/memory_mcp_server.py` are
+`scripts/memory_mcp.py` and `src/mcp/memory_mcp.py` are
 intentionally different. The standalone `scripts/` copy keeps the lightweight
 `memory_*` contract; the installed `src/mcp/` copy additionally exposes the
 optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
@@ -499,6 +591,16 @@ Ideas, bug reports, documentation improvements, and code contributions are
 welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue
 or pull request.
 
+### Project-level `opencode.json`
+
+The published package carries no `opencode.json` template. `init` still writes
+your project's `opencode.json` itself, and the few product defaults an install
+seeds — `default_agent: zeus` and `permission.skill` — come from the installer
+code, not from a packaged file. Contributors who keep a project-level
+`opencode.json` for their own OpenCode sessions should leave it untracked —
+`.git/info/exclude` per clone, or a shared `.gitignore` decision — rather than
+versioning it.
+
 ## Citation and DOI
 
 Pantheon is released under the [MIT License](LICENSE). Cite the

package/README.pt-BR.md

@@ -171,11 +171,20 @@ 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.
 
@@ -344,7 +353,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).
@@ -54,6 +56,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)',
@@ -287,6 +292,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 +374,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',
@@ -402,7 +424,8 @@ async function main() {
         model: modelOpt,
         smallModel: smallModelOpt,
         preset: presetOpt,
-        version: versionOpt ?? 'v1',
+        version: versionOpt ?? 'auto',
+        mergeDevConfig: mergeDevConfigOpt,
       })
     } catch (err) {
       if (err?.message === 'Canceled') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.6.0-beta.4",
+  "version": "1.6.0-beta.6",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "workspaces": [
@@ -41,12 +41,12 @@
     "hooks:install": "pre-commit install",
     "hooks:update": "pre-commit autoupdate",
     "test:security": "npm run secret-scan",
-    "test:node": "node --test tests/*.mjs tests/pantheon/*.mjs",
-    "coverage": "echo 'Node coverage (report-only, NO threshold is enforced).' && echo 'Covers: the .mjs/.js modules under scripts/, src/ and bin/ that test:node exercises.' && echo 'Does NOT cover: test:ts (hand-rolled tsx loop, no node --test runner) and test:ci (pytest).' && echo '             TypeScript under src/ (41 files) is therefore entirely unmeasured here.' && echo '' && node --test --experimental-test-coverage --test-coverage-include='scripts/**/*.mjs' --test-coverage-include='src/**/*.mjs' --test-coverage-include='src/**/*.js' --test-coverage-include='bin/**/*.mjs' tests/*.mjs tests/pantheon/*.mjs",
+    "test:node": "node scripts/run-node-tests.mjs --label 'test:node' 'tests/*.mjs' 'tests/pantheon/*.mjs'",
+    "coverage": "echo 'Node coverage (report-only, NO threshold is enforced).' && echo 'Covers: the .mjs/.js modules under scripts/, src/ and bin/ that test:node exercises.' && echo 'Does NOT cover: test:ts (hand-rolled tsx loop, no node --test runner) and test:ci (pytest).' && echo '             TypeScript under src/ (41 files) is therefore entirely unmeasured here.' && echo '' && node scripts/run-node-tests.mjs --label 'coverage' -- --experimental-test-coverage --test-coverage-include='scripts/**/*.mjs' --test-coverage-include='src/**/*.mjs' --test-coverage-include='src/**/*.js' --test-coverage-include='bin/**/*.mjs' 'tests/*.mjs' 'tests/pantheon/*.mjs'",
     "coverage:plugin-v2": "node scripts/check-plugin-v2-coverage.mjs",
     "test:ts": "for f in tests/pantheon/*.test.ts; do if [ \"$f\" = tests/pantheon/plugin-v2-contract.test.ts ]; then NODE_OPTIONS=--conditions=import tsx \"$f\"; else tsx \"$f\"; fi || exit 1; done",
-    "test:hooks": "node --test tests/pantheon/plugin-v2-hook-canary.test.mjs",
-    "test:tool-canary": "node --test tests/canary/plugin-v2-tool-canary.test.mjs",
+    "test:hooks": "node scripts/run-node-tests.mjs --label 'test:hooks' 'tests/pantheon/plugin-v2-hook-canary.test.mjs'",
+    "test:tool-canary": "node scripts/run-node-tests.mjs --label 'test:tool-canary' 'tests/canary/plugin-v2-tool-canary.test.mjs'",
     "test:all": "npm run test:ci && npm run test:node && npm run test:ts",
     "test": "npm run test:all",
     "test:ci": "python3 -m pytest -q --tb=short 2>&1"
@@ -76,7 +76,6 @@
     "bin/*.mjs",
     "AGENTS.md",
     "CHANGELOG.md",
-    "opencode.json",
     "src/mcp/*.py",
     "src/instructions/*.instructions.md",
     "src/mcp/*.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.6.0-beta.4",
+  "version": "1.6.0-beta.6",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.6.0-beta.4"
+version = "1.6.0-beta.6"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []
@@ -39,11 +39,11 @@ select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "PL", "RUF", "C901"]
 "tests/test_memory_mcp_server.py" = ["PLC0415", "PLR2004"]
 # Existing public APIs and test fixtures are intentionally broad/simple; refactoring
 # them would be behavior-affecting rather than a mechanical lint correction.
-"scripts/code_mode_server.py" = ["PLR0913", "PLR0917"]
-"src/mcp/code_mode_server.py" = ["PLR0913", "PLR0917"]
-"scripts/mcp_persistence_server.py" = ["PLR0913", "PLR0917"]
-"src/mcp/mcp_persistence_server.py" = ["PLR0913", "PLR0917"]
-"scripts/memory_mcp_server.py" = ["C901"]
+"scripts/code_mode.py" = ["PLR0913", "PLR0917"]
+"src/mcp/code_mode.py" = ["PLR0913", "PLR0917"]
+"scripts/mcp_persistence.py" = ["PLR0913", "PLR0917"]
+"src/mcp/mcp_persistence.py" = ["PLR0913", "PLR0917"]
+"scripts/memory_mcp.py" = ["C901"]
 "src/mcp/eval_store.py" = ["PLR2004"]
 "tests/test_code_mode_frontmatter.py" = ["PLR2004"]
 "tests/test_eval.py" = ["PLR2004"]

package/scripts/{code_mode_server.py → code_mode.py}

@@ -5,12 +5,12 @@ Provides a confined execution environment for orchestration scripts
 via MCP tools and resources.
 
 Usage:
-    python scripts/code_mode_server.py
+    python scripts/code_mode.py
 
 Or via MCP client (stdio transport):
     pantheon-code-mode:
         command: python
-        args: ["scripts/code_mode_server.py"]
+        args: ["scripts/code_mode.py"]
 """
 
 from __future__ import annotations