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

package/scripts/install/plan.mjs

@@ -0,0 +1,287 @@
+/**
+ * plan.mjs — Per-file change planning for the Pantheon installer.
+ *
+ * Beta 11, Setup phase 1: `pantheon-opencode init ... --dry-run` must print the
+ * REAL per-file change set (create / update / remove / unchanged) that the SAME
+ * code path would produce, and write nothing.
+ *
+ * The plan is built by a change recorder threaded through the writer helpers as
+ * an OPTIONAL argument whose default is a module-level no-op singleton, so any
+ * caller (or writer) that is not instrumented keeps byte-identical behavior.
+ *
+ * NET-OUTCOME semantics: several writers can touch the same path in one pass
+ * (the TUI `unregister`→`register` toggle; the code-mode `syncDir` payload and
+ * its generated `manifest.json`). The LAST writer decides the net disk result,
+ * so a later no-write (skipped/unchanged) leaves the path UNCHANGED even when an
+ * earlier writer computed a would-be update. A no-write never promotes a path to
+ * a scored change.
+ *
+ * "Scored" vs "unscored": writers that increment the install summary
+ * (`stats.created`) alongside a genuine change are SCORED. Artifacts that are
+ * not part of that summary (the synthetic `.venv` entry, the state-only
+ * `.pantheon/install-state.json` write, the backup-set manifest, and the TUI
+ * stale-ref cleanup) are recorded UNSCORED so they still appear in the printed
+ * plan but never affect the consistency guard.
+ *
+ * Security: the recorder, the summary and the formatter deal in paths, actions
+ * and byte sizes ONLY. File contents and hashes stay internal — hashes are kept
+ * so a later phase can detect drift between a preview and an apply, and are
+ * never printed.
+ */
+
+import { createHash } from 'node:crypto'
+import { lstatSync, readFileSync } from 'node:fs'
+import { isAbsolute, relative } from 'node:path'
+
+/** The action vocabulary shared by the recorder, the summary and the formatter. */
+export const ACTIONS = Object.freeze({
+  CREATE: 'create',
+  UPDATE: 'update',
+  REMOVE: 'remove',
+  UNCHANGED: 'unchanged',
+  CONFLICT: 'conflict',
+})
+
+const ACTION_VALUES = new Set(Object.values(ACTIONS))
+
+/** Whether an action represents a real change to the target (not a no-write). */
+function isChange(action) {
+  return action === ACTIONS.CREATE || action === ACTIONS.UPDATE || action === ACTIONS.REMOVE
+}
+
+// Display order for the formatted plan.
+const DISPLAY_ORDER = Object.freeze([
+  ACTIONS.CREATE,
+  ACTIONS.UPDATE,
+  ACTIONS.REMOVE,
+  ACTIONS.CONFLICT,
+  ACTIONS.UNCHANGED,
+])
+
+/**
+ * The module-level no-op recorder. Instrumented writers whose caller did not
+ * pass a recorder fall back to this, so their behavior is byte-identical to an
+ * uninstrumented run (no allocation, no side effects).
+ */
+export function noopRecorder() {}
+
+/** The default recorder instance — the no-op singleton. */
+export const NOOP_RECORDER = noopRecorder
+
+/**
+ * Whether a recorder will actually collect anything. Writers in hot loops use
+ * this to skip `Buffer.byteLength(content)` on the common (uninstrumented) path.
+ *
+ * @param {unknown} recorder
+ * @returns {boolean}
+ */
+export function isRecording(recorder) {
+  return typeof recorder === 'function' && recorder !== NOOP_RECORDER
+}
+
+/** Normalize an arbitrary change into the `{ path, action, bytes, scored }` shape. */
+function normalizeChange(change) {
+  const action = change && ACTION_VALUES.has(change.action) ? change.action : ACTIONS.UNCHANGED
+  return {
+    path: String(change?.path ?? ''),
+    action,
+    bytes: Number.isFinite(change?.bytes) ? change.bytes : 0,
+    // Scored by default: most writers feed the install summary. Synthetic and
+    // state-only entries opt out explicitly with `scored: false`.
+    scored: !(change && change.scored === false),
+  }
+}
+
+/**
+ * Create a recorder that collects changes in memory. `recorder` is the function
+ * to thread into the writer helpers; `entries` holds the raw recorded changes.
+ *
+ * @returns {{ recorder: (change: object) => void, entries: object[] }}
+ */
+export function createRecorder() {
+  const entries = []
+  const recorder = (change) => {
+    entries.push(normalizeChange(change))
+  }
+  return { recorder, entries }
+}
+
+/**
+ * Record a single change. Writers call this instead of touching fs bookkeeping.
+ * With no explicit recorder the module-level no-op singleton is used.
+ *
+ * @param {{ path: string, action: string, bytes?: number, scored?: boolean }} change
+ * @param {(change: object) => void} [recorder]
+ */
+export function recordChange(change, recorder = NOOP_RECORDER) {
+  if (!isRecording(recorder)) return
+  recorder(normalizeChange(change))
+}
+
+/** Sort helper: display order first, then path for determinism. */
+function compareFiles(a, b) {
+  const order = DISPLAY_ORDER.indexOf(a.action) - DISPLAY_ORDER.indexOf(b.action)
+  if (order !== 0) return order
+  return a.path.localeCompare(b.path)
+}
+
+function zeroTotals() {
+  return { create: 0, update: 0, remove: 0, unchanged: 0, conflict: 0 }
+}
+
+/** Tally a change into one of the five action buckets. */
+function tally(totals, action) {
+  if (Object.hasOwn(totals, action)) totals[action] += 1
+}
+
+/**
+ * Collapse recorded changes into the final change set: one entry per path,
+ * reflecting the NET disk outcome, plus totals.
+ *
+ * The last record for a path decides the action, so a later no-write wins over
+ * an earlier would-be write. A path is scored only if at least one of its
+ * CHANGE records was scored AND the net action is still a change — a no-write
+ * can never turn a path into a scored change.
+ *
+ * @param {object[]} entries
+ * @returns {{
+ *   files: object[],
+ *   totals: { create: number, update: number, remove: number, unchanged: number, conflict: number },
+ *   scored: { create: number, update: number, remove: number, unchanged: number, conflict: number },
+ * }}
+ */
+export function summarizeChanges(entries = []) {
+  const byPath = new Map()
+  for (const entry of entries ?? []) {
+    const change = normalizeChange(entry)
+    let record = byPath.get(change.path)
+    if (!record) {
+      record = { path: change.path, action: change.action, bytes: change.bytes, scored: false }
+      byPath.set(change.path, record)
+    }
+    // The LAST writer decides the net on-disk outcome. A later no-write
+    // (skipped/unchanged) leaves the path unchanged even if an earlier writer
+    // computed a would-be update (e.g. unregister→register toggling).
+    record.action = change.action
+    record.bytes = change.bytes
+    // Only a genuine change can score a path; a no-write never does.
+    if (isChange(change.action) && change.scored) record.scored = true
+  }
+
+  const files = [...byPath.values()].sort(compareFiles)
+  for (const file of files) {
+    if (!isChange(file.action)) file.scored = false
+  }
+
+  const totals = zeroTotals()
+  const scored = zeroTotals()
+  for (const file of files) {
+    tally(totals, file.action)
+    if (file.scored) tally(scored, file.action)
+  }
+  return { files, totals, scored }
+}
+
+/** Human-readable byte size. The caller never sees raw bytes or hashes. */
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
+  if (bytes < 1024) return `${bytes} B`
+  const kb = bytes / 1024
+  if (kb < 1024) return `${kb.toFixed(1)} KB`
+  return `${(kb / 1024).toFixed(1)} MB`
+}
+
+/** Path shown in the plan: relative to the target when it lives inside it. */
+export function displayPath(target, filePath) {
+  if (!target) return filePath
+  const rel = relative(target, filePath)
+  if (rel === '') return '.'
+  return rel.startsWith('..') || isAbsolute(rel) ? filePath : rel
+}
+
+/**
+ * Render the secret-safe plan: paths + action + byte size ONLY. No contents,
+ * no hashes.
+ *
+ * @param {string} target - install target (used to relativize paths)
+ * @param {{ files: object[], totals: object }} plan
+ * @returns {string}
+ */
+export function formatChangePlan(target, plan) {
+  const { files, totals } = plan
+  const lines = []
+  lines.push(`Change plan — ${target}`)
+  for (const file of files) {
+    const isWrite = file.action === ACTIONS.CREATE || file.action === ACTIONS.UPDATE
+    const size = isWrite ? `  (${formatBytes(file.bytes)})` : ''
+    lines.push(`  ${file.action.padEnd(9)} ${displayPath(target, file.path)}${size}`)
+  }
+  lines.push(`  ${'─'.repeat(28)}`)
+  lines.push(
+    `  ${totals.create} create · ${totals.update} update · ${totals.remove} remove · ` +
+      `${totals.unchanged} unchanged · ${totals.conflict} conflict`,
+  )
+  lines.push('  No files were written.')
+  return lines.join('\n')
+}
+
+/**
+ * Snapshot a path for later drift comparison. Hashes stay internal.
+ *
+ * @param {string} filePath
+ * @returns {{ exists: boolean, sha256: string|null, size: number, mode: number|null }}
+ */
+export function snapshot(filePath) {
+  let stat
+  try {
+    stat = lstatSync(filePath)
+  } catch {
+    return { exists: false, sha256: null, size: 0, mode: null }
+  }
+  if (!stat.isFile()) {
+    return { exists: true, sha256: null, size: stat.size, mode: stat.mode }
+  }
+  let buffer
+  try {
+    buffer = readFileSync(filePath)
+  } catch {
+    return { exists: true, sha256: null, size: stat.size, mode: stat.mode }
+  }
+  return {
+    exists: true,
+    sha256: createHash('sha256').update(buffer).digest('hex'),
+    size: buffer.length,
+    mode: stat.mode,
+  }
+}
+
+/**
+ * Compare the preview's SCORED change count against this call's install
+ * summary delta. Returns a descriptor on mismatch, or `null` when they agree.
+ *
+ * Only the CHANGED count is gated (`create + update + remove` vs
+ * `stats.created`). `stats.skipped` deliberately mixes genuine file-unchanged
+ * outcomes with logical no-op skips that never touch a file (e.g. the V2 TUI
+ * registration skip), so it cannot be reconciled against `plan.scored.unchanged`
+ * without making the guard cry wolf. The meaningful invariant is: every change
+ * the summary counted must have been recorded — a preview that silently missed
+ * a writer is exactly a `stats.created` with no recorded change.
+ *
+ * Both sides must be scoped to a SINGLE `installOpenCode` call.
+ *
+ * @param {{ scored: object }} plan
+ * @param {{ created: number, skipped: number }} stats - per-call delta
+ * @returns {{ changed: number, unchanged: number, recordedChanged: number, recordedUnchanged: number }|null}
+ */
+export function planStatsMismatch(plan, stats) {
+  const changed = plan.scored.create + plan.scored.update + plan.scored.remove
+  if (changed !== stats.created) {
+    return {
+      changed,
+      unchanged: plan.scored.unchanged,
+      recordedChanged: stats.created,
+      recordedUnchanged: stats.skipped,
+    }
+  }
+  return null
+}

package/scripts/install/plugin.mjs

@@ -17,9 +17,14 @@ import { ROOT, writeIfChanged } from './shared.mjs'
  * @param {object} [options]
  * @param {boolean} [options.dryRun=false] - If true, don't write files
  * @param {'v1'|'v2'} [options.version='v1'] - Host plugin generation
+ * @param {(change: object) => void} [options.recorder] - optional change recorder for preview
  * @returns {{ created: number, skipped: number }}
  */
-export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1' } = {}) {
+export function copyPluginFiles(
+  srcDir,
+  dstDir,
+  { dryRun = false, version = 'v1', recorder = null } = {},
+) {
   const result = { created: 0, skipped: 0 }
 
   if (!dryRun) mkdirSync(dstDir, { recursive: true })
@@ -36,7 +41,7 @@ export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1'
   if (existsSync(distSrc)) {
     for (const f of readdirSync(distSrc)) {
       const c = readFileSync(join(distSrc, f), 'utf8')
-      const status = writeIfChanged(join(dstDir, 'dist', f), c, dryRun)
+      const status = writeIfChanged(join(dstDir, 'dist', f), c, dryRun, { recorder })
       if (status === 'created') result.created++
       else result.skipped++
     }
@@ -53,6 +58,7 @@ export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1'
       join(dstDir, 'package.json'),
       `${JSON.stringify(packageJson, null, 2)}\n`,
       dryRun,
+      { recorder },
     )
     if (pkgStatus === 'created') result.created++
     else result.skipped++
@@ -65,6 +71,7 @@ export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1'
       join(dstDir, 'tui.ts'),
       readFileSync(tuiEntrySrc, 'utf8'),
       dryRun,
+      { recorder },
     )
     if (entryStatus === 'created') result.created++
     else result.skipped++
@@ -77,6 +84,7 @@ export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1'
       v2ServerDestination,
       readFileSync(v2ServerEntry, 'utf8'),
       dryRun,
+      { recorder },
     )
     if (entryStatus === 'created') result.created++
     else result.skipped++
@@ -92,6 +100,7 @@ export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1'
       join(dstDir, 'package-lock.json'),
       readFileSync(lockSrc, 'utf8'),
       dryRun,
+      { recorder },
     )
     if (lockStatus === 'created') result.created++
     else result.skipped++
@@ -107,12 +116,13 @@ export function copyPluginFiles(srcDir, dstDir, { dryRun = false, version = 'v1'
  * @param {object} [options]
  * @param {boolean} [options.dryRun=false] - If true, don't write files
  * @param {boolean} [options.clean=false] - If true, remove existing before install
+ * @param {(change: object) => void} [options.recorder] - optional change recorder for preview
  * @returns {{ created: number, skipped: number, errors: number }}
  */
 export function installPlugin(
   srcDir,
   dstDir,
-  { dryRun = false, clean = false, version = 'v1' } = {},
+  { dryRun = false, clean = false, version = 'v1', recorder = null } = {},
 ) {
   const result = { created: 0, skipped: 0, errors: 0 }
 
@@ -120,7 +130,7 @@ export function installPlugin(
     rmSync(dstDir, { recursive: true, force: true })
   }
 
-  const copyResult = copyPluginFiles(srcDir, dstDir, { dryRun, version })
+  const copyResult = copyPluginFiles(srcDir, dstDir, { dryRun, version, recorder })
   result.created += copyResult.created
   result.skipped += copyResult.skipped
 
@@ -150,9 +160,10 @@ export function installPluginDependencies(pluginDir, { dryRun = false } = {}) {
  * @param {string} pluginId - Plugin identifier string
  * @param {object} [options]
  * @param {boolean} [options.dryRun=false]
+ * @param {(change: object) => void} [options.recorder] - optional change recorder for preview
  * @returns {'created'|'skipped'}
  */
-export function registerPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
+export function registerPlugin(tuiJsonPath, pluginId, { dryRun = false, recorder = null } = {}) {
   let tuiConfig = { plugin: [] }
   if (existsSync(tuiJsonPath)) {
     try {
@@ -168,7 +179,7 @@ export function registerPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
     tuiConfig.plugin.push(pluginId)
   }
   const tuiContent = `${JSON.stringify(tuiConfig, null, 2)}\n`
-  return writeIfChanged(tuiJsonPath, tuiContent, dryRun)
+  return writeIfChanged(tuiJsonPath, tuiContent, dryRun, { recorder })
 }
 
 /**
@@ -256,12 +267,14 @@ export function staleTuiRefs(pluginArray, knownPantheonPaths = []) {
  * @param {string} pluginId - Plugin to unregister
  * @param {object} [options]
  * @param {boolean} [options.dryRun=false]
+ * @param {string[]} [options.knownPantheonPaths=[]]
+ * @param {(change: object) => void} [options.recorder] - optional change recorder for preview
  * @returns {'created'|'skipped'}
  */
 export function unregisterPlugin(
   tuiJsonPath,
   pluginId,
-  { dryRun = false, knownPantheonPaths = [] } = {},
+  { dryRun = false, knownPantheonPaths = [], recorder = null } = {},
 ) {
   if (!existsSync(tuiJsonPath)) {
     // Nothing to clean — and never create an empty tui.json in a location
@@ -292,5 +305,6 @@ export function unregisterPlugin(
     return !isPantheonTuiRef(ref, knownPantheonPaths)
   })
   const tuiContent = `${JSON.stringify(tuiConfig, null, 2)}\n`
-  return writeIfChanged(tuiJsonPath, tuiContent, dryRun)
+  // Stale-ref cleanup is not part of the install summary, so record it unscored.
+  return writeIfChanged(tuiJsonPath, tuiContent, dryRun, { recorder, scored: false })
 }

package/scripts/install/shared.mjs

@@ -4,8 +4,6 @@
 
 import { spawnSync } from 'node:child_process'
 import {
-  copyFileSync,
-  cpSync,
   existsSync,
   lstatSync,
   mkdirSync,
@@ -16,7 +14,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const REQUIRED_NODE_MAJOR = 18
@@ -27,6 +25,8 @@ if (parseInt(process.versions.node.split('.')[0], 10) < REQUIRED_NODE_MAJOR) {
 
 import { dump, load } from 'js-yaml'
 
+import { ACTIONS, isRecording, recordChange } from './plan.mjs'
+
 export const __dirname = dirname(fileURLToPath(import.meta.url))
 export const ROOT = join(__dirname, '..', '..')
 export const AGENTS_DIR = join(ROOT, 'src', 'agents')
@@ -141,33 +141,6 @@ export function resolveTarget(target) {
   return join(process.cwd(), target)
 }
 
-export function createBackup(target) {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
-  const backupDir = join(target, '..', `.pantheon-bak-${basename(target)}-${timestamp}`)
-
-  console.log(`\n  💾 Creating backup: ${backupDir}`)
-  mkdirSync(backupDir, { recursive: true })
-
-  // Copy only relevant Pantheon directories/files
-  const items = ['agents', 'skills', 'commands', 'instructions', 'opencode.json', 'tui.json']
-  let count = 0
-  for (const item of items) {
-    const src = join(target, item)
-    try {
-      cpSync(src, join(backupDir, item), {
-        recursive: true,
-        errorOnExist: false,
-      })
-      count++
-    } catch {
-      // File or directory doesn't exist in target — skip silently
-    }
-  }
-
-  console.log(`  ✅ Backed up ${count} items to: ${backupDir}`)
-  return backupDir
-}
-
 export function detectAndReport(target) {
   const found = detectPlatforms(target).length > 0
 
@@ -302,19 +275,27 @@ function readFileOrNull(filePath) {
  *   filesystem CAS: the final re-read and the rename are still two syscalls, so
  *   a writer that lands between them is not prevented. What it does close is
  *   the window the installer actually races with — a config the caller parsed
- *   going stale during the same run — and it keeps the target and the `.bak`
- *   consistent with the bytes that were checked.
+ *   going stale during the same run — and it keeps the target consistent with
+ *   the bytes that were checked.
  * @param {(existing: string|null) => void} [options.beforeRecheck] - runs after
  *   the initial content check and before the last-moment re-read. Injection
  *   point so tests can simulate a concurrent writer landing in the window;
  *   production callers omit it (undefined is a no-op).
  * @param {(existing: string|null) => void} [options.beforeSwap] - runs after the
- *   expected-content checks pass and immediately before the rename, so side
- *   effects that must not fire on a conflict (e.g. the `.bak` copy) live here.
+ *   expected-content checks pass and immediately before the rename, for side
+ *   effects that must not fire on a conflict.
+ * @param {(change: object) => void} [options.recorder] - optional change
+ *   recorder. When supplied, the outcome is recorded (path + action + byte
+ *   size only) so `--dry-run` can print the real per-file plan. Defaults to
+ *   the module-level no-op singleton, so an uninstrumented caller is
+ *   byte-identical to before.
+ * @param {boolean} [options.scored] - set `false` when this write is not part
+ *   of the install summary (e.g. stale-ref cleanup), so it is shown in the plan
+ *   but excluded from the consistency guard.
  * @returns {'created'|'skipped'|'conflict'}
  */
 export function writeIfChanged(filePath, content, dryRun, options = {}) {
-  const { expectedContent, beforeSwap, beforeRecheck } = options
+  const { expectedContent, beforeSwap, beforeRecheck, recorder, scored } = options
 
   // Refuse to write through/over a symlink. A dangling symlink is invisible to
   // existsSync, and rename-over-link would replace the link rather than its
@@ -325,12 +306,29 @@ export function writeIfChanged(filePath, content, dryRun, options = {}) {
   }
 
   const existing = stat === null ? null : readFileOrNull(filePath)
+  const record = (outcome) => {
+    if (!isRecording(recorder)) return
+    const action =
+      outcome === 'conflict'
+        ? ACTIONS.CONFLICT
+        : outcome === 'skipped'
+          ? ACTIONS.UNCHANGED
+          : existing === null
+            ? ACTIONS.CREATE
+            : ACTIONS.UPDATE
+    recordChange(
+      { path: filePath, action, bytes: Buffer.byteLength(content, 'utf8'), scored },
+      recorder,
+    )
+  }
   if (existing === content) {
+    record('skipped')
     return 'skipped'
   }
   if (expectedContent !== undefined && existing !== expectedContent) {
     // The file changed since the caller read it (or appeared/disappeared).
     // Do not clobber the newer content; the caller decides how to react.
+    record('conflict')
     return 'conflict'
   }
   if (!dryRun) {
@@ -347,11 +345,12 @@ export function writeIfChanged(filePath, content, dryRun, options = {}) {
     // Last-moment re-read. The initial compare and this rename are separate
     // syscalls, so a concurrent writer can land in between; re-check the
     // expected bytes immediately before the swap. On a mismatch, drop the temp
-    // and leave the target AND any existing `.bak` byte-identical.
+    // and leave the target byte-identical.
     if (expectedContent !== undefined) {
       const current = readFileOrNull(filePath)
       if (current !== expectedContent) {
         rmSync(tmpPath, { force: true })
+        record('conflict')
         return 'conflict'
       }
     }
@@ -359,19 +358,20 @@ export function writeIfChanged(filePath, content, dryRun, options = {}) {
     if (typeof beforeSwap === 'function') beforeSwap(existing)
     renameSync(tmpPath, filePath)
   }
+  record('created')
   return 'created'
 }
 
 /**
- * beta.5: write the user's opencode.json with a same-directory backup of the
- * previous content. The installer rewrites the whole config; a `.bak` gives
- * the user a one-step recovery if a merge ever goes wrong.
+ * Write a config file atomically, honoring the compare-before-write guard.
+ * This used to always keep a `<config>.bak` sidecar; the main `opencode.json`
+ * no longer does — the target-scoped exact backup set
+ * (scripts/install/backup.mjs) preserves it byte-for-byte and
+ * `pantheon-opencode restore` reverts it.
  *
- * The backup is created INSIDE the `beforeSwap` hook, so it fires only after
- * both expected-content checks pass (the initial compare and the last-moment
- * re-read before the rename). A conflict observed at either point leaves the
- * target AND any pre-existing `.bak` untouched, rather than overwriting the
- * user's last known-good backup with a stale copy on a no-op write.
+ * A caller may still supply `beforeSwap` for a file the exact set does NOT
+ * cover: the GLOBAL `opencode-vision.json` lives outside the config dir, so
+ * vision-prompt passes a `beforeSwap` that keeps its `<file>.bak` recovery.
  *
  * @param {string} filePath
  * @param {string} content
@@ -382,14 +382,9 @@ export function writeConfigWithBackup(filePath, content, dryRun, options = {}) {
   return writeIfChanged(filePath, content, dryRun, {
     expectedContent: options.expectedContent,
     beforeRecheck: options.beforeRecheck,
-    beforeSwap: (existing) => {
-      if (existing === null) return
-      try {
-        copyFileSync(filePath, `${filePath}.bak`)
-      } catch {
-        // Best-effort: a backup failure must not block the install.
-      }
-    },
+    beforeSwap: options.beforeSwap,
+    recorder: options.recorder,
+    scored: options.scored,
   })
 }
 
@@ -455,7 +450,7 @@ export function serializeFm(fm) {
   })
 }
 
-export function installSkills(skills, target, dryRun, subDir = '.opencode') {
+export function installSkills(skills, target, dryRun, subDir = '.opencode', recorder = null) {
   const srcSkillsDir = join(ROOT, 'src', 'skills')
   const dstSkillsDir = join(target, subDir, 'skills')
 
@@ -481,9 +476,29 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
           const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
           if (existing === content) {
             skipped++
+            if (isRecording(recorder)) {
+              recordChange(
+                {
+                  path: dstPath,
+                  action: ACTIONS.UNCHANGED,
+                  bytes: Buffer.byteLength(content, 'utf8'),
+                },
+                recorder,
+              )
+            }
           } else {
             if (!dryRun) writeFileSync(dstPath, content, 'utf8')
             created++
+            if (isRecording(recorder)) {
+              recordChange(
+                {
+                  path: dstPath,
+                  action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+                  bytes: Buffer.byteLength(content, 'utf8'),
+                },
+                recorder,
+              )
+            }
           }
         }
       }
@@ -504,6 +519,9 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
           console.log(`    🗑️  Removed stale skill: ${entry}`)
         }
         created++
+        // A stale removal increments `created` (a change), so it must also be
+        // recorded or the preview would under-report on a non-fresh target.
+        recordChange({ path: dstPath, action: ACTIONS.REMOVE, bytes: 0 }, recorder)
       }
     }
   }
@@ -511,7 +529,7 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
   return { created, skipped }
 }
 
-export function syncDir(src, dst, dryRun, clean = false, filter = null) {
+export function syncDir(src, dst, dryRun, clean = false, filter = null, recorder = null) {
   if (!existsSync(src)) return { created: 0, skipped: 0 }
   let created = 0
   let skipped = 0
@@ -530,7 +548,7 @@ export function syncDir(src, dst, dryRun, clean = false, filter = null) {
     const srcPath = join(src, entry)
     const dstPath = join(dst, entry)
     if (statSync(srcPath).isDirectory()) {
-      const sub = syncDir(srcPath, dstPath, dryRun, false, filter)
+      const sub = syncDir(srcPath, dstPath, dryRun, false, filter, recorder)
       created += sub.created
       skipped += sub.skipped
     } else {
@@ -538,9 +556,25 @@ export function syncDir(src, dst, dryRun, clean = false, filter = null) {
       const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
       if (existing === content) {
         skipped++
+        if (isRecording(recorder)) {
+          recordChange(
+            { path: dstPath, action: ACTIONS.UNCHANGED, bytes: Buffer.byteLength(content, 'utf8') },
+            recorder,
+          )
+        }
       } else {
         if (!dryRun) writeFileSync(dstPath, content, 'utf8')
         created++
+        if (isRecording(recorder)) {
+          recordChange(
+            {
+              path: dstPath,
+              action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+              bytes: Buffer.byteLength(content, 'utf8'),
+            },
+            recorder,
+          )
+        }
       }
     }
   }