pantheon-opencode 1.3.3 → 1.3.5-beta.52.c75b04d

package/scripts/install/opencode.mjs

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 /**
  * opencode.mjs — OpenCode platform installer
+ *
+ * Dual-version install (Phase 3): the generated config is V1-shaped and valid
+ * under BOTH OpenCode V1 (`opencode` 1.18.x) and V2 (`opencode2`
+ * v0.0.0-next-17444). V2 reads the same config locations and normalizes V1
+ * fields in memory — do NOT convert to native V2 format. Known V2 beta gaps
+ * handled here: top-level `subagent_depth` is silently ignored (migrated to
+ * `experimental.subagent_depth`), and the `instructions` config key is
+ * accepted-but-not-loaded (content consolidated into AGENTS.md, which both
+ * versions load). Pass --version v2 to pantheon-init for an informational
+ * label; state isolation is handled at runtime via OPENCODE_DB.
  */
 
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, join, resolve } from 'node:path'
 import {
@@ -29,7 +31,7 @@ import {
 } from './cli-ui.mjs'
 import { healthCheck } from './health-check.mjs'
 import { detectVersion, runMigrations } from './migrate.mjs'
-import { installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
+import { copyPluginFiles, installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
 import {
   collectSkillNames,
   copyFiles,
@@ -89,7 +91,7 @@ function mergeMissing(target, source) {
  * installed package.
  *
  * The packaged config may reference plugins via developer-machine absolute
- * paths (e.g. /home/<dev>/pantheon/src/plugin.ts). Copying those verbatim into
+ * paths (e.g. <dev>/pantheon/.../src/plugin.ts). Copying those verbatim into
  * the user's config would break every install on any other machine. This
  * rewrites the entry to the plugin file inside the INSTALLED package (derived
  * from ROOT — never hardcoded), so both dev and global installs resolve to a
@@ -123,6 +125,97 @@ export function isGlobalConfigDir(target) {
   return resolve(target) === xdgDir
 }
 
+/**
+ * Derive where the TUI plugin must be COPIED for a given config directory.
+ *
+ * The TUI plugin's single source of truth is src/plugins/tui inside the
+ * package; the loader must NEVER be pointed at that in-package dir (a package
+ * reinstall/upgrade replaces the dir under a live registration and leaves
+ * diverging copies loading). Instead the installer always copies it into the
+ * config dir's plugins/ dir and registers THAT copy:
+ *
+ *   <configDir>/plugins/pantheon-tui      (dist/ + package.json + index.tsx)
+ *
+ * The loader reads the copied package.json `exports` map:
+ *   exports["./tui"]    → dist/tui.js     (COMPILED Solid output)
+ *   exports["./server"] → dist/server.js  (no-op server() stub)
+ *
+ * @param {string} configDir - directory holding tui.json (target for global
+ *   installs, <target>/.opencode for project installs)
+ * @returns {string} absolute path of the copied plugin directory
+ */
+export function resolveTuiCopyTarget(configDir) {
+  return join(configDir, 'plugins', 'pantheon-tui')
+}
+
+/**
+ * Every tui.json location OpenCode reads: the two global config dirs
+ * (~/.opencode and $XDG_CONFIG_HOME/opencode) plus the target's own project
+ * config. Cleanup runs over ALL of them so a stale Pantheon TUI registration
+ * can never survive in a location the loader still reads.
+ *
+ * @param {string} target - install target directory
+ * @returns {string[]} unique tui.json paths (deterministic order)
+ */
+export function tuiConfigLocations(target) {
+  const homeTui = join(homedir(), '.opencode', 'tui.json')
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  const xdgTui = join(xdgConfig, 'opencode', 'tui.json')
+  const projectTui = join(target, '.opencode', 'tui.json')
+  return [...new Set([homeTui, xdgTui, projectTui])]
+}
+
+/**
+ * Sync the Pantheon TUI plugin registration across EVERY tui.json location
+ * OpenCode reads.
+ *
+ * Contract (single source of truth):
+ *   1. ALWAYS copy src/plugins/tui → <configDir>/plugins/pantheon-tui
+ *      (dist/* + package.json + index.tsx) so the registered reference is a
+ *      directory that exists and carries the loader contract (exports →
+ *      dist/tui.js, dist/server.js). The copy is idempotent: a second run is
+ *      byte-identical.
+ *   2. Clean stale Pantheon TUI refs from ALL tui.json locations OpenCode
+ *      loads — ~/.opencode, $XDG_CONFIG_HOME/opencode and
+ *      <target>/.opencode — covering every old reference shape: dist file
+ *      paths, in-package src/plugins/tui dirs, bare plugins/pantheon-tui
+ *      copies, and npx paths. A stale ref left in the non-target location
+ *      would still be loaded and break the TUI.
+ *   3. Register EXACTLY the copied directory in the selected target only —
+ *      exactly ONE Pantheon TUI reference exists system-wide after install.
+ *
+ * @param {string} target - install target directory
+ * @param {object} [opts]
+ * @param {boolean} [opts.isGlobal=false] - flat global layout vs .opencode/
+ * @param {boolean} [opts.dryRun=false]
+ * @returns {'created'|'skipped'} status for the target registration
+ */
+export function syncTuiRegistration(target, { isGlobal = false, dryRun = false } = {}) {
+  const configDir = isGlobal ? target : join(target, '.opencode')
+  const targetTuiConfigPath = join(configDir, 'tui.json')
+
+  // 1. Always copy the single source of truth into the target config's
+  //    plugins/pantheon-tui. Registering this copied directory (never the
+  //    in-package src/plugins/tui) keeps installs hermetic and idempotent:
+  //    the ref points at a dir that exists and has dist/tui.js.
+  const tuiSrcDir = join(ROOT, 'src', 'plugins', 'tui')
+  const tuiCopyDir = resolveTuiCopyTarget(configDir)
+  if (existsSync(tuiSrcDir)) {
+    copyPluginFiles(tuiSrcDir, tuiCopyDir, { dryRun })
+  }
+
+  // 2. Clean stale Pantheon TUI refs from every location OpenCode reads.
+  //    unregisterPlugin covers the bare relative id plus the extended stale
+  //    patterns (dist files, in-package src/plugins/tui dir, bare
+  //    plugins/pantheon-tui copies, npx paths).
+  for (const tuiConfigPath of tuiConfigLocations(target)) {
+    unregisterPlugin(tuiConfigPath, 'plugins/pantheon-tui', { dryRun })
+  }
+
+  // 3. Register the copied directory in the selected target only.
+  return registerPlugin(targetTuiConfigPath, tuiCopyDir, { dryRun })
+}
+
 export async function installOpenCode(
   target,
   dryRun = false,
@@ -138,6 +231,20 @@ export async function installOpenCode(
   const componentSet = new Set(components)
   const stats = summary.opencode
 
+  // V1/V2 dual-version awareness (Phase 3): the SAME config works under both
+  // OpenCode V1 (`opencode`) and V2 (`opencode2`, beta v0.0.0-next-17444).
+  // V2 normalizes V1 fields in memory (no rewrite) and isolates its state DB
+  // via OPENCODE_DB (~/.local/share/opencode/opencode-v2.db) with a distinct
+  // service port (49375 vs V1's 49374). The installer writes one shared
+  // config; the --version flag only labels the install for the operator.
+  const version = opts.version === 'v2' ? 'v2' : 'v1'
+  if (version === 'v2') {
+    info(
+      'OpenCode V2 target — shared config; state isolated via OPENCODE_DB ' +
+        '(~/.local/share/opencode/opencode-v2.db), service port 49375',
+    )
+  }
+
   // Interactive mode handling
   const stdinTTY = process.stdin.isTTY && process.stdout.isTTY
   const forceInteractive = opts.interactive === true
@@ -250,8 +357,13 @@ export async function installOpenCode(
   }
 
   // -----------------------------------------------------------------------
-  // 2.5 Install instructions: AGENTS.md + instructions/ (--components instructions)
+  // 2.5 Install instructions: AGENTS.md only (--components instructions)
   // -----------------------------------------------------------------------
+  // AGENTS.md is the single instruction file both V1 and V2 load; the
+  // generated file embeds every src/instructions/*.instructions.md body, so
+  // the individual files are NOT copied anymore (nothing references
+  // <config>/instructions/ after the section-D merge fix — copying them would
+  // just leave stale duplicates on disk).
   if (componentSet.has('instructions')) {
     section('\uD83D\uDCCB Instructions')
     // AGENTS.md
@@ -263,14 +375,6 @@ export async function installOpenCode(
       if (status === 'created') stats.created++
       else stats.skipped++
     }
-    // instructions/ directory
-    const srcInstr = join(ROOT, 'src', 'instructions')
-    const dstInstr = join(target, 'instructions')
-    if (existsSync(srcInstr)) {
-      const instrResult = syncDir(srcInstr, dstInstr, dryRun, clean)
-      stats.created += instrResult.created
-      stats.skipped += instrResult.skipped
-    }
   }
 
   // -----------------------------------------------------------------------
@@ -327,19 +431,7 @@ export async function installOpenCode(
   // -----------------------------------------------------------------------
   // 2.9 Create/update tui.json with plugin registration
   // -----------------------------------------------------------------------
-  const targetTuiConfigPath = isGlobal
-    ? join(target, 'tui.json')
-    : join(target, '.opencode', 'tui.json')
-  // Hermetic TUI plugin registration: opencode's tui loader treats relative
-  // entries ("plugins/pantheon-tui") as npm/github package specs and fails
-  // with NpmInstallFailedError ("Repository not found"). Register the plugin
-  // by the ABSOLUTE path of the built dist inside the installed package
-  // (derived from ROOT — never hardcoded), mirroring the loader's
-  // absolute-path support (same pattern as the hooks plugin fix).
-  const tuiPluginRef = join(ROOT, 'src', 'plugins', 'tui', 'dist', 'tui.tsx')
-  // Clean up the old broken relative ref (and stale dist refs) on upgrade.
-  unregisterPlugin(targetTuiConfigPath, 'plugins/pantheon-tui', { dryRun })
-  const tuiStatus = registerPlugin(targetTuiConfigPath, tuiPluginRef, { dryRun })
+  const tuiStatus = syncTuiRegistration(target, { isGlobal, dryRun })
   if (tuiStatus === 'created') stats.created++
   else stats.skipped++
 
@@ -590,19 +682,44 @@ export async function installOpenCode(
   if (!config.default_agent && pantheonConfig.default_agent) {
     config.default_agent = pantheonConfig.default_agent
   }
+  // Merge top-level model/small_model from the repo config when the target
+  // config has no top-level `model` (fresh sandbox installs have none). The
+  // repo's opencode.json carries the default pair
+  // (opencode-go/deepseek-v4-flash); a user-set model is never overwritten.
+  if (!config.model && pantheonConfig.model) {
+    config.model = pantheonConfig.model
+    if (!config.small_model && pantheonConfig.small_model) {
+      config.small_model = pantheonConfig.small_model
+    }
+  }
   // Merge subagent_depth HERE (the config merge always runs, including on a
   // fresh install) instead of a file-existence-gated block, so run #1 already
   // produces the final config — run #2 must be a byte-identical no-op (#19).
-  if (config.subagent_depth === undefined) {
-    config.subagent_depth = 2
+  //
+  // V1/V2 compat (Phase 3): top-level `subagent_depth` is in V2's
+  // unsupportedTopLevel list and is SILENTLY IGNORED. The accepted form is
+  // `experimental.subagent_depth`. Migrate any existing top-level value into
+  // experimental (preserving the user's choice) and default fresh installs to
+  // experimental.subagent_depth = 2. V1 reads experimental.subagent_depth
+  // too, so the V1-shape config stays valid under both versions.
+  if (config.experimental === undefined || typeof config.experimental !== 'object') {
+    config.experimental = {}
+  }
+  if (config.subagent_depth !== undefined) {
+    if (config.experimental.subagent_depth === undefined) {
+      config.experimental.subagent_depth = config.subagent_depth
+    }
+    delete config.subagent_depth
+  } else if (config.experimental.subagent_depth === undefined) {
+    config.experimental.subagent_depth = 2
   }
 
   // --------------------------------------------------------------------
   // B.5.1 Hermetic plugin resolution (packaging fix)
   // --------------------------------------------------------------------
   // The packaged opencode.json may reference plugins via developer-machine
-  // absolute paths (e.g. /home/<dev>/pantheon/src/plugin.ts or
-  // /home/<dev>/pantheon/src/plugins/pantheon-hooks.ts). Copying those
+  // absolute paths (e.g. <dev>/pantheon/.../src/plugin.ts or
+  // <dev>/pantheon/.../src/plugins/pantheon-hooks.ts). Copying those
   // verbatim into the user's config would break every global install on any
   // other machine. resolveInstalledPlugin() rewrites each entry to the plugin
   // file inside the INSTALLED package (derived from ROOT — never hardcoded),
@@ -624,6 +741,25 @@ export async function installOpenCode(
     }
   }
 
+  // The two Pantheon plugins MUST always be registered, on fresh installs AND
+  // upgrades. The packaged opencode.json carries no `plugin` key (dev-machine
+  // paths removed in 3e552cc), so config.plugin would otherwise only contain
+  // whatever the user had — a fresh install would register NOTHING and lose
+  // delegation tools, GoalLoop, cost command, hashline and vision. Register
+  // both unconditionally, replacing any stale entry for the same file
+  // (basename-dedup) so installs and upgrades are idempotent and hermetic
+  // while preserving any user plugins.
+  const ensurePantheonPlugin = (ref) => {
+    const resolved = resolveInstalledPlugin(ref)
+    const file = basename(resolved)
+    config.plugin = config.plugin.filter((p) => basename(p) !== file)
+    config.plugin.push(resolved)
+  }
+  // Root-level delegation plugin (PR #45): tools, GoalLoop, cost, hashline.
+  ensurePantheonPlugin('src/plugin.ts')
+  // Runtime hooks plugin: chat hooks, hook-runner, TUI wiring.
+  ensurePantheonPlugin('src/plugins/pantheon-hooks.ts')
+
   if (!config.provider && pantheonConfig.provider) {
     config.provider = deepClone(pantheonConfig.provider)
   } else if (config.provider && pantheonConfig.provider) {
@@ -665,10 +801,25 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // D. Merge instructions paths
   // --------------------------------------------------------------------
-  const pantheonInstructions = ['AGENTS.md', 'instructions/*.instructions.md']
+  // AGENTS.md is the single instruction file both V1 and V2 load (V1
+  // auto-discovers it, V2 loads it explicitly). The generated AGENTS.md
+  // (scripts/build-agents-md.mjs) already embeds every
+  // src/instructions/*.instructions.md body, so the `instructions/*.md`
+  // glob is no longer needed — keeping it would duplicate content under V1
+  // and is ignored under V2 anyway. Only ensure AGENTS.md is present.
+  const pantheonInstructions = ['AGENTS.md']
   if (!config.instructions) {
     config.instructions = [...pantheonInstructions]
   } else {
+    // Strip stale per-file instruction globs from PREVIOUS installs
+    // (e.g. `instructions/*.instructions.md` / `src/instructions/*.md`).
+    // The merge is additive-only otherwise, so without this filter existing
+    // configs would keep loading instruction content twice under V1
+    // (generated AGENTS.md + individual files). User entries that are not
+    // *.instructions.md globs are preserved.
+    config.instructions = config.instructions.filter(
+      (instr) => typeof instr !== 'string' || !instr.endsWith('.instructions.md'),
+    )
     for (const instr of pantheonInstructions) {
       if (!config.instructions.includes(instr)) {
         config.instructions.push(instr)

package/scripts/install/plugin.mjs

@@ -3,34 +3,34 @@
  */
 
 import { execSync } from 'node:child_process'
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { warning } from './cli-ui.mjs'
 import { writeIfChanged } from './shared.mjs'
 
 /**
- * Install a plugin from source to destination.
+ * Copy a plugin's runtime payload (src/index.tsx → index.tsx, dist/*,
+ * package.json) from source to destination. Pure file copy — no npm install.
  * @param {string} srcDir - Source plugin directory (e.g. ROOT/src/plugins/tui)
  * @param {string} dstDir - Destination plugin directory
  * @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
- * @returns {{ created: number, skipped: number, errors: number }}
+ * @returns {{ created: number, skipped: number }}
  */
-export function installPlugin(srcDir, dstDir, { dryRun = false, clean = false } = {}) {
-  const result = { created: 0, skipped: 0, errors: 0 }
+export function copyPluginFiles(srcDir, dstDir, { dryRun = false } = {}) {
+  const result = { created: 0, skipped: 0 }
 
   if (!dryRun) mkdirSync(dstDir, { recursive: true })
-  if (clean && existsSync(dstDir) && !dryRun) {
-    rmSync(dstDir, { recursive: true, force: true })
-    mkdirSync(dstDir, { recursive: true })
-  }
   if (!dryRun) mkdirSync(join(dstDir, 'dist'), { recursive: true })
 
   // Copy src/index.tsx -> index.tsx
   const srcIdx = join(srcDir, 'src', 'index.tsx')
   if (existsSync(srcIdx)) {
-    const idxStatus = writeIfChanged(join(dstDir, 'index.tsx'), readFileSync(srcIdx, 'utf8'), dryRun)
+    const idxStatus = writeIfChanged(
+      join(dstDir, 'index.tsx'),
+      readFileSync(srcIdx, 'utf8'),
+      dryRun,
+    )
     if (idxStatus === 'created') result.created++
     else result.skipped++
   }
@@ -40,25 +40,53 @@ export function installPlugin(srcDir, dstDir, { dryRun = false, clean = false }
   if (existsSync(distSrc)) {
     for (const f of readdirSync(distSrc)) {
       const c = readFileSync(join(distSrc, f), 'utf8')
-      writeIfChanged(join(dstDir, 'dist', f), c, dryRun)
-      result.created++
+      const status = writeIfChanged(join(dstDir, 'dist', f), c, dryRun)
+      if (status === 'created') result.created++
+      else result.skipped++
     }
   }
 
   // Copy package.json
   const pkgSrc = join(srcDir, 'package.json')
   if (existsSync(pkgSrc)) {
-    const pkgStatus = writeIfChanged(join(dstDir, 'package.json'), readFileSync(pkgSrc, 'utf8'), dryRun)
+    const pkgStatus = writeIfChanged(
+      join(dstDir, 'package.json'),
+      readFileSync(pkgSrc, 'utf8'),
+      dryRun,
+    )
     if (pkgStatus === 'created') result.created++
     else result.skipped++
   }
 
+  return result
+}
+
+/**
+ * Install a plugin from source to destination.
+ * @param {string} srcDir - Source plugin directory (e.g. ROOT/src/plugins/tui)
+ * @param {string} dstDir - Destination plugin directory
+ * @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
+ * @returns {{ created: number, skipped: number, errors: number }}
+ */
+export function installPlugin(srcDir, dstDir, { dryRun = false, clean = false } = {}) {
+  const result = { created: 0, skipped: 0, errors: 0 }
+
+  if (clean && existsSync(dstDir) && !dryRun) {
+    rmSync(dstDir, { recursive: true, force: true })
+  }
+
+  const copyResult = copyPluginFiles(srcDir, dstDir, { dryRun })
+  result.created += copyResult.created
+  result.skipped += copyResult.skipped
+
   // Install plugin dependencies (@opentui/core, @opentui/solid, solid-js)
   if (!dryRun) {
     try {
       execSync('npm install --omit=dev --no-audit', { cwd: dstDir, stdio: 'pipe' })
     } catch (e) {
-      warning('Failed to install TUI plugin dependencies: ' + e.message)
+      warning(`Failed to install TUI plugin dependencies: ${e.message}`)
       result.errors++
     }
   }
@@ -77,7 +105,7 @@ export function installPluginDependencies(pluginDir, { dryRun = false } = {}) {
   try {
     execSync('npm install --omit=dev --no-audit', { cwd: pluginDir, stdio: 'pipe' })
   } catch (e) {
-    warning('Failed to install plugin dependencies: ' + e.message)
+    warning(`Failed to install plugin dependencies: ${e.message}`)
   }
 }
 
@@ -108,6 +136,55 @@ export function registerPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
   return writeIfChanged(tuiJsonPath, tuiContent, dryRun)
 }
 
+/**
+ * Suffix patterns that identify a Pantheon TUI registration as STALE. Every
+ * reference shape ever written by previous installers must be covered:
+ *   - dist file refs (both the old in-package src/plugins/tui target and the
+ *     copied plugins/pantheon-tui target, tsx and js eras)
+ *   - the in-package source dir (src/plugins/tui) — a registration pointing
+ *     into the installed package breaks on reinstall/upgrade (the dir is
+ *     replaced under a live registration)
+ *   - bare copied dirs (plugins/pantheon-tui) from any OLD install target —
+ *     indistinguishable from the current copied dir without knowing the
+ *     install target, so they are flagged too; syncTuiRegistration keeps the
+ *     current ref via unregister-then-register
+ *   - node_modules copies (npx cache installs of the vendored plugin)
+ */
+export const TUI_STALE_SUFFIXES = [
+  '/src/plugins/tui/dist/tui.tsx',
+  '/src/plugins/tui/dist/tui.js',
+  '/src/plugins/tui',
+  '/plugins/pantheon-tui/dist/tui.tsx',
+  '/plugins/pantheon-tui/dist/tui.js',
+  '/plugins/pantheon-tui',
+  '/node_modules/pantheon-tui',
+]
+
+/**
+ * Whether a single tui.json plugin entry is a stale Pantheon TUI reference.
+ * @param {unknown} ref - tui.json plugin entry
+ * @returns {boolean}
+ */
+export function isStaleTuiRef(ref) {
+  if (typeof ref !== 'string') return false
+  if (ref === 'plugins/pantheon-tui') return true
+  const normalized = ref.replaceAll('\\', '/')
+  // npx spec strings ("npx pantheon-tui", "npx -y pantheon-tui",
+  // "npx:pantheon-tui") and npx cache paths end with /node_modules/pantheon-tui.
+  if (/^npx[\s:]/i.test(normalized) && normalized.includes('pantheon-tui')) return true
+  return TUI_STALE_SUFFIXES.some((suffix) => normalized.endsWith(suffix))
+}
+
+/**
+ * Pure filter: return the plugin entries of a tui.json plugin array that are
+ * stale Pantheon TUI references.
+ * @param {unknown[]} pluginArray - tui.json plugin array
+ * @returns {string[]}
+ */
+export function staleTuiRefs(pluginArray) {
+  return (Array.isArray(pluginArray) ? pluginArray : []).filter(isStaleTuiRef)
+}
+
 /**
  * Unregister stale plugin references from tui.json.
  * @param {string} tuiJsonPath - Path to tui.json
@@ -117,25 +194,32 @@ export function registerPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
  * @returns {'created'|'skipped'}
  */
 export function unregisterPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
+  if (!existsSync(tuiJsonPath)) {
+    // Nothing to clean — and never create an empty tui.json in a location
+    // OpenCode reads (the cross-location cleanup also touches global config
+    // dirs that may not exist yet; writing there would ENOENT).
+    return 'skipped'
+  }
   let tuiConfig = { plugin: [] }
-  if (existsSync(tuiJsonPath)) {
-    try {
-      tuiConfig = JSON.parse(readFileSync(tuiJsonPath, 'utf8'))
-    } catch {
-      /* use default */
-    }
+  try {
+    tuiConfig = JSON.parse(readFileSync(tuiJsonPath, 'utf8'))
+  } catch {
+    /* use default */
   }
   if (!Array.isArray(tuiConfig.plugin)) {
     tuiConfig.plugin = []
   }
   // Remove stale refs: the bare relative id (openCode < 1.19 wrote
   // "plugins/pantheon-tui", which its tui loader misreads as an npm/github
-  // spec → NpmInstallFailedError) and the old dist paths.
-  const staleRefs = [pluginId, `${pluginId}/dist/tui.tsx`, `${pluginId}/dist/tui.js`]
-  for (const stale of staleRefs) {
-    const idx = tuiConfig.plugin.indexOf(stale)
-    if (idx !== -1) tuiConfig.plugin.splice(idx, 1)
-  }
+  // spec → NpmInstallFailedError), old dist paths, in-package source dirs,
+  // bare copy dirs from previous install targets, and npx cache copies.
+  // Without removing the absolute paths, each init run accumulates another
+  // TUI plugin and OpenCode loads stale copies.
+  const exactStale = [pluginId, `${pluginId}/dist/tui.tsx`, `${pluginId}/dist/tui.js`]
+  tuiConfig.plugin = tuiConfig.plugin.filter((ref) => {
+    if (exactStale.includes(ref)) return false
+    return !isStaleTuiRef(ref)
+  })
   const tuiContent = `${JSON.stringify(tuiConfig, null, 2)}\n`
   return writeIfChanged(tuiJsonPath, tuiContent, dryRun)
 }

package/scripts/install-mcp.mjs

@@ -37,7 +37,7 @@ const ROOT = join(__dirname, '..')
 // venv python3 and the server script. ROOT alone is ambiguous: when this
 // installer runs from a global npm install, `join(ROOT, '.venv/bin/python3')`
 // points at a venv that does not exist there, and a stale config with a
-// hardcoded path to a migrated home (e.g. /home/admin) fails with
+// hardcoded path to a migrated home (e.g. <dev>/admin) fails with
 // `posix_spawn ENOENT`. Resolution order:
 //   1. Canonical user install: ~/.config/opencode/.venv + ~/.config/opencode/scripts/
 //   2. Local checkout:        <ROOT>/.venv + <ROOT>/<relPath>

package/scripts/redaction-gate.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/** Fail closed when validation artifacts contain callback URLs or credentials. */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+const callbackUrl = /https?:\/\/[^\s"'<>]+(?:callback|redirect|return|webhook)[^\s"'<>]*/iu
+const bearer = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/u
+const jwt = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/u
+const apiSecret =
+  /\b(?:api[_-]?key|token|secret|password)\s*[=:]\s*["'](?!\$\{|process\.env|os\.getenv|env:|<redacted>|\[redacted\]|fixture)[^"']{12,}["']/iu
+
+function isText(buffer) {
+  return !buffer.subarray(0, Math.min(buffer.length, 4096)).includes(0)
+}
+
+function findings(text) {
+  const result = []
+  if (callbackUrl.test(text)) result.push('callback URL')
+  if (bearer.test(text) || jwt.test(text) || apiSecret.test(text)) result.push('credential/token')
+  return result
+}
+
+function scanFile(path) {
+  if (!existsSync(path) || !lstatSync(path).isFile()) return []
+  const content = readFileSync(path)
+  return isText(content) ? findings(content.toString('utf8')) : []
+}
+
+function scanTarball(path) {
+  const entries = execFileSync('tar', ['-tzf', path], { encoding: 'utf8' }).split('\n').filter(Boolean)
+  const result = []
+  for (const entry of entries) {
+    const content = execFileSync('tar', ['-xOzf', path, entry])
+    if (isText(content)) result.push(...findings(content.toString('utf8')))
+  }
+  return [...new Set(result)]
+}
+
+function scanPath(path) {
+  if (path.endsWith('.tgz') || path.endsWith('.tar.gz')) return scanTarball(path)
+  if (!existsSync(path)) throw new Error(`path does not exist: ${path}`)
+  if (lstatSync(path).isDirectory()) {
+    return readdirSync(path, { withFileTypes: true }).flatMap((entry) =>
+      scanPath(join(path, entry.name)),
+    )
+  }
+  return scanFile(path)
+}
+
+const paths = process.argv.slice(2)
+if (paths.length === 0) {
+  console.error(`Usage: ${basename(process.argv[1])} <file|directory|tarball> [...]`)
+  process.exit(2)
+}
+
+try {
+  const hits = [...new Set(paths.flatMap(scanPath))]
+  if (hits.length > 0) {
+    for (const hit of hits) console.error(`[REDACTION GATE] ${hit} detected`)
+    process.exit(1)
+  }
+  console.log('Redaction gate passed: no callback URLs or credentials detected.')
+} catch (error) {
+  console.error(`[REDACTION GATE] failed to inspect input: ${error.message}`)
+  process.exit(2)
+}