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

package/scripts/install-mcp.mjs

@@ -24,6 +24,7 @@ import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
+import { migrateMcpEntrypointPaths } from './install/config-migration.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..')
@@ -70,11 +71,11 @@ function resolveServerScript(relPath) {
 }
 
 const VENV_PYTHON = resolveVenvPython()
-const MCP_RESOURCES_SERVER = resolveServerScript('scripts/mcp_resources_server.py')
-const CODE_MODE_SERVER = resolveServerScript('scripts/code_mode_server.py')
-const MEMORY_MCP_SERVER = resolveServerScript('scripts/memory_mcp_server.py')
-const MCP_PERSISTENCE_SERVER = resolveServerScript('scripts/mcp_persistence_server.py')
-const PANTHEON_VISION_SERVER = resolveServerScript('src/mcp/pantheon_vision_server.py')
+const MCP_RESOURCES_SERVER = resolveServerScript('scripts/mcp_resources.py')
+const CODE_MODE_SERVER = resolveServerScript('scripts/code_mode.py')
+const MEMORY_MCP_SERVER = resolveServerScript('scripts/memory_mcp.py')
+const MCP_PERSISTENCE_SERVER = resolveServerScript('scripts/mcp_persistence.py')
+const PANTHEON_VISION_SERVER = resolveServerScript('src/mcp/pantheon_vision.py')
 
 // ---------------------------------------------------------------------------
 // MCP Definitions
@@ -209,7 +210,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'mcp_resources_server.py not found at resolved path' }
+      return { ok: false, message: 'mcp_resources.py not found at resolved path' }
     },
   },
   'pantheon-code-mode': {
@@ -230,7 +231,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'code_mode_server.py not found at resolved path' }
+      return { ok: false, message: 'code_mode.py not found at resolved path' }
     },
   },
   'pantheon-memory': {
@@ -251,7 +252,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'memory_mcp_server.py not found at resolved path' }
+      return { ok: false, message: 'memory_mcp.py not found at resolved path' }
     },
   },
   'pantheon-persistence': {
@@ -272,7 +273,7 @@ export const MCPS = {
       if (existsSync(scriptPath)) {
         return { ok: true, message: 'server script present' }
       }
-      return { ok: false, message: 'mcp_persistence_server.py not found at resolved path' }
+      return { ok: false, message: 'mcp_persistence.py not found at resolved path' }
     },
   },
   'pantheon-vision': {
@@ -471,8 +472,22 @@ function writeMcpConfig(platformName, mcpKey, dryRun, force) {
     config[key] = {}
   }
 
+  // Heal pre-rename MCP entrypoint paths before the skip check, so re-running
+  // the installer repairs an existing config whose `*_server.py` paths were
+  // orphaned by the entrypoint rename. Without this the rename is a silent
+  // break for every already-installed config (see config-migration.mjs).
+  const healed = migrateMcpEntrypointPaths(config[key])
+
   // Check if the MCP already has an entry
   if (config[key][mcpKey] && !force) {
+    if (healed > 0 && !dryRun) {
+      writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+      return {
+        status: 'healed',
+        path: configPath,
+        reason: `Updated ${healed} stale MCP entrypoint path(s) in ${platform.configFile}`,
+      }
+    }
     return {
       status: 'skipped',
       reason: `Already exists in ${platform.configFile} (use --force to overwrite)`,
@@ -705,6 +720,10 @@ function logResult(platformLabel, mcpKey, result) {
       console.log(`  ⏭️  ${label} — ${result.reason}`)
       progress.skipped.push({ platform: platformLabel, mcp: mcpKey, reason: result.reason })
       break
+    case 'healed':
+      console.log(`  🩹 ${label} — ${result.reason}`)
+      progress.installed.push({ platform: platformLabel, mcp: mcpKey })
+      break
     case 'dry-run': {
       const desc =
         result.entry?.type === 'remote' || result.entry?.type === 'http'

package/scripts/{mcp_persistence_server.py → mcp_persistence.py}

@@ -5,7 +5,7 @@ Key-Value store with FTS5 full-text search, TTL-based expiration,
 and namespace isolation. Uses SQLite with zero external dependencies.
 
 Usage:
-    python scripts/mcp_persistence_server.py
+    python scripts/mcp_persistence.py
 """
 
 from __future__ import annotations
@@ -25,7 +25,7 @@ from pathlib import Path
 from typing import Annotated
 
 from _pantheon_paths import pantheon_home, pantheon_project
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 from pydantic import Field
 
 # ── Schema ──────────────────────────────────────────────────────────────────────
@@ -914,15 +914,35 @@ def _validate_delegations(delegations: object) -> None:
 
 def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
     """Validate bounded serialized tail lines."""
-    if not isinstance(tail, list) or len(tail) > MAX_TAIL_ITEMS:
-        raise ValueError("tail exceeds its size limit")
+    if not isinstance(tail, list):
+        raise ValueError("tail must be an array")
+    if len(tail) > MAX_TAIL_ITEMS:
+        raise ValueError(
+            f"tail has {len(tail)} items; maximum is {MAX_TAIL_ITEMS}; "
+            "remove tail entries or omit tail"
+        )
     for line in tail:
-        if not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH:
-            raise ValueError("tail entries exceed their size limit")
+        if not isinstance(line, str):
+            raise ValueError("tail entries must be strings")
+        line_bytes = len(line.encode())
+        if line_bytes > MAX_TAIL_LINE_LENGTH:
+            raise ValueError(
+                f"tail entries are {line_bytes:,} UTF-8 bytes; maximum is "
+                f"{MAX_TAIL_LINE_LENGTH:,}; remove or shorten tail entries, "
+                "or omit tail"
+            )
     if payload_bytes is not None and payload_bytes > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
-    if sum(len(line.encode()) for line in tail) > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
+        raise ValueError(
+            f"tail payload is {payload_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,}; remove tail entries or omit tail"
+        )
+    tail_bytes = sum(len(line.encode()) for line in tail)
+    if tail_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError(
+            f"tail contains {tail_bytes:,} UTF-8 bytes across strings; maximum "
+            f"is {MAX_CONTEXT_CONTENT_BYTES:,} bytes; remove tail entries or "
+            "omit tail"
+        )
     return tail
 
 
@@ -1020,8 +1040,14 @@ def _collect_context_content_errors(
     if not isinstance(content, str):
         errors.shape(prefix, "a string", content)
         return
-    if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
-        errors.add(prefix, f"exceeds the {MAX_CONTEXT_CONTENT_BYTES}-byte limit")
+    content_bytes = len(content.encode())
+    if content_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        errors.add(
+            prefix,
+            f"is {content_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,} bytes. Reduce content or omit "
+            "optional tail if it contributes",
+        )
         return
     try:
         parsed = json.loads(content)
@@ -1030,11 +1056,10 @@ def _collect_context_content_errors(
         # it as a checkpoint. It is still bounded above.
         return
     if isinstance(parsed, list) and key == "tail":
-        if len(parsed) > MAX_TAIL_ITEMS or any(
-            not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH
-            for line in parsed
-        ):
-            errors.add(f"{prefix}.tail", "exceeds its size limit")
+        try:
+            _validate_tail(parsed)
+        except ValueError as exc:
+            errors.reroot(prefix, str(exc))
         return
     if not isinstance(parsed, dict):
         # The message already names 'content': do not prepend the path again.
@@ -1164,6 +1189,11 @@ def _upsert_context_entry(
     name="context_save",
     description="Save a context checkpoint for a session/phase. "
     "Stores structured JSON in persistence KV with a key-specific TTL. "
+    "The serialized content is limited to 65,536 UTF-8 bytes. An included "
+    "tail may contain at most 100 strings, each at most 4,096 UTF-8 bytes, "
+    "with at most 65,536 UTF-8 bytes across all tail strings. Oversized "
+    "content or tail is rejected, never truncated; remove or omit optional "
+    "tail data when applicable. "
     "content is a JSON STRING; when it parses to an object, 'goal', 'phase', "
     "'delegations' and 'heartbeat' must each be JSON OBJECTS and 'tail' must "
     "be a JSON ARRAY. 'phase' is an object {current,total,name} — NOT a phase "
@@ -1180,7 +1210,12 @@ async def context_save(
         str,
         Field(
             description=(
-                "JSON checkpoint string. When it parses to an object, 'goal', "
+                "JSON checkpoint string, limited to 65,536 UTF-8 bytes. An "
+                "included 'tail' may contain at most 100 strings, each at "
+                "most 4,096 UTF-8 bytes, with at most 65,536 UTF-8 bytes "
+                "across all tail strings. Oversized input is rejected, never "
+                "truncated; remove or omit optional 'tail' when applicable. "
+                "When it parses to an object, 'goal', "
                 "'phase', 'delegations' and 'heartbeat' must be objects and "
                 "'tail' must be an array; all are optional. 'phase' is an "
                 "object {current,total,name}, not a counter. Example: "

package/{src/mcp/mcp_resources_server.py → scripts/mcp_resources.py}

@@ -7,7 +7,7 @@ Provides MCP resources for the Pantheon agent framework:
   plans/status, memory-bank files
 
 Usage:
-    python scripts/mcp_resources_server.py
+    python scripts/mcp_resources.py
 """
 
 from __future__ import annotations
@@ -19,7 +19,7 @@ from typing import Any
 import yaml
 from _pantheon_paths import has_symlink_component, pantheon_home, pantheon_project
 from eval_store import get_latest_eval, list_evals
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 
 # ── Path Resolution ──────────────────────────────────────────────────────────
 _PANTHEON_HOME: Path = pantheon_home()

package/scripts/{memory_mcp_server.py → memory_mcp.py}

@@ -19,7 +19,7 @@ Tools:
     memory_stats   — DB statistics
 
 Usage:
-    python scripts/memory_mcp_server.py
+    python scripts/memory_mcp.py
 """
 
 from __future__ import annotations
@@ -33,7 +33,7 @@ from pathlib import Path
 from typing import Annotated, Any
 
 from _pantheon_paths import pantheon_home
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 from pydantic import BeforeValidator, Field
 
 # ── Paths ─────────────────────────────────────────────────────────────────────

package/scripts/probe-context-rehydrate.mjs

@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url'
 
 const requestedVersion = valueFor('--version')
 const jsonOutput = process.argv.includes('--json')
-const runtime = fileURLToPath(new URL('./mcp_persistence_server.py', import.meta.url))
+const runtime = fileURLToPath(new URL('./mcp_persistence.py', import.meta.url))
 
 function valueFor(name) {
   const index = process.argv.indexOf(name)
@@ -63,6 +63,12 @@ spec.loader.exec_module(module)
 
 async def call(name, arguments):
     result = await module.mcp.call_tool(name, arguments)
+    structured = getattr(result, "structured_content", None)
+    if structured is not None:
+        metadata = getattr(result, "meta", None) or {}
+        if metadata.get("fastmcp", {}).get("wrap_result"):
+            return structured.get("result") if isinstance(structured, dict) else structured
+        return structured
     if isinstance(result, tuple):
         structured = result[1]
         if structured is not None:
@@ -186,7 +192,7 @@ async function main() {
     return
   }
   if (!existsSync(runtime)) {
-    unavailable('installed package does not include mcp_persistence_server.py')
+    unavailable('installed package does not include mcp_persistence.py')
     return
   }
 

package/scripts/probe-pantheon-cost.mjs

@@ -56,11 +56,48 @@ function setEnvironment(values) {
   }
 }
 
+/**
+ * Write the rows in the family the requested host generation actually uses.
+ *
+ * Call sites describe an assistant turn the way they always have
+ * (`role: 'assistant'`, plus a `phase`). This function translates that
+ * descriptor into what is on disk: for V2, `role` becomes the `type` COLUMN and
+ * `phase` is dropped, because a real V2 payload carries neither — measured, the
+ * `role` key is absent from 40052 of 40052 rows on a host 2.0.22 database.
+ *
+ * Keeping that translation in ONE place is the point: a fixture that wrote
+ * `role` into a session_message row asserts the V1 format under a V2 name, which
+ * is exactly how the stale V1 predicate in the CLI mirror stayed green — the
+ * synthetic database agreed with the bug instead of contradicting it.
+ */
 function createSyntheticDb(DatabaseSync, path, rows) {
   const db = new DatabaseSync(path)
-  db.exec('CREATE TABLE message (data TEXT NOT NULL, time_created INTEGER NOT NULL)')
-  const insert = db.prepare('INSERT INTO message (data, time_created) VALUES (?, ?)')
-  for (const data of rows) insert.run(JSON.stringify(data), Date.now())
+  if (requestedVersion === 'v2') {
+    db.exec(
+      'CREATE TABLE session_message (id TEXT, session_id TEXT, type TEXT, seq INTEGER, time_created INTEGER, time_updated INTEGER, data TEXT)',
+    )
+    const insert = db.prepare(
+      'INSERT INTO session_message (id, session_id, type, seq, time_created, time_updated, data) VALUES (?,?,?,?,?,?,?)',
+    )
+    rows.forEach((row, index) => {
+      const payload = { ...row }
+      delete payload.role
+      delete payload.phase
+      insert.run(
+        `msg_${index + 1}`,
+        'ses_probe',
+        row.role,
+        index + 1,
+        Date.now(),
+        Date.now(),
+        JSON.stringify(payload),
+      )
+    })
+  } else {
+    db.exec('CREATE TABLE message (data TEXT NOT NULL, time_created INTEGER NOT NULL)')
+    const insert = db.prepare('INSERT INTO message (data, time_created) VALUES (?, ?)')
+    for (const data of rows) insert.run(JSON.stringify(data), Date.now())
+  }
   db.close()
 }
 
@@ -129,7 +166,10 @@ async function main() {
   const root = mkdtempSync(join(tmpdir(), 'pantheon-cost-probe-'))
   const dataHome = join(root, 'data')
   const opencodeDir = join(dataHome, 'opencode')
-  const selectedDb = join(opencodeDir, requestedVersion === 'v2' ? 'opencode-v2.db' : 'opencode.db')
+  // Every real installation writes `opencode.db`; the v1/v2 distinction is the
+  // SCHEMA of that file, never its name. Deriving `opencode-v2.db` here made the
+  // probe assert a path that exists on no real machine.
+  const selectedDb = join(opencodeDir, 'opencode.db')
   const otherDb = join(root, 'other.db')
   const envDb = join(root, 'env.db')
   const explicitDb = join(root, 'explicit.db')
@@ -139,7 +179,9 @@ async function main() {
   try {
     mkdirSync(opencodeDir, { recursive: true })
     // These rows intentionally include a monetary-looking field to prove it is
-    // ignored; only input/output/total tokens may appear in the report.
+    // ignored; only input/output/total tokens may appear in the report. Every
+    // V2 phase reads back as `unknown` because the V2 reader emits that literal:
+    // a V2 payload carries no phase field for a reader to recover.
     const selectedRows =
       requestedVersion === 'v2'
         ? [
@@ -224,8 +266,8 @@ async function main() {
         selectedOutput,
         requestedVersion === 'v2'
           ? [
-              { agent: 'aphrodite', phase: 'plan', input: 8, output: 10, total: 18 },
-              { agent: 'zeus', phase: 'audit', input: 4, output: 6, total: 10 },
+              { agent: 'aphrodite', phase: 'unknown', input: 8, output: 10, total: 18 },
+              { agent: 'zeus', phase: 'unknown', input: 4, output: 6, total: 10 },
             ]
           : [
               { agent: 'hermes', phase: 'plan', input: 13, output: 24, total: 37 },
@@ -250,7 +292,12 @@ async function main() {
         {},
         { sessionID: 'cost-probe' },
       )
-      requireOutput(output, '| env-agent | override | 1 | 2 | 3 |', 'PANTHEON_COST_DB')
+      // V2 has no phase to report, so the same row reads back as 'unknown'.
+      requireOutput(
+        output,
+        `| env-agent | ${requestedVersion === 'v2' ? 'unknown' : 'override'} | 1 | 2 | 3 |`,
+        'PANTHEON_COST_DB',
+      )
       if (output.includes('wrong-version') || output.includes('env-agent') === false) {
         throw new Error('PANTHEON_COST_DB did not override the version-selected database')
       }
@@ -269,7 +316,11 @@ async function main() {
         {},
         { sessionID: 'cost-probe' },
       )
-      requireOutput(output, '| explicit-agent | explicit | 9 | 1 | 10 |', 'explicit dbPath')
+      requireOutput(
+        output,
+        `| explicit-agent | ${requestedVersion === 'v2' ? 'unknown' : 'explicit'} | 9 | 1 | 10 |`,
+        'explicit dbPath',
+      )
       if (output.includes('env-agent')) throw new Error('explicit dbPath did not take precedence')
       checks.push('explicit dbPath precedence: PASS')
     } finally {
@@ -287,11 +338,7 @@ async function main() {
         { sessionID: 'cost-probe' },
       )
       requireOutput(output, 'not found', 'missing DB')
-      requireOutput(
-        output,
-        requestedVersion === 'v2' ? 'opencode-v2.db' : 'opencode.db',
-        'selected missing DB path',
-      )
+      requireOutput(output, 'opencode.db', 'selected missing DB path')
       checks.push('missing DB: PASS')
     } finally {
       missingRestore()
@@ -302,7 +349,16 @@ async function main() {
     }).pantheon_cost.execute({}, { sessionID: 'cost-probe' })
     requireOutput(incompatibleOutput, 'incompatible opencode.db schema', 'incompatible schema')
     checks.push('incompatible schema: PASS')
-    emit('PASS', 'offline synthetic DB checks passed; no real DB was read', checks)
+    // Names the synthetic fixture that was built, because the previous wording
+    // ("no real DB was read") was true of every run and therefore true of the run
+    // in which the V2 ledger was read as V1 and silently dropped. A verdict that
+    // cannot fail is not a verdict: it stayed green across the exact defect it
+    // was meant to cover.
+    emit(
+      'PASS',
+      `${checks.length} synthetic ${requestedVersion} checks passed against a temporary opencode.db (no user database was read)`,
+      checks,
+    )
   } catch (error) {
     emit('FAIL', diagnostic(error), checks)
   } finally {

package/scripts/prune.mjs

@@ -9,7 +9,10 @@
  * SAFETY: prune NEVER touches the active config, the active venv, the package
  * repo, or the installed package. It only:
  *   - lists old global `pantheon` installs (suggests `npm uninstall -g pantheon`)
- *   - removes stale `opencode.json.bak*` backups (age > threshold) with --apply
+ *   - removes stale LEGACY `opencode.json.bak*` backups (age > threshold) with
+ *     --apply. The modern installer no longer writes that sidecar — it creates an
+ *     exact backup set under `.pantheon/backups/` (retained by the installer, not
+ *     pruned here) — so this scan only cleans up pre-phase-2 installs.
  *   - lists legacy directories whose opencode.json references dead/relative
  *     paths (removal requires --apply --remove-dirs as explicit confirmation)
  *
@@ -102,8 +105,11 @@ export function findLegacyGlobalInstalls() {
 }
 
 // ---------------------------------------------------------------------------
-// (b) Stale opencode.json.bak* backups (age > threshold) in the config dir
-//     → removable with --apply. Fresh backups are listed as kept.
+// (b) Stale LEGACY opencode.json.bak* backups (age > threshold) in the config
+//     dir → removable with --apply. Fresh backups are listed as kept. The
+//     current installer does not create this sidecar (it keeps an exact,
+//     self-retaining backup set under .pantheon/backups/), so this only cleans
+//     up installs from before phase 2.
 // ---------------------------------------------------------------------------
 
 export function findStaleBackups(configDir, maxAgeDays = DEFAULT_BACKUP_AGE_DAYS) {

package/scripts/restore.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * restore.mjs — Pantheon exact-restore CLI (Beta 11 Setup, phase 2).
+ *
+ * Restores a backup set created by the installer back into the config dir,
+ * reproducing each file byte-for-byte and re-applying its recorded mode. The
+ * restore is itself reversible: the CURRENT state is backed up first.
+ *
+ * Safety contract:
+ *   - the backup manifest is verified (hash of every backed-up file) before any
+ *     restore; a tampered or incomplete set is refused outright;
+ *   - the backup-vs-current diff is shown BY PATH ONLY (never file contents);
+ *   - writing requires explicit authorization (`--yes`); a non-TTY run without
+ *     `--yes` previews and exits without writing.
+ *
+ * Usage:
+ *   pantheon-opencode restore [--project] [--from <dir>] [--dry-run] [--yes]
+ *
+ * Exit codes:
+ *   0 = restored (or preview shown with --dry-run)
+ *   1 = refused (missing/tampered backup, or no authorization)
+ *   2 = usage error
+ */
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+
+import {
+  backupRoot,
+  createBackupSet,
+  isBackupDirName,
+  listBackupSets,
+  planRestore,
+  restoreBackupSet,
+  verifyBackupSet,
+} from './install/backup.mjs'
+
+/**
+ * Resolve the config dir whose `opencode.json` the installer manages.
+ * `--project` targets the CWD; otherwise XDG / PANTHEON_HOME.
+ * @param {{ project?: boolean }} opts
+ * @returns {string}
+ */
+export function resolveConfigDir({ project = false } = {}) {
+  if (project) return resolve(process.cwd())
+  if (process.env.PANTHEON_HOME) return resolve(process.env.PANTHEON_HOME)
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  return join(base, 'opencode')
+}
+
+export function parseArgs(argv) {
+  const args = { project: false, from: null, dryRun: false, yes: false, help: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    switch (arg) {
+      case '--project':
+        args.project = true
+        break
+      case '--dry-run':
+        args.dryRun = true
+        break
+      case '--yes':
+      case '-y':
+        args.yes = true
+        break
+      case '--from':
+        args.from = argv[++i] ?? null
+        break
+      case '--help':
+      case '-h':
+        args.help = true
+        break
+      default:
+        break
+    }
+  }
+  return args
+}
+
+export function showHelp() {
+  console.log(`
+pantheon-opencode restore — restore an exact installer backup
+
+Usage:
+  pantheon-opencode restore                       restore newest backup (global config)
+  pantheon-opencode restore --project             restore newest backup (project)
+  pantheon-opencode restore --from <dir>          restore a specific backup set
+  pantheon-opencode restore --dry-run             preview only (writes nothing)
+  pantheon-opencode restore --yes                 authorize the write (non-interactive)
+
+A backup set lives under <config-dir>/.pantheon/backups/<timestamp>/.
+Restore reproduces each file byte-for-byte and re-applies its recorded mode.
+File contents are never printed.
+`)
+}
+
+/**
+ * Choose the backup set to restore.
+ * @param {string} configDir
+ * @param {string|null} from
+ * @returns {{ dir: string, name: string } | null}
+ */
+export function pickBackupSet(configDir, from) {
+  if (from) {
+    // Accept either a bare timestamp set name (resolved under the backups root)
+    // or an explicit directory path.
+    if (isBackupDirName(from)) {
+      const dir = join(backupRoot(configDir), from)
+      return existsSync(dir) ? { dir, name: from } : null
+    }
+    const dir = isAbsolute(from) ? from : resolve(process.cwd(), from)
+    if (!existsSync(dir)) return null
+    return { dir, name: dir.split(/[\\/]/).pop() }
+  }
+  return listBackupSets(configDir)[0] ?? null
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.configDir
+ * @param {string} opts.backupDir
+ * @param {boolean} [opts.dryRun]
+ * @param {boolean} [opts.yes]
+ * @returns {Promise<{ ok: boolean, code: number, entries?: object[] }>}
+ */
+export async function runRestore({ configDir, backupDir, dryRun = false, yes = false }) {
+  const verify = verifyBackupSet(backupDir)
+  if (!verify.ok) {
+    console.error(
+      `❌ Refusing to restore: backup failed integrity verification (${verify.reason ?? 'hash mismatch'}).`,
+    )
+    return { ok: false, code: 1 }
+  }
+
+  const plan = planRestore(backupDir, configDir)
+  if (plan.error) {
+    console.error(`❌ Refusing to restore: ${plan.error}.`)
+    return { ok: false, code: 1 }
+  }
+
+  const counts = { create: 0, update: 0, remove: 0, unchanged: 0 }
+  for (const entry of plan.entries) counts[entry.action] += 1
+
+  console.log('')
+  console.log(`Restore plan — ${configDir}`)
+  console.log(`  from   ${backupDir}`)
+  for (const entry of plan.entries) {
+    if (entry.action === 'unchanged') continue
+    console.log(`  ${entry.action.padEnd(9)} ${entry.relativePath}`)
+  }
+  console.log(
+    `  ${counts.create} create · ${counts.update} update · ${counts.remove} remove · ${counts.unchanged} unchanged`,
+  )
+
+  if (dryRun) {
+    console.log('  (dry-run) No files were written.')
+    return { ok: true, code: 0, entries: plan.entries }
+  }
+
+  if (!yes) {
+    // Reuse the shared confirm semantics (default NO). An interactive TTY may
+    // authorize without --yes; a non-TTY run must never proceed silently.
+    const tty = Boolean(process.stdin.isTTY && process.stdout.isTTY)
+    if (!tty) {
+      console.error('❌ Refusing to restore without authorization. Re-run with --yes.')
+      return { ok: false, code: 1 }
+    }
+    const { promptReview } = await import('./install/interactive.mjs')
+    const accepted = await promptReview('Restore these changes?', { default: false })
+    if (!accepted) {
+      console.log('  Nothing restored.')
+      return { ok: true, code: 0, entries: plan.entries }
+    }
+  }
+
+  // Reversible: snapshot the CURRENT state of exactly the affected paths first.
+  // Retention is DISABLED here (`keep: 0`): a retention pass at this point could
+  // delete the very set being restored once 5 older sets already exist (the new
+  // snapshot would be the 6th, and pruning would drop the oldest two — including
+  // the source). Apply still prunes; restore never deletes backups.
+  const { dir: preDir } = createBackupSet({
+    configDir,
+    entries: plan.manifest.entries.map((e) => e.relativePath),
+    packageVersion: plan.manifest.packageVersion,
+    keep: 0,
+  })
+  console.log(`  pre-restore backup: ${preDir}`)
+
+  restoreBackupSet(backupDir, configDir, { dryRun: false })
+  console.log(`  ✅ Restored ${plan.entries.length} path(s).`)
+  return { ok: true, code: 0, entries: plan.entries }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    showHelp()
+    return
+  }
+  const configDir = resolveConfigDir({ project: args.project })
+  const backup = pickBackupSet(configDir, args.from)
+  if (!backup) {
+    console.error(`❌ No backup set found under ${backupRoot(configDir)}`)
+    process.exitCode = 1
+    return
+  }
+  const result = await runRestore({
+    configDir,
+    backupDir: backup.dir,
+    dryRun: args.dryRun,
+    yes: args.yes,
+  })
+  if (!result.ok) process.exitCode = result.code
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((err) => {
+    console.error(`❌ Restore failed: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
+  })
+}