pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/scripts/install/opencode.mjs

@@ -2,20 +2,20 @@
 /**
  * opencode.mjs — OpenCode platform installer
  *
- * 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
- * fields in memory — do NOT convert to native V2 format. Known V2 beta gaps
- * handled here: top-level `subagent_depth` is silently ignored (migrated to
- * `experimental.subagent_depth`), and the `instructions` config key is
- * accepted-but-not-loaded (content 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.
+ * 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
+ * load. Pass --version v2 to pantheon-init for an informational label; state
+ * isolation is handled at runtime via OPENCODE_DB.
  */
 
+import { createHash } from 'node:crypto'
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { basename, join, resolve } from 'node:path'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import {
   bullet,
   colors,
@@ -29,10 +29,13 @@ import {
   success,
   warning,
 } from './cli-ui.mjs'
+import { migrateV1toV2 } from './config-migration.mjs'
 import { healthCheck } from './health-check.mjs'
 import { detectVersion, runMigrations } from './migrate.mjs'
+import { resolveOpenCodeVersion } from './opencode-version.mjs'
 import { copyPluginFiles, installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
 import {
+  checkRuntimePrerequisites,
   collectSkillNames,
   copyFiles,
   installSkills,
@@ -41,8 +44,10 @@ import {
   sourceDirValid,
   summary,
   syncDir,
+  writeConfigWithBackup,
   writeIfChanged,
 } from './shared.mjs'
+import { strings } from './strings.mjs'
 
 import { setupVenv, venvPythonPath } from './venv.mjs'
 
@@ -60,6 +65,34 @@ function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * (Re)generate the code-mode manifest with SHA-256 digests for every bundled
+ * script. This is the explicit installation opt-in: the MCP server only
+ * executes scripts listed here whose on-disk hash matches. Missing or empty
+ * directories approve nothing (0) — execution is never implicit.
+ */
+function writeCodeModeManifest(dir, dryRun) {
+  if (!existsSync(dir)) return 0
+  let names
+  try {
+    names = readdirSync(dir)
+      .filter((name) => /\.(sh|py)$/i.test(name) && !name.startsWith('.'))
+      .sort()
+  } catch {
+    return 0
+  }
+  if (names.length === 0) return 0
+  const scripts = {}
+  for (const name of names) {
+    scripts[name] = createHash('sha256')
+      .update(readFileSync(join(dir, name)))
+      .digest('hex')
+  }
+  const payload = `${JSON.stringify({ version: 1, scripts }, null, 2)}\n`
+  writeIfChanged(join(dir, 'manifest.json'), payload, dryRun)
+  return names.length
+}
+
 function readJsonConfig(filePath) {
   if (!existsSync(filePath)) return {}
 
@@ -101,24 +134,149 @@ function mergeMissing(target, source) {
  * Resolve a plugin ref from the packaged opencode.json to a path INSIDE the
  * installed package.
  *
- * The packaged config may reference plugins via developer-machine absolute
- * paths (e.g. <dev>/pantheon/.../src/plugin.ts). Copying those verbatim into
- * the user's config would break every install on any other machine. This
- * rewrites the entry to the plugin file inside the INSTALLED package (derived
- * from ROOT — never hardcoded), so both dev and global installs resolve to a
- * path that actually exists.
+ * Only exact Pantheon plugin identities are resolved into the installed
+ * package. In particular, a third-party absolute path ending in
+ * `src/plugin.ts` or `src/plugins/pantheon-hooks.ts` is not evidence that the
+ * plugin belongs to Pantheon and must be preserved verbatim.
  */
 export function resolveInstalledPlugin(plugin) {
-  // Map any ref whose path tail starts with `src/` to the matching file INSIDE
-  // the installed package. This preserves the ref's relative location, so both
-  // src/plugins/* (hooks) and the root-level src/plugin.ts (delegation plugin,
-  // PR #45) resolve correctly — nothing is forced into src/plugins/.
-  const srcIndex = plugin.indexOf('src/')
-  if (srcIndex === -1) return plugin
-  const packaged = join(ROOT, plugin.slice(srcIndex))
-  return existsSync(packaged) ? packaged : plugin
+  if (typeof plugin !== 'string') return plugin
+  const normalized = normalizePluginRef(plugin)
+  if (PANTHEON_PLUGIN_IDENTITIES.has(normalized)) return join(ROOT, normalized)
+  // Legacy V2 file ref (pre-directory-contract): migrate to the installed
+  // plugin directory so the beta loader accepts the entry.
+  if (normalized === PANTHEON_V2_LEGACY_FILE) return join(ROOT, PANTHEON_V2_PLUGIN)
+  const identity = managedPluginIdentity(plugin)
+  if (identity !== null && isAbsolute(normalized)) {
+    return INSTALLED_PANTHEON_PLUGIN_PATHS.get(identity) ?? plugin
+  }
+  return plugin
+}
+
+function normalizePluginRef(ref) {
+  return typeof ref === 'string' ? ref.replaceAll('\\', '/').replace(/\/$/, '') : ref
+}
+
+const PANTHEON_V1_PLUGIN = 'src/plugin.ts'
+const PANTHEON_V1_HOOKS = 'src/plugins/pantheon-hooks.ts'
+// Canonical V2 entry is the plugin DIRECTORY (beta loader contract: entries
+// must be dirs with a real index.ts — file paths warn "must be a directory",
+// symlinks are ignored). The shim at src/plugin-v2/index.ts re-exports the
+// real entry src/plugin-v2.ts (single source of truth).
+const PANTHEON_V2_PLUGIN = 'src/plugin-v2'
+// Legacy V2 file ref from before the directory contract (installer + template
+// used to register src/plugin-v2.ts). Still recognized for migration.
+const PANTHEON_V2_LEGACY_FILE = 'src/plugin-v2.ts'
+const PANTHEON_V1_EXPORT = 'pantheon-opencode/plugin'
+const PANTHEON_V2_EXPORT = 'pantheon-opencode/plugin-v2'
+const PANTHEON_PLUGIN_IDENTITIES = new Set([
+  PANTHEON_V1_PLUGIN,
+  PANTHEON_V1_HOOKS,
+  PANTHEON_V2_PLUGIN,
+])
+
+const INSTALLED_PANTHEON_PLUGIN_PATHS = new Map([
+  [PANTHEON_V1_PLUGIN, resolve(ROOT, PANTHEON_V1_PLUGIN)],
+  [PANTHEON_V1_HOOKS, resolve(ROOT, PANTHEON_V1_HOOKS)],
+  [PANTHEON_V2_PLUGIN, resolve(ROOT, PANTHEON_V2_PLUGIN)],
+])
+
+function normalizePluginPath(ref) {
+  return ref.replaceAll('\\', '/')
+}
+
+function pluginMetadataReferences(ref) {
+  if (typeof ref === 'string') return [ref]
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref)) return []
+  return ['package', 'id', 'name', 'path', 'source']
+    .filter((key) => typeof ref[key] === 'string')
+    .map((key) => ref[key])
+}
+
+function managedPluginIdentity(ref) {
+  const normalized = normalizePluginRef(ref)
+  if (typeof normalized !== 'string') return null
+
+  if (PANTHEON_PLUGIN_IDENTITIES.has(normalized)) return normalized
+  if (normalized === PANTHEON_V2_LEGACY_FILE) return PANTHEON_V2_PLUGIN
+  if (normalized === PANTHEON_V1_EXPORT || normalized.startsWith(`${PANTHEON_V1_EXPORT}@`)) {
+    return PANTHEON_V1_PLUGIN
+  }
+  if (normalized === PANTHEON_V2_EXPORT || normalized.startsWith(`${PANTHEON_V2_EXPORT}@`)) {
+    return PANTHEON_V2_PLUGIN
+  }
+
+  if (isAbsolute(normalized)) {
+    const absolutePath = normalizePluginPath(resolve(normalized))
+    for (const [identity, installedPath] of INSTALLED_PANTHEON_PLUGIN_PATHS) {
+      if (absolutePath === normalizePluginPath(installedPath)) return identity
+    }
+    // Legacy absolute V2 file path inside OUR installed package (pre-
+    // directory-contract installs) migrates to the directory identity.
+    // ROOT-scoped: third-party paths ending in src/plugin-v2.ts stay theirs.
+    if (absolutePath === normalizePluginPath(resolve(ROOT, PANTHEON_V2_LEGACY_FILE))) {
+      return PANTHEON_V2_PLUGIN
+    }
+    // beta.5: stale refs from OTHER installed copies of this package (older
+    // nvm prefixes, npx cache hashes). Only paths inside
+    // `node_modules/pantheon-opencode/` count as installed copies — a dev
+    // checkout elsewhere (e.g. a vendor folder named pantheon-opencode) remains
+    // protected by the third-party rule above.
+    const installedMarker = '/node_modules/pantheon-opencode/'
+    const withSlashes = normalizePluginPath(normalized)
+    const markerIndex = withSlashes.lastIndexOf(installedMarker)
+    if (markerIndex !== -1) {
+      const suffix = withSlashes.slice(markerIndex + installedMarker.length)
+      if (suffix === PANTHEON_V1_PLUGIN) return PANTHEON_V1_PLUGIN
+      if (suffix === PANTHEON_V1_HOOKS) return PANTHEON_V1_HOOKS
+      if (suffix === PANTHEON_V2_PLUGIN) return PANTHEON_V2_PLUGIN
+      if (suffix === PANTHEON_V2_LEGACY_FILE) return PANTHEON_V2_PLUGIN
+    }
+  }
+
+  return null
+}
+
+/**
+ * Return the stable identity for a Pantheon plugin, or its normalized path.
+ * Basenames are deliberately not used: unrelated user plugins may share a
+ * filename such as `plugin.ts`.
+ */
+export function pluginReferenceIdentity(ref) {
+  const references = pluginMetadataReferences(ref)
+  for (const reference of references) {
+    const identity = managedPluginIdentity(reference)
+    if (identity !== null) return identity
+  }
+  if (references.length > 0) return normalizePluginPath(normalizePluginRef(references[0]))
+  return ref
+}
+
+function isPantheonPluginReference(ref) {
+  return PANTHEON_PLUGIN_IDENTITIES.has(pluginReferenceIdentity(ref))
+}
+
+function removePantheonPluginReferences(refs) {
+  return (Array.isArray(refs) ? refs : []).filter((ref) => !isPantheonPluginReference(ref))
+}
+
+function hasPluginReference(refs, candidate) {
+  const identity = pluginReferenceIdentity(candidate)
+  return refs.some((ref) => pluginReferenceIdentity(ref) === identity)
 }
 
+export function deduplicatePluginReferences(refs) {
+  const seen = new Set()
+  return (Array.isArray(refs) ? refs : []).filter((ref) => {
+    const identity = pluginReferenceIdentity(ref)
+    if (seen.has(identity)) return false
+    seen.add(identity)
+    return true
+  })
+}
+
+export { parseOpenCodeVersion, resolveOpenCodeVersion } from './opencode-version.mjs'
+
 /**
  * Detect whether `target` is the user's global OpenCode installation directory
  * (~/.opencode or $XDG_CONFIG_HOME/opencode).
@@ -217,16 +375,60 @@ export function syncTuiRegistration(target, { isGlobal = false, dryRun = false }
 
   // 2. Clean stale Pantheon TUI refs from every location OpenCode reads.
   //    unregisterPlugin covers the bare relative id plus the extended stale
-  //    patterns (dist files, in-package src/plugins/tui dir, bare
-  //    plugins/pantheon-tui copies, npx paths).
+  //    patterns (dist files, identifiable in-package paths, owned copied
+  //    directories, relative ids, and npx package identities).
   for (const tuiConfigPath of tuiConfigLocations(target)) {
-    unregisterPlugin(tuiConfigPath, 'plugins/pantheon-tui', { dryRun })
+    const configDirForPath = dirname(tuiConfigPath)
+    const ownedCopy = resolveTuiCopyTarget(configDirForPath)
+    unregisterPlugin(tuiConfigPath, 'plugins/pantheon-tui', {
+      dryRun,
+      knownPantheonPaths: [ownedCopy, tuiCopyDir],
+    })
   }
 
   // 3. Register the copied directory in the selected target only.
   return registerPlugin(targetTuiConfigPath, tuiCopyDir, { dryRun })
 }
 
+/**
+ * beta.5: set up the Python venv + run the health check. Never throws —
+ * failures are reported as warnings and return false so the caller omits
+ * MCP entries from the config (entries pointing at a missing venv would
+ * make every MCP fail to launch). `deps` is injectable for tests.
+ */
+export function setupRuntimePhase(target, { dryRun, clean, isGlobal }, stats, deps = {}) {
+  const S = strings()
+  const setup = deps.setupVenv ?? setupVenv
+  const check = deps.healthCheck ?? healthCheck
+  try {
+    const venvSpinner = spinner(S.settingUpRuntime)
+    setup(target, { dryRun, force: clean })
+    venvSpinner(true)
+    const runtimeTarget = isGlobal ? target : join(target, '.opencode')
+    const health = check(runtimeTarget, { dryRun, pythonTarget: target })
+
+    section(`\uD83D\uDD0D ${S.healthSection}`)
+    const healthStep = step(S.runningHealthChecks)
+    for (const p of health.passed) success(`${p.check}: ${p.detail}`)
+    for (const w of health.warnings) warning(`${w.check}: ${w.detail}`)
+    for (const f of health.failed) error(`${f.check}: ${f.detail}`)
+
+    if (health.failed.length > 0) {
+      healthStep(false)
+      warning(`${health.failed.length} check(s) failed — review above`)
+      stats.warnings += health.failed.length
+      return false
+    }
+    healthStep(true)
+    return true
+  } catch (err) {
+    error(S.runtimeFailed(err.message))
+    warning(S.runtimeSkippedMcp)
+    stats.warnings += 1
+    return false
+  }
+}
+
 export async function installOpenCode(
   target,
   dryRun = false,
@@ -241,14 +443,14 @@ export async function installOpenCode(
 
   const componentSet = new Set(components)
   const stats = summary.opencode
-
-  // V1/V2 dual-version awareness (Phase 3): the SAME config works under both
-  // OpenCode V1 (`opencode`) and V2 (`opencode2`, beta v0.0.0-next-17444).
-  // 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). The installer writes one shared
-  // config; the --version flag only labels the install for the operator.
-  const version = opts.version === 'v2' ? 'v2' : 'v1'
+  const S = strings()
+
+  // V1/V2 dual-version awareness (Phase 3): the installer builds a unified
+  // config, then applies V2-native migration (migrateV1toV2) when
+  // --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')
   if (version === 'v2') {
     info(
       'OpenCode V2 target — shared config; state isolated via OPENCODE_DB ' +
@@ -290,6 +492,17 @@ export async function installOpenCode(
   const config = readJsonConfig(targetConfigPath)
   const pantheonConfig = readJsonConfig(pantheonConfigPath)
 
+  // beta.5 preflight: fail BEFORE any files are written when the runtime
+  // component needs toolchain pieces that are missing. Nothing has been
+  // copied yet at this point, so the failure is clean.
+  if (componentSet.has('runtime') && !dryRun) {
+    const missing = checkRuntimePrerequisites()
+    if (missing.length > 0) {
+      for (const problem of missing) error(problem)
+      throw new Error(S.prereqMissing)
+    }
+  }
+
   // Determine layout based on install scope.
   // Global config dir (~/.opencode or ~/.config/opencode) uses a flat layout:
   //   agents/   skills/   commands/   plugins/
@@ -302,7 +515,7 @@ export async function installOpenCode(
   configure({ dryRun })
 
   if (isGlobal) {
-    info('Global config directory detected — using flat layout (agents/, skills/, commands/)')
+    info(S.globalLayout)
   }
 
   // -----------------------------------------------------------------------
@@ -315,7 +528,7 @@ export async function installOpenCode(
       warning(`Agent source directory not found: ${srcDir}`)
       stats.errors++
     } else {
-      const agentStep = step('Installing agents')
+      const agentStep = step(S.installingAgents)
       const dstDir = isGlobal ? join(target, 'agents') : join(target, '.opencode', 'agents')
       if (!dryRun) mkdirSync(dstDir, { recursive: true })
       if (clean && existsSync(dstDir) && !dryRun) {
@@ -445,11 +658,20 @@ export async function installOpenCode(
   }
 
   // -----------------------------------------------------------------------
-  // 2.9 Create/update tui.json with plugin registration
+  // 2.9 Create/update tui.json with plugin registration (--components plugins)
   // -----------------------------------------------------------------------
-  const tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun })
-  if (tuiStatus === 'created') stats.created++
-  else stats.skipped++
+  if (componentSet.has('plugins')) {
+    let tuiStatus
+    try {
+      tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun })
+    } catch (cause) {
+      error(`TUI plugin setup failed: ${cause.message}`)
+      stats.errors++
+      throw new Error('TUI plugin setup failed; installation was not completed', { cause })
+    }
+    if (tuiStatus === 'created') stats.created++
+    else stats.skipped++
+  }
 
   // -----------------------------------------------------------------------
   // 2.10 Install runtime infrastructure (--components runtime)
@@ -531,6 +753,21 @@ export async function installOpenCode(
       const cmResult = syncDir(srcCodeModeDir, dstCodeModeDir, dryRun, clean)
       stats.created += cmResult.created
       stats.skipped += cmResult.skipped
+    } else {
+      // The code-mode payload ships inside the published tarball
+      // (package.json `files` includes .pantheon/code-mode/**). When it is
+      // absent, still create the runtime dir so the code-mode MCP server has
+      // a stable home, and warn loudly instead of silently skipping.
+      warning(`Code-mode source not found: ${srcCodeModeDir} — creating empty ${dstCodeModeDir}`)
+      if (!dryRun) mkdirSync(dstCodeModeDir, { recursive: true })
+      stats.created++
+    }
+
+    // B3-08: explicit installation mode — seed the manifest with SHA-256
+    // digests so the server never executes a script implicitly.
+    const approvedScripts = writeCodeModeManifest(dstCodeModeDir, dryRun)
+    if (approvedScripts > 0) {
+      info(`Code-mode manifest: ${approvedScripts} script(s) approved`)
     }
 
     // ── tiers.json ──
@@ -544,10 +781,21 @@ export async function installOpenCode(
     }
   }
 
+  // -----------------------------------------------------------------------
+  // 2.11 Setup virtual environment + health check (--components runtime)
+  // beta.5: runs BEFORE the config write and is no longer fatal — on failure
+  // the install completes without MCP entries (which would point at a venv
+  // that does not exist) instead of aborting a half-done installation.
+  // -----------------------------------------------------------------------
+  let runtimeHealthy = !componentSet.has('runtime')
+  if (componentSet.has('runtime')) {
+    runtimeHealthy = setupRuntimePhase(target, { dryRun, clean, isGlobal }, stats)
+  }
+
   // -----------------------------------------------------------------------
   // 3. Create/update opencode.json (always runs)
   //    Reads TARGET's existing config first, then merges Pantheon settings
-  //    on top. Preserves user's MCP, provider, plugin, compaction, theme.
+  //    on top. Preserves user's MCP, provider, plugins, compaction, theme.
   // -----------------------------------------------------------------------
   // --------------------------------------------------------------------
   // A. Parse canonical agent config from agents/*.agent.md frontmatter
@@ -635,9 +883,8 @@ export async function installOpenCode(
             existing[field] = JSON.parse(JSON.stringify(agentCfg[field]))
           }
         }
-        // Remove stale fields that are no longer in canonical config
-        delete existing.model
-        delete existing.small_model
+        // Existing agent fields belong to the user; never remove them during
+        // an install. Canonical values are merged only when absent.
       } else {
         // ── New agent ──
         const newAgent = {}
@@ -663,17 +910,7 @@ export async function installOpenCode(
       }
     }
 
-    // Remove stale agents (exist in target config but not in canonical source)
-    // Only removes agents whose source is managed (starts with our prefix)
-    // so user-defined agents with different source paths are preserved.
-    const canonicalNames = new Set(Object.keys(canonicalAgentConfig))
-    for (const [agentName, agentCfg] of Object.entries(config.agent)) {
-      const source = agentCfg?.source || ''
-      if (source.startsWith(agentPrefix) && !canonicalNames.has(agentName)) {
-        delete config.agent[agentName]
-      }
-    }
-    if (Object.keys(config.agent).length === 0) delete config.agent
+    // Do not remove stale or user-defined agents. Installation is additive.
   }
 
   // --------------------------------------------------------------------
@@ -738,39 +975,70 @@ export async function installOpenCode(
   // The source opencode.json keeps its dev path for local development; the
   // transform happens at install/sync time only.
 
-  if (config.plugin === undefined) {
-    config.plugin = []
-  }
-  if (Array.isArray(config.plugin)) {
-    if (Array.isArray(pantheonConfig.plugin)) {
-      for (const plugin of pantheonConfig.plugin) {
-        const resolved = resolveInstalledPlugin(plugin)
-        const file = basename(resolved)
-        // Replace any pre-existing entry for the same plugin file (e.g. a stale
-        // dev-machine path from an earlier install) so upgrades stay hermetic.
-        config.plugin = config.plugin.filter((p) => basename(p) !== file)
+  if (version === 'v1') {
+    // V1 loads the singular `plugin` list. Remove every Pantheon V2 entry from
+    // both config shapes before restoring the two V1 plugins. User plugins in
+    // either list are retained verbatim.
+    if (Array.isArray(config.plugins)) {
+      config.plugins = removePantheonPluginReferences(config.plugins)
+    }
+    if (config.plugin === undefined) config.plugin = []
+    if (Array.isArray(config.plugin)) {
+      config.plugin = removePantheonPluginReferences(config.plugin)
+      if (Array.isArray(pantheonConfig.plugin)) {
+        for (const plugin of pantheonConfig.plugin) {
+          if (!isPantheonPluginReference(plugin) && !hasPluginReference(config.plugin, plugin)) {
+            config.plugin.push(deepClone(plugin))
+          }
+        }
+      }
+
+      const ensurePantheonPlugin = (ref) => {
+        const resolved = resolveInstalledPlugin(ref)
+        config.plugin = config.plugin.filter(
+          (plugin) => pluginReferenceIdentity(plugin) !== pluginReferenceIdentity(resolved),
+        )
         config.plugin.push(resolved)
       }
+      // Root-level delegation plugin remains a V1-only registration.
+      ensurePantheonPlugin('src/plugin.ts')
+      ensurePantheonPlugin('src/plugins/pantheon-hooks.ts')
     }
+  }
 
-    // The two Pantheon plugins MUST always be registered, on fresh installs AND
-    // upgrades. The packaged opencode.json carries no `plugin` key (dev-machine
-    // paths removed in 3e552cc), so config.plugin would otherwise only contain
-    // whatever the user had — a fresh install would register NOTHING and lose
-    // delegation tools, GoalLoop, cost command, hashline and vision. Register
-    // both unconditionally, replacing any stale entry for the same file
-    // (basename-dedup) so installs and upgrades are idempotent and hermetic
-    // while preserving any user plugins.
-    const ensurePantheonPlugin = (ref) => {
-      const resolved = resolveInstalledPlugin(ref)
-      const file = basename(resolved)
-      config.plugin = config.plugin.filter((p) => basename(p) !== file)
-      config.plugin.push(resolved)
+  if (version === 'v2') {
+    // V2 loads the plural `plugins` list. Keep third-party V1 entries in the
+    // legacy list for users who still use them, but never leave a Pantheon V1
+    // entry configured alongside the V2 package export.
+    if (Array.isArray(config.plugin)) {
+      config.plugin = removePantheonPluginReferences(config.plugin)
+    }
+    if (!Array.isArray(config.plugins)) config.plugins = []
+    config.plugins = deduplicatePluginReferences(removePantheonPluginReferences(config.plugins))
+    if (Array.isArray(pantheonConfig.plugins)) {
+      for (const plugin of pantheonConfig.plugins) {
+        if (!isPantheonPluginReference(plugin) && !hasPluginReference(config.plugins, plugin)) {
+          config.plugins.push(deepClone(plugin))
+        }
+      }
     }
-    // Root-level delegation plugin (PR #45): tools, GoalLoop, cost, hashline.
-    ensurePantheonPlugin('src/plugin.ts')
-    // Runtime hooks plugin: chat hooks, hook-runner, TUI wiring.
-    ensurePantheonPlugin('src/plugins/pantheon-hooks.ts')
+    // The beta resolves every `plugins` entry through npm install, so an
+    // `a/b` shorthand (e.g. the published `pantheon-opencode/plugin-v2`
+    // export) is treated as a GitHub repo and dies with NpmInstallFailedError
+    // (beta log evidence). The beta loader additionally requires each entry
+    // to be a DIRECTORY with a real index.js/index.ts — a file path warns
+    // "must be a directory" and a symlink is ignored (sandbox probe
+    // evidence). Register the V2 plugin DIRECTORY inside the INSTALLED
+    // package — exactly like V1's ensurePantheonPlugin, but pointing at
+    // src/plugin-v2 whose index.ts shim re-exports the real entry.
+    // Legacy refs (npm shorthand, the old src/plugin-v2.ts file path) are
+    // recognized via managedPluginIdentity and already stripped above, so
+    // they migrate here.
+    const resolvedV2 = resolveInstalledPlugin(PANTHEON_V2_PLUGIN)
+    config.plugins = config.plugins.filter(
+      (plugin) => pluginReferenceIdentity(plugin) !== pluginReferenceIdentity(resolvedV2),
+    )
+    config.plugins.push(resolvedV2)
   }
 
   if (config.provider === undefined && pantheonConfig.provider !== undefined) {
@@ -854,19 +1122,26 @@ export async function installOpenCode(
   }
 
   // --------------------------------------------------------------------
-  // F. Compatibility cleanup (OpenCode >= v1.15.7)
+  // F. Compatibility cleanup (OpenCode V1 >= 1.15.7)
   // --------------------------------------------------------------------
-  // `todoContinuation` is rejected by newer OpenCode versions.
-  // Remove it from merged user config to avoid startup/config failures.
-  if (Object.hasOwn(config, 'todoContinuation')) {
+  // Recent V1 releases reject the legacy `todoContinuation` setting. Remove
+  // it from the merged V1 config, while leaving the V2-shaped configuration
+  // untouched.
+  if (version === 'v1' && Object.hasOwn(config, 'todoContinuation')) {
     delete config.todoContinuation
   }
 
   // --------------------------------------------------------------------
   // F.5 MCP server entries (for runtime-deployed scripts)
+  // beta.5: skipped when the Python runtime setup failed — entries pointing
+  // at a venv that does not exist would make every MCP fail to launch.
   // --------------------------------------------------------------------
-  if (componentSet.has('runtime')) {
+  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
@@ -940,8 +1215,17 @@ export async function installOpenCode(
     }
   }
 
-  const configContent = `${JSON.stringify(config, null, 2)}\n`
-  const status = writeIfChanged(targetConfigPath, configContent, dryRun)
+  // ── V2 native migration ──
+  // When targeting V2, convert the merged V1-shaped config to native V2 format
+  // before writing. V1 path is untouched (zero regression).
+  let configToWrite = config
+  if (version === 'v2') {
+    info(S.v2Migrating)
+    configToWrite = migrateV1toV2(config)
+  }
+
+  const configContent = `${JSON.stringify(configToWrite, null, 2)}\n`
+  const status = writeConfigWithBackup(targetConfigPath, configContent, dryRun)
   if (status === 'created') stats.created++
   else stats.skipped++
 
@@ -962,42 +1246,24 @@ export async function installOpenCode(
   }
 
   // -----------------------------------------------------------------------
-  // 4. Setup virtual environment + health check (--components runtime)
+  // 4. (runtime setup moved to 2.11 — before the config write — so MCP
+  //    entries are only added when the Python runtime is actually healthy)
   // -----------------------------------------------------------------------
-  if (componentSet.has('runtime')) {
-    try {
-      const venvSpinner = spinner('Setting up Python virtual environment')
-      setupVenv(target, { dryRun, force: clean })
-      venvSpinner(true)
-      const health = healthCheck(target, { dryRun })
-
-      // Print health summary
-      section('\uD83D\uDD0D Health Check')
-      const healthStep = step('Running health checks')
-      for (const p of health.passed) success(`${p.check}: ${p.detail}`)
-      for (const w of health.warnings) warning(`${w.check}: ${w.detail}`)
-      for (const f of health.failed) error(`${f.check}: ${f.detail}`)
-
-      if (health.failed.length > 0) {
-        healthStep(false)
-        warning(`${health.failed.length} check(s) failed — review above`)
-        stats.errors += health.failed.length
-      } else {
-        healthStep(true)
-      }
-    } catch (err) {
-      error(`Setup failed: ${err.message}`)
-      throw err // Fatal — abort installation
-    }
-  }
 
   if (interactive && !dryRun) {
     const created = stats.created
     const skipped = stats.skipped
     const errors = stats.errors
+    const warnings = stats.warnings ?? 0
 
     process.stdout.write('\n')
-    process.stdout.write(`  ${colors.bold(colors.green('Installation complete'))}\n`)
+    process.stdout.write(
+      `  ${colors.bold(
+        errors > 0
+          ? colors.yellow('Installation completed with errors')
+          : colors.green('Installation complete'),
+      )}\n`,
+    )
     process.stdout.write(
       `  ${colors.dim('\u2500'.repeat(Math.min(process.stdout.columns || 60, 60)))}\n`,
     )
@@ -1006,11 +1272,14 @@ export async function installOpenCode(
       process.stdout.write(`  ${colors.dim('\u2014')} ${skipped} already up-to-date\n`)
     if (errors > 0)
       process.stdout.write(`  ${colors.yellow('\u26a0')} ${errors} error(s) encountered\n`)
+    if (warnings > 0)
+      process.stdout.write(
+        `  ${colors.yellow('\u26a0')} ${warnings} warning(s) — run 'pantheon-opencode doctor' for details\n`,
+      )
     process.stdout.write('\n')
     process.stdout.write(`  ${colors.bold('Next steps:')}\n`)
     process.stdout.write(`  ${colors.dim('\u2022')} Configure agents in opencode.json\n`)
-    process.stdout.write(`  ${colors.dim('\u2022')} Add MCP servers in mcp.json\n`)
-    process.stdout.write(`  ${colors.dim('\u2022')} Run 'opencode doctor' to verify\n`)
+    process.stdout.write(`  ${colors.dim('\u2022')} Run 'pantheon-opencode doctor' to verify\n`)
     process.stdout.write(
       `  ${colors.dim('\u2022')} Run 'opencode' to start using Pantheon agents\n`,
     )
@@ -1034,4 +1303,10 @@ export async function installOpenCode(
     const { writeActivePreset } = await import('./model-picker.mjs')
     writeActivePreset(target, opts.preset, { source: 'cli' })
   }
+
+  // Fail-closed: accumulated stats.errors (bad sources, missing requirements,
+  // failed health checks) must never masquerade as a successful installation.
+  if (stats.errors > 0) {
+    throw new Error(`installation completed with ${stats.errors} error(s); see output above`)
+  }
 }