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

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.
  */
@@ -15,7 +19,10 @@
 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 { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { listV2UnsupportedFeatures } from '../../src/pantheon/v2-unsupported.mjs'
+import { copyAgentPrompts, writeAgentsMdManaged } from '../build-agents-md.mjs'
+import { backupSetPath, backupWarning, createBackupSet, nextBackupName } from './backup.mjs'
 import {
   bullet,
   colors,
@@ -27,17 +34,32 @@ import {
   spinner,
   step,
   success,
+  tag,
   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'
+import {
+  ACTIONS,
+  createRecorder,
+  displayPath,
+  formatChangePlan,
+  isRecording,
+  planStatsMismatch,
+  recordChange,
+  snapshot,
+  summarizeChanges,
+} from './plan.mjs'
 import { copyPluginFiles, installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
 import {
   checkRuntimePrerequisites,
   collectSkillNames,
-  copyFiles,
   installSkills,
   parseFrontmatter,
   ROOT,
@@ -47,6 +69,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,36 +84,343 @@ const COMPONENT_NAMES = [
   'runtime',
 ]
 
+/**
+ * MCP server scripts the runtime component installs. Hoisted so the backup-set
+ * enumeration and the runtime writer share one source of truth.
+ */
+const MCP_SCRIPTS = [
+  'mcp_resources.py',
+  'code_mode.py',
+  'memory_mcp.py',
+  'scrub-secrets.py',
+  '_pantheon_paths.py',
+  'mcp_codemap_module.py',
+  'mcp_persistence.py',
+  'pantheon_vision.py',
+  'eval_store.py',
+  'themis_heuristic_scan.py',
+]
+
+/** Recursively list regular files under `root`, relative to `root`. */
+function walkFiles(root, base = root, out = []) {
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const full = join(root, entry.name)
+    if (entry.isDirectory()) walkFiles(full, base, out)
+    else if (entry.isFile()) out.push(relative(base, full))
+  }
+  return out
+}
+
+/**
+ * Enumerate what the backup set must preserve, derived from the selected
+ * components. It returns:
+ *   - `entries`: paths (relative to `target`) the run can CREATE/UPDATE/REMOVE.
+ *     For every managed destination tree we take the UNION of the files that
+ *     already exist there (so a `--clean`, a stale removal, or an
+ *     instructions-only refresh is captured) and the source-derived destination
+ *     paths (so a file that will be created is recorded as absent). The union is
+ *     a superset of the plan's changes — unchanged files are backed up too.
+ *   - `notRevertible`: paths the run may delete or write but whose byte-for-byte
+ *     copy is not feasible or is out of the config dir (bulk `.venv` / plugin
+ *     `node_modules`, the global `tui.json` copies and the global vision config).
+ *     These are recorded explicitly in the manifest rather than silently ignored.
+ * It never reads file contents.
+ *
+ * @param {string} target
+ * @param {Set<string>} componentSet
+ * @param {string} version
+ * @param {boolean} isGlobal
+ * @returns {{ entries: string[], notRevertible: string[] }}
+ */
+function collectInstallBackupEntries(target, componentSet, version, isGlobal) {
+  const entries = []
+  const notRevertible = []
+  const rel = (abs) => relative(target, abs)
+  const addFile = (abs) => entries.push(rel(abs))
+  // Existing files under an in-target tree (covers removals / clean / refresh).
+  // `skipDirNames` prunes bulk subdirectories (e.g. plugin `node_modules`) so the
+  // walk stays cheap while everything else — including legacy files a clean pass
+  // deletes — is captured.
+  const addExisting = (dir, skipDirNames = null) => {
+    if (!existsSync(dir)) return
+    const walk = (base) => {
+      for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (skipDirNames && entry.isDirectory() && skipDirNames.has(entry.name)) continue
+        const full = join(base, entry.name)
+        if (entry.isDirectory()) walk(full)
+        else if (entry.isFile()) addFile(full)
+      }
+    }
+    walk(dir)
+  }
+  // Destination paths derived from a source tree (covers files to be created).
+  const addSource = (srcDir, dstDir, filter = null) => {
+    if (!existsSync(srcDir)) return
+    for (const r of walkFiles(srcDir)) {
+      if (filter && !filter(r)) continue
+      addFile(join(dstDir, r))
+    }
+  }
+
+  const baseDir = isGlobal ? target : join(target, '.opencode')
+  const agentPrefix = isGlobal || version === 'v2' ? 'agents' : '.opencode/agents'
+  const agentDir = join(target, agentPrefix)
+
+  // Always touched.
+  addFile(join(target, 'opencode.json'))
+  addFile(join(target, '.pantheon', 'install-state.json'))
+  addFile(join(baseDir, 'opencode-vision.json'))
+  // The active-preset writer (writeActivePreset(target, …)) lives at
+  // <target>/.pantheon, NOT under <baseDir>, for both project and global scope.
+  addFile(join(target, '.pantheon', 'active-preset.json'))
+  addFile(join(target, '.pantheon', 'active-preset.json.bak'))
+
+  // The agent prompt dir is refreshed (existing-only) by an instructions-only
+  // run too, so enumerate it whenever EITHER component can write it.
+  if (componentSet.has('agents') || componentSet.has('instructions')) {
+    addExisting(agentDir)
+  }
+  if (componentSet.has('agents')) {
+    addFile(join(target, 'routing.yml'))
+    addSource(
+      join(ROOT, 'src', 'agents'),
+      agentDir,
+      (r) => r.endsWith('.md') && r.toLowerCase() !== 'readme.md',
+    )
+  }
+  if (componentSet.has('skills')) {
+    addExisting(join(baseDir, 'skills'))
+    addSource(join(ROOT, 'src', 'skills'), join(baseDir, 'skills'))
+  }
+  if (componentSet.has('instructions')) addFile(join(target, 'AGENTS.md'))
+  if (componentSet.has('prompts')) {
+    addExisting(join(target, 'prompts'))
+    addSource(join(ROOT, 'prompts'), join(target, 'prompts'))
+  }
+  if (componentSet.has('commands')) {
+    const commandDir = isGlobal || version === 'v2' ? 'commands' : '.opencode/commands'
+    addExisting(join(target, commandDir))
+    addSource(join(ROOT, 'commands'), join(target, commandDir), (r) => r.endsWith('.md'))
+  }
+  if (componentSet.has('plugins')) {
+    const dstPluginDir = isGlobal
+      ? join(target, 'plugins', 'pantheon-tui')
+      : join(target, '.opencode', 'plugins', 'pantheon-tui')
+    // Existing files under the installed plugin dir (legacy `index.tsx` /
+    // `dist/tui.tsx` and any extras a `--clean` run deletes) are captured, like
+    // every sibling tree — EXCEPT the bulk `node_modules`, which is regenerated
+    // by `npm ci` and listed as not revertible.
+    addExisting(dstPluginDir, new Set(['node_modules']))
+    addSource(join(ROOT, 'src', 'plugins', 'tui', 'dist'), join(dstPluginDir, 'dist'))
+    addFile(join(dstPluginDir, 'package.json'))
+    addFile(join(dstPluginDir, 'package-lock.json'))
+    addFile(join(dstPluginDir, 'tui.ts'))
+    addFile(join(dstPluginDir, 'index.ts'))
+    notRevertible.push(rel(join(dstPluginDir, 'node_modules')))
+    if (version === 'v1') {
+      const projectTui = join(baseDir, 'tui.json')
+      addFile(projectTui)
+      // Cross-location cleanup touches copies OUTSIDE the config dir.
+      for (const loc of tuiConfigLocations(target)) {
+        if (resolve(loc) !== resolve(projectTui)) notRevertible.push(loc)
+      }
+    }
+  }
+  if (componentSet.has('runtime')) {
+    const runtimeTarget = isGlobal ? target : join(target, '.opencode')
+    addExisting(join(runtimeTarget, 'scripts'))
+    for (const script of MCP_SCRIPTS) addFile(join(runtimeTarget, 'scripts', script))
+    addFile(join(runtimeTarget, 'requirements-vision.txt'))
+    addSource(join(ROOT, '.pantheon', 'code-mode'), join(runtimeTarget, '.pantheon', 'code-mode'))
+    addExisting(join(runtimeTarget, '.pantheon', 'code-mode'))
+    addFile(join(runtimeTarget, '.pantheon', 'tiers.json'))
+    // `--force` recreates the venv from scratch: bulk, not copied.
+    notRevertible.push(rel(join(target, '.venv')))
+  }
+
+  // The vision config is written GLOBALLY (outside the config dir).
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  const globalVision = join(xdg, 'opencode', 'opencode-vision.json')
+  if (resolve(globalVision) !== resolve(join(baseDir, 'opencode-vision.json'))) {
+    notRevertible.push(globalVision)
+  }
+
+  return { entries, notRevertible }
+}
+
+/**
+ * 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))
 }
 
 /**
  * (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.
+ * script, and write it to the destination. This is the explicit installation
+ * opt-in: the MCP server only executes scripts listed here whose on-disk hash
+ * matches. Missing or empty source approves nothing — execution is never
+ * implicit.
+ *
+ * This function is the SINGLE owner of `manifest.json`: `syncDir` deliberately
+ * excludes it (see the runtime block), so exactly one writer and one stats
+ * count exist for that path. The payload is derived from the SOURCE scripts
+ * (what will be installed), then compared against the CURRENT installed
+ * manifest, so the preview action matches what apply writes — including on a
+ * script upgrade, where the installed manifest is stale.
+ *
+ * @returns {{ approved: number, status: 'created'|'skipped'|'conflict'|null }}
  */
-function writeCodeModeManifest(dir, dryRun) {
-  if (!existsSync(dir)) return 0
+function writeCodeModeManifest(srcDir, dstDir, dryRun, recorder = null) {
+  if (!existsSync(srcDir)) return { approved: 0, status: null }
   let names
   try {
-    names = readdirSync(dir)
+    names = readdirSync(srcDir)
       .filter((name) => /\.(sh|py)$/i.test(name) && !name.startsWith('.'))
       .sort()
   } catch {
-    return 0
+    return { approved: 0, status: null }
   }
-  if (names.length === 0) return 0
+  if (names.length === 0) return { approved: 0, status: null }
   const scripts = {}
   for (const name of names) {
     scripts[name] = createHash('sha256')
-      .update(readFileSync(join(dir, name)))
+      .update(readFileSync(join(srcDir, name)))
       .digest('hex')
   }
   const payload = `${JSON.stringify({ version: 1, scripts }, null, 2)}\n`
-  writeIfChanged(join(dir, 'manifest.json'), payload, dryRun)
-  return names.length
+  const status = writeIfChanged(join(dstDir, 'manifest.json'), payload, dryRun, { recorder })
+  return { approved: names.length, status }
 }
 
 function readJsonConfig(filePath) {
@@ -103,6 +433,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 +482,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 +520,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 +549,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 +638,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 +729,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,42 +762,41 @@ 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]
  * @param {boolean} [opts.isGlobal=false] - flat global layout vs .opencode/
  * @param {boolean} [opts.dryRun=false]
+ * @param {(change: object) => void} [opts.recorder] - optional change recorder for preview
  * @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', recorder = null } = {},
+) {
   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, recorder })
   }
 
   // 2. Clean stale Pantheon TUI refs from every location OpenCode reads.
@@ -383,11 +809,17 @@ export function syncTuiRegistration(target, { isGlobal = false, dryRun = false }
     unregisterPlugin(tuiConfigPath, 'plugins/pantheon-tui', {
       dryRun,
       knownPantheonPaths: [ownedCopy, tuiCopyDir],
+      recorder,
     })
   }
 
+  // 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 })
+  return registerPlugin(targetTuiConfigPath, tuiCopyDir, { dryRun, recorder })
 }
 
 /**
@@ -396,13 +828,18 @@ export function syncTuiRegistration(target, { isGlobal = false, dryRun = false }
  * 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 = {}) {
+export function setupRuntimePhase(
+  target,
+  { dryRun, clean, isGlobal, recorder = null },
+  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 })
+    setup(target, { dryRun, force: clean, recorder })
     venvSpinner(true)
     const runtimeTarget = isGlobal ? target : join(target, '.opencode')
     const health = check(runtimeTarget, { dryRun, pythonTarget: target })
@@ -429,12 +866,206 @@ 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 }
+}
+
+/**
+ * Phase 4 drift detection: the planned targets whose on-disk state changed
+ * between the plan pass (snapshots) and the apply pass. A path counts as drifted
+ * when its existence, content hash, size, or mode differs — which includes a
+ * planned-NEW path that now exists. Returns the absolute paths (empty = no
+ * drift); callers print only these paths, never contents or hashes.
+ */
+function detectSnapshotDrift(snapshots) {
+  if (!Array.isArray(snapshots)) return []
+  const changed = []
+  for (const before of snapshots) {
+    const now = snapshot(before.path)
+    if (
+      now.exists !== before.exists ||
+      now.sha256 !== before.sha256 ||
+      now.size !== before.size ||
+      now.mode !== before.mode
+    ) {
+      changed.push(before.path)
+    }
+  }
+  return changed
+}
+
+/**
+ * Remove lingering atomic-write temp siblings (`<file>.tmp-<pid>`) left behind
+ * when a writer aborted mid-write. Best-effort; skips the bulk dirs so a failure
+ * path stays cheap.
+ */
+/**
+ * Remove lingering atomic-write temp siblings (`<file>.tmp-<pid>`) left when a
+ * writer aborted mid-write. Only files matching the installer's own temp
+ * pattern are removed, and the bulk/foreign dirs are skipped so a failure path
+ * stays cheap and never touches unrelated files.
+ */
+function cleanupTempSiblings(root) {
+  if (!root) return
+  const suffix = `.tmp-${process.pid}`
+  const skip = new Set(['.git', '.pantheon', 'node_modules', '.venv'])
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (skip.has(entry.name)) continue
+        walk(join(dir, entry.name))
+      } else if (entry.isFile() && entry.name.endsWith(suffix)) {
+        try {
+          rmSync(join(dir, entry.name), { force: true })
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    }
+  }
+  walk(root)
+}
+
+/**
+ * Phase 5 failure semantics. `installPass` is the whole installer; this thin
+ * wrapper reports a mid-apply failure HONESTLY: it aborts the remaining writes
+ * (the throw), cleans up any lingering atomic-write temp siblings, reports the
+ * PATHS already applied (never contents), prints the recovery path, and
+ * re-throws so the CLI exits non-zero. There is NO automatic rollback — the
+ * exact backup set + `pantheon-opencode restore` is the recovery.
+ *
+ * Progress is tracked in `_lastRun` (set only by a non-dry pass, so the nested
+ * dry plan pass never clobbers it). The RESOLVED target is read back from
+ * `_lastRun.target` so the report and the sweep work when the caller passed
+ * `undefined` (the default global install resolves to `~/.config/opencode`).
+ */
+let _lastRun = null
+
 export async function installOpenCode(
   target,
   dryRun = false,
   clean = false,
   components = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime'],
   opts = {},
+) {
+  // Reset per-call so a stale run can never leak into a fresh failure report.
+  if (!dryRun) _lastRun = null
+  try {
+    return await installPass(target, dryRun, clean, components, opts)
+  } catch (err) {
+    const run = dryRun ? null : _lastRun
+    if (run) {
+      const S = strings()
+      const paths = summarizeChanges(run.entries ?? [])
+        .files.filter((f) => f.action !== ACTIONS.UNCHANGED && f.action !== ACTIONS.CONFLICT)
+        .map((f) => displayPath(run.target, f.path))
+      error(S.applyFailed(err instanceof Error ? err.message : String(err)))
+      if (paths.length > 0) {
+        warning(S.alreadyApplied)
+        for (const p of paths) warning(`  ${p}`)
+      }
+      warning(run.backupDir ? S.restoreRecoveryHint(run.backupDir) : S.restoreNoBackup)
+      // Sweep only on the failure path (never a full walk on a clean apply).
+      cleanupTempSiblings(run.target)
+    }
+    throw err
+  }
+}
+
+async function installPass(
+  target,
+  dryRun = false,
+  clean = false,
+  components = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime'],
+  opts = {},
 ) {
   // Default target if not provided (global ~/.config/opencode)
   if (!target) {
@@ -443,19 +1074,69 @@ export async function installOpenCode(
 
   const componentSet = new Set(components)
   const stats = summary.opencode
+  // Per-call baseline. `stats` is the module-level cumulative summary, so the
+  // consistency guard must compare against THIS call's delta, not the total.
+  const statsBefore = { created: stats.created, skipped: stats.skipped }
+  // Number of planned changes, filled by a dry plan pass (used by the gate).
+  let plannedChanges = 0
+  // Phase 4: planned-target snapshots from the plan pass, used for drift checks.
+  let plannedSnapshots = null
   const S = strings()
 
+  // Beta 11 (Setup phase 1): a dry pass records every writer's intended change
+  // so we can print the REAL per-file plan without writing anything. A recorder
+  // ALWAYS runs now: a dry pass builds the preview/plan from it, and an apply
+  // pass uses it to report which PATHS were already written if a writer throws
+  // (Phase 5 failure semantics). The default is the module-level no-op recorder,
+  // so an uninstrumented caller stays byte-identical.
+  const ownRecorder = opts.recorder ? null : createRecorder()
+  const preview = dryRun && ownRecorder ? ownRecorder : null
+  let recorder = opts.recorder ?? ownRecorder.recorder
+  // Test-only failure seam: throw after N recorded writes so the failure path is
+  // deterministic. Never reachable from production callers (opts.deps is not a
+  // CLI flag) and never applied to the internal dry plan pass.
+  if (!dryRun && typeof opts.deps?.failAfter === 'number') {
+    const base = recorder
+    const limit = opts.deps.failAfter
+    let applied = 0
+    recorder = (change) => {
+      base(change)
+      if (++applied >= limit) throw new Error('injected failure (test-only failAfter seam)')
+    }
+  }
+  // Track this apply so the wrapper can report the paths written on a failure.
+  if (!dryRun) _lastRun = { target, entries: ownRecorder?.entries ?? [], backupDir: null }
+
   // 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')
+  // 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
@@ -474,7 +1155,7 @@ export async function installOpenCode(
 
     if (!result.confirmed && !autoYes) {
       info('Installation canceled.')
-      return stats
+      return { ...stats, applied: false, reason: 'canceled' }
     }
 
     // Map target selection to actual path
@@ -487,10 +1168,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,16 +1198,116 @@ 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, quiet: opts.quiet === true })
+
+  // -----------------------------------------------------------------------
+  // Plan pass + apply gate + drift check (Beta 11 Setup phases 3-4).
+  //   * the plan pass (a dry run — writes nothing) prints the plan and
+  //     snapshots every planned target;
+  //   * applying requires explicit authorization (Phase 3): a declined or
+  //     unauthorized run writes NOTHING;
+  //   * drift (Phase 4) aborts BEFORE any write if a planned target changed
+  //     between the plan pass and now.
+  // A result with `applied: false` means the caller must not print success.
+  // -----------------------------------------------------------------------
+  const applyRequested = !dryRun
+  if (applyRequested) {
+    const savedStats = { ...stats }
+    let planned
+    try {
+      // Use the LIVE selection: the wizard above may have changed componentSet.
+      // An AUTHORIZED apply (`--yes`) is not a preview: compute the plan +
+      // snapshots but stay silent. The gate path (no `--yes`) still prints the
+      // plan for the review / decline preview.
+      planned = await installOpenCode(target, true, clean, [...componentSet], {
+        ...opts,
+        planOnly: true,
+        quiet: autoYes,
+        quietPlan: autoYes,
+      })
+    } finally {
+      Object.assign(stats, savedStats)
+      // The plan pass left the UI in dry-run mode; restore this run's mode.
+      configure({ dryRun, quiet: opts.quiet === true })
+    }
+    plannedSnapshots = planned?.snapshots ?? null
+
+    if (!autoYes) {
+      const injected = opts.deps?.promptReview
+      const canPrompt = typeof injected === 'function' || interactive
+      if (canPrompt) {
+        const { promptReview } = await import('./interactive.mjs')
+        const ask = typeof injected === 'function' ? injected : promptReview
+        const accepted = await ask(`Apply these ${planned?.planned ?? 0} changes?`, {
+          default: false,
+        })
+        if (!accepted) {
+          info(S.nothingApplied)
+          return { ...stats, applied: false, reason: 'declined' }
+        }
+      } else {
+        info(S.planOnlyNoYes)
+        return { ...stats, applied: false, reason: 'not-authorized' }
+      }
+    }
 
-  configure({ dryRun })
+    // Test seam: mutate a target between the plan/authorization and the drift
+    // check. Absent in production callers.
+    if (typeof opts.deps?.betweenPlanAndApply === 'function') opts.deps.betweenPlanAndApply()
+
+    const drifted = detectSnapshotDrift(plannedSnapshots)
+    if (drifted.length > 0) {
+      warning(S.driftHeader)
+      for (const p of drifted) warning(`  ${displayPath(target, p)}`)
+      warning(S.driftAbort)
+      return {
+        ...stats,
+        applied: false,
+        reason: 'drift',
+        drift: drifted.map((p) => displayPath(target, p)),
+      }
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // 0. Exact backup (Beta 11 Setup phase 2): preserve the CURRENT state of
+  //    every regular file this run can modify/remove INSIDE the config dir,
+  //    byte-for-byte, BEFORE the first modifying write. Bulk directories and
+  //    out-of-target global files are recorded in the manifest as
+  //    `notRevertible`. A dry run records the planned backup-manifest path only.
+  // -----------------------------------------------------------------------
+  const backupManifestPath = join(
+    backupSetPath(target, nextBackupName(target, new Date())),
+    'manifest.json',
+  )
+  if (dryRun) {
+    if (isRecording(recorder)) {
+      recordChange(
+        { path: backupManifestPath, action: ACTIONS.CREATE, bytes: 0, scored: false },
+        recorder,
+      )
+    }
+  } else {
+    const backupPlan = collectInstallBackupEntries(target, componentSet, version, isGlobal)
+    const pkgVersion = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version
+    const { dir: backupDir } = createBackupSet({
+      configDir: target,
+      entries: backupPlan.entries,
+      notRevertible: backupPlan.notRevertible,
+      packageVersion: pkgVersion,
+    })
+    if (_lastRun && _lastRun.target === target) _lastRun.backupDir = backupDir
+    // Secret-safe: the path only. The exact wording is fixed (once per apply).
+    console.warn(backupWarning(backupDir))
+  }
 
   if (isGlobal) {
     info(S.globalLayout)
@@ -529,7 +1324,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 +1332,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, false, recorder)
       stats.created += created
       stats.skipped += skipped
       agentStep(true)
@@ -551,7 +1346,9 @@ export async function installOpenCode(
     const srcRouting = join(ROOT, 'src', 'routing.yml')
     const dstRouting = join(target, 'routing.yml')
     if (existsSync(srcRouting)) {
-      const routingStatus = writeIfChanged(dstRouting, readFileSync(srcRouting, 'utf8'), dryRun)
+      const routingStatus = writeIfChanged(dstRouting, readFileSync(srcRouting, 'utf8'), dryRun, {
+        recorder,
+      })
       if (routingStatus === 'created') stats.created++
       else stats.skipped++
     }
@@ -578,6 +1375,7 @@ export async function installOpenCode(
         target,
         dryRun,
         installSubDir,
+        recorder,
       )
       stats.created += sCreated
       stats.skipped += sSkipped
@@ -586,23 +1384,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, recorder)
+      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, recorder)
+        stats.created += refreshed.created
+        stats.skipped += refreshed.skipped
+      }
     }
   }
 
@@ -614,7 +1434,7 @@ export async function installOpenCode(
     const srcPrompts = join(ROOT, 'prompts')
     const dstPrompts = join(target, 'prompts')
     if (existsSync(srcPrompts)) {
-      const promptsResult = syncDir(srcPrompts, dstPrompts, dryRun, clean)
+      const promptsResult = syncDir(srcPrompts, dstPrompts, dryRun, clean, null, recorder)
       stats.created += promptsResult.created
       stats.skipped += promptsResult.skipped
     }
@@ -626,9 +1446,13 @@ 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'))
+      const cmdResult = syncDir(srcCmds, dstCmds, dryRun, clean, (f) => f.endsWith('.md'), recorder)
       stats.created += cmdResult.created
       stats.skipped += cmdResult.skipped
     }
@@ -651,7 +1475,12 @@ 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,
+      recorder,
+    })
     stats.created += pluginStats.created
     stats.skipped += pluginStats.skipped
     stats.errors += pluginStats.errors
@@ -663,7 +1492,7 @@ export async function installOpenCode(
   if (componentSet.has('plugins')) {
     let tuiStatus
     try {
-      tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun })
+      tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun, version, recorder })
     } catch (cause) {
       error(`TUI plugin setup failed: ${cause.message}`)
       stats.errors++
@@ -682,31 +1511,21 @@ export async function installOpenCode(
     const runtimeTarget = isGlobal ? target : join(target, '.opencode')
 
     // ── MCP server scripts ──
-    const mcpScripts = [
-      'mcp_resources_server.py',
-      'code_mode_server.py',
-      'memory_mcp_server.py',
-      'scrub-secrets.py',
-      '_pantheon_paths.py',
-      'mcp_codemap_module.py',
-      'mcp_persistence_server.py',
-      'pantheon_vision_server.py',
-      'eval_store.py',
-    ]
+    const mcpScripts = MCP_SCRIPTS
     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')
@@ -720,7 +1539,7 @@ export async function installOpenCode(
       }
       const content = readFileSync(src, 'utf8')
       const dst = join(dstScriptsDir, script)
-      const status = writeIfChanged(dst, content, dryRun)
+      const status = writeIfChanged(dst, content, dryRun, { recorder })
       if (status === 'created') {
         stats.created++
         // Make executable
@@ -738,7 +1557,9 @@ export async function installOpenCode(
     const visionRequirements = join(ROOT, 'src', 'mcp', 'requirements-vision.txt')
     if (existsSync(visionRequirements)) {
       const destination = join(runtimeTarget, 'requirements-vision.txt')
-      const status = writeIfChanged(destination, readFileSync(visionRequirements, 'utf8'), dryRun)
+      const status = writeIfChanged(destination, readFileSync(visionRequirements, 'utf8'), dryRun, {
+        recorder,
+      })
       if (status === 'created') stats.created++
       else stats.skipped++
     } else {
@@ -750,7 +1571,17 @@ export async function installOpenCode(
     const srcCodeModeDir = join(ROOT, '.pantheon', 'code-mode')
     const dstCodeModeDir = join(runtimeTarget, '.pantheon', 'code-mode')
     if (existsSync(srcCodeModeDir)) {
-      const cmResult = syncDir(srcCodeModeDir, dstCodeModeDir, dryRun, clean)
+      // manifest.json is owned by writeCodeModeManifest (below), not by the dir
+      // sync. Excluding it here keeps exactly ONE writer/count for that path,
+      // so the preview action and the install summary can never diverge.
+      const cmResult = syncDir(
+        srcCodeModeDir,
+        dstCodeModeDir,
+        dryRun,
+        clean,
+        (f) => f !== 'manifest.json',
+        recorder,
+      )
       stats.created += cmResult.created
       stats.skipped += cmResult.skipped
     } else {
@@ -761,13 +1592,18 @@ export async function installOpenCode(
       warning(`Code-mode source not found: ${srcCodeModeDir} — creating empty ${dstCodeModeDir}`)
       if (!dryRun) mkdirSync(dstCodeModeDir, { recursive: true })
       stats.created++
+      // The empty runtime dir is a real create counted by `stats.created`, so
+      // record it too (or the preview under-reports on this fallback path).
+      recordChange({ path: dstCodeModeDir, action: ACTIONS.CREATE, bytes: 0 }, recorder)
     }
 
     // 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`)
+    const manifest = writeCodeModeManifest(srcCodeModeDir, dstCodeModeDir, dryRun, recorder)
+    if (manifest.status === 'created') stats.created++
+    else if (manifest.status === 'skipped') stats.skipped++
+    if (manifest.approved > 0) {
+      info(`Code-mode manifest: ${manifest.approved} script(s) approved`)
     }
 
     // ── tiers.json ──
@@ -775,7 +1611,7 @@ export async function installOpenCode(
     const dstTiers = join(runtimeTarget, '.pantheon', 'tiers.json')
     if (existsSync(srcTiers)) {
       const content = readFileSync(srcTiers, 'utf8')
-      const status = writeIfChanged(dstTiers, content, dryRun)
+      const status = writeIfChanged(dstTiers, content, dryRun, { recorder })
       if (status === 'created') stats.created++
       else stats.skipped++
     }
@@ -789,7 +1625,7 @@ export async function installOpenCode(
   // -----------------------------------------------------------------------
   let runtimeHealthy = !componentSet.has('runtime')
   if (componentSet.has('runtime')) {
-    runtimeHealthy = setupRuntimePhase(target, { dryRun, clean, isGlobal }, stats)
+    runtimeHealthy = setupRuntimePhase(target, { dryRun, clean, isGlobal, recorder }, stats)
   }
 
   // -----------------------------------------------------------------------
@@ -798,7 +1634,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 +1672,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 +1682,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 +1696,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 +1754,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 +1800,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 +1821,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 +1850,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 +1886,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 +1962,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 +1971,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 +2018,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 +2039,53 @@ 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,
+    recorder,
+  })
+  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 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++
 
@@ -1235,7 +2095,7 @@ export async function installOpenCode(
   if (componentSet.has('runtime')) {
     const currentVersion = detectVersion(target)
     if (currentVersion) {
-      const migration = runMigrations(target, currentVersion, { dryRun })
+      const migration = runMigrations(target, currentVersion, { dryRun, recorder })
       if (migration.applied > 0) {
         success(`Applied ${migration.applied} migration(s)`)
         for (const msg of migration.messages) {
@@ -1245,6 +2105,56 @@ export async function installOpenCode(
     }
   }
 
+  // -----------------------------------------------------------------------
+  // 3.75 Preview summary (Beta 11 Setup phase 1): print the REAL per-file
+  //      change set this same pass would apply. Paths + action + byte size
+  //      ONLY — never file contents or hashes. Nothing was written.
+  // -----------------------------------------------------------------------
+  if (preview) {
+    // Apply always writes the install-state file (terminal step); record the
+    // planned state-only write here so the printed plan is complete. Unscored:
+    // it is bookkeeping, not part of the install summary.
+    recordChange(
+      {
+        path: join(target, '.pantheon', 'install-state.json'),
+        action: hasState(target) ? ACTIONS.UPDATE : ACTIONS.CREATE,
+        bytes: 0,
+        scored: false,
+      },
+      recorder,
+    )
+    const plan = summarizeChanges(preview.entries)
+    plannedChanges = plan.totals.create + plan.totals.update + plan.totals.remove
+    // Phase 4: snapshot each planned target now, so the apply pass can detect
+    // any change between plan and apply (drift) before the first write.
+    plannedSnapshots = plan.files.map((f) => ({ path: f.path, ...snapshot(f.path) }))
+    const statsDelta = {
+      created: stats.created - statsBefore.created,
+      skipped: stats.skipped - statsBefore.skipped,
+    }
+    const mismatch = planStatsMismatch(plan, statsDelta)
+    if (mismatch) {
+      // Development safety net: a writer that incremented THIS call's install
+      // stats but never recorded a change would otherwise make the preview
+      // silently incomplete. Surface it loudly instead of hiding it.
+      warning(
+        `Change-plan consistency mismatch: plan reports ${mismatch.changed} changed / ` +
+          `${mismatch.unchanged} unchanged vs stats ${mismatch.recordedChanged}/${mismatch.recordedUnchanged}`,
+      )
+    }
+    // Tag the plan like every other dry-run line so the output reads uniformly.
+    // An internal snapshot pass on the apply path (`quietPlan`, e.g. an
+    // authorized `--yes` run) computes the plan and snapshots but must NOT echo
+    // it — a real apply is not a dry run.
+    if (!opts.quietPlan) {
+      console.log('')
+      for (const line of formatChangePlan(target, plan).split('\n')) {
+        console.log(tag(line))
+      }
+      console.log('')
+    }
+  }
+
   // -----------------------------------------------------------------------
   // 4. (runtime setup moved to 2.11 — before the config write — so MCP
   //    entries are only added when the Python runtime is actually healthy)
@@ -1284,7 +2194,7 @@ export async function installOpenCode(
       `  ${colors.dim('\u2022')} Run 'opencode' to start using Pantheon agents\n`,
     )
     process.stdout.write('\n')
-  } else {
+  } else if (!opts.planOnly) {
     printSummary(target, ['opencode'], stats)
   }
 
@@ -1304,9 +2214,59 @@ 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)
+  }
+
+  // Beta 11 Setup phase 3: report whether this call APPLIED, so the caller can
+  // avoid a success banner for a plan-only / unauthorized run. The dry pass also
+  // returns the planned-target snapshots for the apply pass's drift check.
+  return dryRun
+    ? {
+        ...stats,
+        applied: false,
+        reason: 'plan',
+        planned: plannedChanges,
+        snapshots: plannedSnapshots,
+      }
+    : { ...stats, applied: true, reason: 'applied' }
 }