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

package/scripts/install/strings.mjs

@@ -47,6 +47,16 @@ const TABLE = {
     prereqMissing:
       'runtime prerequisites missing — install the tools above, or re-run with --no-mcp to install without Python MCP servers',
     v2Migrating: 'Migrating config to V2 native format...',
+    nothingApplied: 'Nothing applied.',
+    planOnlyNoYes: 'Plan only — re-run with --yes to apply.',
+    driftHeader: 'State changed since preview — aborting before any write:',
+    driftAbort: 'No files were written. Re-run to re-review.',
+    applyFailed: (msg) => `❌ Apply failed: ${msg}`,
+    alreadyApplied: 'Paths already applied — no automatic rollback:',
+    restoreRecoveryHint: (dir) => `Recover with: pantheon-opencode restore  (backup at ${dir})`,
+    restoreNoBackup:
+      'No backup was created (the failure occurred before the first write); the target is unchanged.',
+    dryRunNothingWritten: 'Preview only — no files were written.',
     // summary (printSummary)
     summaryInstalled: (target) => `OpenCode installed in ${target}`,
     summaryWithErrors: (target) => `Installation finished WITH ERRORS in ${target}`,
@@ -95,6 +105,16 @@ const TABLE = {
     prereqMissing:
       'pré-requisitos do runtime ausentes — instale as ferramentas acima, ou rode de novo com --no-mcp para instalar sem os MCPs Python',
     v2Migrating: 'Migrando config para o formato nativo V2...',
+    nothingApplied: 'Nada foi aplicado.',
+    planOnlyNoYes: 'Apenas o plano — rode de novo com --yes para aplicar.',
+    driftHeader: 'O estado mudou desde o preview — abortando antes de qualquer escrita:',
+    driftAbort: 'Nenhum arquivo foi escrito. Rode de novo para revisar.',
+    applyFailed: (msg) => `❌ Falha ao aplicar: ${msg}`,
+    alreadyApplied: 'Caminhos já aplicados — sem rollback automático:',
+    restoreRecoveryHint: (dir) => `Recupere com: pantheon-opencode restore  (backup em ${dir})`,
+    restoreNoBackup:
+      'Nenhum backup foi criado (a falha ocorreu antes da primeira escrita); o alvo está intacto.',
+    dryRunNothingWritten: 'Somente prévia — nenhum arquivo foi escrito.',
     // summary (printSummary)
     summaryInstalled: (target) => `OpenCode instalado em ${target}`,
     summaryWithErrors: (target) => `Instalação concluída COM ERROS em ${target}`,

package/scripts/install/venv.mjs

@@ -10,10 +10,12 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import { existsSync, rmSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { ACTIONS, recordChange, recordRemovalTree, removeReviewedTree } from './plan.mjs'
+
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..', '..')
 
@@ -40,24 +42,37 @@ export function venvPythonPath(target) {
  * Set up a Python virtual environment and install MCP dependencies.
  *
  * @param {string} target - Target installation directory (e.g. ~/.config/opencode)
- * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean }} [options]
+ * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean, recorder?: (change: object) => void, reviewedRemovals?: Set<string>|null, reviewedSnapshots?: Map<string, object>|null }} [options]
  * @returns {{ venvPath: string, python: string }}
  */
-export function setupVenv(target, { dryRun = false, skipInstall = false, force = false } = {}) {
+export function setupVenv(
+  target,
+  {
+    dryRun = false,
+    skipInstall = false,
+    force = false,
+    recorder = null,
+    reviewedRemovals = null,
+    reviewedSnapshots = null,
+  } = {},
+) {
   const venvPath = join(target, '.venv')
   const pythonBin = venvPythonPath(target)
 
   // Step 1: Force recreate venv if --force
   if (force && existsSync(venvPath)) {
-    if (!dryRun) {
+    if (dryRun) {
+      recordRemovalTree(venvPath, recorder)
+    } else {
       console.log('  Removing existing .venv (--force)...')
-      rmSync(venvPath, { recursive: true })
+      removeReviewedTree(venvPath, reviewedRemovals, reviewedSnapshots)
     }
     console.log('  ✅ .venv removed')
   }
 
   // Step 1b: Create venv if not exists
-  if (!existsSync(pythonBin)) {
+  const venvExists = existsSync(pythonBin)
+  if (!venvExists) {
     if (!dryRun) {
       console.log('  Creating .venv...')
       const result = spawnSync('python3', ['-m', 'venv', venvPath], {
@@ -69,8 +84,12 @@ export function setupVenv(target, { dryRun = false, skipInstall = false, force =
       }
     }
     console.log('  ✅ .venv created')
+    // A single synthetic entry for the venv directory — never enumerate its
+    // thousands of files. Unscored: the install summary does not count it.
+    recordChange({ path: venvPath, action: ACTIONS.CREATE, bytes: 0, scored: false }, recorder)
   } else {
     console.log('  ⏭️  .venv already exists')
+    recordChange({ path: venvPath, action: ACTIONS.UNCHANGED, bytes: 0, scored: false }, recorder)
   }
 
   // Step 2: Install MCP dependencies

package/scripts/install/verify.mjs

@@ -0,0 +1,128 @@
+import {
+  closeSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { isAbsolute, parse, relative, resolve, sep } from 'node:path'
+
+/** Reject symlinked path components before a managed filesystem operation. */
+export function assertNoSymlinkAncestors(filePath, { includeLeaf = true } = {}) {
+  const absolute = resolve(filePath)
+  const root = parse(absolute).root
+  const parts = absolute.slice(root.length).split(sep).filter(Boolean)
+  const checked = parts.slice(0, includeLeaf ? parts.length : Math.max(0, parts.length - 1))
+  let current = root
+  for (const [index, part] of checked.entries()) {
+    current = current ? `${current}${current.endsWith(sep) ? '' : sep}${part}` : part
+    let info
+    try {
+      info = lstatSync(current)
+    } catch (error) {
+      if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return true
+      throw error
+    }
+    if (info.isSymbolicLink()) throw new Error(`Path contains a symlink: ${current}`)
+    if (index < checked.length - 1 && !info.isDirectory()) {
+      throw new Error(`Path ancestor is not a directory: ${current}`)
+    }
+  }
+  return true
+}
+
+/** Require a destination to remain lexically inside its selected target. */
+export function assertPathWithin(rootPath, destinationPath) {
+  const root = resolve(rootPath)
+  const destination = resolve(destinationPath)
+  const fromRoot = relative(root, destination)
+  if (fromRoot === '..' || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+    throw new Error(`Path escapes selected target: ${destinationPath}`)
+  }
+  return true
+}
+
+/** Validate lexical containment and reject links before deleting a path. */
+export function assertSafeRemoval(rootPath, destinationPath) {
+  assertPathWithin(rootPath, destinationPath)
+  assertNoSymlinkAncestors(destinationPath)
+  return true
+}
+
+/** Read back a regular-file write without ever including file contents in errors. */
+export function verifyRegularFile(filePath, expected) {
+  const info = lstatSync(filePath)
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new Error(`Managed-file write did not produce a regular file: ${filePath}`)
+  }
+  const actual = readFileSync(filePath)
+  const expectedBuffer = Buffer.isBuffer(expected) ? expected : Buffer.from(expected)
+  if (!actual.equals(expectedBuffer)) {
+    throw new Error(`Managed-file read-back verification failed: ${filePath}`)
+  }
+  return true
+}
+
+/**
+ * Atomically write a managed file using a private, exclusively-created temp.
+ * Existing destinations are replaced only after path checks and a temp read-back.
+ */
+export function writeFileAtomically(filePath, content) {
+  const temporary = `${filePath}.tmp-${process.pid}`
+  assertNoSymlinkAncestors(filePath)
+  assertRegularFileOrMissing(filePath)
+  assertNoSymlinkAncestors(temporary)
+
+  let fd
+  let createdTemporary = false
+  try {
+    fd = openSync(temporary, 'wx', 0o600)
+    createdTemporary = true
+    writeFileSync(fd, content)
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = undefined
+
+    verifyRegularFile(temporary, content)
+    assertNoSymlinkAncestors(filePath)
+    assertRegularFileOrMissing(filePath)
+    renameSync(temporary, filePath)
+    createdTemporary = false
+    verifyRegularFile(filePath, content)
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+    if (createdTemporary) {
+      try {
+        assertNoSymlinkAncestors(temporary)
+        unlinkSync(temporary)
+      } catch {
+        // Preserve the write error; do not follow or remove an unsafe path.
+      }
+    }
+  }
+}
+
+function assertRegularFileOrMissing(filePath) {
+  try {
+    const info = lstatSync(filePath)
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new Error(`Refusing to replace non-regular file: ${filePath}`)
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+}
+
+/** Verify a managed path was removed, without following symlinks. */
+export function verifyPathRemoved(filePath) {
+  try {
+    lstatSync(filePath)
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return true
+    throw error
+  }
+  throw new Error(`Managed-path removal verification failed: ${filePath}`)
+}

package/scripts/install/vision-prompt.mjs

@@ -16,10 +16,11 @@
  * The write mirrors the `/pantheon-vision` command: atomic, `.bak` backup,
  * and a MERGE — existing keys are never overwritten.
  */
-import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { writeConfigWithBackup } from './shared.mjs'
+import { verifyRegularFile } from './verify.mjs'
 
 const CONFIG_FILENAME = 'opencode-vision.json'
 /** `provider/model` — exactly one slash, no surrounding whitespace. */
@@ -81,6 +82,17 @@ export function mergeVisionModel(
   const status = writeConfigWithBackup(configPath, content, false, {
     expectedContent: existingRaw,
     beforeRecheck,
+    // This file is GLOBAL and lives outside the config dir, so the target-scoped
+    // exact backup set never captures it. Keep its own `<file>.bak` recovery.
+    beforeSwap: (existing) => {
+      if (existing === null) return
+      try {
+        copyFileSync(configPath, `${configPath}.bak`)
+        verifyRegularFile(`${configPath}.bak`, readFileSync(configPath))
+      } catch {
+        // Best-effort: a backup failure must not block the write.
+      }
+    },
   })
   return { path: configPath, wrote: status === 'created', reason: status }
 }

package/scripts/install-mcp.mjs

@@ -238,7 +238,7 @@ export const MCPS = {
     tier: 1,
     name: 'Pantheon Memory',
     description:
-      'Pantheon Memory MCP Server — persistent memory with semantic search, recall, knowledge graph, compression, and verification',
+      'Pantheon Memory MCP Server — persistent SQLite memory with FTS5/BM25 keyword search, exact-key recall, and explicit maintenance; no embedding/vector search',
     platforms: {
       opencode: {
         type: 'local',

package/scripts/manifest-inventory.mjs

@@ -57,6 +57,18 @@ export const MANIFEST_INVENTORY = Object.freeze([
     name: 'pantheon-tui',
     valuePath: ['name'],
   }),
+  Object.freeze({
+    id: 'zenodo-release-metadata',
+    role: 'metadata',
+    file: '.zenodo.json',
+    kind: 'json',
+  }),
+  Object.freeze({
+    id: 'citation-release-metadata',
+    role: 'metadata',
+    file: 'CITATION.cff',
+    kind: 'cff',
+  }),
   Object.freeze({
     id: 'root-lock',
     role: 'lock',
@@ -76,7 +88,7 @@ export const MANIFEST_INVENTORY = Object.freeze([
 ])
 
 export const VERSION_MANIFEST_INVENTORY = Object.freeze(
-  MANIFEST_INVENTORY.filter(({ role }) => role === 'manifest'),
+  MANIFEST_INVENTORY.filter(({ role }) => role !== 'lock'),
 )
 
 export const LOCK_INVENTORY = Object.freeze(
@@ -99,11 +111,18 @@ function readToml(file, text) {
   return parsed
 }
 
+function readCff(file, text) {
+  const match = /^version:\s*([^\s#]+)\s*(?:#.*)?$/m.exec(text)
+  if (!match) throw new Error(`${file} is missing top-level version metadata`)
+  return { version: match[1] }
+}
+
 function readDocument(root, entry) {
   const path = join(root, entry.file)
   if (!existsSync(path)) throw new Error(`manifest inventory file is missing: ${entry.file}`)
   const text = readFileSync(path, 'utf8')
   if (entry.kind === 'toml') return { entry, path, text, data: readToml(entry.file, text) }
+  if (entry.kind === 'cff') return { entry, path, text, data: readCff(entry.file, text) }
   let data
   try {
     data = JSON.parse(text)
@@ -175,6 +194,24 @@ function validateLock(document, manifestsByFile, allowVersionDivergence) {
   if (!allowVersionDivergence && rootPackage.version !== manifestVersionValue) {
     throw new Error(`${entry.file} packages[""] version diverges from ${entry.packageFile}`)
   }
+
+  if (entry.file === 'package-lock.json') {
+    const tuiManifest = manifestsByFile.get('src/plugins/tui/package.json')
+    const tuiWorkspace = data.packages?.['src/plugins/tui']
+    if (!tuiManifest) throw new Error('package-lock.json has no TUI workspace manifest partner')
+    if (!tuiWorkspace || typeof tuiWorkspace !== 'object' || Array.isArray(tuiWorkspace)) {
+      throw new Error('package-lock.json is missing packages["src/plugins/tui"]')
+    }
+    if (tuiWorkspace.name !== 'pantheon-tui') {
+      throw new Error('package-lock.json TUI workspace name must be pantheon-tui')
+    }
+    assertSemver(tuiWorkspace.version, 'package-lock.json TUI workspace version')
+    if (!allowVersionDivergence && tuiWorkspace.version !== manifestVersion(tuiManifest)) {
+      throw new Error(
+        'package-lock.json TUI workspace version diverges from src/plugins/tui/package.json',
+      )
+    }
+  }
 }
 
 /** Read and validate every entry before a caller is allowed to write anything. */
@@ -186,7 +223,7 @@ export function validateInventory(root, { allowVersionDivergence = false } = {})
       .map((document) => [document.entry.file, document]),
   )
   const versions = documents
-    .filter(({ entry }) => entry.role === 'manifest')
+    .filter(({ entry }) => entry.role === 'manifest' || entry.role === 'metadata')
     .map((document) => ({ file: document.entry.file, version: manifestVersion(document) }))
   documents.filter(({ entry }) => entry.role === 'manifest').forEach(manifestName)
   const sourceVersion = versions[0].version
@@ -309,8 +346,17 @@ function replaceTomlProjectVersion(text, version, file) {
 
 function prepareDocumentVersion(document, version) {
   const { entry, text } = document
+  if (entry.role === 'metadata') {
+    const current = manifestVersion(document)
+    return text.split(current).join(version)
+  }
   if (entry.kind === 'toml') return replaceTomlProjectVersion(text, version, entry.file)
-  const paths = entry.role === 'lock' ? [['version'], ['packages', '', 'version']] : [['version']]
+  const paths =
+    entry.role === 'lock'
+      ? entry.file === 'package-lock.json'
+        ? [['version'], ['packages', '', 'version'], ['packages', 'src/plugins/tui', 'version']]
+        : [['version'], ['packages', '', 'version']]
+      : [['version']]
   return replaceJsonStringValues(text, paths, version, entry.file)
 }
 

package/scripts/mcp_persistence.py

@@ -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/scripts/node-engine-policy.mjs

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const MIN_SUPPORTED_NODE_VERSION = '26.4.0'
+export const REQUIRED_NODE_ENGINE_RANGE = `>=${MIN_SUPPORTED_NODE_VERSION}`
+
+function parseNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([^+]+))?(?:\+([\w.-]+))?$/.exec(String(version))
+  if (!match) return null
+  return { parts: match.slice(1, 4).map(Number), prerelease: match[4] !== undefined }
+}
+
+/** Return whether a runtime version meets Pantheon's supported Node floor. */
+export function isSupportedNodeVersion(version) {
+  const parsed = parseNodeVersion(version)
+  const minimum = parseNodeVersion(MIN_SUPPORTED_NODE_VERSION)
+  if (!parsed || !minimum || parsed.prerelease) return false
+  for (let index = 0; index < minimum.parts.length; index += 1) {
+    if (parsed.parts[index] !== minimum.parts[index]) {
+      return parsed.parts[index] > minimum.parts[index]
+    }
+  }
+  return true
+}
+
+function readJson(root, file, errors) {
+  try {
+    const document = JSON.parse(readFileSync(join(root, file), 'utf8'))
+    if (!document || typeof document !== 'object' || Array.isArray(document)) {
+      throw new Error('expected a JSON object')
+    }
+    return document
+  } catch (error) {
+    errors.push(`${file}: ${error.message}`)
+    return null
+  }
+}
+
+function checkEngineRange(value, label, errors) {
+  if (value !== REQUIRED_NODE_ENGINE_RANGE) {
+    errors.push(`${label} must declare engines.node as "${REQUIRED_NODE_ENGINE_RANGE}"`)
+  }
+}
+
+/** Validate Node support claims in package manifests and their npm locks. */
+export function validateNodeEnginePolicy(root) {
+  const errors = []
+  const rootPackage = readJson(root, 'package.json', errors)
+  const tuiPackage = readJson(root, 'src/plugins/tui/package.json', errors)
+  const rootLock = readJson(root, 'package-lock.json', errors)
+  const tuiLock = readJson(root, 'src/plugins/tui/package-lock.json', errors)
+
+  if (rootPackage) checkEngineRange(rootPackage.engines?.node, 'package.json', errors)
+  if (tuiPackage) checkEngineRange(tuiPackage.engines?.node, 'src/plugins/tui/package.json', errors)
+
+  const rootLockPackage = rootLock?.packages?.['']
+  if (!rootLockPackage) errors.push('package-lock.json is missing packages[""]')
+  else checkEngineRange(rootLockPackage.engines?.node, 'package-lock.json packages[""]', errors)
+
+  const workspacePackage = rootLock?.packages?.['src/plugins/tui']
+  if (!workspacePackage) errors.push('package-lock.json is missing the TUI workspace package')
+  else checkEngineRange(workspacePackage.engines?.node, 'package-lock.json TUI workspace', errors)
+
+  const tuiLockPackage = tuiLock?.packages?.['']
+  if (!tuiLockPackage) errors.push('src/plugins/tui/package-lock.json is missing packages[""]')
+  else
+    checkEngineRange(
+      tuiLockPackage.engines?.node,
+      'src/plugins/tui/package-lock.json packages[""]',
+      errors,
+    )
+
+  return errors
+}

package/scripts/package-evidence.mjs

@@ -17,6 +17,7 @@ import {
 import { tmpdir } from 'node:os'
 import { isAbsolute, join } from 'node:path'
 import { validateInventory } from './manifest-inventory.mjs'
+import { validateNodeEnginePolicy } from './node-engine-policy.mjs'
 
 const CI_ARGS = ['ci', '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund']
 const REQUIRED_PAYLOAD = [
@@ -32,6 +33,8 @@ const REQUIRED_PAYLOAD = [
   'package/src/plugins/tui/dist/server.js',
   'package/bin/pantheon-init.mjs',
   'package/scripts/doctor.mjs',
+  'package/scripts/node-engine-policy.mjs',
+  'package/scripts/validate-node-engine-policy.mjs',
   'package/.pantheon/code-mode/compress-inline.py',
 ]
 
@@ -132,6 +135,7 @@ function validatePayload(packageRoot, inventory) {
   }
   for (const document of inventory.documents) {
     const { entry, path: sourcePath } = document
+    if (entry.role === 'metadata') continue
     const packagedPath = join(packageRoot, entry.file)
     if (entry.role === 'lock' && entry.file === 'package-lock.json' && !existsSync(packagedPath)) {
       // npm-packlist excludes the package root lockfile by policy. It remains
@@ -181,6 +185,8 @@ function sha256(path) {
 
 export function createPackageEvidence(root, { outputDir, targetSha } = {}) {
   const inventory = validateInventory(root)
+  const engineErrors = validateNodeEnginePolicy(root)
+  if (engineErrors.length) fail(engineErrors.join('; '))
   const sha = resolveTargetSha(root, targetSha)
   const output = createOutputDirectory(outputDir)
   let workDir

package/scripts/postinstall.mjs

@@ -5,14 +5,13 @@
  * Runs after `npm install` completes. Validates environment and prints
  * setup instructions. Does NOT install Pantheon platform components.
  */
-const REQUIRED_NODE_MAJOR = 18
-const nodeMajor = parseInt(process.versions.node.split('.')[0], 10)
+import { isSupportedNodeVersion, MIN_SUPPORTED_NODE_VERSION } from './node-engine-policy.mjs'
 
 try {
   // Validate Node.js version
-  if (nodeMajor < REQUIRED_NODE_MAJOR) {
+  if (!isSupportedNodeVersion(process.versions.node)) {
     console.error(
-      `❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`,
+      `❌ Pantheon requires Node.js >= ${MIN_SUPPORTED_NODE_VERSION} (current: ${process.versions.node})`,
     )
     process.exit(1)
   }

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) {