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

package/scripts/cost.mjs

@@ -3,19 +3,42 @@
  * cost.mjs — read-only token aggregation from opencode.db.
  *
  * CLI fallback for the `pantheon_cost` tool when node:sqlite is unavailable
- * in the plugin process. Uses node:sqlite itself and prints a single JSON
- * object to stdout:
- *   { ok: true, days, rows: [{agent, phase, tokensInput, tokensOutput, tokensTotal}] }
+ * in the plugin process. Prints a single JSON object to stdout:
+ *   { ok: true, days, rows: [{agent, phase, tokensInput, tokensOutput, tokensTotal}], coverage }
  *   { ok: false, error: "<message>" }          (exit code 1)
  *
- * NEVER writes to the database — opened read-only. Malformed rows are
- * skipped; assistant messages carry the authoritative token usage.
+ * ## This file is a MIRROR of src/pantheon/cost-command.ts
+ *
+ * It cannot import that module — it exists precisely to run on a plain Node
+ * where the plugin runtime cannot — so the two implementations duplicate the
+ * same contract on purpose:
+ *   - ledger families are detected by TABLE PRESENCE, never by filename and
+ *     never by a pinned host generation;
+ *   - PANTHEON_OPENCODE_VERSION only NARROWS an already-detected set;
+ *   - V1 marks assistant turns with `data.role`, V2 with the `type` COLUMN
+ *     (V2 payloads carry no `role` key at all);
+ *   - the coverage counters mean the same thing in both, because the caller
+ *     feeds them to the same diagnosis.
+ *
+ * Every one of those was a real divergence once: this script kept the V1
+ * predicate and dropped 100% of a V2 ledger, while the caller reported a
+ * successful, empty report. A change to one side that is not made on the other
+ * is a regression, not a refactor.
+ *
+ * NEVER writes to the database — opened read-only. Malformed rows are skipped;
+ * assistant messages carry the authoritative token usage.
  *
  * Usage: node scripts/cost.mjs --db-path <dbPath> --days <days>
  */
 import { existsSync } from 'node:fs'
 import { DatabaseSync } from 'node:sqlite'
 
+/** Ledger families a host database can carry; a migrated one carries both. */
+const COST_SOURCES = ['message', 'session_message']
+
+/** Which family each host generation stores its ledger in. */
+const VERSION_SOURCES = { v1: 'message', v2: 'session_message' }
+
 /**
  * Fail via exitCode + natural process exit (NEVER process.exit right after
  * stdout.write — the pipe is async and the write can be truncated).
@@ -26,22 +49,201 @@ function fail(message) {
   process.exitCode = 1
 }
 
-function assertCompatibleSchema(db) {
-  const table = db
-    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'message'")
-    .get()
-  if (!table)
-    throw new Error('incompatible opencode.db schema: required "message" table is missing')
-  const columns = db.prepare('PRAGMA table_info(message)').all()
-  const names = new Set(columns.map((column) => column.name))
-  const missing = ['data', 'time_created'].filter((name) => !names.has(name))
+/** Read and validate the optional host-generation selector. */
+function requestedVersion() {
+  const configured = process.env.PANTHEON_OPENCODE_VERSION
+  if (configured === undefined || configured === '') return undefined
+  if (configured !== 'v1' && configured !== 'v2') {
+    throw new Error(`invalid PANTHEON_OPENCODE_VERSION "${configured}"; expected "v1" or "v2"`)
+  }
+  return configured
+}
+
+/**
+ * Detect the ledger families by TABLE PRESENCE, then narrow if asked.
+ *
+ * Presence is the only reliable discriminator: every real installation writes
+ * `opencode.db`, and a migrated database carries BOTH families at once.
+ */
+function resolveSources(db) {
+  const present = new Set(
+    db
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('message', 'session_message')",
+      )
+      .all()
+      .map((row) => String(row.name)),
+  )
+  const detected = COST_SOURCES.filter((source) => present.has(source))
+  if (detected.length === 0) {
+    throw new Error(
+      'incompatible opencode.db schema: neither the "message" nor the "session_message" table exists, so there is no token ledger to read',
+    )
+  }
+  const requested = requestedVersion()
+  if (requested === undefined) return detected
+  const narrowed = detected.filter((source) => source === VERSION_SOURCES[requested])
+  if (narrowed.length === 0) {
+    throw new Error(
+      `incompatible opencode.db schema: PANTHEON_OPENCODE_VERSION=${requested} selected no table family, but this database contains ${detected.join(' and ')}`,
+    )
+  }
+  return narrowed
+}
+
+/** The columns this reader needs from the family it is about to query. */
+function assertColumns(db, source) {
+  const names = new Set(
+    db
+      .prepare(`PRAGMA table_info(${source})`)
+      .all()
+      .map((column) => String(column.name)),
+  )
+  const required =
+    source === 'session_message' ? ['data', 'time_created', 'type'] : ['data', 'time_created']
+  const missing = required.filter((name) => !names.has(name))
   if (missing.length > 0) {
     throw new Error(
-      `incompatible opencode.db schema: message table is missing ${missing.join(', ')}; select the matching V1/V2 database`,
+      `incompatible opencode.db schema: ${source} table is missing ${missing.join(', ')}; select a database whose token layout this build understands`,
     )
   }
 }
 
+/**
+ * Parse one payload. Returns undefined for anything unparseable, which is how
+ * both readers treat it: the V1 counter requires json_valid(data) and the V2
+ * aggregate does too, so a malformed row contributes to nothing.
+ *
+ * Deliberately NOT unwrapping a nested `data` string: the in-process reader
+ * extracts `$.role`/`$.agent` from the TOP level, so a wrapped payload yields
+ * NULL there and is dropped. Unwrapping here would resurrect rows the primary
+ * path cannot see, and the two readers would disagree on the same file.
+ */
+function readPayload(data) {
+  try {
+    const parsed = JSON.parse(String(data))
+    return typeof parsed === 'object' && parsed !== null ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** CAST(json_extract(...) AS INTEGER) semantics: absent or non-numeric → 0. */
+function toToken(value) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * Map key for one aggregated row.
+ *
+ * NUL-separated: agent names cannot contain it, so an agent whose name ends
+ * in the phase cannot collide with a phase-only row.
+ */
+function rowKey(agent, phase) {
+  return `${agent}\u0000${phase}`
+}
+
+/** Read one family.
+ *
+ * `assistantRows` follows the per-generation discriminator exactly, including
+ * the asymmetry that matters: V2 counts an assistant row by its COLUMN whether
+ * or not the payload parses, because that counter SQL has no json_valid gate.
+ */
+function readSource(db, source, since) {
+  const windowRow = db
+    .prepare(
+      `SELECT COUNT(*) AS scanned, MIN(time_created) AS windowStart FROM ${source} WHERE time_created >= ?`,
+    )
+    .get(since)
+  const databaseRow = db.prepare(`SELECT MIN(time_created) AS databaseStart FROM ${source}`).get()
+  const select = source === 'session_message' ? 'SELECT type, data' : 'SELECT data'
+  const rows = db.prepare(`${select} FROM ${source} WHERE time_created >= ?`).all(since)
+
+  const groups = new Map()
+  let assistantRows = 0
+  for (const row of rows) {
+    const info = readPayload(row.data)
+    if (source === 'session_message') {
+      if (row.type !== 'assistant') continue
+      assistantRows += 1
+      if (info === undefined) continue
+    } else {
+      if (info === undefined || info.role !== 'assistant') continue
+      assistantRows += 1
+    }
+    const rawAgent = info.agent
+    const agent = rawAgent == null ? '' : typeof rawAgent === 'string' ? rawAgent : String(rawAgent)
+    if (agent === '') continue
+    // V2 has no phase anywhere: its SQL emits the literal, so the mirror does
+    // too rather than inventing a column the reader never had.
+    const metadata = info.metadata
+    const phase =
+      source === 'session_message'
+        ? 'unknown'
+        : (typeof info.phase === 'string' && info.phase) ||
+          (typeof metadata?.phase === 'string' && metadata.phase) ||
+          'unknown'
+    const tokensInput = toToken(info.tokens?.input)
+    const tokensOutput = toToken(info.tokens?.output)
+    const key = rowKey(agent, phase)
+    const acc = groups.get(key) ?? {
+      agent,
+      phase,
+      tokensInput: 0,
+      tokensOutput: 0,
+      tokensTotal: 0,
+    }
+    acc.tokensInput += tokensInput
+    acc.tokensOutput += tokensOutput
+    acc.tokensTotal += tokensInput + tokensOutput
+    groups.set(key, acc)
+  }
+
+  return {
+    groups,
+    scanned: Number(windowRow?.scanned ?? 0) || 0,
+    windowStart: numberOrUndefined(windowRow?.windowStart),
+    databaseStart: numberOrUndefined(databaseRow?.databaseStart),
+    assistantRows,
+  }
+}
+
+function numberOrUndefined(value) {
+  if (value === null || value === undefined) return undefined
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/**
+ * The same verdict the in-process reader reaches, with the same phrase: the
+ * caller maps "no readable token source" to UNSUPPORTED, so emitting anything
+ * softer here would resurrect the silent-empty-report failure this replaced.
+ *
+ * `scanned === 0` is NOT unreadable — an empty window is a real, reportable
+ * answer, and only a ledger that was found and could not be read is a fault.
+ */
+function diagnoseUnreadableLedger(coverage, rows, days) {
+  if (coverage.scanned === 0) return undefined
+  const tables = coverage.sources.join(' and ')
+  if (coverage.assistantRows === 0) {
+    return (
+      `no readable token source: ${coverage.scanned} row(s) were scanned in the last ${days} day(s) ` +
+      `but none matched the assistant discriminator of ${tables}, so no usage can be attributed. ` +
+      'This is an unrecognised ledger layout, not an empty one; point PANTHEON_COST_DB at a ' +
+      'database whose token layout this build understands.'
+    )
+  }
+  if (!rows.some((row) => row.tokensInput !== 0 || row.tokensOutput !== 0)) {
+    return (
+      `no readable token source: ${coverage.assistantRows} assistant row(s) were found in ${tables} ` +
+      'but none carried both an attributable agent and a token payload, so no usage can be ' +
+      'attributed. This is an unrecognised ledger layout, not an empty one.'
+    )
+  }
+  return undefined
+}
+
 function main() {
   const argv = process.argv.slice(2)
   const valueFor = (name) => {
@@ -56,44 +258,45 @@ function main() {
 
   try {
     const db = new DatabaseSync(dbPath, { readOnly: true })
-    assertCompatibleSchema(db)
+    const sources = resolveSources(db)
+    for (const source of sources) assertColumns(db, source)
     const since = Date.now() - days * 86_400_000
-    const rows = db.prepare('SELECT data FROM message WHERE time_created >= ?').all(since)
-    db.close()
 
     const byAgent = new Map()
-    for (const row of rows) {
-      try {
-        const outer = JSON.parse(String(row.data))
-        const info = typeof outer.data === 'string' ? JSON.parse(outer.data) : outer
-        if (info.role !== 'assistant') continue
-        const agent = typeof info.agent === 'string' && info.agent !== '' ? info.agent : null
-        if (!agent) continue
-        const metadata = info.metadata
-        const phase =
-          (typeof info.phase === 'string' && info.phase) ||
-          (typeof metadata?.phase === 'string' && metadata.phase) ||
-          'unknown'
-        const tokensInput = Number(info.tokens?.input) || 0
-        const tokensOutput = Number(info.tokens?.output) || 0
-        const key = `${agent}\u0000${phase}`
+    const coverage = { sources: [], scanned: 0, assistantRows: 0 }
+    const note = (key, value) => {
+      if (value === undefined) return
+      const current = coverage[key]
+      coverage[key] = current === undefined ? value : Math.min(current, value)
+    }
+    for (const source of sources) {
+      const read = readSource(db, source, since)
+      for (const row of read.groups.values()) {
+        const key = rowKey(row.agent, row.phase)
         const acc = byAgent.get(key) ?? {
-          agent,
-          phase,
+          agent: row.agent,
+          phase: row.phase,
           tokensInput: 0,
           tokensOutput: 0,
           tokensTotal: 0,
         }
-        acc.tokensInput += tokensInput
-        acc.tokensOutput += tokensOutput
-        acc.tokensTotal += tokensInput + tokensOutput
+        acc.tokensInput += row.tokensInput
+        acc.tokensOutput += row.tokensOutput
+        acc.tokensTotal += row.tokensInput + row.tokensOutput
         byAgent.set(key, acc)
-      } catch {
-        // Skip malformed rows — a partial ledger never breaks the report.
       }
+      coverage.sources.push(source)
+      coverage.scanned += read.scanned
+      coverage.assistantRows += read.assistantRows
+      note('windowStart', read.windowStart)
+      note('databaseStart', read.databaseStart)
     }
+    db.close()
+
     const result = [...byAgent.values()].sort((a, b) => b.tokensTotal - a.tokensTotal)
-    process.stdout.write(JSON.stringify({ ok: true, days, rows: result }))
+    const unreadable = diagnoseUnreadableLedger(coverage, result, days)
+    if (unreadable !== undefined) return fail(unreadable)
+    process.stdout.write(JSON.stringify({ ok: true, days, rows: result, coverage }))
   } catch (err) {
     fail(err instanceof Error ? err.message : String(err))
   }

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

@@ -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),

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
 // ---------------------------------------------------------------------------