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

package/AGENTS.md

@@ -275,8 +275,14 @@ Para otimizar decisoes de delegacao e reduzir gasto de tokens:
 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})
+
+   `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("deleg:<pattern>", ...)** para padroes recorrentes de delegacao
 5. **kv_get("deleg:<pattern>")** para reusar decisoes ja tomadas
@@ -305,14 +311,19 @@ memory_store({
     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:
@@ -425,9 +436,17 @@ No file I/O, no checkpoint_session.py — TTL (4h) handles cleanup automatically
 Before ANY delegate dispatch, save a checkpoint:
 ```
 context_save(slug, "phase:N", json({
-  "phase": N, "turn_count": N, "agent": "...", "summary": "..."
+  "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)

package/CHANGELOG.md

@@ -18,6 +18,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.6.0-beta.5] - 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
+
+- **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
 
 <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -188,12 +188,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 +237,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
@@ -450,7 +460,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 +509,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.5",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "workspaces": [
@@ -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.5",
   "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.5"
 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

package/scripts/doctor.mjs

@@ -29,6 +29,8 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { listV2UnsupportedFeatures } from '../src/pantheon/v2-unsupported.mjs'
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -1000,7 +1002,7 @@ function checkVenvLayer(args) {
 /**
  * Return whether *dir* contains an executable code-mode target.
  *
- * Mirrors `_has_usable_scripts` in `scripts/code_mode_server.py`: a directory
+ * Mirrors `_has_usable_scripts` in `scripts/code_mode.py`: a directory
  * is only a valid resolver candidate when it is a real (non-symlink) directory
  * containing a regular `.py`/`.sh` direct child. This prevents an empty project
  * overlay from masking a lower-priority installation that actually ships
@@ -1430,6 +1432,153 @@ export function checkPluginVersionDrift(args) {
   return 'sync'
 }
 
+// ---------------------------------------------------------------------------
+// Check H4: V2 feature reduction (the surface a migrating user loses)
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an opencode.json registers the V2 generation of the Pantheon plugin.
+ *
+ * The V2 contract is the PLURAL `plugins` key; V1 is the singular `plugin` key.
+ * So the key alone is not the test — a config can legitimately carry a
+ * third-party entry in `plugins`. What identifies the generation is a Pantheon
+ * V2 entry inside it. Matched on the `plugin-v2` marker so all three real
+ * spellings are recognised: the canonical DIRECTORY (`src/plugin-v2`), an
+ * absolute path to it, and the package export (`pantheon-opencode/plugin-v2`).
+ *
+ * @param {unknown} ref
+ * @returns {boolean}
+ */
+function isV2PluginRef(ref) {
+  const candidate =
+    typeof ref === 'string'
+      ? ref
+      : ref && typeof ref === 'object'
+        ? (ref.path ?? ref.source ?? ref.id ?? ref.name)
+        : undefined
+  return typeof candidate === 'string' && candidate.includes('plugin-v2')
+}
+
+/**
+ * Whether any reachable config registers the V2 generation of the Pantheon
+ * plugin. Split out of {@link collectV2UnsupportedFeatures} because "is the V2
+ * generation registered" and "does the seed list anything" are TWO facts: the
+ * first is about the user's config, the second about this repository's seed. A
+ * single `features.length === 0` cannot tell them apart, and conflating them
+ * let an emptied seed print "no V2 generation registered — nothing reduced".
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {boolean}
+ */
+export function isV2GenerationRegistered(configs) {
+  return configs.some((cfg) => {
+    const list = cfg.data?.plugins
+    return Array.isArray(list) && list.some(isV2PluginRef)
+  })
+}
+
+/**
+ * The V2 feature-reduction markers to report for a set of collected configs.
+ *
+ * Returns the shared seed verbatim when ANY reachable config registers the V2
+ * generation, and an empty list otherwise. The strings come from
+ * `src/pantheon/v2-unsupported.mjs` — the same seed `getUnsupportedFeatures()`
+ * is built from — so doctor cannot report a reduction the plugin does not, or
+ * miss one it does. Nothing is reworded here.
+ *
+ * An empty result is ambiguous on its own and deliberately not interpreted
+ * here: ask {@link isV2GenerationRegistered} for the registration fact, or
+ * {@link describeV2Reduction} to get both at once.
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {string[]}
+ */
+export function collectV2UnsupportedFeatures(configs) {
+  return isV2GenerationRegistered(configs) ? listV2UnsupportedFeatures() : []
+}
+
+/**
+ * Decide what H4 prints, from the two distinct facts rather than from one list
+ * length.
+ *
+ * Three cases, and the middle one used to be silently reported as the first:
+ *
+ *   - not registered → info. A V1 install is a supported configuration with
+ *     nothing to reduce, and saying so plainly is correct.
+ *   - registered, seed EMPTY → warn. This is a packaging fault in THIS repo,
+ *     not an absence of reduction: the V2 surface really is reduced and the
+ *     report is missing. It must never claim "nothing reduced".
+ *   - registered, seed populated → warn, listing every marker.
+ *
+ * Pure and exported so the empty-seed branch is testable without stubbing the
+ * frozen seed module. `status` is returned alongside the text so a caller never
+ * has to recover the case by matching on the message.
+ *
+ * @param {{registered:boolean, features:string[]}} input
+ * @returns {{status:'reported'|'empty-seed'|'no-v2-generation', level:'info'|'warn', message:string}}
+ */
+export function describeV2Reduction({ registered, features }) {
+  if (!registered) {
+    return {
+      status: 'no-v2-generation',
+      level: 'info',
+      message: 'No V2 plugin generation registered — nothing reduced',
+    }
+  }
+  if (features.length === 0) {
+    return {
+      status: 'empty-seed',
+      level: 'warn',
+      message:
+        'Pantheon IS registered on the V2 plugin generation, but the shared ' +
+        'unsupported-feature seed is empty, so the reduction cannot be reported. ' +
+        "That is a fault in this installation's reporting, not an absence of " +
+        'reduction: the V2 surface still drops the 3 goal tools and the ' +
+        'caller/target delegation matrix.',
+    }
+  }
+  return {
+    status: 'reported',
+    level: 'warn',
+    message:
+      'Pantheon is registered on the V2 plugin generation, which registers 3 tools ' +
+      "(hashline_edit, pantheon_cost, pantheon_model) instead of the V1 surface's 6 plus " +
+      `the BackgroundJobBoard and the caller/target delegation matrix. Unsupported: ${features.join(', ')}`,
+  }
+}
+
+/**
+ * Report the V2 feature reduction through doctor's own output shape
+ * (section + warn/info), so it lands in the health summary like every other
+ * finding and never changes the exit code: a V2 install is a supported
+ * configuration, not a broken one.
+ *
+ * @param {{target:string, env?:object}} args
+ * @returns {'reported'|'empty-seed'|'no-v2-generation'|'no-config'}
+ */
+export function checkV2UnsupportedFeatures(args) {
+  section('H4. V2 Feature Reduction')
+
+  const configs = collectMcpConfigs(args)
+  if (configs.length === 0) {
+    info('No opencode.json was found — V2 feature reduction check skipped')
+    return 'no-config'
+  }
+
+  // Branch on REGISTRATION, not on the marker count: an empty seed on a
+  // registered V2 generation is a reporting fault and must not be reported as
+  // the reassuring "nothing reduced".
+  const registered = isV2GenerationRegistered(configs)
+  const verdict = describeV2Reduction({
+    registered,
+    features: collectV2UnsupportedFeatures(configs),
+  })
+  if (verdict.level === 'info') info(verdict.message)
+  else warn(verdict.message)
+
+  return verdict.status
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1802,6 +1951,7 @@ async function main() {
   checkAgentsMdFreshness(args)
   checkSubagentDepthPlacement(args)
   checkPermissionTaskPresence(args)
+  checkV2UnsupportedFeatures(args)
 
   printSummary(args.target)
 

package/scripts/install/config-migration.mjs

@@ -229,8 +229,11 @@ function convertProviderV2toV1(_name, config) {
 /**
  * Convert V1 MCP config to V2.
  *
- * V1: { bifrost: { type: "remote", url: "...", enabled: true, timeout: 30000 } }
- * V2 installer output: { bifrost: { type: "remote", url: "...", enabled: true } }
+ * The server names are arbitrary — a user calls theirs whatever they like, and
+ * which MCP servers exist is entirely their configuration, never ours.
+ *
+ * V1: { myserver: { type: "remote", url: "...", enabled: true, timeout: 30000 } }
+ * V2 installer output: { myserver: { type: "remote", url: "...", enabled: true } }
  *
  * OpenCode 1.18.18 does not have an `mcp.servers` wrapper. It interprets
  * `servers` as the name of an MCP server and then rejects it with
@@ -285,6 +288,81 @@ function convertMcpV2toV1(mcpConfig) {
   return convertMcpV1toV2(mcpConfig)
 }
 
+// ---------------------------------------------------------------------------
+// MCP entrypoint path migration
+// ---------------------------------------------------------------------------
+
+/**
+ * Entrypoint filename renames: every historical Python MCP entrypoint shared
+ * the `server.py` token, so a broad `pkill -f server.py` (a common idiom in
+ * agent and scratch tooling) matched the entire fleet and killed it as
+ * collateral. The five entrypoints now carry distinct tokens.
+ *
+ * The rename alone is a BREAKING change for existing installs: their
+ * `opencode.json` carries literal paths like `scripts/memory_mcp_server.py`,
+ * and a path that no longer resolves fails every MCP server silently (the
+ * same class of failure as the dead plugin surface). This map is the single
+ * source of truth for the stale → current basename rewrite that repairs them.
+ */
+export const MCP_ENTRYPOINT_RENAMES = Object.freeze({
+  'mcp_resources_server.py': 'mcp_resources.py',
+  'code_mode_server.py': 'code_mode.py',
+  'memory_mcp_server.py': 'memory_mcp.py',
+  'mcp_persistence_server.py': 'mcp_persistence.py',
+  'pantheon_vision_server.py': 'pantheon_vision.py',
+})
+
+/**
+ * Rewrite a single path/argument string when its basename is a renamed MCP
+ * entrypoint. The directory prefix is preserved verbatim, so both relative
+ * (`scripts/memory_mcp_server.py`) and absolute/hand-edited paths heal without
+ * discarding a user's chosen location. Non-matching values pass through.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function renameMcpEntrypointPath(value) {
+  if (typeof value !== 'string') return value
+  const slash = Math.max(value.lastIndexOf('/'), value.lastIndexOf('\\'))
+  const base = value.slice(slash + 1)
+  const renamed = MCP_ENTRYPOINT_RENAMES[base]
+  if (!renamed) return value
+  return value.slice(0, value.length - base.length) + renamed
+}
+
+/**
+ * Heal stale MCP entrypoint paths in a flat named-server map, in place.
+ *
+ * Scans every server — not only the `pantheon-*` keys — because a user who
+ * hand-edited their config may have renamed the key while keeping the
+ * Pantheon path. Both `command` (installer writes `[python, script]`) and
+ * `args` (the standalone installer writes `[script]`) are covered, since
+ * which array carries the script differs between installers.
+ *
+ * @param {object} mcp - the `mcp` map from a config (mutated in place)
+ * @returns {number} count of rewritten strings (0 = already current)
+ */
+export function migrateMcpEntrypointPaths(mcp) {
+  if (!mcp || typeof mcp !== 'object' || Array.isArray(mcp)) return 0
+
+  let changed = 0
+  for (const server of Object.values(mcp)) {
+    if (!server || typeof server !== 'object') continue
+    for (const field of ['command', 'args']) {
+      const list = server[field]
+      if (!Array.isArray(list)) continue
+      for (let i = 0; i < list.length; i++) {
+        const next = renameMcpEntrypointPath(list[i])
+        if (next !== list[i]) {
+          list[i] = next
+          changed++
+        }
+      }
+    }
+  }
+  return changed
+}
+
 // ---------------------------------------------------------------------------
 // Top-level key mappings
 // ---------------------------------------------------------------------------