pantheon-opencode 1.5.0-beta.2 → 1.5.0-beta.20

package/scripts/doctor.mjs

@@ -22,7 +22,8 @@
  */
 
 import { spawn as spawnAsync, spawnSync } from 'node:child_process'
-import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -389,7 +390,7 @@ function checkMcpConfig(args) {
     // ENOENT-on-spawn failure class (dead hardcoded path, ambiguous relative
     // path) before opencode tries to spawn the server.
     for (const [name, mcpEntry] of Object.entries(mcp)) {
-      if (!mcpEntry || mcpEntry.type !== 'local') continue
+      if (mcpEntry?.type !== 'local') continue
       const cmd = mcpEntry.command
       if (!Array.isArray(cmd) || cmd.length === 0) {
         warn(`${cfg.label}: MCP "${name}" has no command array`)
@@ -530,7 +531,7 @@ async function checkMcpRuntimeSmoke(args) {
   const local = []
   for (const cfg of collectMcpConfigs(args)) {
     for (const [name, entry] of Object.entries(cfg.data.mcp ?? {})) {
-      if (!entry || entry.type !== 'local') continue
+      if (entry?.type !== 'local') continue
       if (!Array.isArray(entry.command) || entry.command.length === 0) continue
       const cwd = resolveMcpCwd(entry, cfg.path)
       const command = entry.command.map((part, index) =>
@@ -958,6 +959,35 @@ function checkVenvLayer(args) {
 // Check F.2: Code-Mode Scripts Directory
 // ---------------------------------------------------------------------------
 
+/**
+ * Return whether *dir* contains an executable code-mode target.
+ *
+ * Mirrors `_has_usable_scripts` in `scripts/code_mode_server.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
+ * scripts. Keep both implementations in sync (see tests/test_doctor_layers.mjs).
+ */
+function hasUsableScripts(dir) {
+  try {
+    if (!existsSync(dir)) return false
+    const stat = lstatSync(dir)
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return false
+    return readdirSync(dir).some((name) => {
+      if (name.startsWith('.')) return false
+      const lower = name.toLowerCase()
+      if (!lower.endsWith('.py') && !lower.endsWith('.sh')) return false
+      try {
+        return statSync(join(dir, name)).isFile()
+      } catch {
+        return false
+      }
+    })
+  } catch {
+    return false
+  }
+}
+
 /**
  * Verify the code-mode scripts directory exists for the resolved runtime
  * root (project → <target>/.opencode, otherwise the global config dir).
@@ -966,12 +996,20 @@ function checkVenvLayer(args) {
  */
 export function checkCodeModeDir(args) {
   section('F.2 Code-Mode Scripts')
-  const target = resolve(args.target)
-  const isProject = existsSync(join(target, '.opencode'))
-  const runtimeRoot = isProject ? target : resolveOpenCodeConfigDir(args.env ?? process.env)
-  const codeModeDir = isProject
-    ? join(runtimeRoot, '.opencode', '.pantheon', 'code-mode')
-    : join(runtimeRoot, '.pantheon', 'code-mode')
+  const env = args.env ?? process.env
+  const target = resolve(env.PANTHEON_PROJECT ?? args.target)
+  const projectCandidates = [
+    join(target, '.opencode', '.pantheon', 'code-mode'),
+    join(target, '.pantheon', 'code-mode'),
+  ]
+  // Seeding semantics: an existing project candidate wins; a project
+  // install (.opencode present) gets its runtime dir created when missing.
+  // Only targets with no project layout fall back to the global config dir.
+  const codeModeDir =
+    projectCandidates.find(hasUsableScripts) ??
+    (existsSync(join(target, '.opencode'))
+      ? projectCandidates[0]
+      : join(resolveOpenCodeConfigDir(env), '.pantheon', 'code-mode'))
   if (existsSync(codeModeDir)) {
     pass(`Code-mode scripts directory exists: ${codeModeDir}`)
     return codeModeDir
@@ -986,6 +1024,83 @@ export function checkCodeModeDir(args) {
   return codeModeDir
 }
 
+/** Resolve code-mode using the same project-first rule as the MCP server. */
+export function resolveCodeModeDir(args) {
+  const env = args.env ?? process.env
+  const target = resolve(env.PANTHEON_PROJECT ?? args.target)
+  const projectCandidates = [
+    join(target, '.opencode', '.pantheon', 'code-mode'),
+    join(target, '.pantheon', 'code-mode'),
+  ]
+  const projectDir = projectCandidates.find(hasUsableScripts)
+  if (projectDir) return projectDir
+  return join(resolveOpenCodeConfigDir(env), '.pantheon', 'code-mode')
+}
+
+/** Validate a code-mode manifest without modifying it. */
+export function validateCodeModeManifest(codeModeDir) {
+  const manifestPath = join(codeModeDir, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    return { ok: false, message: `Code-mode manifest missing: ${manifestPath}` }
+  }
+
+  let data
+  try {
+    data = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch {
+    return { ok: false, message: `Code-mode manifest malformed: ${manifestPath}` }
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, message: 'Code-mode manifest malformed: root must be an object' }
+  }
+  if (data.version !== 1) {
+    return { ok: false, message: 'Code-mode manifest malformed: version must be 1' }
+  }
+  if (!data.scripts || typeof data.scripts !== 'object' || Array.isArray(data.scripts)) {
+    return { ok: false, message: 'Code-mode manifest malformed: scripts must be an object' }
+  }
+
+  const listed = Object.keys(data.scripts)
+  const invalid = listed.filter(
+    (name) => typeof data.scripts[name] !== 'string' || !/^[a-f0-9]{64}$/i.test(data.scripts[name]),
+  )
+  if (invalid.length) {
+    return { ok: false, message: `Code-mode manifest invalid digest: ${invalid.join(', ')}` }
+  }
+
+  const actualScripts = readdirSync(codeModeDir).filter(
+    (name) =>
+      (name.endsWith('.py') || name.endsWith('.sh')) && statSync(join(codeModeDir, name)).isFile(),
+  )
+  const missing = listed.filter((name) => !existsSync(join(codeModeDir, name)))
+  const extra = actualScripts.filter((name) => !Object.hasOwn(data.scripts, name))
+  const differing = listed.filter((name) => {
+    const path = join(codeModeDir, name)
+    if (!existsSync(path)) return false
+    const digest = createHash('sha256').update(readFileSync(path)).digest('hex')
+    return digest !== data.scripts[name].toLowerCase()
+  })
+  if (missing.length || extra.length || differing.length) {
+    const names = [...new Set([...missing, ...extra, ...differing])]
+    return {
+      ok: false,
+      message: `Code-mode manifest mismatch: ${differing.length + missing.length + extra.length}/${listed.length} scripts differ — ${names.join(', ')}`,
+    }
+  }
+  return { ok: true, count: listed.length, total: actualScripts.length }
+}
+
+/** Run the diagnostic manifest check after directory validation. */
+export function checkCodeModeManifest(args) {
+  const codeModeDir = resolveCodeModeDir(args)
+  const result = validateCodeModeManifest(codeModeDir)
+  if (!result.ok) {
+    error(result.message)
+    return
+  }
+  pass(`✅ Code-mode manifest valid: ${result.count}/${result.total} scripts verified`)
+}
+
 /** Resolve the venv created by init for either a project or global install. */
 export function resolveRuntimePython(args) {
   const target = resolve(args.target)
@@ -1018,6 +1133,87 @@ export function resolveMcpCwd(entry, configPath = '') {
   return dirname(configPath)
 }
 
+// ---------------------------------------------------------------------------
+// Check H2: installed-version drift (beta.5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Prerelease-aware comparison for pantheon versions (X.Y.Z or X.Y.Z-beta.N).
+ * A stable release outranks any beta of the same core version. Returns
+ * <0, 0, >0 (a - b). The shared compareVersions/parseVersion above ignores
+ * the `-beta.N` suffix (it only reads 4 numeric groups), which would make
+ * every beta pair compare equal.
+ */
+function comparePantheonVersions(a, b) {
+  const parse = (v) => {
+    const m = String(v)
+      .trim()
+      .match(/^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/)
+    if (!m) return null
+    return {
+      core: [+m[1], +m[2], +m[3]],
+      beta: m[4] === undefined ? Number.POSITIVE_INFINITY : +m[4],
+    }
+  }
+  const pa = parse(a)
+  const pb = parse(b)
+  if (!pa || !pb) return 0
+  for (let i = 0; i < 3; i++) {
+    if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i]
+  }
+  return pa.beta - pb.beta
+}
+
+/**
+ * Compare the version recorded in the installation marker
+ * (<config>/.pantheon/install-state.json, written by the postinstall sync)
+ * against this package's version. When the package is newer, the config
+ * merge/venv/MCP wiring may be stale — point the user at `update`.
+ * Advisory only: a missing marker (pre-beta.5 install) is not an error.
+ */
+export function checkInstallVersionDrift(args) {
+  section('H2 Installed Version')
+  const env = args.env ?? process.env
+  let pkgVersion = null
+  try {
+    pkgVersion = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version
+  } catch {
+    return 'no-marker'
+  }
+  if (!pkgVersion) return 'no-marker'
+
+  const statePath = join(resolveOpenCodeConfigDir(env), '.pantheon', 'install-state.json')
+  let installed = null
+  if (existsSync(statePath)) {
+    try {
+      installed = JSON.parse(readFileSync(statePath, 'utf8')).pantheon_version ?? null
+    } catch {
+      installed = null
+    }
+  }
+  if (!installed) {
+    info('No installation version marker found (pre-beta.5 install) — skipping drift check')
+    return 'no-marker'
+  }
+  const drift = comparePantheonVersions(pkgVersion, installed)
+  if (drift > 0) {
+    warn(
+      `Package v${pkgVersion} is newer than the last-synced installation (v${installed}) — ` +
+        'run `npx pantheon-opencode update` (or re-run init) to refresh config, venv and MCP entries',
+    )
+    return 'package-newer'
+  }
+  if (drift < 0) {
+    warn(
+      `Installation marker (v${installed}) is newer than this package (v${pkgVersion}) — ` +
+        'the doctor is running from a different install than the last sync',
+    )
+    return 'install-newer'
+  }
+  pass(`Installation in sync with package v${pkgVersion}`)
+  return 'sync'
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1314,6 +1510,8 @@ async function main() {
   checkMcpConfig(args)
   checkVenvLayer(args)
   checkCodeModeDir(args)
+  checkCodeModeManifest(args)
+  checkInstallVersionDrift(args)
   await checkMcpRuntimeSmoke(args)
   checkPermissionMismatches(args)
   checkSyncStatus(args)

package/scripts/install/cli-ui.mjs

@@ -1,3 +1,5 @@
+import { strings } from './strings.mjs'
+
 export const icons = {
   success: '\u2705',
   warning: '\u26a0\ufe0f ',
@@ -8,9 +10,9 @@ export const icons = {
   arrow: '\u2192',
   bullet: '\u2022',
   star: '\u2b50',
-  wrench: '\U0001f527',
-  rocket: '\U0001f680',
-  package: '\U0001f4e6',
+  wrench: '\u{1F527}',
+  rocket: '\u{1F680}',
+  package: '\u{1F4E6}',
   gear: '\u2699\ufe0f',
 }
 
@@ -160,28 +162,32 @@ export function spinner(message) {
 export function printSummary(target, platforms, stats) {
   if (_quiet) return
 
+  const S = strings()
   const line = '\u2500'.repeat(Math.min(process.stdout.columns || 60, 60))
   const hasErrors = stats && stats.errors > 0
   console.log(
     tag(
       hasErrors
-        ? `${icons.warning} Instalação concluída com erros em ${target}`
-        : `${icons.rocket} OpenCode instalado em ${target}`,
+        ? `${icons.warning} ${S.summaryWithErrors(target)}`
+        : `${icons.rocket} ${S.summaryInstalled(target)}`,
     ),
   )
   console.log(tag(line))
   console.log('')
 
   if (stats) {
-    console.log(tag(`  Componentes:\t${stats.created} instalados, ${stats.skipped} pulados`))
+    console.log(tag(S.summaryComponents(stats.created, stats.skipped)))
     if (stats.errors > 0) {
-      console.warn(tag(`  ${icons.warning}${stats.errors} erro(s) encontrados`))
+      console.warn(tag(S.summaryErrors(stats.errors)))
+    }
+    if (stats.warnings > 0) {
+      console.warn(tag(S.summaryWarnings(stats.warnings)))
     }
     console.log('')
   }
 
-  console.log(tag(`  ${icons.star} Próximos passos:`))
-  console.log(tag(`    ${icons.bullet} Configure seus agentes em opencode.json`))
-  console.log(tag(`    ${icons.bullet} Adicione MCP servers em mcp.json`))
-  console.log(tag(`    ${icons.bullet} Rode 'opencode doctor' para verificar a instalação`))
+  console.log(tag(`  ${icons.star} ${S.summaryNext.trim()}`))
+  console.log(tag(S.summaryNextAgents))
+  console.log(tag(S.summaryNextMcp))
+  console.log(tag(S.summaryNextDoctor))
 }

package/scripts/install/config-migration.mjs

@@ -73,7 +73,7 @@ function convertPermissionsV2toV1(permArray) {
   const result = {}
   // Reverse action mapping: V2 action → V1 key
   const ACTION_TO_V1 = Object.fromEntries(
-    Object.entries(V1_PERMISSION_TO_ACTION).map(([k, v]) => [v, k])
+    Object.entries(V1_PERMISSION_TO_ACTION).map(([k, v]) => [v, k]),
   )
 
   for (const { action, resource, effect } of permArray) {
@@ -104,7 +104,7 @@ const PROVIDER_RENAME = {
 
 /** Reverse: V2 → V1 */
 const PROVIDER_RENAME_REVERSE = Object.fromEntries(
-  Object.entries(PROVIDER_RENAME).map(([k, v]) => [v, k])
+  Object.entries(PROVIDER_RENAME).map(([k, v]) => [v, k]),
 )
 
 /**
@@ -176,9 +176,7 @@ function convertProviderV2toV1(name, config) {
 
   // package → npm (strip aisdk: prefix)
   if (result.package !== undefined) {
-    result.npm = result.package.startsWith('aisdk:')
-      ? result.package.slice(6)
-      : result.package
+    result.npm = result.package.startsWith('aisdk:') ? result.package.slice(6) : result.package
     delete result.package
   }
 
@@ -303,7 +301,7 @@ const V1_TO_V2_RENAMES = {
 
 /** Build reverse map */
 const V2_TO_V1_RENAMES = Object.fromEntries(
-  Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k])
+  Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k]),
 )
 
 // ---------------------------------------------------------------------------

package/scripts/install/opencode.mjs

@@ -12,6 +12,7 @@
  * 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 { dirname, isAbsolute, join, resolve } from 'node:path'
@@ -34,6 +35,7 @@ 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,
@@ -42,8 +44,10 @@ import {
   sourceDirValid,
   summary,
   syncDir,
+  writeConfigWithBackup,
   writeIfChanged,
 } from './shared.mjs'
+import { strings } from './strings.mjs'
 
 import { setupVenv, venvPythonPath } from './venv.mjs'
 
@@ -61,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 {}
 
@@ -185,6 +217,21 @@ function managedPluginIdentity(ref) {
     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
@@ -343,6 +390,45 @@ export function syncTuiRegistration(target, { isGlobal = false, dryRun = false }
   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,
@@ -357,6 +443,7 @@ export async function installOpenCode(
 
   const componentSet = new Set(components)
   const stats = summary.opencode
+  const S = strings()
 
   // V1/V2 dual-version awareness (Phase 3): the installer builds a unified
   // config, then applies V2-native migration (migrateV1toV2) when
@@ -405,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/
@@ -417,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)
   }
 
   // -----------------------------------------------------------------------
@@ -430,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) {
@@ -665,6 +763,13 @@ export async function installOpenCode(
       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 ──
     const srcTiers = join(ROOT, '.pantheon', 'tiers.json')
     const dstTiers = join(runtimeTarget, '.pantheon', 'tiers.json')
@@ -676,6 +781,17 @@ 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
@@ -1017,8 +1133,10 @@ export async function installOpenCode(
 
   // --------------------------------------------------------------------
   // 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
@@ -1102,12 +1220,12 @@ export async function installOpenCode(
   // before writing. V1 path is untouched (zero regression).
   let configToWrite = config
   if (version === 'v2') {
-    info('Migrating config to V2 native format...')
+    info(S.v2Migrating)
     configToWrite = migrateV1toV2(config)
   }
 
   const configContent = `${JSON.stringify(configToWrite, null, 2)}\n`
-  const status = writeIfChanged(targetConfigPath, configContent, dryRun)
+  const status = writeConfigWithBackup(targetConfigPath, configContent, dryRun)
   if (status === 'created') stats.created++
   else stats.skipped++
 
@@ -1128,40 +1246,15 @@ 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 runtimeTarget = isGlobal ? target : join(target, '.opencode')
-      const health = healthCheck(runtimeTarget, { dryRun, pythonTarget: target })
-
-      // 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(
@@ -1179,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`,
     )
@@ -1207,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`)
+  }
 }