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

package/scripts/doctor.mjs

@@ -29,6 +29,8 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { listV2UnsupportedFeatures } from '../src/pantheon/v2-unsupported.mjs'
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -1000,7 +1002,7 @@ function checkVenvLayer(args) {
 /**
  * Return whether *dir* contains an executable code-mode target.
  *
- * Mirrors `_has_usable_scripts` in `scripts/code_mode_server.py`: a directory
+ * Mirrors `_has_usable_scripts` in `scripts/code_mode.py`: a directory
  * is only a valid resolver candidate when it is a real (non-symlink) directory
  * containing a regular `.py`/`.sh` direct child. This prevents an empty project
  * overlay from masking a lower-priority installation that actually ships
@@ -1430,6 +1432,153 @@ export function checkPluginVersionDrift(args) {
   return 'sync'
 }
 
+// ---------------------------------------------------------------------------
+// Check H4: V2 feature reduction (the surface a migrating user loses)
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an opencode.json registers the V2 generation of the Pantheon plugin.
+ *
+ * The V2 contract is the PLURAL `plugins` key; V1 is the singular `plugin` key.
+ * So the key alone is not the test — a config can legitimately carry a
+ * third-party entry in `plugins`. What identifies the generation is a Pantheon
+ * V2 entry inside it. Matched on the `plugin-v2` marker so all three real
+ * spellings are recognised: the canonical DIRECTORY (`src/plugin-v2`), an
+ * absolute path to it, and the package export (`pantheon-opencode/plugin-v2`).
+ *
+ * @param {unknown} ref
+ * @returns {boolean}
+ */
+function isV2PluginRef(ref) {
+  const candidate =
+    typeof ref === 'string'
+      ? ref
+      : ref && typeof ref === 'object'
+        ? (ref.path ?? ref.source ?? ref.id ?? ref.name)
+        : undefined
+  return typeof candidate === 'string' && candidate.includes('plugin-v2')
+}
+
+/**
+ * Whether any reachable config registers the V2 generation of the Pantheon
+ * plugin. Split out of {@link collectV2UnsupportedFeatures} because "is the V2
+ * generation registered" and "does the seed list anything" are TWO facts: the
+ * first is about the user's config, the second about this repository's seed. A
+ * single `features.length === 0` cannot tell them apart, and conflating them
+ * let an emptied seed print "no V2 generation registered — nothing reduced".
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {boolean}
+ */
+export function isV2GenerationRegistered(configs) {
+  return configs.some((cfg) => {
+    const list = cfg.data?.plugins
+    return Array.isArray(list) && list.some(isV2PluginRef)
+  })
+}
+
+/**
+ * The V2 feature-reduction markers to report for a set of collected configs.
+ *
+ * Returns the shared seed verbatim when ANY reachable config registers the V2
+ * generation, and an empty list otherwise. The strings come from
+ * `src/pantheon/v2-unsupported.mjs` — the same seed `getUnsupportedFeatures()`
+ * is built from — so doctor cannot report a reduction the plugin does not, or
+ * miss one it does. Nothing is reworded here.
+ *
+ * An empty result is ambiguous on its own and deliberately not interpreted
+ * here: ask {@link isV2GenerationRegistered} for the registration fact, or
+ * {@link describeV2Reduction} to get both at once.
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {string[]}
+ */
+export function collectV2UnsupportedFeatures(configs) {
+  return isV2GenerationRegistered(configs) ? listV2UnsupportedFeatures() : []
+}
+
+/**
+ * Decide what H4 prints, from the two distinct facts rather than from one list
+ * length.
+ *
+ * Three cases, and the middle one used to be silently reported as the first:
+ *
+ *   - not registered → info. A V1 install is a supported configuration with
+ *     nothing to reduce, and saying so plainly is correct.
+ *   - registered, seed EMPTY → warn. This is a packaging fault in THIS repo,
+ *     not an absence of reduction: the V2 surface really is reduced and the
+ *     report is missing. It must never claim "nothing reduced".
+ *   - registered, seed populated → warn, listing every marker.
+ *
+ * Pure and exported so the empty-seed branch is testable without stubbing the
+ * frozen seed module. `status` is returned alongside the text so a caller never
+ * has to recover the case by matching on the message.
+ *
+ * @param {{registered:boolean, features:string[]}} input
+ * @returns {{status:'reported'|'empty-seed'|'no-v2-generation', level:'info'|'warn', message:string}}
+ */
+export function describeV2Reduction({ registered, features }) {
+  if (!registered) {
+    return {
+      status: 'no-v2-generation',
+      level: 'info',
+      message: 'No V2 plugin generation registered — nothing reduced',
+    }
+  }
+  if (features.length === 0) {
+    return {
+      status: 'empty-seed',
+      level: 'warn',
+      message:
+        'Pantheon IS registered on the V2 plugin generation, but the shared ' +
+        'unsupported-feature seed is empty, so the reduction cannot be reported. ' +
+        "That is a fault in this installation's reporting, not an absence of " +
+        'reduction: the V2 surface still drops the 3 goal tools and the ' +
+        'caller/target delegation matrix.',
+    }
+  }
+  return {
+    status: 'reported',
+    level: 'warn',
+    message:
+      'Pantheon is registered on the V2 plugin generation, which registers 3 tools ' +
+      "(hashline_edit, pantheon_cost, pantheon_model) instead of the V1 surface's 6 plus " +
+      `the BackgroundJobBoard and the caller/target delegation matrix. Unsupported: ${features.join(', ')}`,
+  }
+}
+
+/**
+ * Report the V2 feature reduction through doctor's own output shape
+ * (section + warn/info), so it lands in the health summary like every other
+ * finding and never changes the exit code: a V2 install is a supported
+ * configuration, not a broken one.
+ *
+ * @param {{target:string, env?:object}} args
+ * @returns {'reported'|'empty-seed'|'no-v2-generation'|'no-config'}
+ */
+export function checkV2UnsupportedFeatures(args) {
+  section('H4. V2 Feature Reduction')
+
+  const configs = collectMcpConfigs(args)
+  if (configs.length === 0) {
+    info('No opencode.json was found — V2 feature reduction check skipped')
+    return 'no-config'
+  }
+
+  // Branch on REGISTRATION, not on the marker count: an empty seed on a
+  // registered V2 generation is a reporting fault and must not be reported as
+  // the reassuring "nothing reduced".
+  const registered = isV2GenerationRegistered(configs)
+  const verdict = describeV2Reduction({
+    registered,
+    features: collectV2UnsupportedFeatures(configs),
+  })
+  if (verdict.level === 'info') info(verdict.message)
+  else warn(verdict.message)
+
+  return verdict.status
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1802,6 +1951,7 @@ async function main() {
   checkAgentsMdFreshness(args)
   checkSubagentDepthPlacement(args)
   checkPermissionTaskPresence(args)
+  checkV2UnsupportedFeatures(args)
 
   printSummary(args.target)
 

package/scripts/install/config-migration.mjs

@@ -229,8 +229,11 @@ function convertProviderV2toV1(_name, config) {
 /**
  * Convert V1 MCP config to V2.
  *
- * V1: { bifrost: { type: "remote", url: "...", enabled: true, timeout: 30000 } }
- * V2 installer output: { bifrost: { type: "remote", url: "...", enabled: true } }
+ * The server names are arbitrary — a user calls theirs whatever they like, and
+ * which MCP servers exist is entirely their configuration, never ours.
+ *
+ * V1: { myserver: { type: "remote", url: "...", enabled: true, timeout: 30000 } }
+ * V2 installer output: { myserver: { type: "remote", url: "...", enabled: true } }
  *
  * OpenCode 1.18.18 does not have an `mcp.servers` wrapper. It interprets
  * `servers` as the name of an MCP server and then rejects it with
@@ -285,6 +288,81 @@ function convertMcpV2toV1(mcpConfig) {
   return convertMcpV1toV2(mcpConfig)
 }
 
+// ---------------------------------------------------------------------------
+// MCP entrypoint path migration
+// ---------------------------------------------------------------------------
+
+/**
+ * Entrypoint filename renames: every historical Python MCP entrypoint shared
+ * the `server.py` token, so a broad `pkill -f server.py` (a common idiom in
+ * agent and scratch tooling) matched the entire fleet and killed it as
+ * collateral. The five entrypoints now carry distinct tokens.
+ *
+ * The rename alone is a BREAKING change for existing installs: their
+ * `opencode.json` carries literal paths like `scripts/memory_mcp_server.py`,
+ * and a path that no longer resolves fails every MCP server silently (the
+ * same class of failure as the dead plugin surface). This map is the single
+ * source of truth for the stale → current basename rewrite that repairs them.
+ */
+export const MCP_ENTRYPOINT_RENAMES = Object.freeze({
+  'mcp_resources_server.py': 'mcp_resources.py',
+  'code_mode_server.py': 'code_mode.py',
+  'memory_mcp_server.py': 'memory_mcp.py',
+  'mcp_persistence_server.py': 'mcp_persistence.py',
+  'pantheon_vision_server.py': 'pantheon_vision.py',
+})
+
+/**
+ * Rewrite a single path/argument string when its basename is a renamed MCP
+ * entrypoint. The directory prefix is preserved verbatim, so both relative
+ * (`scripts/memory_mcp_server.py`) and absolute/hand-edited paths heal without
+ * discarding a user's chosen location. Non-matching values pass through.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function renameMcpEntrypointPath(value) {
+  if (typeof value !== 'string') return value
+  const slash = Math.max(value.lastIndexOf('/'), value.lastIndexOf('\\'))
+  const base = value.slice(slash + 1)
+  const renamed = MCP_ENTRYPOINT_RENAMES[base]
+  if (!renamed) return value
+  return value.slice(0, value.length - base.length) + renamed
+}
+
+/**
+ * Heal stale MCP entrypoint paths in a flat named-server map, in place.
+ *
+ * Scans every server — not only the `pantheon-*` keys — because a user who
+ * hand-edited their config may have renamed the key while keeping the
+ * Pantheon path. Both `command` (installer writes `[python, script]`) and
+ * `args` (the standalone installer writes `[script]`) are covered, since
+ * which array carries the script differs between installers.
+ *
+ * @param {object} mcp - the `mcp` map from a config (mutated in place)
+ * @returns {number} count of rewritten strings (0 = already current)
+ */
+export function migrateMcpEntrypointPaths(mcp) {
+  if (!mcp || typeof mcp !== 'object' || Array.isArray(mcp)) return 0
+
+  let changed = 0
+  for (const server of Object.values(mcp)) {
+    if (!server || typeof server !== 'object') continue
+    for (const field of ['command', 'args']) {
+      const list = server[field]
+      if (!Array.isArray(list)) continue
+      for (let i = 0; i < list.length; i++) {
+        const next = renameMcpEntrypointPath(list[i])
+        if (next !== list[i]) {
+          list[i] = next
+          changed++
+        }
+      }
+    }
+  }
+  return changed
+}
+
 // ---------------------------------------------------------------------------
 // Top-level key mappings
 // ---------------------------------------------------------------------------

package/scripts/install/health-check.mjs

@@ -27,7 +27,7 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
   const visionServer = resolveVisionServer(target)
 
   // Check 1: Critical runtime scripts exist
-  const scripts = ['mcp_persistence_server.py', '_pantheon_paths.py']
+  const scripts = ['mcp_persistence.py', '_pantheon_paths.py']
   for (const script of scripts) {
     const path = join(target, 'scripts', script)
     if (existsSync(path)) {
@@ -44,8 +44,8 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
       check: visionServer.check,
       detail: visionServer.detail,
     })
-    const installedVisionServer = join(target, 'scripts', 'pantheon_vision_server.py')
-    const canonicalVisionServer = join(target, 'src', 'mcp', 'pantheon_vision_server.py')
+    const installedVisionServer = join(target, 'scripts', 'pantheon_vision.py')
+    const canonicalVisionServer = join(target, 'src', 'mcp', 'pantheon_vision.py')
     if (existsSync(installedVisionServer) && existsSync(canonicalVisionServer)) {
       try {
         if (
@@ -54,7 +54,7 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
         ) {
           results.failed.push({
             check: 'pantheon-vision source drift',
-            detail: 'installed script differs from src/mcp/pantheon_vision_server.py',
+            detail: 'installed script differs from src/mcp/pantheon_vision.py',
           })
         }
       } catch {
@@ -66,7 +66,7 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
     }
   } else {
     results.failed.push({
-      check: 'src/mcp/pantheon_vision_server.py',
+      check: 'src/mcp/pantheon_vision.py',
       detail: 'NOT FOUND — canonical vision server source is unavailable',
     })
   }
@@ -104,12 +104,7 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
   }
 
   // Check 2: Syntax check on each MCP server script
-  const mcpScripts = [
-    'mcp_persistence_server.py',
-    'mcp_resources_server.py',
-    'code_mode_server.py',
-    'memory_mcp_server.py',
-  ]
+  const mcpScripts = ['mcp_persistence.py', 'mcp_resources.py', 'code_mode.py', 'memory_mcp.py']
   for (const script of mcpScripts) {
     const path = join(target, 'scripts', script)
     if (existsSync(path) && python) {
@@ -135,12 +130,12 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
     })
     if (result.status === 0) {
       results.passed.push({
-        check: 'syntax:pantheon_vision_server.py',
+        check: 'syntax:pantheon_vision.py',
         detail: 'valid',
       })
     } else {
       results.failed.push({
-        check: 'syntax:pantheon_vision_server.py',
+        check: 'syntax:pantheon_vision.py',
         detail: result.stderr.toString().trim().split('\n').slice(-1)[0],
       })
     }
@@ -231,13 +226,13 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
 function resolveVisionServer(target) {
   const candidates = [
     {
-      path: join(target, 'src', 'mcp', 'pantheon_vision_server.py'),
-      check: 'src/mcp/pantheon_vision_server.py',
+      path: join(target, 'src', 'mcp', 'pantheon_vision.py'),
+      check: 'src/mcp/pantheon_vision.py',
       detail: 'canonical source exists',
     },
     {
-      path: join(target, 'scripts', 'pantheon_vision_server.py'),
-      check: 'scripts/pantheon_vision_server.py',
+      path: join(target, 'scripts', 'pantheon_vision.py'),
+      check: 'scripts/pantheon_vision.py',
       detail: 'installed copy exists (deployed from src/mcp)',
     },
   ]

package/scripts/install/opencode-version.mjs

@@ -1,5 +1,9 @@
 /** OpenCode major-version selection shared by the CLI and installer. */
 
+import { spawnSync } from 'node:child_process'
+
+import { warning } from './cli-ui.mjs'
+
 const VALID_VERSIONS = new Set(['v1', 'v2', 'auto'])
 
 /** @param {string[]} args @returns {'v1'|'v2'|'auto'|null} */
@@ -28,12 +32,185 @@ function normalize(value) {
 }
 
 /**
- * Resolve auto conservatively: only an explicit hint selects V2.
+ * Ask the host binary for its version. Throws on any spawn failure so the
+ * caller can fail soft in one place.
+ *
+ * stderr is captured alongside stdout. A host that prints its version banner to
+ * stderr and nothing to stdout would otherwise soft-fail to V1 — a wrong
+ * answer whose cause has nothing to do with the host's generation.
+ * @param {string} binary
+ * @returns {{stdout: string, stderr: string}}
+ */
+function probeHostVersion(binary) {
+  const result = spawnSync(binary, ['--version'], {
+    encoding: 'utf8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error(`"${binary} --version" exited with status ${result.status}`)
+  }
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '' }
+}
+
+// A version-SHAPED token: optional "v", a major, a dot, a minor. The lookbehind
+// rejects starting mid-number so "1.18.33" offers ONE candidate ("1.18") rather
+// than also offering "18.33". Case-insensitive because hosts print both
+// "opencode v2.0.22" and "OpenCode V2.0.22".
+const VERSION_TOKEN = /(?<![\d.])v?(\d+)\.(\d+)/gi
+
+// A token immediately preceded by the tool name IS that host's own version,
+// whatever else the banner mentions. This is what distinguishes
+// "node v22.1.0 (opencode 1.18.33)" — where the two candidates are a runtime
+// version and the tool version — from a genuine contradiction.
+//
+// KNOWN LIMIT, deliberately not worked around: this anchor is a NAME anchor, so
+// any sentence that puts "opencode" in front of a version-shaped token reads as
+// a host banner. A probe whose output is `warning: deprecated, upgrade to
+// opencode 2.0.0` resolves to v2 in silence. Closing it would need a rule that
+// rejects a mid-sentence "opencode X.Y.Z" — but "node v22.1.0 (opencode 1.18.33)"
+// is exactly such a mid-sentence anchor, and it is the reason the anchor exists:
+// dropping it lets a leading runtime token flip a genuine 1.x host to v2. The
+// defect class is not the nag wording (a phrase blacklist closes these three
+// strings and none of the others), it is name-adjacency. `probeHostVersion`
+// spawns whatever OPENCODE_BIN names and accepts any exit-0 binary, so a wrapper
+// or shim printing a bare path is indistinguishable from the real host by
+// construction. An operator whose `opencode` is a wrapper gets v2 silently; the
+// documented remedy is `--opencode-version`, not a heuristic that would trade
+// this silent misclassification for a different one.
+const ANCHOR_NAME = 'opencode'
+
+// How far back the anchor scan looks. `[\s:=]*` is unbounded, so no finite
+// window is exact — the cap is what makes the scan O(1) per token instead of
+// copying the whole prefix, which was quadratic and let a verbose host outrun the
+// 5s spawn timeout (that timeout guards the spawn, not the parse). The budget is
+// sized from the anchor itself (ANCHOR_NAME plus separators), not guessed: the
+// longest separator run in any realistic banner is ~10 bytes. Past the budget an
+// anchor is simply missed, and that degrades to the loud consensus path — it can
+// turn a quiet resolution into a warned one, never into a different resolution.
+const ANCHOR_SEPARATOR_BUDGET = 56
+const ANCHOR_WINDOW_BYTES = ANCHOR_NAME.length + ANCHOR_SEPARATOR_BUDGET
+const TOOL_NAME_BEFORE = new RegExp(`${ANCHOR_NAME}[\\s:=]*$`, 'i')
+
+// A major at or above this is a calendar year, not a release number:
+// "built 2026.10.04" is version-SHAPED but describes no release. So is major 0,
+// which is a prerelease placeholder rather than a release — and major 0 read as
+// "older than 2" is the original defect (V1 config on a 2.x host) recurring for
+// a 2.x beta. Which brings the subtlety this gate turns on:
+//
+//   * UNANCHORED and implausible -> noise. A date or a build counter says
+//     nothing about the host's generation, so dropping it is a resolution, not a
+//     failure: "opencode v2.0.22 built 2026.10.04" stays quiet.
+//   * ANCHORED and implausible -> the host's OWN version, which we cannot read.
+//     Discarding it would promote a surviving `node v22` token to deciding power
+//     and answer in silence — "opencode 100.0.0 (node v22.1.0)" would resolve to
+//     v2 with no warning. So a refused anchored major is reported, not dropped.
+//
+// Both cases fail LOUD rather than silently, which is the safe direction, and
+// the loud-v1 claim holds for the anchored case without depending on the dropped
+// token being the only candidate.
+const FIRST_PLAUSIBLE_MAJOR = 100
+
+/** Is `major` a value we refuse to read as a release number? */
+function isImplausibleMajor(major) {
+  return major === 0 || major >= FIRST_PLAUSIBLE_MAJOR
+}
+
+/**
+ * The slice of `source` the anchor scan inspects — bounded on purpose (see
+ * ANCHOR_WINDOW_BYTES) so the scan does not copy the prefix per token.
+ * @param {string} source @param {number} index @returns {string}
+ */
+function anchorWindow(source, index) {
+  return source.slice(Math.max(0, index - ANCHOR_WINDOW_BYTES), index)
+}
+
+/**
+ * Reduce a `--version` string to the single major it unambiguously reports.
+ *
+ * Anchoring on the tool name — rather than taking the first or the last
+ * version-shaped token — is what makes this robust on both sides. First-match
+ * anchoring lets a leading `node v22` outrank the tool's own version and flips
+ * a 1.x host to v2; last-match anchoring lets a trailing `built 2026.10.04`
+ * outrank it and does the same. A name-anchored token defeats both.
+ *
+ * @param {string} text raw `--version` output from one stream
+ * @returns {{major: number}|{ambiguous: number[]}|{unreadable: number}|null}
+ *   `{major}` when the host version is identifiable, `{ambiguous}` when
+ *   version-shaped tokens disagree and nothing says which is the host's,
+ *   `{unreadable}` when the host's own anchored token reports a major this gate
+ *   will not interpret, and `null` when nothing is version-shaped.
+ */
+function parseHostMajor(text) {
+  const source = String(text ?? '')
+  const candidates = []
+  let unreadable = null
+  for (const match of source.matchAll(VERSION_TOKEN)) {
+    const major = Number(match[1])
+    const anchored = TOOL_NAME_BEFORE.test(anchorWindow(source, match.index))
+    if (isImplausibleMajor(major)) {
+      if (anchored && unreadable === null) unreadable = major
+      continue
+    }
+    candidates.push({ major, anchored })
+  }
+  if (unreadable !== null) return { unreadable }
+  if (candidates.length === 0) return null
+
+  const anchored = candidates.filter((candidate) => candidate.anchored)
+  if (anchored.length > 0) {
+    const majors = new Set(anchored.map((candidate) => candidate.major))
+    if (majors.size === 1) return { major: anchored[0].major }
+    return { ambiguous: [...majors].sort((a, b) => a - b) }
+  }
+
+  const majors = new Set(candidates.map((candidate) => candidate.major))
+  if (majors.size === 1) return { major: candidates[0].major }
+  return { ambiguous: [...majors].sort((a, b) => a - b) }
+}
+
+/**
+ * Resolve the target OpenCode generation.
+ *
+ * `auto` precedence — the order is load-bearing, do not "simplify" it:
+ *   1. explicit `--opencode-version` argument
+ *   2. OPENCODE_VERSION env var
+ *   3. an `opencode2` binary basename
+ *   4. a `--version` probe of the host binary (major >= 2 => v2)
+ *   5. soft-fail to v1 with one visible warning
+ *
+ * Step 3 stays ahead of step 4 because of WHAT THE TWO STEPS ARE. Step 3 is an
+ * explicit operator hint: naming a binary `opencode2` and pointing
+ * `OPENCODE_BIN` at it is a deliberate act, and it is the only one of the two
+ * the operator gets to state. Step 4 is a heuristic read of a free-form string
+ * that some program chose to print. A hint must not be overruled by a
+ * heuristic — and the argument holds no matter what any given build prints.
+ *
+ * Historical note, NOT an observation of this host: an OpenCode 2.x prerelease
+ * once printed "0.0.0-next-17444", which any "major >= 2 => v2" probe reads as
+ * major 0 and would resolve to v1. That string does not come from the host —
+ * it survives only in this repo's comments and test fixtures. It is also why a
+ * major-0 anchored token now takes the loud path rather than resolving to v1 in
+ * silence (see FIRST_PLAUSIBLE_MAJOR). Verified 2026-10-04: `opencode2` here is
+ * a 47-byte shim that execs `opencode`, and `opencode2 --version` prints
+ * "opencode v2.0.22" on stdout. So for a real `opencode2` today both the
+ * basename and the probe return v2 and the ordering is harmless rather than
+ * load-bearing; what it still defends is the general case above.
+ *
+ * Step 5 falls back to v1 rather than v2 on purpose. Writing a plural
+ * `plugins` directory entry on an unknown 1.x host would be ignored there,
+ * losing the plugin on that host AND dropping the V1-only surface — strictly
+ * worse than the V1 default, which at least still works. The fallback is only
+ * tolerable because it warns; a silent v1 is what made this a silent failure.
+ *
  * @param {'v1'|'v2'|'auto'|null|undefined} requested
- * @param {{env?: Record<string, string|undefined>, binary?: string}} [options]
+ * @param {{env?: Record<string, string|undefined>, binary?: string,
+ *          probe?: () => string|{stdout?: string, stderr?: string},
+ *          warn?: (message: string) => void}} [options]
  * @returns {'v1'|'v2'}
  */
-export function resolveOpenCodeVersion(requested = 'v1', options = {}) {
+export function resolveOpenCodeVersion(requested = 'auto', options = {}) {
   if (!VALID_VERSIONS.has(requested)) {
     throw new Error(`Invalid OpenCode version "${requested}" — expected v1, v2, or auto`)
   }
@@ -43,5 +220,70 @@ export function resolveOpenCodeVersion(requested = 'v1', options = {}) {
     return env.OPENCODE_VERSION
   }
   const binary = options.binary ?? env.OPENCODE_BIN ?? ''
-  return /(?:^|[\\/])opencode2(?:\.exe)?$/i.test(binary) ? 'v2' : 'v1'
+  if (/(?:^|[\\/])opencode2(?:\.exe)?$/i.test(binary)) return 'v2'
+
+  const probe = options.probe ?? (() => probeHostVersion(binary || 'opencode'))
+  const warn = options.warn ?? warning
+  let raw
+  try {
+    raw = probe()
+  } catch (err) {
+    warn(
+      `Could not read the host OpenCode version (${err.message}). Falling back to the V1 ` +
+        `configuration; if this host is OpenCode 2.x re-run with --opencode-version v2 ` +
+        `(or v1 to force V1).`,
+    )
+    return 'v1'
+  }
+
+  // Accept both the real probe's {stdout, stderr} shape and a bare string, so a
+  // caller (or CI) can inject a probe without spawning a host binary.
+  const streams =
+    raw !== null && typeof raw === 'object'
+      ? { stdout: String(raw.stdout ?? ''), stderr: String(raw.stderr ?? '') }
+      : { stdout: String(raw ?? ''), stderr: '' }
+
+  // stdout decides alone when it yields a version; stderr is a FALLBACK for the
+  // host that prints nothing there, never a second vote. If both parse, stdout
+  // wins, so a stderr banner can never overrule the primary source.
+  const parsed = parseHostMajor(streams.stdout) ?? parseHostMajor(streams.stderr)
+
+  if (parsed === null) {
+    // A probe that RAN but whose output we cannot read is just as dangerous as
+    // one that failed: silently landing on V1 is the bug this gate exists to
+    // fix, so it gets the same visible warning.
+    warn(
+      `Could not parse the host OpenCode version from ` +
+        `${JSON.stringify(`${streams.stdout}${streams.stderr}`.trim())}. ` +
+        `Falling back to the V1 configuration; if this host is OpenCode 2.x re-run with ` +
+        `--opencode-version v2 (or v1 to force V1).`,
+    )
+    return 'v1'
+  }
+  if (parsed.unreadable !== undefined) {
+    // The host named itself and reported a major this gate refuses to read (0,
+    // or a calendar year). That is not noise like a trailing build date — it is
+    // the host's own version, so letting a surviving runtime token decide would
+    // be a silent guess. Say what we saw and fall back loudly.
+    warn(
+      `The host OpenCode version output reports major ${parsed.unreadable}, which is ` +
+        `not a release number this gate can interpret (a prerelease placeholder or a ` +
+        `calendar year). Falling back to the V1 configuration; pass --opencode-version v2 ` +
+        `if this host is OpenCode 2.x (or v1 to force V1).`,
+    )
+    return 'v1'
+  }
+  if (parsed.ambiguous) {
+    // Version-shaped tokens that disagree, with no tool name to break the tie.
+    // The reviewer accepted "wrong but loud" here; guessing silently is the
+    // defect this branch exists to prevent.
+    warn(
+      `The host OpenCode version output has contradictory versions ` +
+        `(${parsed.ambiguous.map((major) => `major ${major}`).join(', ')}) and does not say ` +
+        `which is the host's. Falling back to the V1 configuration; pass ` +
+        `--opencode-version v2 if this host is OpenCode 2.x (or v1 to force V1).`,
+    )
+    return 'v1'
+  }
+  return parsed.major >= 2 ? 'v2' : 'v1'
 }