pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.10

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,8 @@ 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 { copyAgentPrompts, writeAgentsMdManaged } from '../build-agents-md.mjs'
 import {
   bullet,
   colors,
@@ -29,7 +35,11 @@ import {
   success,
   warning,
 } from './cli-ui.mjs'
-import { migrateV1toV2 } from './config-migration.mjs'
+import {
+  mergeContextSandboxBlocks,
+  migrateMcpEntrypointPaths,
+  migrateV1toV2,
+} from './config-migration.mjs'
 import { healthCheck } from './health-check.mjs'
 import { detectVersion, runMigrations } from './migrate.mjs'
 import { resolveOpenCodeVersion } from './opencode-version.mjs'
@@ -37,7 +47,6 @@ import { copyPluginFiles, installPlugin, registerPlugin, unregisterPlugin } from
 import {
   checkRuntimePrerequisites,
   collectSkillNames,
-  copyFiles,
   installSkills,
   parseFrontmatter,
   ROOT,
@@ -47,6 +56,7 @@ import {
   writeConfigWithBackup,
   writeIfChanged,
 } from './shared.mjs'
+import { createInitialState, hasState, readState, setComponentState, writeState } from './state.mjs'
 import { strings } from './strings.mjs'
 
 import { setupVenv, venvPythonPath } from './venv.mjs'
@@ -61,6 +71,139 @@ 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
+ * new agent they are the seed. Everything else on an existing entry is the
+ * user's and is left alone.
+ *
+ * `source` is written right next to these (for both new and existing agents) but
+ * is kept out of the loop so it can also be set independently — the migration in
+ * config-migration.mjs mirrors this list plus `source`, and tests assert the two
+ * stay equal as sets.
+ *
+ * KNOWN DEBT: `permission` is the V1 spelling. V2 reads `permissions`, so an
+ * agent can carry both keys after an install and the V1 one becomes dead weight.
+ * Tracked for the next slice; changing it here would change what an install
+ * writes.
+ *
+ * @type {readonly string[]}
+ */
+export const MANAGED_FIELDS = Object.freeze([
+  'temperature',
+  'color',
+  'permission',
+  'mode',
+  'hidden',
+  'disable_model_invocation',
+])
+
+const PANTHEON_MCP_SERVERS = Object.freeze([
+  'pantheon-resources',
+  'pantheon-memory',
+  'pantheon-code-mode',
+  'pantheon-persistence',
+  'pantheon-vision',
+])
+
+function normalizeMcpPermissionSegment(value) {
+  return value.replace(/[^a-zA-Z0-9_]/g, '_')
+}
+
+/**
+ * Translate an agent's `mcp_tools` frontmatter into per-tool native
+ * permissions. V1 matches the original server-tool names; V2 normalizes
+ * punctuation to underscores. Emitting both spellings keeps the same source
+ * metadata valid for either host. Unlisted bundled Pantheon servers default to
+ * deny; unrelated user MCP servers are not touched.
+ *
+ * @param {Record<string, 'all' | string[]>} mcpTools
+ * @returns {Record<string, 'allow' | 'deny'>}
+ */
+export function deriveNativeMcpPermissions(mcpTools) {
+  if (mcpTools === null || typeof mcpTools !== 'object' || Array.isArray(mcpTools)) {
+    throw new TypeError('mcp_tools must be an object keyed by MCP server name')
+  }
+
+  const servers = new Set([...PANTHEON_MCP_SERVERS, ...Object.keys(mcpTools)])
+  const permissions = {}
+
+  for (const server of servers) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(server)) {
+      throw new TypeError(`mcp_tools server name is invalid: ${server}`)
+    }
+    const tools = Object.hasOwn(mcpTools, server) ? mcpTools[server] : []
+    if (
+      tools !== 'all' &&
+      (!Array.isArray(tools) ||
+        tools.some((tool) => typeof tool !== 'string' || !/^[a-zA-Z0-9._-]+$/.test(tool)))
+    ) {
+      throw new TypeError(`mcp_tools.${server} must be "all" or an array of tool names`)
+    }
+
+    const serverAliases = new Set([server, normalizeMcpPermissionSegment(server)])
+    for (const alias of serverAliases) permissions[`${alias}_*`] = 'deny'
+  }
+
+  for (const server of servers) {
+    const tools = Object.hasOwn(mcpTools, server) ? mcpTools[server] : []
+    const serverAliases = new Set([server, normalizeMcpPermissionSegment(server)])
+    if (tools === 'all') {
+      for (const alias of serverAliases) permissions[`${alias}_*`] = 'allow'
+      continue
+    }
+
+    for (const tool of tools) {
+      const toolAliases = new Set([tool, normalizeMcpPermissionSegment(tool)])
+      for (const serverAlias of serverAliases) {
+        for (const toolAlias of toolAliases) {
+          permissions[`${serverAlias}_${toolAlias}`] = 'allow'
+        }
+      }
+    }
+  }
+
+  return permissions
+}
+
 function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
 }
@@ -103,6 +246,27 @@ function readJsonConfig(filePath) {
   }
 }
 
+/**
+ * Read a JSON config AND the exact raw text it was parsed from.
+ *
+ * The raw text is threaded to {@link writeConfigWithBackup} as the
+ * expected-content guard, so the compare-before-rename uses the SAME bytes the
+ * caller parsed — no second read that could observe a different file.
+ *
+ * @param {string} filePath
+ * @returns {{ config: object, raw: string|null }}
+ * @throws {Error} on invalid JSON (before any write happens)
+ */
+function readJsonConfigWithRaw(filePath) {
+  if (!existsSync(filePath)) return { config: {}, raw: null }
+  const raw = readFileSync(filePath, 'utf8')
+  try {
+    return { config: JSON.parse(raw), raw }
+  } catch (cause) {
+    throw new Error(`Invalid JSON in ${filePath}`, { cause })
+  }
+}
+
 function mergeMissing(target, source) {
   if (!source || typeof source !== 'object' || Array.isArray(source)) return target
   if (!target || typeof target !== 'object' || Array.isArray(target)) return deepClone(source)
@@ -131,8 +295,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
@@ -169,6 +333,7 @@ const PANTHEON_V2_PLUGIN = 'src/plugin-v2'
 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_PACKAGE_REF = /^pantheon-opencode(?:@[^/]+)?(?:\/(plugin|plugin-v2))?$/
 const PANTHEON_PLUGIN_IDENTITIES = new Set([
   PANTHEON_V1_PLUGIN,
   PANTHEON_V1_HOOKS,
@@ -197,6 +362,17 @@ function managedPluginIdentity(ref) {
   const normalized = normalizePluginRef(ref)
   if (typeof normalized !== 'string') return null
 
+  // Older installs registered the package root itself (often pinned to a
+  // beta version) in OpenCode's plural `plugins` list. Treat all exact npm
+  // specs for this package as managed so an update removes the old cached
+  // copy before registering the current package path. Do not match similarly
+  // named third-party packages such as `pantheon-opencode-fork`.
+  const packageRef = normalized.match(PANTHEON_PACKAGE_REF)
+  if (packageRef !== null) {
+    if (packageRef[1] === 'plugin') return PANTHEON_V1_PLUGIN
+    return PANTHEON_V2_PLUGIN
+  }
+
   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}@`)) {
@@ -275,6 +451,71 @@ export function deduplicatePluginReferences(refs) {
   })
 }
 
+/**
+ * Duplicate the V1 top-level `context_sandbox` block into the exact Pantheon V2
+ * plugin entry's `options`, converting a plain-string entry into the
+ * `{ package, options }` object form the host accepts.
+ *
+ * Why the copy is required: OpenCode V2.0.25 silently drops a top-level
+ * `context_sandbox` key (probe evidence in the module header of
+ * config-migration.mjs), so the V1 setting would be lost on a V1→V2 install.
+ * The V1 top-level block is LEFT IN PLACE so a downgrade keeps working.
+ *
+ * Precedence is delegated to {@link mergeContextSandboxBlocks}: an explicit V2
+ * option leaf wins, the legacy block fills only unset leaves, and the runtime
+ * resolver supplies defaults. Only the Pantheon V2 entry is touched — every
+ * other plugin entry, and every other option on this entry, is preserved.
+ *
+ * The managed V2 option is ALWAYS validated — even when no legacy V1 block is
+ * present — because the migration is the only place that validates it. An
+ * earlier version returned early on `legacySandbox === undefined`, so an
+ * explicit `plugins[].options.context_sandbox` of `null` (or any type-invalid
+ * known value) was never checked and persisted straight to disk.
+ *
+ * @param {unknown[]} plugins - V2 `plugins` array (mutated in place)
+ * @param {unknown} legacySandbox - V1 top-level `context_sandbox` (may be undefined)
+ * @returns {unknown[]} the same array
+ * @throws {Error} when the legacy block or the existing V2 option is null or
+ *   type-invalid (checked before any config write)
+ */
+export function applyContextSandboxToV2Plugins(plugins, legacySandbox) {
+  if (!Array.isArray(plugins)) return plugins
+
+  const index = plugins.findIndex((ref) => pluginReferenceIdentity(ref) === PANTHEON_V2_PLUGIN)
+  if (index === -1) return plugins
+
+  const entry = plugins[index]
+  const isObjectEntry = typeof entry === 'object' && entry !== null && !Array.isArray(entry)
+  const hasOptions =
+    isObjectEntry &&
+    typeof entry.options === 'object' &&
+    entry.options !== null &&
+    !Array.isArray(entry.options)
+  const existingOptions = hasOptions ? entry.options : {}
+  const hasExistingSandbox = Object.hasOwn(existingOptions, 'context_sandbox')
+
+  // Nothing managed to migrate OR validate: leave the entry untouched so a
+  // re-install stays a true no-op. `legacySandbox === undefined` covers an
+  // absent V1 key; `!hasExistingSandbox` covers a V2 entry with no managed
+  // option yet. An explicit `null` is a PRESENT key (`hasExistingSandbox`), so
+  // it is deliberately NOT skipped and must be validated below.
+  if (legacySandbox === undefined && !hasExistingSandbox) return plugins
+
+  // Run the managed option through the validator unconditionally, merging the
+  // legacy block in only when it exists. A null/type-invalid existing option
+  // throws here, BEFORE the config is written.
+  const mergedSandbox = mergeContextSandboxBlocks(existingOptions.context_sandbox, legacySandbox)
+  const packageId = isObjectEntry ? entry.package : entry
+
+  // Rebuild the entry as an object so the options survive a V2 host (which
+  // preserves plugin option objects verbatim).
+  plugins[index] = {
+    package: packageId,
+    options: { ...existingOptions, context_sandbox: mergedSandbox },
+  }
+  return plugins
+}
+
 export { parseOpenCodeVersion, resolveOpenCodeVersion } from './opencode-version.mjs'
 
 /**
@@ -301,15 +542,14 @@ export function isGlobalConfigDir(target) {
  * package; the loader must NEVER be pointed at that in-package dir (a package
  * reinstall/upgrade replaces the dir under a live registration and leaves
  * diverging copies loading). Instead the installer always copies it into the
- * config dir's plugins/ dir and registers THAT copy:
+ * config dir's plugins/ dir and uses THAT copy:
  *
- *   <configDir>/plugins/pantheon-tui      (dist/ + package.json + index.tsx)
+ *   <configDir>/plugins/pantheon-tui      (tui.ts + dist/ + package manifests)
  *
- * The loader reads the copied package.json `exports` map:
- *   exports["./tui"]    → dist/tui.js     (COMPILED Solid output)
- *   exports["./server"] → dist/server.js  (no-op server() stub)
+ * V1 registers that copy through tui.json. V2 discovers the local plugin's
+ * index.ts + tui.ts pair; the V2 shim re-exports dist/tui-v2.js.
  *
- * @param {string} configDir - directory holding tui.json (target for global
+ * @param {string} configDir - OpenCode config directory (target for global
  *   installs, <target>/.opencode for project installs)
  * @returns {string} absolute path of the copied plugin directory
  */
@@ -335,23 +575,20 @@ export function tuiConfigLocations(target) {
 }
 
 /**
- * Sync the Pantheon TUI plugin registration across EVERY tui.json location
- * OpenCode reads.
+ * Sync the Pantheon TUI plugin payload and V1 registration. V2 discovers the
+ * copied local-plugin entrypoints and does not use a project tui.json.
  *
  * Contract (single source of truth):
- *   1. ALWAYS copy src/plugins/tui → <configDir>/plugins/pantheon-tui
- *      (dist/* + package.json + index.tsx) so the registered reference is a
- *      directory that exists and carries the loader contract (exports →
- *      dist/tui.js, dist/server.js). The copy is idempotent: a second run is
- *      byte-identical.
+ *   1. ALWAYS copy src/plugins/tui → <configDir>/plugins/pantheon-tui with the
+ *      selected host entrypoints and compiled bundle. The copy is idempotent.
  *   2. Clean stale Pantheon TUI refs from ALL tui.json locations OpenCode
  *      loads — ~/.opencode, $XDG_CONFIG_HOME/opencode and
  *      <target>/.opencode — covering every old reference shape: dist file
  *      paths, in-package src/plugins/tui dirs, bare plugins/pantheon-tui
  *      copies, and npx paths. A stale ref left in the non-target location
  *      would still be loaded and break the TUI.
- *   3. Register EXACTLY the copied directory in the selected target only —
- *      exactly ONE Pantheon TUI reference exists system-wide after install.
+ *   3. V1 registers the copied directory in the selected target. V2 relies on
+ *      local-plugin discovery and does not write a project tui.json entry.
  *
  * @param {string} target - install target directory
  * @param {object} [opts]
@@ -359,18 +596,19 @@ export function tuiConfigLocations(target) {
  * @param {boolean} [opts.dryRun=false]
  * @returns {'created'|'skipped'} status for the target registration
  */
-export function syncTuiRegistration(target, { isGlobal = false, dryRun = false } = {}) {
+export function syncTuiRegistration(
+  target,
+  { isGlobal = false, dryRun = false, version = 'v1' } = {},
+) {
   const configDir = isGlobal ? target : join(target, '.opencode')
   const targetTuiConfigPath = join(configDir, 'tui.json')
 
-  // 1. Always copy the single source of truth into the target config's
-  //    plugins/pantheon-tui. Registering this copied directory (never the
-  //    in-package src/plugins/tui) keeps installs hermetic and idempotent:
-  //    the ref points at a dir that exists and has dist/tui.js.
+  // 1. Copy the host-specific plugin into the target config's
+  //    plugins/pantheon-tui. This keeps the installed entry hermetic.
   const tuiSrcDir = join(ROOT, 'src', 'plugins', 'tui')
   const tuiCopyDir = resolveTuiCopyTarget(configDir)
   if (existsSync(tuiSrcDir)) {
-    copyPluginFiles(tuiSrcDir, tuiCopyDir, { dryRun })
+    copyPluginFiles(tuiSrcDir, tuiCopyDir, { dryRun, version })
   }
 
   // 2. Clean stale Pantheon TUI refs from every location OpenCode reads.
@@ -386,6 +624,11 @@ export function syncTuiRegistration(target, { isGlobal = false, dryRun = false }
     })
   }
 
+  // OpenCode V2 discovers local plugins from the config plugins directories;
+  // its TUI plugin API is exposed by the sibling tui.ts entrypoint. V1 still
+  // requires the explicit tui.json registration.
+  if (version === 'v2') return 'skipped'
+
   // 3. Register the copied directory in the selected target only.
   return registerPlugin(targetTuiConfigPath, tuiCopyDir, { dryRun })
 }
@@ -429,6 +672,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,
@@ -450,12 +779,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
@@ -487,10 +835,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 { config, raw: configRaw } = readJsonConfigWithRaw(targetConfigPath)
+  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
@@ -503,14 +865,13 @@ export async function installOpenCode(
     }
   }
 
-  // Determine layout based on install scope.
-  // Global config dir (~/.opencode or ~/.config/opencode) uses a flat layout:
-  //   agents/   skills/   commands/   plugins/
-  // Project installs use the .opencode/ sub-directory layout:
-  //   .opencode/agents/   .opencode/skills/   .opencode/commands/
+  // V1 project installs use the legacy .opencode/agents layout. OpenCode V2's
+  // active config directory is the project root and its agent loader scans
+  // <config-dir>/{agent,agents}/**, so V2 project agents must be at ./agents.
+  // Global installs are flat for both versions.
   const isGlobal = isGlobalConfigDir(target)
   const _subDir = isGlobal ? '' : '.opencode'
-  const agentPrefix = isGlobal ? 'agents' : '.opencode/agents'
+  const agentPrefix = isGlobal || version === 'v2' ? 'agents' : '.opencode/agents'
 
   configure({ dryRun })
 
@@ -529,7 +890,7 @@ export async function installOpenCode(
       stats.errors++
     } else {
       const agentStep = step(S.installingAgents)
-      const dstDir = isGlobal ? join(target, 'agents') : join(target, '.opencode', 'agents')
+      const dstDir = join(target, agentPrefix)
       if (!dryRun) mkdirSync(dstDir, { recursive: true })
       if (clean && existsSync(dstDir) && !dryRun) {
         const existing = readdirSync(dstDir)
@@ -537,7 +898,7 @@ export async function installOpenCode(
           rmSync(join(dstDir, f), { recursive: true, force: true })
         }
       }
-      const { created, skipped } = copyFiles(srcDir, dstDir, dryRun)
+      const { created, skipped } = copyAgentPrompts(srcDir, dstDir, dryRun)
       stats.created += created
       stats.skipped += skipped
       agentStep(true)
@@ -586,23 +947,45 @@ export async function installOpenCode(
   }
 
   // -----------------------------------------------------------------------
-  // 2.5 Install instructions: AGENTS.md only (--components instructions)
+  // 2.5 Install shared instructions: AGENTS.md (--components instructions)
   // -----------------------------------------------------------------------
-  // AGENTS.md is the single instruction file both V1 and V2 load; the
-  // generated file embeds every src/instructions/*.instructions.md body, so
-  // the individual files are NOT copied anymore (nothing references
-  // <config>/instructions/ after the section-D merge fix — copying them would
-  // just leave stale duplicates on disk).
+  // Both AGENTS.md artifacts are managed regions (scripts/build-agents-md.mjs).
+  // A GLOBAL config dir receives the repo-agnostic global artifact (agent
+  // table + shared rules); a PROJECT layout keeps the repository artifact.
+  // writeAgentsMdManaged is conservative: content outside the managed region
+  // is never deleted, and a legacy fully-generated file upgrades in place.
   if (componentSet.has('instructions')) {
     section('\uD83D\uDCCB Instructions')
-    // AGENTS.md
-    const srcAgentsMd = join(ROOT, 'AGENTS.md')
+    const srcAgentsMd = isGlobal ? join(ROOT, 'AGENTS.global.md') : join(ROOT, 'AGENTS.md')
     const dstAgentsMd = join(target, 'AGENTS.md')
     if (existsSync(srcAgentsMd)) {
       const content = readFileSync(srcAgentsMd, 'utf8')
-      const status = writeIfChanged(dstAgentsMd, content, dryRun)
-      if (status === 'created') stats.created++
-      else stats.skipped++
+      const status = writeAgentsMdManaged(dstAgentsMd, content, dryRun)
+      if (status === 'skipped') stats.skipped++
+      else {
+        stats.created++
+        if (status === 'merged') {
+          warning(
+            `AGENTS.md had non-generated content — it was preserved around the ` +
+              `Pantheon managed region in ${dstAgentsMd}. Review and merge manually.`,
+          )
+        }
+      }
+    } else {
+      warning(`AGENTS.md artifact not found in the package: ${srcAgentsMd}`)
+      stats.errors++
+    }
+    // An instruction-only upgrade must also refresh selective guidance on
+    // already-installed Pantheon agents, but must not create agents the user
+    // did not install. Full agent installs do this in phase 1 above.
+    if (!componentSet.has('agents')) {
+      const installedAgents = join(target, agentPrefix)
+      const sourceAgents = join(ROOT, 'src', 'agents')
+      if (existsSync(installedAgents) && existsSync(sourceAgents)) {
+        const refreshed = copyAgentPrompts(sourceAgents, installedAgents, dryRun, true)
+        stats.created += refreshed.created
+        stats.skipped += refreshed.skipped
+      }
     }
   }
 
@@ -626,7 +1009,11 @@ export async function installOpenCode(
   if (componentSet.has('commands')) {
     section('\u26A1 Commands')
     const srcCmds = join(ROOT, 'commands')
-    const dstCmds = isGlobal ? join(target, 'commands') : join(target, '.opencode', 'commands')
+    // V2 project sandboxes use OPENCODE_CONFIG_DIR=<project root>, so OpenCode
+    // discovers custom commands from <target>/commands. V1 project installs
+    // keep the standard .opencode/commands layout; global installs are flat.
+    const commandDir = isGlobal || version === 'v2' ? 'commands' : '.opencode/commands'
+    const dstCmds = join(target, commandDir)
     if (existsSync(srcCmds)) {
       const cmdResult = syncDir(srcCmds, dstCmds, dryRun, clean, (f) => f.endsWith('.md'))
       stats.created += cmdResult.created
@@ -651,7 +1038,7 @@ export async function installOpenCode(
     const dstPluginDir = isGlobal
       ? join(target, 'plugins', 'pantheon-tui')
       : join(target, '.opencode', 'plugins', 'pantheon-tui')
-    const pluginStats = installPlugin(srcPluginDir, dstPluginDir, { dryRun, clean })
+    const pluginStats = installPlugin(srcPluginDir, dstPluginDir, { dryRun, clean, version })
     stats.created += pluginStats.created
     stats.skipped += pluginStats.skipped
     stats.errors += pluginStats.errors
@@ -663,7 +1050,7 @@ export async function installOpenCode(
   if (componentSet.has('plugins')) {
     let tuiStatus
     try {
-      tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun })
+      tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun, version })
     } catch (cause) {
       error(`TUI plugin setup failed: ${cause.message}`)
       stats.errors++
@@ -683,30 +1070,31 @@ 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',
+      'themis_heuristic_scan.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')
@@ -798,7 +1186,7 @@ export async function installOpenCode(
   //    on top. Preserves user's MCP, provider, plugins, compaction, theme.
   // -----------------------------------------------------------------------
   // --------------------------------------------------------------------
-  // A. Parse canonical agent config from agents/*.agent.md frontmatter
+  // A. Parse canonical agent config from src/agents/*.md frontmatter
   //    and merge into opencode.json config.
   // --------------------------------------------------------------------
   function getAgentSources(agentPrefix) {
@@ -836,7 +1224,6 @@ export async function installOpenCode(
       if (fm.mode) agent.mode = fm.mode
       if (fm.hidden) agent.hidden = fm.hidden
       if (fm.temperature !== undefined) agent.temperature = fm.temperature
-      if (fm.steps !== undefined) agent.steps = fm.steps
       // Support both hyphen (YAML) and underscore (JSON) key variants
       if (fm['disable-model-invocation'] !== undefined)
         agent.disable_model_invocation = fm['disable-model-invocation']
@@ -847,6 +1234,12 @@ export async function installOpenCode(
       if (fm.permission) {
         agent.permission = JSON.parse(JSON.stringify(fm.permission))
       }
+      if (fm.mcp_tools !== undefined) {
+        agent.permission = {
+          ...(agent.permission ?? {}),
+          ...deriveNativeMcpPermissions(fm.mcp_tools),
+        }
+      }
 
       config[name] = agent
     }
@@ -855,15 +1248,6 @@ export async function installOpenCode(
 
   const canonicalAgentConfig = readAgentConfigFromCanonical()
   const agentSources = getAgentSources(agentPrefix)
-  const MANAGED_FIELDS = [
-    'steps',
-    'temperature',
-    'color',
-    'permission',
-    'mode',
-    'hidden',
-    'disable_model_invocation',
-  ]
 
   if (config.agent === undefined) config.agent = {}
 
@@ -922,8 +1306,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.
@@ -965,8 +1352,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
@@ -985,7 +1373,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))
@@ -1014,8 +1402,20 @@ export async function installOpenCode(
       config.plugin = removePantheonPluginReferences(config.plugin)
     }
     if (!Array.isArray(config.plugins)) config.plugins = []
+    // Preserve any options already set on the Pantheon V2 entry across the
+    // remove/re-add below. The context_sandbox migration reads them, and a
+    // silent drop would lose a hand-set sandbox limit or any other plugin
+    // option the user chose. Only the object form can carry options.
+    const existingV2Options =
+      config.plugins
+        .filter((ref) => pluginReferenceIdentity(ref) === PANTHEON_V2_PLUGIN)
+        .map((ref) =>
+          typeof ref === 'object' && ref !== null && !Array.isArray(ref) ? ref.options : null,
+        )
+        .find((options) => options && typeof options === 'object' && !Array.isArray(options)) ??
+      null
     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))
@@ -1038,36 +1438,75 @@ export async function installOpenCode(
     config.plugins = config.plugins.filter(
       (plugin) => pluginReferenceIdentity(plugin) !== pluginReferenceIdentity(resolvedV2),
     )
-    config.plugins.push(resolvedV2)
+    config.plugins.push(
+      existingV2Options === null
+        ? resolvedV2
+        : { package: resolvedV2, options: deepClone(existingV2Options) },
+    )
   }
 
-  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',
@@ -1075,12 +1514,6 @@ export async function installOpenCode(
         'npx *': 'allow',
         'pytest *': 'allow',
         'ruff *': 'allow',
-        'black *': 'allow',
-        'pip *': 'allow',
-        'docker *': 'allow',
-        'curl *': 'allow',
-        'gh *': 'allow',
-        'make *': 'allow',
       }
     }
   }
@@ -1090,8 +1523,8 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // AGENTS.md is the single instruction file both V1 and V2 load (V1
   // auto-discovers it, V2 loads it explicitly). The generated AGENTS.md
-  // (scripts/build-agents-md.mjs) already embeds every
-  // src/instructions/*.instructions.md body, so the `instructions/*.md`
+  // contains shared rules; agent-scoped rules are in the installed agent
+  // prompts. The `instructions/*.md`
   // glob is no longer needed — keeping it would duplicate content under V1
   // and is ignored under V2 anyway. Only ensure AGENTS.md is present.
   const pantheonInstructions = ['AGENTS.md']
@@ -1137,82 +1570,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 ──
@@ -1222,10 +1591,52 @@ export async function installOpenCode(
   if (version === 'v2') {
     info(S.v2Migrating)
     configToWrite = migrateV1toV2(config)
+
+    // Pantheon no longer sets a step ceiling. Any `steps` sitting on a managed
+    // agent was written by an earlier install and never chosen by the user —
+    // the merge above is additive by design (no delete path), so drop it here
+    // and let the host default apply. This runs after the migration because
+    // migrateV1toV2 copies the V1 `agent` block across verbatim (including any
+    // stale `steps`), which is exactly how the value reappears in V2.
+    // User-defined agents are out of scope and keep their value; the V1
+    // singular `agent` block is deliberately untouched (V1 is retiring).
+    const v2Agents = configToWrite.agents
+    if (v2Agents && typeof v2Agents === 'object' && !Array.isArray(v2Agents)) {
+      for (const name of Object.keys(canonicalAgentConfig)) {
+        const entry = v2Agents[name]
+        if (entry && typeof entry === 'object' && !Array.isArray(entry)) delete entry.steps
+      }
+    }
+
+    // Carry the V1 top-level `context_sandbox` into the exact Pantheon V2
+    // plugin entry's `options` — V2.0.25 silently drops the top-level key, so
+    // without this the user's enabled/limits choice is lost on a V1→V2 install.
+    // The V1 block itself is preserved by migrateV1toV2 for a downgrade.
+    // A null/type-invalid block throws HERE, before any config write.
+    configToWrite.plugins = applyContextSandboxToV2Plugins(
+      configToWrite.plugins,
+      config.context_sandbox,
+    )
   }
 
   const configContent = `${JSON.stringify(configToWrite, null, 2)}\n`
-  const status = writeConfigWithBackup(targetConfigPath, configContent, dryRun)
+  const status = writeConfigWithBackup(targetConfigPath, configContent, dryRun, {
+    expectedContent: configRaw,
+    // Test seam: lets a test simulate a concurrent writer landing between the
+    // initial config read and the pre-swap recheck. Absent in production.
+    beforeRecheck: opts.deps?.beforeRecheck,
+  })
+  if (status === 'conflict') {
+    // The user's config changed under the installer between the read and the
+    // swap. Treating this as an ordinary skipped write would report a
+    // successful install over a file we never actually updated — fail loudly
+    // and leave the target and its `.bak` byte-identical instead.
+    throw new Error(
+      `Installation aborted: ${targetConfigPath} changed on disk during install ` +
+        '(it no longer matches the content that was read); refusing to overwrite it. ' +
+        'Re-run the installer once the file is stable.',
+    )
+  }
   if (status === 'created') stats.created++
   else stats.skipped++
 
@@ -1304,9 +1715,46 @@ export async function installOpenCode(
     writeActivePreset(target, opts.preset, { source: 'cli' })
   }
 
+  // -----------------------------------------------------------------------
+  // 5.5 Optional vision prompt (interactive TTY only). The default — automatic
+  //     discovery — writes nothing, and non-interactive flows (no TTY, --yes,
+  //     --headless, automated sandboxes) never reach this block, so no run
+  //     blocks on stdin and the default behavior is unchanged. A failure here
+  //     must never fail the install: vision stays optional.
+  // -----------------------------------------------------------------------
+  if (interactive && !dryRun && !autoYes) {
+    const { runVisionPrompt } = await import('./vision-prompt.mjs')
+    try {
+      await runVisionPrompt({ logger: console })
+    } catch (err) {
+      warning(`Vision setup skipped: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
   // 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`)
   }
+
+  // Record the component state only after the install has completed. The
+  // postinstall marker can predate `init` and start with every component
+  // pending; leaving it untouched made a healthy beta install look incomplete
+  // to `doctor` forever. Unselected components retain their previous state.
+  if (!dryRun) {
+    const packageVersion = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version
+    let state = readState(target)
+    if (!state && hasState(target)) {
+      throw new Error('Installation state exists but cannot be read; refusing to replace it')
+    }
+    state ??= createInitialState(packageVersion)
+    state.pantheon_version = packageVersion
+    for (const component of ['agents', 'skills', 'plugins', 'runtime']) {
+      if (!componentSet.has(component)) continue
+      const status = component === 'runtime' && !runtimeHealthy ? 'failed' : 'installed'
+      const componentVersion = state.components?.[component]?.version ?? 1
+      setComponentState(state, component, componentVersion, status)
+    }
+    writeState(target, state)
+  }
 }