pantheon-opencode 1.6.0-beta.6 → 1.6.0-beta.8

package/scripts/install/config-migration.mjs

@@ -29,9 +29,10 @@ function deepClone(obj) {
 // V1 → V2 helpers
 // ---------------------------------------------------------------------------
 
-/** Action name mapping for permissions (V1 key → V2 action) */
+/** Action name mapping for permissions (V1 key → V2 action), including task → subagent. */
 const V1_PERMISSION_TO_ACTION = {
   bash: 'shell',
+  task: 'subagent',
   skill: 'skill',
   edit: 'edit',
   websearch: 'websearch',
@@ -490,6 +491,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/interactive.mjs

@@ -329,7 +329,7 @@ export async function runInteractiveInstall({ components = [], defaultComponents
     {
       name: 'skills',
       value: 'skills',
-      description: `Reusable skill workflows (${21} skills)`,
+      description: `Reusable skill workflows (${20} skills)`,
     },
     {
       name: 'instructions',

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,
@@ -131,6 +135,74 @@ export const MANAGED_FIELDS = Object.freeze([
   '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))
 }
@@ -173,6 +245,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)
@@ -239,6 +332,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,
@@ -267,6 +361,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}@`)) {
@@ -345,6 +450,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 +845,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 +896,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 +945,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 +964,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 +1172,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) {
@@ -1035,6 +1220,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
     }
@@ -1197,6 +1388,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) {
@@ -1221,7 +1424,11 @@ 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 (pantheonConfig !== null) {
@@ -1302,8 +1509,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 +1593,36 @@ 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,
+    )
   }
 
   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++
 

package/scripts/install/shared.mjs

@@ -7,6 +7,7 @@ import {
   copyFileSync,
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
@@ -257,17 +258,105 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
   return { created, skipped }
 }
 
-export function writeIfChanged(filePath, content, dryRun) {
-  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null
+/**
+ * `lstat` that returns `null` instead of throwing for an absent path.
+ *
+ * Deliberately `lstat`, not `stat`/`existsSync`: both of those follow the link,
+ * so a DANGLING symlink reads as absent and the atomic rename below would then
+ * silently replace the link itself. `lstat` sees the link and lets the write
+ * guard refuse it.
+ */
+function lstatOrNull(filePath) {
+  try {
+    return lstatSync(filePath)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read a path's raw text, or `null` when it cannot be read (absent, dangling
+ * symlink target, permission error). The caller decides what "unreadable"
+ * means; this never throws.
+ */
+function readFileOrNull(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Atomically create/overwrite a text file, skipping an unchanged write.
+ *
+ * @param {string} filePath - destination path
+ * @param {string} content - full file content
+ * @param {boolean} dryRun - when true, compute the outcome without writing
+ * @param {object} [options]
+ * @param {string|null} [options.expectedContent] - the raw content the caller
+ *   read this path from, if any. When supplied, the write proceeds only if the
+ *   on-disk content STILL matches it — compared once up front AND again
+ *   immediately before the rename; otherwise it returns `'conflict'` and leaves
+ *   the file alone. This is a best-effort COMPARE-BEFORE-WRITE guard, NOT a
+ *   filesystem CAS: the final re-read and the rename are still two syscalls, so
+ *   a writer that lands between them is not prevented. What it does close is
+ *   the window the installer actually races with — a config the caller parsed
+ *   going stale during the same run — and it keeps the target and the `.bak`
+ *   consistent with the bytes that were checked.
+ * @param {(existing: string|null) => void} [options.beforeRecheck] - runs after
+ *   the initial content check and before the last-moment re-read. Injection
+ *   point so tests can simulate a concurrent writer landing in the window;
+ *   production callers omit it (undefined is a no-op).
+ * @param {(existing: string|null) => void} [options.beforeSwap] - runs after the
+ *   expected-content checks pass and immediately before the rename, so side
+ *   effects that must not fire on a conflict (e.g. the `.bak` copy) live here.
+ * @returns {'created'|'skipped'|'conflict'}
+ */
+export function writeIfChanged(filePath, content, dryRun, options = {}) {
+  const { expectedContent, beforeSwap, beforeRecheck } = options
+
+  // Refuse to write through/over a symlink. A dangling symlink is invisible to
+  // existsSync, and rename-over-link would replace the link rather than its
+  // target — both are silent redirections the installer must not perform.
+  const stat = lstatOrNull(filePath)
+  if (stat?.isSymbolicLink()) {
+    throw new Error(`Refusing to write through symlink: ${filePath}`)
+  }
+
+  const existing = stat === null ? null : readFileOrNull(filePath)
   if (existing === content) {
     return 'skipped'
   }
+  if (expectedContent !== undefined && existing !== expectedContent) {
+    // The file changed since the caller read it (or appeared/disappeared).
+    // Do not clobber the newer content; the caller decides how to react.
+    return 'conflict'
+  }
   if (!dryRun) {
+    // Seam for a concurrent writer to land between the read above and the
+    // re-read below. No production caller passes this.
+    if (typeof beforeRecheck === 'function') beforeRecheck(existing)
+
     // Atomic write: write a temp sibling and rename over the target so a
     // crash mid-write can never leave a truncated file behind (rename is
     // atomic within the same directory).
     const tmpPath = `${filePath}.tmp-${process.pid}`
     writeFileSync(tmpPath, content, 'utf8')
+
+    // Last-moment re-read. The initial compare and this rename are separate
+    // syscalls, so a concurrent writer can land in between; re-check the
+    // expected bytes immediately before the swap. On a mismatch, drop the temp
+    // and leave the target AND any existing `.bak` byte-identical.
+    if (expectedContent !== undefined) {
+      const current = readFileOrNull(filePath)
+      if (current !== expectedContent) {
+        rmSync(tmpPath, { force: true })
+        return 'conflict'
+      }
+    }
+
+    if (typeof beforeSwap === 'function') beforeSwap(existing)
     renameSync(tmpPath, filePath)
   }
   return 'created'
@@ -277,12 +366,31 @@ export function writeIfChanged(filePath, content, dryRun) {
  * beta.5: write the user's opencode.json with a same-directory backup of the
  * previous content. The installer rewrites the whole config; a `.bak` gives
  * the user a one-step recovery if a merge ever goes wrong.
+ *
+ * The backup is created INSIDE the `beforeSwap` hook, so it fires only after
+ * both expected-content checks pass (the initial compare and the last-moment
+ * re-read before the rename). A conflict observed at either point leaves the
+ * target AND any pre-existing `.bak` untouched, rather than overwriting the
+ * user's last known-good backup with a stale copy on a no-op write.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @param {boolean} dryRun
+ * @param {object} [options] - forwarded to {@link writeIfChanged}
  */
-export function writeConfigWithBackup(filePath, content, dryRun) {
-  if (!dryRun && existsSync(filePath)) {
-    copyFileSync(filePath, `${filePath}.bak`)
-  }
-  return writeIfChanged(filePath, content, dryRun)
+export function writeConfigWithBackup(filePath, content, dryRun, options = {}) {
+  return writeIfChanged(filePath, content, dryRun, {
+    expectedContent: options.expectedContent,
+    beforeRecheck: options.beforeRecheck,
+    beforeSwap: (existing) => {
+      if (existing === null) return
+      try {
+        copyFileSync(filePath, `${filePath}.bak`)
+      } catch {
+        // Best-effort: a backup failure must not block the install.
+      }
+    },
+  })
 }
 
 /**