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

package/scripts/install/opencode.mjs

@@ -4,10 +4,14 @@
  *
  * Dual-version install (Phase 3): V1 and V2 receive the schema each runtime
  * actually consumes. V1 (`opencode` 1.18.x) uses the singular `plugin` key;
- * V2 (`opencode2` v0.0.0-next-17444) converts that list to `plugins` before
- * writing its config. Known V2 beta gaps handled here: top-level
- * `subagent_depth` is migrated to `experimental.subagent_depth`, and the
- * instruction content is consolidated into AGENTS.md, which both versions
+ * V2 (`opencode2`, OpenCode 2.x — `opencode2 --version` prints
+ * "opencode v2.0.22") converts that list to `plugins` before
+ * writing its config. An early 2.x prerelease printed "0.0.0-next-17444"
+ * instead; that is history, not what hosts report today, and it must not be
+ * cited as an observation (see the precedence rationale in
+ * scripts/install/opencode-version.mjs). Known V2 beta gaps handled here:
+ * top-level `subagent_depth` is migrated to `experimental.subagent_depth`, and
+ * the instruction content is consolidated into AGENTS.md, which both versions
  * load. Pass --version v2 to pantheon-init for an informational label; state
  * isolation is handled at runtime via OPENCODE_DB.
  */
@@ -16,6 +20,7 @@ import { createHash } from 'node:crypto'
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { listV2UnsupportedFeatures } from '../../src/pantheon/v2-unsupported.mjs'
 import {
   bullet,
   colors,
@@ -29,7 +34,7 @@ import {
   success,
   warning,
 } from './cli-ui.mjs'
-import { migrateV1toV2 } from './config-migration.mjs'
+import { migrateMcpEntrypointPaths, migrateV1toV2 } from './config-migration.mjs'
 import { healthCheck } from './health-check.mjs'
 import { detectVersion, runMigrations } from './migrate.mjs'
 import { resolveOpenCodeVersion } from './opencode-version.mjs'
@@ -61,6 +66,44 @@ const COMPONENT_NAMES = [
   'runtime',
 ]
 
+/**
+ * The product defaults an install seeds into the user's `opencode.json`.
+ *
+ * They live HERE, in code, rather than in a template shipped in the npm
+ * tarball: that template also carried a maintainer's private MCP endpoint,
+ * provider models and per-developer permission overrides, and shipping it to
+ * every installer was the bug (#199). Reading defaults off it meant deleting it
+ * silently stopped the seeding, so the defaults are now stated next to the code
+ * that consumes them.
+ *
+ * PERSONAL CONFIGURATION MUST NEVER BE SEEDED HERE: this is the installer's
+ * contract with every user, and a value that is only right on one machine
+ * belongs in that machine's own `opencode.json`. Deliberately NOT carried over
+ * from the template, each because it was personal rather than a product
+ * default:
+ *   - `provider` — pinned the maintainer's provider, model and modalities.
+ *   - `mcp` — a private remote MCP endpoint.
+ *   - `agent` — the maintainer's per-agent permission overrides.
+ *   - `permission.websearch: "deny"` — a personal restriction; a user may rely
+ *     on web search, so denying it is not ours to decide.
+ *   - `permission.bash` — the template's dev allowlist (git, npm, ruff, …), a
+ *     personal judgement about which commands to trust.
+ * Anything added here must be justifiable as "correct for a fresh install of
+ * the product, for anyone".
+ *
+ * Other seeding paths are untouched by this constant and still run: the config
+ * merge derives plugin refs, provider and compaction from a repository-root
+ * opencode.json when a contributor has one, and separately gates its own
+ * permission grants — `skill` on the skills component, `bash` unconditionally —
+ * on whether the user's own config already set them.
+ *
+ * Frozen, and copied only into a confirmed gap (never into a key the user
+ * already set), so nothing here can be mutated through a user's config.
+ */
+const PRODUCT_CONFIG_DEFAULTS = Object.freeze({
+  default_agent: 'zeus',
+})
+
 /**
  * Per-agent fields owned by the framework: for an agent that already exists in
  * the target config these are overwritten from the canonical source, and for a
@@ -158,8 +201,8 @@ function mergeMissing(target, source) {
 }
 
 /**
- * Resolve a plugin ref from the packaged opencode.json to a path INSIDE the
- * installed package.
+ * Resolve a plugin ref from the repository-root opencode.json to a path INSIDE
+ * the installed package.
  *
  * Only exact Pantheon plugin identities are resolved into the installed
  * package. In particular, a third-party absolute path ending in
@@ -456,6 +499,92 @@ export function setupRuntimePhase(target, { dryRun, clean, isGlobal }, stats, de
   }
 }
 
+/**
+ * Write the five managed MCP server entries into `config`, healing any stale
+ * entrypoint paths first.
+ *
+ * The heal runs on EVERY install, not only when an entry is missing: the
+ * per-server guards below are add-only, so an existing install whose
+ * `opencode.json` still carries a pre-rename `*_server.py` path would never be
+ * repaired. Healing first means a re-run of the installer fixes an orphaned
+ * config in place — the migration that makes the rename non-breaking.
+ *
+ * @param {object} config - full config object (mutated in place)
+ * @param {{ runtimeTarget: string, venvPython: string }} ctx
+ * @returns {{ healed: number }} number of stale path strings rewritten
+ */
+export function applyMcpServerEntries(config, { runtimeTarget, venvPython }) {
+  config.mcp = config.mcp || {}
+  // MCP stays a flat named-server map for BOTH V1 and V2: OpenCode 1.18.x has
+  // no `mcp.servers` wrapper and rejects one with "Missing key
+  // mcp.servers.enabled". config-migration.mjs normalizes any legacy
+  // wrapper-shaped entries back to the flat map.
+  const healed = migrateMcpEntrypointPaths(config.mcp)
+
+  // Only add if not already configured by user
+  if (!config.mcp['pantheon-resources']) {
+    config.mcp['pantheon-resources'] = {
+      type: 'local',
+      cwd: runtimeTarget,
+      command: [venvPython, 'scripts/mcp_resources.py'],
+      enabled: true,
+    }
+  }
+  if (!config.mcp['pantheon-code-mode']) {
+    config.mcp['pantheon-code-mode'] = {
+      type: 'local',
+      cwd: runtimeTarget,
+      command: [venvPython, 'scripts/code_mode.py'],
+      enabled: true,
+    }
+  }
+  if (!config.mcp['pantheon-memory']) {
+    config.mcp['pantheon-memory'] = {
+      type: 'local',
+      cwd: runtimeTarget,
+      command: [venvPython, 'scripts/memory_mcp.py'],
+      enabled: true,
+    }
+  }
+  if (!config.mcp['pantheon-persistence']) {
+    config.mcp['pantheon-persistence'] = {
+      type: 'local',
+      cwd: runtimeTarget,
+      command: [venvPython, 'scripts/mcp_persistence.py'],
+      enabled: true,
+    }
+  }
+  if (!config.mcp['pantheon-vision']) {
+    config.mcp['pantheon-vision'] = {
+      type: 'local',
+      cwd: runtimeTarget,
+      command: [venvPython, 'scripts/pantheon_vision.py'],
+      enabled: true,
+    }
+  }
+
+  // Default MCP permissions
+  config.permission = config.permission || {}
+  config.permission.mcp = config.permission.mcp || {}
+  if (!config.permission.mcp['pantheon-resources']) {
+    config.permission.mcp['pantheon-resources'] = 'allow'
+  }
+  if (!config.permission.mcp['pantheon-code-mode']) {
+    config.permission.mcp['pantheon-code-mode'] = 'ask'
+  }
+  if (!config.permission.mcp['pantheon-memory']) {
+    config.permission.mcp['pantheon-memory'] = 'allow'
+  }
+  if (!config.permission.mcp['pantheon-persistence']) {
+    config.permission.mcp['pantheon-persistence'] = 'allow'
+  }
+  if (!config.permission.mcp['pantheon-vision']) {
+    config.permission.mcp['pantheon-vision'] = 'ask'
+  }
+
+  return { healed }
+}
+
 export async function installOpenCode(
   target,
   dryRun = false,
@@ -477,12 +606,31 @@ export async function installOpenCode(
   // --opencode-version=v2. V2 normalizes V1 fields in memory (no rewrite) and
   // isolates its state DB via OPENCODE_DB (~/.local/share/opencode/opencode-v2.db)
   // with a distinct service port (49375 vs V1's 49374).
-  const version = resolveOpenCodeVersion(opts.version ?? 'v1')
+  // Default to 'auto' so a flagless run resolves against the actual host. A
+  // hardcoded 'v1' here (or in bin/pantheon-init.mjs) is what shipped the bug:
+  // the V1 branch writes .ts file paths that a 2.x host drops from the config.
+  // `opts` is forwarded as the resolver's options bag so a caller (and CI) can
+  // pin env/probe instead of spawning a real host binary.
+  const version = resolveOpenCodeVersion(opts.version ?? 'auto', opts)
   if (version === 'v2') {
     info(
       'OpenCode V2 target — shared config; state isolated via OPENCODE_DB ' +
         '(~/.local/share/opencode/opencode-v2.db), service port 49375',
     )
+    // Say what the V2 contract does NOT give you, at the moment the user picks
+    // it. The V2 surface is 3 tools (hashline_edit, pantheon_cost,
+    // pantheon_model); V1's is 6 plus the BackgroundJobBoard, the three goal
+    // tools and the caller/target delegation matrix. This list was previously
+    // reachable only through `getUnsupportedFeatures()`, which no production
+    // code called — a user migrating hit the reduction with no warning at all.
+    //
+    // The markers are read from the same seed `getUnsupportedFeatures()` is
+    // built from (src/pantheon/v2-unsupported.mjs), so this notice cannot drift
+    // from what the plugin reports. Advisory: a V2 install is a supported
+    // configuration, not a failure.
+    info(
+      `V2 plugin generation — reduced surface. Unsupported features: ${listV2UnsupportedFeatures().join(', ')}`,
+    )
   }
 
   // Interactive mode handling
@@ -514,10 +662,24 @@ export async function installOpenCode(
     }
   }
 
-  const pantheonConfigPath = join(ROOT, 'opencode.json')
+  // Product defaults live in code (PRODUCT_CONFIG_DEFAULTS). A repository-root
+  // opencode.json is a contributor's PERSONAL dev harness, not product data, so
+  // it must never be read just because it happens to exist: doing so silently
+  // injects the developer's provider/plugins/compaction into every config an
+  // install generates. The merge is therefore opt-in only, via
+  // --merge-dev-config <path>. Absent the flag, no root-level config is read.
+  const mergeDevConfigOpt = opts.mergeDevConfig ?? null
+  if (mergeDevConfigOpt !== null && typeof mergeDevConfigOpt !== 'string') {
+    throw new Error('mergeDevConfig requires a file path string')
+  }
+  const pantheonConfigPath =
+    typeof mergeDevConfigOpt === 'string' ? resolve(mergeDevConfigOpt) : null
   const targetConfigPath = join(target, 'opencode.json')
   const config = readJsonConfig(targetConfigPath)
-  const pantheonConfig = readJsonConfig(pantheonConfigPath)
+  const pantheonConfig =
+    pantheonConfigPath !== null && existsSync(pantheonConfigPath)
+      ? readJsonConfig(pantheonConfigPath)
+      : null
 
   // beta.5 preflight: fail BEFORE any files are written when the runtime
   // component needs toolchain pieces that are missing. Nothing has been
@@ -710,30 +872,30 @@ export async function installOpenCode(
 
     // ── MCP server scripts ──
     const mcpScripts = [
-      'mcp_resources_server.py',
-      'code_mode_server.py',
-      'memory_mcp_server.py',
+      'mcp_resources.py',
+      'code_mode.py',
+      'memory_mcp.py',
       'scrub-secrets.py',
       '_pantheon_paths.py',
       'mcp_codemap_module.py',
-      'mcp_persistence_server.py',
-      'pantheon_vision_server.py',
+      'mcp_persistence.py',
+      'pantheon_vision.py',
       'eval_store.py',
     ]
     const srcScriptsDir = join(ROOT, 'scripts')
     // Canonical MCP server sources live in src/mcp/. Map them explicitly so the
     // sync always copies from the canonical source, never from the stale root
     // scripts/ copies (which previously propagated bugs like the missing
-    // `import uuid` in mcp_persistence_server.py). scrub-secrets.py is not in
+    // `import uuid` in mcp_persistence.py). scrub-secrets.py is not in
     // src/mcp/ and intentionally falls back to join(ROOT, 'scripts').
     const canonicalMcpScripts = {
-      'mcp_resources_server.py': join(ROOT, 'src', 'mcp', 'mcp_resources_server.py'),
-      'code_mode_server.py': join(ROOT, 'src', 'mcp', 'code_mode_server.py'),
-      'memory_mcp_server.py': join(ROOT, 'src', 'mcp', 'memory_mcp_server.py'),
+      'mcp_resources.py': join(ROOT, 'src', 'mcp', 'mcp_resources.py'),
+      'code_mode.py': join(ROOT, 'src', 'mcp', 'code_mode.py'),
+      'memory_mcp.py': join(ROOT, 'src', 'mcp', 'memory_mcp.py'),
       '_pantheon_paths.py': join(ROOT, 'src', 'mcp', '_pantheon_paths.py'),
       'mcp_codemap_module.py': join(ROOT, 'src', 'mcp', 'mcp_codemap_module.py'),
-      'mcp_persistence_server.py': join(ROOT, 'src', 'mcp', 'mcp_persistence_server.py'),
-      'pantheon_vision_server.py': join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py'),
+      'mcp_persistence.py': join(ROOT, 'src', 'mcp', 'mcp_persistence.py'),
+      'pantheon_vision.py': join(ROOT, 'src', 'mcp', 'pantheon_vision.py'),
       'eval_store.py': join(ROOT, 'src', 'mcp', 'eval_store.py'),
     }
     const dstScriptsDir = join(runtimeTarget, 'scripts')
@@ -939,8 +1101,11 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // B.5 Ensure critical top-level OpenCode config sections
   // --------------------------------------------------------------------
-  if (config.default_agent === undefined && pantheonConfig.default_agent !== undefined) {
-    config.default_agent = pantheonConfig.default_agent
+  // Seeded from code, not from a packaged template: see
+  // PRODUCT_CONFIG_DEFAULTS. Only fills a gap — a user who already chose a
+  // default agent keeps it.
+  if (config.default_agent === undefined) {
+    config.default_agent = PRODUCT_CONFIG_DEFAULTS.default_agent
   }
   // Apply only explicit top-level model overrides. Existing values remain
   // untouched and an install without either flag leaves both fields absent.
@@ -982,8 +1147,9 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // B.5.1 Hermetic plugin resolution (packaging fix)
   // --------------------------------------------------------------------
-  // The packaged opencode.json may reference plugins via developer-machine
-  // absolute paths (e.g. <dev>/pantheon/.../src/plugin.ts or
+  // A developer running from a checkout has a repository-root opencode.json
+  // that may reference plugins via developer-machine absolute paths (e.g.
+  // <dev>/pantheon/.../src/plugin.ts or
   // <dev>/pantheon/.../src/plugins/pantheon-hooks.ts). Copying those
   // verbatim into the user's config would break every global install on any
   // other machine. resolveInstalledPlugin() rewrites each entry to the plugin
@@ -1002,7 +1168,7 @@ export async function installOpenCode(
     if (config.plugin === undefined) config.plugin = []
     if (Array.isArray(config.plugin)) {
       config.plugin = removePantheonPluginReferences(config.plugin)
-      if (Array.isArray(pantheonConfig.plugin)) {
+      if (Array.isArray(pantheonConfig?.plugin)) {
         for (const plugin of pantheonConfig.plugin) {
           if (!isPantheonPluginReference(plugin) && !hasPluginReference(config.plugin, plugin)) {
             config.plugin.push(deepClone(plugin))
@@ -1032,7 +1198,7 @@ export async function installOpenCode(
     }
     if (!Array.isArray(config.plugins)) config.plugins = []
     config.plugins = deduplicatePluginReferences(removePantheonPluginReferences(config.plugins))
-    if (Array.isArray(pantheonConfig.plugins)) {
+    if (Array.isArray(pantheonConfig?.plugins)) {
       for (const plugin of pantheonConfig.plugins) {
         if (!isPantheonPluginReference(plugin) && !hasPluginReference(config.plugins, plugin)) {
           config.plugins.push(deepClone(plugin))
@@ -1058,33 +1224,68 @@ export async function installOpenCode(
     config.plugins.push(resolvedV2)
   }
 
-  if (config.provider === undefined && pantheonConfig.provider !== undefined) {
-    config.provider = deepClone(pantheonConfig.provider)
-  } else if (config.provider !== undefined && pantheonConfig.provider !== undefined) {
-    mergeMissing(config.provider, pantheonConfig.provider)
-  }
+  if (pantheonConfig !== null) {
+    if (config.provider === undefined && pantheonConfig.provider !== undefined) {
+      config.provider = deepClone(pantheonConfig.provider)
+    } else if (config.provider !== undefined && pantheonConfig.provider !== undefined) {
+      mergeMissing(config.provider, pantheonConfig.provider)
+    }
 
-  if (config.compaction === undefined && pantheonConfig.compaction !== undefined) {
-    config.compaction = deepClone(pantheonConfig.compaction)
-  } else if (config.compaction !== undefined && pantheonConfig.compaction !== undefined) {
-    mergeMissing(config.compaction, pantheonConfig.compaction)
+    if (config.compaction === undefined && pantheonConfig.compaction !== undefined) {
+      config.compaction = deepClone(pantheonConfig.compaction)
+    } else if (config.compaction !== undefined && pantheonConfig.compaction !== undefined) {
+      mergeMissing(config.compaction, pantheonConfig.compaction)
+    }
   }
 
   // --------------------------------------------------------------------
   // C. Merge permissions
   // --------------------------------------------------------------------
   if (config.permission === undefined) config.permission = {}
-  if (pantheonConfig.permission !== undefined) {
-    mergeMissing(config.permission, pantheonConfig.permission)
-  }
   if (
     typeof config.permission === 'object' &&
     config.permission !== null &&
     !Array.isArray(config.permission)
   ) {
-    if (componentSet.has('skills')) {
+    // Fill-if-absent, never overwrite. Pantheon's skills cannot be invoked
+    // without this grant, so an install that just installed them seeds it —
+    // but a user who deliberately set `permission.skill` (to `deny`, or to a
+    // partial map of their own) keeps their choice. This was an unconditional
+    // assignment nine lines below a comment that said "never overwrite", which
+    // silently flipped an explicit deny to allow.
+    //
+    // Gated on the skills component AND absent-only, which is the whole point:
+    // `skill` is a capability grant for something this install just wrote to
+    // disk. A runtime-only or agents-only install has nothing to grant, so it
+    // must not seed the key. It used to anyway, via the unconditional
+    // PRODUCT_CONFIG_DEFAULTS.permission merge that sat above this block —
+    // which also made this gate dead code.
+    if (componentSet.has('skills') && config.permission.skill === undefined) {
       config.permission.skill = { '*': 'allow' }
     }
+    // These five are the commands Pantheon's OWN agents must be able to run
+    // unattended to do their job: version control, package execution, and the
+    // test/lint pair every implementation agent reaches for. That is the whole
+    // bar for a grant made on every install.
+    //
+    // Anything beyond it is the installing user's judgement about which
+    // commands to trust on their machine, to be made in THEIR config — not ours
+    // to grant silently on their behalf. The personal dev allowlist this grew
+    // out of was the same category of decision, one layer further out of view.
+    //
+    // Specifically NOT granted, and why:
+    //   - `curl` — arbitrary network egress; the widest grant on the list and
+    //     not required to install or run anything here.
+    //   - `docker` — host/daemon access; a container runtime is not an
+    //     installation requirement.
+    //   - `gh` — third-party account access on someone's behalf; a GitHub CLI
+    //     login is never something an installer may assume.
+    //   - `pip`, `black`, `make` — ordinary toolchain commands with no Pantheon
+    //     agent dependency; users who want them can add them.
+    //
+    // NOTE: this grant is NOT gated on the skills component — unlike
+    // permission.skill above, agents are installed by the agents component and
+    // the test/lint commands are needed whichever components were selected.
     if (config.permission.bash === undefined) {
       config.permission.bash = {
         'git *': 'allow',
@@ -1092,12 +1293,6 @@ export async function installOpenCode(
         'npx *': 'allow',
         'pytest *': 'allow',
         'ruff *': 'allow',
-        'black *': 'allow',
-        'pip *': 'allow',
-        'docker *': 'allow',
-        'curl *': 'allow',
-        'gh *': 'allow',
-        'make *': 'allow',
       }
     }
   }
@@ -1154,82 +1349,18 @@ export async function installOpenCode(
   // at a venv that does not exist would make every MCP fail to launch.
   // --------------------------------------------------------------------
   if (componentSet.has('runtime') && runtimeHealthy) {
-    config.mcp = config.mcp || {}
-    // MCP stays a flat named-server map for BOTH V1 and V2: OpenCode 1.18.x
-    // has no `mcp.servers` wrapper and rejects one with
-    // "Missing key mcp.servers.enabled". config-migration.mjs normalizes any
-    // legacy wrapper-shaped entries back to the flat map.
-    // P1-3: derive the MCP python from the SAME venv layout setupVenv
-    // creates (<target>/.venv via venvPythonPath). For project installs the
-    // runtime payload lives under <target>/.opencode (runtimeTarget), but the
-    // venv is created at <target>/.venv — pointing MCP commands at
+    // P1-3: derive the MCP python from the SAME venv layout setupVenv creates
+    // (<target>/.venv via venvPythonPath). For project installs the runtime
+    // payload lives under <target>/.opencode (runtimeTarget), but the venv is
+    // created at <target>/.venv — pointing MCP commands at
     // runtimeTarget/.venv would reference an executable that never exists.
-    const runtimeTarget = isGlobal ? target : join(target, '.opencode')
-    const venvPython = venvPythonPath(target)
     // Point the config at the venv even on a first install; setupVenv runs
     // later in this function and creates this path before OpenCode starts.
-    const memoryPython = venvPython
-
-    // Only add if not already configured by user
-    if (!config.mcp['pantheon-resources']) {
-      config.mcp['pantheon-resources'] = {
-        type: 'local',
-        cwd: runtimeTarget,
-        command: [memoryPython, 'scripts/mcp_resources_server.py'],
-        enabled: true,
-      }
-    }
-    if (!config.mcp['pantheon-code-mode']) {
-      config.mcp['pantheon-code-mode'] = {
-        type: 'local',
-        cwd: runtimeTarget,
-        command: [memoryPython, 'scripts/code_mode_server.py'],
-        enabled: true,
-      }
-    }
-    if (!config.mcp['pantheon-memory']) {
-      config.mcp['pantheon-memory'] = {
-        type: 'local',
-        cwd: runtimeTarget,
-        command: [memoryPython, 'scripts/memory_mcp_server.py'],
-        enabled: true,
-      }
-    }
-    if (!config.mcp['pantheon-persistence']) {
-      config.mcp['pantheon-persistence'] = {
-        type: 'local',
-        cwd: runtimeTarget,
-        command: [memoryPython, 'scripts/mcp_persistence_server.py'],
-        enabled: true,
-      }
-    }
-    if (!config.mcp['pantheon-vision']) {
-      config.mcp['pantheon-vision'] = {
-        type: 'local',
-        cwd: runtimeTarget,
-        command: [memoryPython, 'scripts/pantheon_vision_server.py'],
-        enabled: true,
-      }
-    }
-
-    // Default MCP permissions
-    config.permission = config.permission || {}
-    config.permission.mcp = config.permission.mcp || {}
-    if (!config.permission.mcp['pantheon-resources']) {
-      config.permission.mcp['pantheon-resources'] = 'allow'
-    }
-    if (!config.permission.mcp['pantheon-code-mode']) {
-      config.permission.mcp['pantheon-code-mode'] = 'ask'
-    }
-    if (!config.permission.mcp['pantheon-memory']) {
-      config.permission.mcp['pantheon-memory'] = 'allow'
-    }
-    if (!config.permission.mcp['pantheon-persistence']) {
-      config.permission.mcp['pantheon-persistence'] = 'allow'
-    }
-    if (!config.permission.mcp['pantheon-vision']) {
-      config.permission.mcp['pantheon-vision'] = 'ask'
-    }
+    const runtimeTarget = isGlobal ? target : join(target, '.opencode')
+    applyMcpServerEntries(config, {
+      runtimeTarget,
+      venvPython: venvPythonPath(target),
+    })
   }
 
   // ── V2 native migration ──

package/scripts/install-mcp.mjs

@@ -24,6 +24,7 @@ import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
+import { migrateMcpEntrypointPaths } from './install/config-migration.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..')
@@ -70,11 +71,11 @@ function resolveServerScript(relPath) {
 }
 
 const VENV_PYTHON = resolveVenvPython()
-const MCP_RESOURCES_SERVER = resolveServerScript('scripts/mcp_resources_server.py')
-const CODE_MODE_SERVER = resolveServerScript('scripts/code_mode_server.py')
-const MEMORY_MCP_SERVER = resolveServerScript('scripts/memory_mcp_server.py')
-const MCP_PERSISTENCE_SERVER = resolveServerScript('scripts/mcp_persistence_server.py')
-const PANTHEON_VISION_SERVER = resolveServerScript('src/mcp/pantheon_vision_server.py')
+const MCP_RESOURCES_SERVER = resolveServerScript('scripts/mcp_resources.py')
+const CODE_MODE_SERVER = resolveServerScript('scripts/code_mode.py')
+const MEMORY_MCP_SERVER = resolveServerScript('scripts/memory_mcp.py')
+const MCP_PERSISTENCE_SERVER = resolveServerScript('scripts/mcp_persistence.py')
+const PANTHEON_VISION_SERVER = resolveServerScript('src/mcp/pantheon_vision.py')
 
 // ---------------------------------------------------------------------------
 // MCP Definitions
@@ -209,7 +210,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'mcp_resources_server.py not found at resolved path' }
+      return { ok: false, message: 'mcp_resources.py not found at resolved path' }
     },
   },
   'pantheon-code-mode': {
@@ -230,7 +231,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'code_mode_server.py not found at resolved path' }
+      return { ok: false, message: 'code_mode.py not found at resolved path' }
     },
   },
   'pantheon-memory': {
@@ -251,7 +252,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'memory_mcp_server.py not found at resolved path' }
+      return { ok: false, message: 'memory_mcp.py not found at resolved path' }
     },
   },
   'pantheon-persistence': {
@@ -272,7 +273,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'mcp_persistence_server.py not found at resolved path' }
+      return { ok: false, message: 'mcp_persistence.py not found at resolved path' }
     },
   },
   'pantheon-vision': {
@@ -471,8 +472,22 @@ function writeMcpConfig(platformName, mcpKey, dryRun, force) {
     config[key] = {}
   }
 
+  // Heal pre-rename MCP entrypoint paths before the skip check, so re-running
+  // the installer repairs an existing config whose `*_server.py` paths were
+  // orphaned by the entrypoint rename. Without this the rename is a silent
+  // break for every already-installed config (see config-migration.mjs).
+  const healed = migrateMcpEntrypointPaths(config[key])
+
   // Check if the MCP already has an entry
   if (config[key][mcpKey] && !force) {
+    if (healed > 0 && !dryRun) {
+      writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+      return {
+        status: 'healed',
+        path: configPath,
+        reason: `Updated ${healed} stale MCP entrypoint path(s) in ${platform.configFile}`,
+      }
+    }
     return {
       status: 'skipped',
       reason: `Already exists in ${platform.configFile} (use --force to overwrite)`,
@@ -705,6 +720,10 @@ function logResult(platformLabel, mcpKey, result) {
       console.log(`  ⏭️  ${label} — ${result.reason}`)
       progress.skipped.push({ platform: platformLabel, mcp: mcpKey, reason: result.reason })
       break
+    case 'healed':
+      console.log(`  🩹 ${label} — ${result.reason}`)
+      progress.installed.push({ platform: platformLabel, mcp: mcpKey })
+      break
     case 'dry-run': {
       const desc =
         result.entry?.type === 'remote' || result.entry?.type === 'http'

package/scripts/{mcp_persistence_server.py → mcp_persistence.py}

@@ -5,7 +5,7 @@ Key-Value store with FTS5 full-text search, TTL-based expiration,
 and namespace isolation. Uses SQLite with zero external dependencies.
 
 Usage:
-    python scripts/mcp_persistence_server.py
+    python scripts/mcp_persistence.py
 """
 
 from __future__ import annotations

package/{src/mcp/mcp_resources_server.py → scripts/mcp_resources.py}

@@ -7,7 +7,7 @@ Provides MCP resources for the Pantheon agent framework:
   plans/status, memory-bank files
 
 Usage:
-    python scripts/mcp_resources_server.py
+    python scripts/mcp_resources.py
 """
 
 from __future__ import annotations

package/scripts/{memory_mcp_server.py → memory_mcp.py}

@@ -19,7 +19,7 @@ Tools:
     memory_stats   — DB statistics
 
 Usage:
-    python scripts/memory_mcp_server.py
+    python scripts/memory_mcp.py
 """
 
 from __future__ import annotations

package/scripts/probe-context-rehydrate.mjs

@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url'
 
 const requestedVersion = valueFor('--version')
 const jsonOutput = process.argv.includes('--json')
-const runtime = fileURLToPath(new URL('./mcp_persistence_server.py', import.meta.url))
+const runtime = fileURLToPath(new URL('./mcp_persistence.py', import.meta.url))
 
 function valueFor(name) {
   const index = process.argv.indexOf(name)
@@ -192,7 +192,7 @@ async function main() {
     return
   }
   if (!existsSync(runtime)) {
-    unavailable('installed package does not include mcp_persistence_server.py')
+    unavailable('installed package does not include mcp_persistence.py')
     return
   }