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

package/scripts/install/shared.mjs

@@ -4,9 +4,8 @@
 
 import { spawnSync } from 'node:child_process'
 import {
-  copyFileSync,
-  cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
@@ -15,7 +14,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const REQUIRED_NODE_MAJOR = 18
@@ -24,7 +23,9 @@ if (parseInt(process.versions.node.split('.')[0], 10) < REQUIRED_NODE_MAJOR) {
   process.exit(1)
 }
 
-import yaml from 'js-yaml'
+import { dump, load } from 'js-yaml'
+
+import { ACTIONS, isRecording, recordChange } from './plan.mjs'
 
 export const __dirname = dirname(fileURLToPath(import.meta.url))
 export const ROOT = join(__dirname, '..', '..')
@@ -140,33 +141,6 @@ export function resolveTarget(target) {
   return join(process.cwd(), target)
 }
 
-export function createBackup(target) {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
-  const backupDir = join(target, '..', `.pantheon-bak-${basename(target)}-${timestamp}`)
-
-  console.log(`\n  💾 Creating backup: ${backupDir}`)
-  mkdirSync(backupDir, { recursive: true })
-
-  // Copy only relevant Pantheon directories/files
-  const items = ['agents', 'skills', 'commands', 'instructions', 'opencode.json', 'tui.json']
-  let count = 0
-  for (const item of items) {
-    const src = join(target, item)
-    try {
-      cpSync(src, join(backupDir, item), {
-        recursive: true,
-        errorOnExist: false,
-      })
-      count++
-    } catch {
-      // File or directory doesn't exist in target — skip silently
-    }
-  }
-
-  console.log(`  ✅ Backed up ${count} items to: ${backupDir}`)
-  return backupDir
-}
-
 export function detectAndReport(target) {
   const found = detectPlatforms(target).length > 0
 
@@ -257,32 +231,161 @@ 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 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, for side
+ *   effects that must not fire on a conflict.
+ * @param {(change: object) => void} [options.recorder] - optional change
+ *   recorder. When supplied, the outcome is recorded (path + action + byte
+ *   size only) so `--dry-run` can print the real per-file plan. Defaults to
+ *   the module-level no-op singleton, so an uninstrumented caller is
+ *   byte-identical to before.
+ * @param {boolean} [options.scored] - set `false` when this write is not part
+ *   of the install summary (e.g. stale-ref cleanup), so it is shown in the plan
+ *   but excluded from the consistency guard.
+ * @returns {'created'|'skipped'|'conflict'}
+ */
+export function writeIfChanged(filePath, content, dryRun, options = {}) {
+  const { expectedContent, beforeSwap, beforeRecheck, recorder, scored } = 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)
+  const record = (outcome) => {
+    if (!isRecording(recorder)) return
+    const action =
+      outcome === 'conflict'
+        ? ACTIONS.CONFLICT
+        : outcome === 'skipped'
+          ? ACTIONS.UNCHANGED
+          : existing === null
+            ? ACTIONS.CREATE
+            : ACTIONS.UPDATE
+    recordChange(
+      { path: filePath, action, bytes: Buffer.byteLength(content, 'utf8'), scored },
+      recorder,
+    )
+  }
   if (existing === content) {
+    record('skipped')
     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.
+    record('conflict')
+    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 byte-identical.
+    if (expectedContent !== undefined) {
+      const current = readFileOrNull(filePath)
+      if (current !== expectedContent) {
+        rmSync(tmpPath, { force: true })
+        record('conflict')
+        return 'conflict'
+      }
+    }
+
+    if (typeof beforeSwap === 'function') beforeSwap(existing)
     renameSync(tmpPath, filePath)
   }
+  record('created')
   return 'created'
 }
 
 /**
- * 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.
+ * Write a config file atomically, honoring the compare-before-write guard.
+ * This used to always keep a `<config>.bak` sidecar; the main `opencode.json`
+ * no longer does — the target-scoped exact backup set
+ * (scripts/install/backup.mjs) preserves it byte-for-byte and
+ * `pantheon-opencode restore` reverts it.
+ *
+ * A caller may still supply `beforeSwap` for a file the exact set does NOT
+ * cover: the GLOBAL `opencode-vision.json` lives outside the config dir, so
+ * vision-prompt passes a `beforeSwap` that keeps its `<file>.bak` recovery.
+ *
+ * @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: options.beforeSwap,
+    recorder: options.recorder,
+    scored: options.scored,
+  })
 }
 
 /**
@@ -326,10 +429,10 @@ export function collectSkillNames() {
  * Returns { fm: object, body: string } or null if no frontmatter.
  */
 export function parseFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  const match = content.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---\r?\n?([\s\S]*)$/)
   if (!match) return null
   return {
-    fm: yaml.load(match[1]) ?? {},
+    fm: match[1].trim() ? (load(match[1]) ?? {}) : {},
     body: match[2],
   }
 }
@@ -339,15 +442,15 @@ export function parseFrontmatter(content) {
  * Uses long-line mode and avoids unnecessary quoting.
  */
 export function serializeFm(fm) {
-  return yaml.dump(fm, {
+  return dump(fm, {
     lineWidth: -1,
-    quotingType: '"',
+    quoteStyle: 'double',
     forceQuotes: false,
     noRefs: true,
   })
 }
 
-export function installSkills(skills, target, dryRun, subDir = '.opencode') {
+export function installSkills(skills, target, dryRun, subDir = '.opencode', recorder = null) {
   const srcSkillsDir = join(ROOT, 'src', 'skills')
   const dstSkillsDir = join(target, subDir, 'skills')
 
@@ -373,9 +476,29 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
           const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
           if (existing === content) {
             skipped++
+            if (isRecording(recorder)) {
+              recordChange(
+                {
+                  path: dstPath,
+                  action: ACTIONS.UNCHANGED,
+                  bytes: Buffer.byteLength(content, 'utf8'),
+                },
+                recorder,
+              )
+            }
           } else {
             if (!dryRun) writeFileSync(dstPath, content, 'utf8')
             created++
+            if (isRecording(recorder)) {
+              recordChange(
+                {
+                  path: dstPath,
+                  action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+                  bytes: Buffer.byteLength(content, 'utf8'),
+                },
+                recorder,
+              )
+            }
           }
         }
       }
@@ -396,6 +519,9 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
           console.log(`    🗑️  Removed stale skill: ${entry}`)
         }
         created++
+        // A stale removal increments `created` (a change), so it must also be
+        // recorded or the preview would under-report on a non-fresh target.
+        recordChange({ path: dstPath, action: ACTIONS.REMOVE, bytes: 0 }, recorder)
       }
     }
   }
@@ -403,7 +529,7 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
   return { created, skipped }
 }
 
-export function syncDir(src, dst, dryRun, clean = false, filter = null) {
+export function syncDir(src, dst, dryRun, clean = false, filter = null, recorder = null) {
   if (!existsSync(src)) return { created: 0, skipped: 0 }
   let created = 0
   let skipped = 0
@@ -422,7 +548,7 @@ export function syncDir(src, dst, dryRun, clean = false, filter = null) {
     const srcPath = join(src, entry)
     const dstPath = join(dst, entry)
     if (statSync(srcPath).isDirectory()) {
-      const sub = syncDir(srcPath, dstPath, dryRun, false, filter)
+      const sub = syncDir(srcPath, dstPath, dryRun, false, filter, recorder)
       created += sub.created
       skipped += sub.skipped
     } else {
@@ -430,9 +556,25 @@ export function syncDir(src, dst, dryRun, clean = false, filter = null) {
       const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
       if (existing === content) {
         skipped++
+        if (isRecording(recorder)) {
+          recordChange(
+            { path: dstPath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(content, 'utf8') },
+            recorder,
+          )
+        }
       } else {
         if (!dryRun) writeFileSync(dstPath, content, 'utf8')
         created++
+        if (isRecording(recorder)) {
+          recordChange(
+            {
+              path: dstPath,
+              action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+              bytes: Buffer.byteLength(content, 'utf8'),
+            },
+            recorder,
+          )
+        }
       }
     }
   }

package/scripts/install/strings.mjs

@@ -47,6 +47,16 @@ const TABLE = {
     prereqMissing:
       'runtime prerequisites missing — install the tools above, or re-run with --no-mcp to install without Python MCP servers',
     v2Migrating: 'Migrating config to V2 native format...',
+    nothingApplied: 'Nothing applied.',
+    planOnlyNoYes: 'Plan only — re-run with --yes to apply.',
+    driftHeader: 'State changed since preview — aborting before any write:',
+    driftAbort: 'No files were written. Re-run to re-review.',
+    applyFailed: (msg) => `❌ Apply failed: ${msg}`,
+    alreadyApplied: 'Paths already applied — no automatic rollback:',
+    restoreRecoveryHint: (dir) => `Recover with: pantheon-opencode restore  (backup at ${dir})`,
+    restoreNoBackup:
+      'No backup was created (the failure occurred before the first write); the target is unchanged.',
+    dryRunNothingWritten: 'Preview only — no files were written.',
     // summary (printSummary)
     summaryInstalled: (target) => `OpenCode installed in ${target}`,
     summaryWithErrors: (target) => `Installation finished WITH ERRORS in ${target}`,
@@ -95,6 +105,16 @@ const TABLE = {
     prereqMissing:
       'pré-requisitos do runtime ausentes — instale as ferramentas acima, ou rode de novo com --no-mcp para instalar sem os MCPs Python',
     v2Migrating: 'Migrando config para o formato nativo V2...',
+    nothingApplied: 'Nada foi aplicado.',
+    planOnlyNoYes: 'Apenas o plano — rode de novo com --yes para aplicar.',
+    driftHeader: 'O estado mudou desde o preview — abortando antes de qualquer escrita:',
+    driftAbort: 'Nenhum arquivo foi escrito. Rode de novo para revisar.',
+    applyFailed: (msg) => `❌ Falha ao aplicar: ${msg}`,
+    alreadyApplied: 'Caminhos já aplicados — sem rollback automático:',
+    restoreRecoveryHint: (dir) => `Recupere com: pantheon-opencode restore  (backup em ${dir})`,
+    restoreNoBackup:
+      'Nenhum backup foi criado (a falha ocorreu antes da primeira escrita); o alvo está intacto.',
+    dryRunNothingWritten: 'Somente prévia — nenhum arquivo foi escrito.',
     // summary (printSummary)
     summaryInstalled: (target) => `OpenCode instalado em ${target}`,
     summaryWithErrors: (target) => `Instalação concluída COM ERROS em ${target}`,

package/scripts/install/venv.mjs

@@ -14,6 +14,8 @@ import { existsSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { ACTIONS, recordChange } from './plan.mjs'
+
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..', '..')
 
@@ -40,10 +42,13 @@ export function venvPythonPath(target) {
  * Set up a Python virtual environment and install MCP dependencies.
  *
  * @param {string} target - Target installation directory (e.g. ~/.config/opencode)
- * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean }} [options]
+ * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean, recorder?: (change: object) => void }} [options]
  * @returns {{ venvPath: string, python: string }}
  */
-export function setupVenv(target, { dryRun = false, skipInstall = false, force = false } = {}) {
+export function setupVenv(
+  target,
+  { dryRun = false, skipInstall = false, force = false, recorder = null } = {},
+) {
   const venvPath = join(target, '.venv')
   const pythonBin = venvPythonPath(target)
 
@@ -57,7 +62,8 @@ export function setupVenv(target, { dryRun = false, skipInstall = false, force =
   }
 
   // Step 1b: Create venv if not exists
-  if (!existsSync(pythonBin)) {
+  const venvExists = existsSync(pythonBin)
+  if (!venvExists) {
     if (!dryRun) {
       console.log('  Creating .venv...')
       const result = spawnSync('python3', ['-m', 'venv', venvPath], {
@@ -69,8 +75,12 @@ export function setupVenv(target, { dryRun = false, skipInstall = false, force =
       }
     }
     console.log('  ✅ .venv created')
+    // A single synthetic entry for the venv directory — never enumerate its
+    // thousands of files. Unscored: the install summary does not count it.
+    recordChange({ path: venvPath, action: ACTIONS.CREATE, bytes: 0, scored: false }, recorder)
   } else {
     console.log('  ⏭️  .venv already exists')
+    recordChange({ path: venvPath, action: ACTIONS.UNCHANGED, bytes: 0, scored: false }, recorder)
   }
 
   // Step 2: Install MCP dependencies

package/scripts/install/vision-prompt.mjs

@@ -0,0 +1,171 @@
+/**
+ * vision-prompt.mjs — optional vision step of `pantheon-opencode init`.
+ *
+ * After the model-preset wizard, an interactive TTY session is offered a
+ * three-way choice for the vision model:
+ *   1. automatic discovery (default, Enter) — writes nothing
+ *   2. pin a `provider/model`              — merges `visionModel` into the
+ *      GLOBAL vision config (~/.config/opencode/opencode-vision.json)
+ *   3. skip                                 — writes nothing
+ *
+ * Non-interactive runs (no TTY, `--yes`, `--headless`, automated sandboxes)
+ * never reach this module: `installOpenCode` only calls it when
+ * `interactive && !dryRun && !autoYes`. Automatic discovery therefore stays
+ * the default in every non-interactive flow and no run blocks on stdin.
+ *
+ * The write mirrors the `/pantheon-vision` command: atomic, `.bak` backup,
+ * and a MERGE — existing keys are never overwritten.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { writeConfigWithBackup } from './shared.mjs'
+
+const CONFIG_FILENAME = 'opencode-vision.json'
+/** `provider/model` — exactly one slash, no surrounding whitespace. */
+const MODEL_PATTERN = /^[^\s/]+\/[^\s/]+$/
+const MAX_PIN_ATTEMPTS = 3
+
+/** Global vision config path, honoring `XDG_CONFIG_HOME` (same rule as the plugin). */
+export function globalVisionConfigPath(env = process.env) {
+  const home = env.HOME?.trim() || homedir()
+  const xdg = env.XDG_CONFIG_HOME?.trim() || join(home, '.config')
+  return join(xdg, 'opencode', CONFIG_FILENAME)
+}
+
+/** True when `value` looks like a `provider/model` id (one slash, no spaces). */
+export function isValidVisionModel(value) {
+  return typeof value === 'string' && MODEL_PATTERN.test(value.trim())
+}
+
+/**
+ * Merge `visionModel` into a vision config, preserving every other key.
+ * Defaults to the GLOBAL config; pass `configPath` to target another file
+ * (e.g. the project config `.opencode/opencode-vision.json`). Creates the
+ * parent directory when missing; never overwrites existing keys. A corrupted
+ * JSON file is left byte-identical (the caller decides what to tell the user)
+ * rather than clobbered.
+ *
+ * A concurrent writer that changes the file between the read and the atomic
+ * swap makes `writeConfigWithBackup` return `'conflict'`: the write is aborted,
+ * `wrote` is `false`, and the newer content is left untouched.
+ *
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]
+ * @param {boolean} [opts.dryRun]
+ * @param {string} [opts.configPath] - explicit target file (defaults to global)
+ * @param {(existing: string|null) => void} [opts.beforeRecheck] - test seam
+ *   forwarded to `writeConfigWithBackup` to simulate a concurrent writer.
+ * @returns {{path: string, wrote: boolean, reason: 'created'|'skipped'|'conflict'|'corrupt'|'dry-run'}}
+ */
+export function mergeVisionModel(
+  model,
+  { env = process.env, dryRun = false, beforeRecheck, configPath: target } = {},
+) {
+  const configPath = target ?? globalVisionConfigPath(env)
+  let parsed = {}
+  let existingRaw
+  if (existsSync(configPath)) {
+    existingRaw = readFileSync(configPath, 'utf8')
+    try {
+      const data = JSON.parse(existingRaw)
+      if (data && typeof data === 'object' && !Array.isArray(data)) parsed = data
+    } catch {
+      return { path: configPath, wrote: false, reason: 'corrupt' }
+    }
+  }
+  if (dryRun) return { path: configPath, wrote: false, reason: 'dry-run' }
+  const next = { ...parsed, visionModel: model }
+  const content = `${JSON.stringify(next, null, 2)}\n`
+  mkdirSync(dirname(configPath), { recursive: true })
+  const status = writeConfigWithBackup(configPath, content, false, {
+    expectedContent: existingRaw,
+    beforeRecheck,
+    // This file is GLOBAL and lives outside the config dir, so the target-scoped
+    // exact backup set never captures it. Keep its own `<file>.bak` recovery.
+    beforeSwap: (existing) => {
+      if (existing === null) return
+      try {
+        copyFileSync(configPath, `${configPath}.bak`)
+      } catch {
+        // Best-effort: a backup failure must not block the write.
+      }
+    },
+  })
+  return { path: configPath, wrote: status === 'created', reason: status }
+}
+
+/**
+ * Ask the interactive vision question. `rl` may be injected (tests / an
+ * existing readline interface); otherwise a private one is created and closed.
+ * Returns `{action, visionModel?, wrote?, path?}` — never throws on bad input,
+ * and never writes for the default/skip paths.
+ *
+ * @param {{rl?: object, logger?: object, env?: Record<string, string|undefined>, dryRun?: boolean, beforeRecheck?: (existing: string|null) => void}} [opts]
+ */
+export async function runVisionPrompt({
+  rl,
+  logger = console,
+  env = process.env,
+  dryRun = false,
+  beforeRecheck,
+} = {}) {
+  let iface = rl
+  let closeAfter = false
+  if (!iface) {
+    const { createInterface } = await import('node:readline/promises')
+    iface = createInterface({ input: process.stdin, output: process.stdout })
+    closeAfter = true
+  }
+  try {
+    logger.log?.('')
+    logger.log?.('Vision — how should images be described?')
+    logger.log?.(
+      '  1) Automatic discovery (default) — pick a vision-capable model from the host catalog',
+    )
+    logger.log?.('  2) Pin a provider/model (e.g. opencode-go/mimo-v2.5)')
+    logger.log?.('  3) Skip')
+    const answer = (await iface.question('Choice [1]: ')).trim().toLowerCase()
+
+    if (answer === '' || answer === '1' || answer === 'auto' || answer === 'discovery') {
+      logger.log?.('Vision: automatic discovery (no config written).')
+      return { action: 'auto' }
+    }
+    if (answer === '3' || answer === 'skip' || answer === 'no') {
+      logger.log?.('Vision: skipped (no config written).')
+      return { action: 'skip' }
+    }
+    if (answer === '2' || answer === 'pin') {
+      for (let attempt = 0; attempt < MAX_PIN_ATTEMPTS; attempt++) {
+        const raw = (await iface.question('provider/model (e.g. opencode-go/mimo-v2.5): ')).trim()
+        if (!isValidVisionModel(raw)) {
+          logger.warn?.(`Invalid model "${raw}" — expected provider/model (one slash, no spaces).`)
+          continue
+        }
+        const result = mergeVisionModel(raw, { env, dryRun, beforeRecheck })
+        if (result.reason === 'corrupt') {
+          logger.warn?.(
+            `Vision config at ${result.path} is not valid JSON — leaving it untouched; fix it and re-run.`,
+          )
+          return { action: 'pin', visionModel: raw, wrote: false, path: result.path }
+        }
+        if (result.reason === 'conflict') {
+          logger.warn?.(
+            `Vision: not saved — config at ${result.path} was modified concurrently; re-run to retry.`,
+          )
+        } else {
+          logger.log?.(`Vision: pinned ${raw} in ${result.path}.`)
+        }
+        return { action: 'pin', visionModel: raw, wrote: result.wrote, path: result.path }
+      }
+      logger.warn?.('Vision: no valid model entered — skipping (no config written).')
+      return { action: 'skip' }
+    }
+    logger.warn?.(
+      `Unknown choice "${answer}" — defaulting to automatic discovery (no config written).`,
+    )
+    return { action: 'auto' }
+  } finally {
+    if (closeAfter) iface.close()
+  }
+}