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

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/exit-codes.mjs

@@ -0,0 +1,26 @@
+/**
+ * exit-codes.mjs — the process exit code the `init` CLI returns for an
+ * `installOpenCode` result. Pure, so the mapping is unit-testable without
+ * spawning the CLI.
+ *
+ *   `0`   success, or plan-only / declined (nothing applied)
+ *   `1`   failure (the CLI handles thrown errors separately)
+ *   `2`   apply requested without authorization (non-interactive, no --yes)
+ *   `3`   drift detected — a planned target changed between plan and apply
+ *   `130` canceled
+ */
+
+export function resolveInstallExitCode(result, isDryRun) {
+  if (isDryRun) return 0
+  if (result?.applied !== false) return 0
+  switch (result.reason) {
+    case 'not-authorized':
+      return 2
+    case 'drift':
+      return 3
+    case 'canceled':
+      return 130
+    default:
+      return 0
+  }
+}

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)',
     },
   ]

package/scripts/install/interactive.mjs

@@ -184,7 +184,7 @@ export async function promptConfirm(message, { default: def = true } = {}) {
       reject(new Error('Canceled'))
     }
 
-    function handler(_str, key) {
+    function handler(str, key) {
       if (!key) return
       if ((key.ctrl && key.name === 'c') || key.name === 'escape') {
         cancel()
@@ -208,6 +208,20 @@ export async function promptConfirm(message, { default: def = true } = {}) {
   })
 }
 
+/**
+ * Apply-gate prompt. Unlike the pre-install confirm this defaults to NO, so a
+ * bare Enter never authorizes a write. In a non-TTY it returns the default
+ * (`false`) without blocking — callers that must not prompt at all should branch
+ * on TTY before calling.
+ *
+ * @param {string} planSummary e.g. "Apply these 12 changes?"
+ * @param {{ default?: boolean }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function promptReview(planSummary, { default: def = false } = {}) {
+  return promptConfirm(planSummary, { default: def })
+}
+
 export async function promptList(options, { title = '' } = {}) {
   if (options.length === 0) throw new Error('No options provided')
   if (options.length === 1) return options[0].value
@@ -329,7 +343,7 @@ export async function runInteractiveInstall({ components = [], defaultComponents
     {
       name: 'skills',
       value: 'skills',
-      description: `Reusable skill workflows (${21} skills)`,
+      description: `Reusable skill workflows (${20} skills)`,
     },
     {
       name: 'instructions',

package/scripts/install/migrate.mjs

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { ACTIONS, recordChange, snapshot } from './plan.mjs'
 import { createInitialState, readState, writeState } from './state.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -44,10 +45,10 @@ export function detectVersion(target) {
  *
  * @param {string} target - Installation directory
  * @param {string|null} currentVersion - Detected version (null = fresh install)
- * @param {{ dryRun?: boolean }} [options]
+ * @param {{ dryRun?: boolean, recorder?: (change: object) => void }} [options]
  * @returns {{ applied: number, messages: string[] }}
  */
-export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
+export function runMigrations(target, currentVersion, { dryRun = false, recorder = null } = {}) {
   const applied = []
   const semver = parseSemver(currentVersion)
 
@@ -104,28 +105,46 @@ export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
   }
 
   // ── Write updated state ───────────────────────────────────────────
-  if (applied.length > 0 && !dryRun) {
-    const newVersion = formatSemver(semver)
-    let state = readState(target)
-    if (!state) state = createInitialState(newVersion)
-    state.pantheon_version = newVersion
-    for (const m of applied) {
-      state.applied_migrations.push({
-        from: m.from,
-        to: m.to,
-        applied_at: new Date().toISOString(),
-        status: 'completed',
-      })
-    }
-    if (!state.components) {
-      state.components = {
-        agents: { version: 1, status: 'installed' },
-        skills: { version: 1, status: 'installed' },
-        plugins: { version: 1, status: 'installed' },
-        runtime: { version: 1, status: 'installed' },
+  if (applied.length > 0) {
+    const statePath = join(target, '.pantheon', 'install-state.json')
+    if (dryRun) {
+      // State-only bookkeeping write: recorded so the preview is complete, but
+      // unscored because the install summary does not count it. Classified as
+      // an update — a migration that applies implies a state file existed.
+      recordChange({ path: statePath, action: ACTIONS.UPDATE, bytes: 0, scored: false }, recorder)
+    } else {
+      const newVersion = formatSemver(semver)
+      let state = readState(target)
+      const stateExisted = state !== null
+      if (!state) state = createInitialState(newVersion)
+      state.pantheon_version = newVersion
+      for (const m of applied) {
+        state.applied_migrations.push({
+          from: m.from,
+          to: m.to,
+          applied_at: new Date().toISOString(),
+          status: 'completed',
+        })
       }
+      if (!state.components) {
+        state.components = {
+          agents: { version: 1, status: 'installed' },
+          skills: { version: 1, status: 'installed' },
+          plugins: { version: 1, status: 'installed' },
+          runtime: { version: 1, status: 'installed' },
+        }
+      }
+      writeState(target, state)
+      recordChange(
+        {
+          path: statePath,
+          action: stateExisted ? ACTIONS.UPDATE : ACTIONS.CREATE,
+          bytes: snapshot(statePath).size,
+          scored: false,
+        },
+        recorder,
+      )
     }
-    writeState(target, state)
   }
 
   return {