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

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/agents-md.mjs

@@ -2,7 +2,7 @@
 /**
  * agents-md.mjs — Dynamic AGENTS.md generator from canonical agent frontmatter
  *
- * Reads all agents/*.agent.md files, extracts name + description from frontmatter,
+ * Reads all canonical src/agents/*.md files, extracts name + description from frontmatter,
  * and generates AGENTS.md content dynamically. Eliminates hardcoded agent tables
  * in platform installers (claude.mjs, cursor.mjs, windsurf.mjs, cline.mjs, etc.).
  *
@@ -21,7 +21,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import yaml from 'js-yaml'
+import { load } from 'js-yaml'
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -47,7 +47,7 @@ function parseAgentFrontmatter(content) {
   if (!match) return null
 
   try {
-    const fm = yaml.load(match[1])
+    const fm = load(match[1])
     if (!fm || typeof fm !== 'object' || !fm.name) return null
     return {
       name: String(fm.name),
@@ -64,7 +64,7 @@ function parseAgentFrontmatter(content) {
 // ---------------------------------------------------------------------------
 
 /**
- * Read all canonical agents/*.agent.md files, parse frontmatter,
+ * Read all canonical src/agents/*.md files, parse frontmatter,
  * and return an array of agent metadata objects sorted alphabetically by name.
  *
  * Skips files that don't match the `*.agent.md` pattern, files without

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',
@@ -229,8 +230,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 +289,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
 // ---------------------------------------------------------------------------
@@ -304,6 +383,227 @@ const V2_TO_V1_RENAMES = Object.fromEntries(
   Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k]),
 )
 
+/**
+ * Agent fields owned by the framework. Mirrors the exported MANAGED_FIELDS in
+ * install/opencode.mjs plus `source`, which the installer writes next to them.
+ * The migration runs before that merge, so it has to apply the same precedence
+ * itself when both `agent` and `agents` coexist: these come from the V1 block,
+ * every other field stays the user's.
+ *
+ * `permissions` is the V2 name — the converter renames the V1 `permission`
+ * block before the merge runs.
+ *
+ * `description` is deliberately absent, and this list is deliberately narrower
+ * than what the installer writes. The installer writes a description only when
+ * it creates an agent (install/opencode.mjs, the new-agent branch); on an agent
+ * that already exists it leaves the value alone, under its own comment "Existing
+ * agent fields belong to the user". So a description is framework-owned for a
+ * NEW agent and user-owned for an EXISTING one. Listing it here would make the
+ * migration stricter than the installer and would overwrite a description the
+ * installer deliberately preserves. mergeManagedAgents carries the value across
+ * instead, so it survives the merge without being treated as framework-owned.
+ *
+ * KNOWN DEBT: the installer still writes the V1 spelling `permission`, while V2
+ * reads `permissions`. An agent that goes through this merge can therefore end
+ * up carrying both keys, with `permission` left as dead weight that nothing
+ * reads. Tracked for the next slice; not fixed here, because picking a winner
+ * changes what an install writes.
+ */
+export const MANAGED_AGENT_FIELDS = Object.freeze([
+  'source',
+  'temperature',
+  'color',
+  'permissions',
+  'mode',
+  'hidden',
+  'disable_model_invocation',
+])
+
+/**
+ * Compare this module's managed-agent list against the installer's.
+ *
+ * The two merge paths have to agree: the migration reimplements the installer's
+ * merge because it runs before it. A field present on only one side is silent
+ * divergence — either the migration overwrites a field the installer leaves
+ * alone, or it stops mirroring one the installer now writes. Both directions
+ * matter, so the result is reported as a pair of differences rather than a
+ * boolean.
+ *
+ * Names are compared after the converter's renames, because that is the
+ * spelling the merge actually sees.
+ *
+ * @param {string[]} installerFields - MANAGED_FIELDS as exported by install/opencode.mjs
+ * @returns {{ onlyInMigration: string[], onlyInInstaller: string[] }}
+ */
+export function managedAgentFieldDrift(installerFields) {
+  const toV2Name = (field) => V1_TO_V2_RENAMES[field] ?? field
+  const migration = new Set(MANAGED_AGENT_FIELDS.map(toV2Name))
+  const installer = new Set(installerFields.map(toV2Name))
+  return {
+    onlyInMigration: [...migration].filter((f) => !installer.has(f)).sort(),
+    onlyInInstaller: [...installer].filter((f) => !migration.has(f)).sort(),
+  }
+}
+
+/** @returns {boolean} true for a plain name→config map (not null/array) */
+function isAgentMap(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Merge the converted V1 `agent` block into an existing V2 `agents` base.
+ *
+ * Agents present in both are merged field by field: the base is kept, keys the
+ * base does not have are filled in from the V1 block, and MANAGED_AGENT_FIELDS
+ * are overwritten by the V1 values. Agents present in only one block are taken
+ * as they are — a union, not a replacement.
+ *
+ * Filling the gaps matters, and it is not description-specific: any key present
+ * only in the V1 block used to vanish here — `model`, `provider` and `mcp` too.
+ * `description` is the visible case, because the installer never writes one for
+ * an existing agent, so the V1 block is the only place that value can come from
+ * and the agent lost it on every install, permanently. Filling gaps can never
+ * destroy a base value; on conflict the base still wins, as before.
+ *
+ * @param {object} base - existing V2 `agents` map
+ * @param {object} managed - converted V1 `agent` map
+ * @returns {object} merged map
+ */
+function mergeManagedAgents(base, managed) {
+  const merged = { ...base }
+
+  for (const [name, agentConfig] of Object.entries(managed)) {
+    const existing = merged[name]
+    if (!isAgentMap(existing) || !isAgentMap(agentConfig)) {
+      merged[name] = agentConfig
+      continue
+    }
+    const entry = { ...existing }
+    for (const [field, value] of Object.entries(agentConfig)) {
+      if (!(field in entry)) entry[field] = value
+    }
+    for (const field of MANAGED_AGENT_FIELDS) {
+      if (field in agentConfig) entry[field] = agentConfig[field]
+    }
+    merged[name] = entry
+  }
+
+  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
 // ---------------------------------------------------------------------------
@@ -333,7 +633,20 @@ export function migrateV1toV2(config) {
         }
         agents[agentName] = ac
       }
-      result.agents = agents
+      // An `agents` (V2) block may already exist — the installed opencode.json
+      // carries both, in either key order. Renaming onto it with a plain
+      // replace dropped the whole managed merge, so merge instead.
+      const base = result.agents
+      result.agents = isAgentMap(base) ? mergeManagedAgents(base, agents) : agents
+    } else if (key === 'agents') {
+      // V2 block: it is the base. The singular `agent` key may already have
+      // been converted above, in which case merge the two.
+      const managed = result.agents
+      if (isAgentMap(value)) {
+        result.agents = isAgentMap(managed) ? mergeManagedAgents(value, managed) : value
+      } else if (!isAgentMap(managed)) {
+        result.agents = value
+      }
     } else if (key === 'provider' && typeof value === 'object' && value !== null) {
       const providers = {}
       for (const [provName, provConfig] of Object.entries(value)) {

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],
       })
     }
@@ -173,13 +168,20 @@ export function healthCheck(target, { dryRun = false, pythonTarget = target } =
   if (python) {
     const mcpResult = spawnSync(
       python,
-      ['-c', 'from mcp.server.fastmcp import FastMCP; print(FastMCP.__module__)'],
+      [
+        '-c',
+        'import importlib.metadata as metadata; from fastmcp import FastMCP; ' +
+          'print(f\'mcp={metadata.version("mcp")} fastmcp={metadata.version("fastmcp")} {FastMCP.__module__}\')',
+      ],
       { stdio: 'pipe' },
     )
     if (mcpResult.status === 0) {
       results.passed.push({ check: 'mcp-sdk', detail: mcpResult.stdout.toString().trim() })
     } else {
-      results.failed.push({ check: 'mcp-sdk', detail: 'NOT INSTALLED — all MCP servers will fail' })
+      results.failed.push({
+        check: 'mcp-sdk',
+        detail: 'MCP SDK or standalone FastMCP is unavailable — all MCP servers will fail',
+      })
     }
   }
   // Check 4: the memory server's only search backend is the stdlib's own
@@ -224,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)',
     },
   ]