pantheon-opencode 1.6.0-beta.5 → 1.6.0-beta.7

package/scripts/install/config-migration.mjs

@@ -34,10 +34,22 @@ const V1_PERMISSION_TO_ACTION = {
   bash: 'shell',
   skill: 'skill',
   edit: 'edit',
+  // V2 folds V1's `write` tool permission into the `edit` action, which also
+  // governs write and patch tools. Keep `edit` as the canonical reverse name.
+  write: 'edit',
+  task: 'subagent',
   websearch: 'websearch',
   // passthrough unknowns
 }
 
+const V2_ACTION_TO_V1_PERMISSION = {
+  shell: 'bash',
+  skill: 'skill',
+  edit: 'edit',
+  subagent: 'task',
+  websearch: 'websearch',
+}
+
 /**
  * Convert V1 permission object to V2 permissions array.
  *
@@ -49,15 +61,41 @@ const V1_PERMISSION_TO_ACTION = {
  */
 function convertPermissionsV1toV2(permObj) {
   const result = []
+  const resultIndices = new Map()
+  const effectRank = { allow: 0, ask: 1, deny: 2 }
+
+  const appendPermission = (action, resource, effect) => {
+    const key = JSON.stringify([action, resource])
+    const previousIndex = resultIndices.get(key)
+    if (previousIndex === undefined) {
+      resultIndices.set(key, result.length)
+      result.push({ action, resource, effect })
+      return
+    }
+
+    const previous = result[previousIndex]
+    if (previous.effect === effect) return
+
+    // V1 keeps `edit` and `write` as separate permission keys; V2's `edit`
+    // action covers both. If their rules collide on one resource, retain the
+    // stricter effect rather than letting object order turn a deny into allow.
+    console.warn(
+      `[config-migration] Conflicting V1 permission aliases for ${action}:${resource}; keeping the more restrictive effect`,
+    )
+    if ((effectRank[effect] ?? 0) > (effectRank[previous.effect] ?? 0)) {
+      previous.effect = effect
+    }
+  }
+
   for (const [key, value] of Object.entries(permObj)) {
     const action = V1_PERMISSION_TO_ACTION[key] || key
     if (typeof value === 'string') {
       // Simple: { edit: "allow" } → [{ action: "edit", resource: "*", effect: "allow" }]
-      result.push({ action, resource: '*', effect: value })
+      appendPermission(action, '*', value)
     } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
       // Nested: { bash: { "git *": "allow" } } → [{ action: "shell", resource: "git *", effect: "allow" }]
       for (const [resource, effect] of Object.entries(value)) {
-        result.push({ action, resource, effect })
+        appendPermission(action, resource, effect)
       }
     } else {
       console.warn(`[config-migration] Unexpected permission value for "${key}":`, value)
@@ -71,13 +109,9 @@ function convertPermissionsV1toV2(permObj) {
  */
 function convertPermissionsV2toV1(permArray) {
   const result = {}
-  // Reverse action mapping: V2 action → V1 key
-  const ACTION_TO_V1 = Object.fromEntries(
-    Object.entries(V1_PERMISSION_TO_ACTION).map(([k, v]) => [v, k]),
-  )
 
   for (const { action, resource, effect } of permArray) {
-    const v1Key = ACTION_TO_V1[action] || action
+    const v1Key = V2_ACTION_TO_V1_PERMISSION[action] || action
     if (resource === '*') {
       result[v1Key] = effect
     } else {
@@ -490,6 +524,119 @@ function mergeManagedAgents(base, managed) {
   return merged
 }
 
+// ---------------------------------------------------------------------------
+// context_sandbox: V1 top-level block → V2 plugin options
+// ---------------------------------------------------------------------------
+//
+// `context_sandbox` is a Pantheon-owned, V1 top-level setting (src/plugin.ts
+// reads `config.context_sandbox`). OpenCode V2 no longer carries custom
+// top-level keys: a sandbox probe against V2.0.25 showed `context_sandbox`
+// exits 0 but is SILENTLY DROPPED — identical to an arbitrary unknown key and
+// with no warning — while a value nested under a plugin entry's `options`
+// survives verbatim (plugin options are not schema-validated). The V2 adapter
+// reads the setting as `ctx.options.context_sandbox`.
+//
+// So the migration DUPLICATES the V1 top-level block into the exact Pantheon V2
+// plugin entry's options. The top-level block is deliberately LEFT IN PLACE so
+// a user who downgrades to V1 keeps the setting. Precedence per leaf:
+//   explicit V2 plugin option  >  legacy top-level fill  >  runtime defaults
+// (defaults are never written by the installer — the adapter resolves them).
+//
+// A null or type-invalid known field is not silently coerced: the merge throws
+// BEFORE the config is written, so a malformed block aborts the install instead
+// of persisting a value that changes runtime behaviour.
+
+/** Tool-keyed leaf fields of `context_sandbox.limits`. */
+export const CONTEXT_SANDBOX_LIMIT_FIELDS = Object.freeze({
+  read: Object.freeze(['maxLines', 'keepHead', 'keepTail']),
+  grep: Object.freeze(['maxResults', 'keepTop']),
+  glob: Object.freeze(['maxFiles', 'keepTop']),
+  webfetch: Object.freeze(['maxChars', 'keepHead']),
+})
+
+/** @returns {boolean} true for a plain name→value map (not null/array) */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Validate one `context_sandbox` block (top-level legacy or V2 plugin option).
+ *
+ * `undefined` (key absent) is valid. Anything else must be a plain object with
+ * an optional boolean `enabled` and an optional `limits` object whose known
+ * tool groups are plain objects carrying only non-negative finite numbers.
+ * Unknown keys are ignored (the runtime resolver does the same).
+ *
+ * @param {unknown} block
+ * @param {string} label - human-readable origin, used in the thrown message
+ * @throws {Error} on a null or type-invalid known field
+ */
+function assertSandboxBlock(block, label) {
+  if (block === undefined) return
+  if (!isPlainObject(block)) {
+    throw new Error(`${label} must be an object when present`)
+  }
+  if ('enabled' in block && typeof block.enabled !== 'boolean') {
+    throw new Error(`${label}.enabled must be a boolean`)
+  }
+  if ('limits' in block) {
+    if (!isPlainObject(block.limits)) {
+      throw new Error(`${label}.limits must be an object`)
+    }
+    for (const [tool, fields] of Object.entries(CONTEXT_SANDBOX_LIMIT_FIELDS)) {
+      const group = block.limits[tool]
+      if (group === undefined) continue
+      if (!isPlainObject(group)) {
+        throw new Error(`${label}.limits.${tool} must be an object`)
+      }
+      for (const field of fields) {
+        if (!(field in group)) continue
+        const value = group[field]
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+          throw new Error(`${label}.limits.${tool}.${field} must be a non-negative number`)
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Merge a legacy (V1 top-level) context_sandbox block into an optional explicit
+ * V2 block. Values are compared per leaf, so `enabled: false` and a numeric `0`
+ * are preserved (not mistaken for "unset").
+ *
+ * @param {object|undefined} v2Explicit - existing `plugins[...].options.context_sandbox`
+ * @param {object|undefined} legacy - top-level `context_sandbox`
+ * @returns {object} merged block (only keys that were actually set)
+ * @throws {Error} when either block is null/type-invalid
+ */
+export function mergeContextSandboxBlocks(v2Explicit, legacy) {
+  assertSandboxBlock(v2Explicit, 'plugins[...].options.context_sandbox')
+  assertSandboxBlock(legacy, 'context_sandbox')
+
+  const explicit = isPlainObject(v2Explicit) ? v2Explicit : {}
+  const base = isPlainObject(legacy) ? legacy : {}
+  const merged = {}
+
+  if ('enabled' in explicit) merged.enabled = explicit.enabled
+  else if ('enabled' in base) merged.enabled = base.enabled
+
+  const mergedLimits = {}
+  for (const [tool, fields] of Object.entries(CONTEXT_SANDBOX_LIMIT_FIELDS)) {
+    const explicitGroup = isPlainObject(explicit.limits?.[tool]) ? explicit.limits[tool] : null
+    const baseGroup = isPlainObject(base.limits?.[tool]) ? base.limits[tool] : null
+    const group = {}
+    for (const field of fields) {
+      if (explicitGroup && field in explicitGroup) group[field] = explicitGroup[field]
+      else if (baseGroup && field in baseGroup) group[field] = baseGroup[field]
+    }
+    if (Object.keys(group).length > 0) mergedLimits[tool] = group
+  }
+  if (Object.keys(mergedLimits).length > 0) merged.limits = mergedLimits
+
+  return merged
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/scripts/install/opencode.mjs

@@ -21,6 +21,7 @@ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } f
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { listV2UnsupportedFeatures } from '../../src/pantheon/v2-unsupported.mjs'
+import { copyAgentPrompts } from '../build-agents-md.mjs'
 import {
   bullet,
   colors,
@@ -34,7 +35,11 @@ import {
   success,
   warning,
 } from './cli-ui.mjs'
-import { migrateMcpEntrypointPaths, 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'
@@ -42,7 +47,6 @@ import { copyPluginFiles, installPlugin, registerPlugin, unregisterPlugin } from
 import {
   checkRuntimePrerequisites,
   collectSkillNames,
-  copyFiles,
   installSkills,
   parseFrontmatter,
   ROOT,
@@ -173,6 +177,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)
@@ -201,23 +226,26 @@ function mergeMissing(target, source) {
 }
 
 /**
- * Resolve a plugin ref from the repository-root opencode.json to a path INSIDE
- * the installed package.
+ * Resolve a plugin ref from the repository-root opencode.json to its stable
+ * installed form.
  *
  * Only exact Pantheon plugin identities are resolved into the installed
  * package. In particular, a third-party absolute path ending in
  * `src/plugin.ts` or `src/plugins/pantheon-hooks.ts` is not evidence that the
- * plugin belongs to Pantheon and must be preserved verbatim.
+ * plugin belongs to Pantheon and must be preserved verbatim. V1 remains a pair
+ * of package-local paths; V2 uses an exact npm version so it is independent of
+ * the installer's global prefix or transient npx cache.
  */
 export function resolveInstalledPlugin(plugin) {
   if (typeof plugin !== 'string') return plugin
   const normalized = normalizePluginRef(plugin)
+  if (normalized === PANTHEON_V2_PLUGIN || normalized === PANTHEON_V2_LEGACY_FILE) {
+    return PANTHEON_V2_PACKAGE_SPEC
+  }
   if (PANTHEON_PLUGIN_IDENTITIES.has(normalized)) return join(ROOT, normalized)
-  // Legacy V2 file ref (pre-directory-contract): migrate to the installed
-  // plugin directory so the beta loader accepts the entry.
-  if (normalized === PANTHEON_V2_LEGACY_FILE) return join(ROOT, PANTHEON_V2_PLUGIN)
   const identity = managedPluginIdentity(plugin)
   if (identity !== null && isAbsolute(normalized)) {
+    if (identity === PANTHEON_V2_PLUGIN) return PANTHEON_V2_PACKAGE_SPEC
     return INSTALLED_PANTHEON_PLUGIN_PATHS.get(identity) ?? plugin
   }
   return plugin
@@ -239,6 +267,14 @@ 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 PACKAGE_MANIFEST = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+const PANTHEON_V2_PACKAGE_SPEC = `${PACKAGE_MANIFEST.name}@${PACKAGE_MANIFEST.version}`
+// Installation origin probe: npm copies (global prefix, npx cache) always live
+// under a `node_modules` directory; a repo checkout does not. From a checkout —
+// or between a version bump and its publish — the V2 pin above names a version
+// that may not exist on the npm registry yet, and the host cannot resolve it
+// until publish. Advisory only: the install itself is structurally correct.
+const RUNNING_FROM_NPM_INSTALL = import.meta.url.includes('/node_modules/')
 const PANTHEON_PLUGIN_IDENTITIES = new Set([
   PANTHEON_V1_PLUGIN,
   PANTHEON_V1_HOOKS,
@@ -272,6 +308,9 @@ function managedPluginIdentity(ref) {
   if (normalized === PANTHEON_V1_EXPORT || normalized.startsWith(`${PANTHEON_V1_EXPORT}@`)) {
     return PANTHEON_V1_PLUGIN
   }
+  if (normalized === PACKAGE_MANIFEST.name || normalized.startsWith(`${PACKAGE_MANIFEST.name}@`)) {
+    return PANTHEON_V2_PLUGIN
+  }
   if (normalized === PANTHEON_V2_EXPORT || normalized.startsWith(`${PANTHEON_V2_EXPORT}@`)) {
     return PANTHEON_V2_PLUGIN
   }
@@ -345,6 +384,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'
 
 /**
@@ -675,7 +779,7 @@ export async function installOpenCode(
   const pantheonConfigPath =
     typeof mergeDevConfigOpt === 'string' ? resolve(mergeDevConfigOpt) : null
   const targetConfigPath = join(target, 'opencode.json')
-  const config = readJsonConfig(targetConfigPath)
+  const { config, raw: configRaw } = readJsonConfigWithRaw(targetConfigPath)
   const pantheonConfig =
     pantheonConfigPath !== null && existsSync(pantheonConfigPath)
       ? readJsonConfig(pantheonConfigPath)
@@ -726,7 +830,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)
@@ -775,11 +879,12 @@ 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
+  // generated file embeds shared instructions; agent-scoped instructions are
+  // already rendered into supported agent prompt markdown during copy. The
+  // individual source fragments are NOT copied (nothing references
   // <config>/instructions/ after the section-D merge fix — copying them would
   // just leave stale duplicates on disk).
   if (componentSet.has('instructions')) {
@@ -793,6 +898,20 @@ export async function installOpenCode(
       if (status === 'created') stats.created++
       else stats.skipped++
     }
+    // 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 = isGlobal
+        ? join(target, 'agents')
+        : join(target, '.opencode', 'agents')
+      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
+      }
+    }
   }
 
   // -----------------------------------------------------------------------
@@ -987,7 +1106,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) {
@@ -1147,16 +1266,12 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // B.5.1 Hermetic plugin resolution (packaging fix)
   // --------------------------------------------------------------------
-  // 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
-  // file inside the INSTALLED package (derived from ROOT — never hardcoded),
-  // so both dev and global installs resolve to a path that actually exists.
-  // The source opencode.json keeps its dev path for local development; the
-  // transform happens at install/sync time only.
+  // A developer running from a checkout may have a repository-root
+  // opencode.json with machine-specific plugin paths. V1 rewrites its two
+  // managed entries to paths under the installed package. V2 instead writes
+  // the exact package-root npm spec so it survives global-prefix and npx-cache
+  // changes; a source-checkout V2 install warns that the version may not yet
+  // exist on npm. Third-party paths remain untouched in either generation.
 
   if (version === 'v1') {
     // V1 loads the singular `plugin` list. Remove every Pantheon V2 entry from
@@ -1197,6 +1312,18 @@ 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)) {
       for (const plugin of pantheonConfig.plugins) {
@@ -1205,23 +1332,22 @@ export async function installOpenCode(
         }
       }
     }
-    // The beta resolves every `plugins` entry through npm install, so an
-    // `a/b` shorthand (e.g. the published `pantheon-opencode/plugin-v2`
-    // export) is treated as a GitHub repo and dies with NpmInstallFailedError
-    // (beta log evidence). The beta loader additionally requires each entry
-    // to be a DIRECTORY with a real index.js/index.ts — a file path warns
-    // "must be a directory" and a symlink is ignored (sandbox probe
-    // evidence). Register the V2 plugin DIRECTORY inside the INSTALLED
-    // package — exactly like V1's ensurePantheonPlugin, but pointing at
-    // src/plugin-v2 whose index.ts shim re-exports the real entry.
-    // Legacy refs (npm shorthand, the old src/plugin-v2.ts file path) are
-    // recognized via managedPluginIdentity and already stripped above, so
-    // they migrate here.
+    // V2 plugin entries are resolved by OpenCode as npm packages. Pin the
+    // exact current version and use the package-root export, which is the V2
+    // default plugin. Unlike an absolute path into ROOT, this survives moving
+    // between a global install and an npx cache; unlike an unpinned package,
+    // it cannot silently change underneath an existing config. Legacy local
+    // directory/file refs are recognized via managedPluginIdentity and are
+    // replaced here.
     const resolvedV2 = resolveInstalledPlugin(PANTHEON_V2_PLUGIN)
     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 (pantheonConfig !== null) {
@@ -1302,8 +1428,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']
@@ -1386,10 +1512,46 @@ export async function installOpenCode(
         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,
+    )
+
+    // Bootstrap chicken-and-egg: the pin names the CURRENT package version,
+    // which exists on the registry only after publish. From an npm install
+    // (global prefix / npx cache) that is the published version by
+    // construction; from a repo checkout the pin may point at an unpublished
+    // version the host cannot resolve. Warn instead of failing — the config is
+    // structurally correct and the pin realigns once the version is out.
+    if (!RUNNING_FROM_NPM_INSTALL) {
+      warning(S.v2UnpublishedPin(PANTHEON_V2_PACKAGE_SPEC))
+    }
   }
 
   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++