pantheon-opencode 1.3.2 → 1.3.4

package/scripts/doctor.mjs

@@ -34,7 +34,7 @@ import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..')
-const AGENTS_DIR = join(ROOT, "src", "agents")
+const AGENTS_DIR = join(ROOT, 'src', 'agents')
 const PLATFORM_DIR = join(ROOT, 'platform')
 
 // All known platforms (must match platform/ subdirectories with adapter.json)
@@ -246,7 +246,9 @@ function checkAgentFiles(args) {
 
   // Determine which platforms to check
   if (!existsSync(PLATFORM_DIR)) {
-    info(`Platform component not distributed in this package — platform check skipped (${args.profile} profile)`)
+    info(
+      `Platform component not distributed in this package — platform check skipped (${args.profile} profile)`,
+    )
     return
   }
   const platformDirs = readdirSync(PLATFORM_DIR, { withFileTypes: true })
@@ -255,7 +257,9 @@ function checkAgentFiles(args) {
     .filter((name) => !args.platform || name === args.platform)
 
   if (platformDirs.length === 0) {
-    info(`No platform directories found in platform/ — platform check skipped (${args.profile} profile)`)
+    info(
+      `No platform directories found in platform/ — platform check skipped (${args.profile} profile)`,
+    )
     return
   }
 
@@ -377,7 +381,8 @@ function checkMcpConfig(args) {
 
     const mcp = cfg.data.mcp
     if (!mcp || typeof mcp !== 'object') {
-      if (requiredMcpNames.length > 0) error(`${cfg.label}: required MCPs missing — no "mcp" section`)
+      if (requiredMcpNames.length > 0)
+        error(`${cfg.label}: required MCPs missing — no "mcp" section`)
       else info(`${cfg.label}: no "mcp" section (${args.profile} profile — optional)`)
       continue
     }
@@ -450,7 +455,9 @@ function checkMcpConfig(args) {
       const exe = cmd[0]
       if (!exe.includes('/')) {
         // PATH-resolved executable — cannot verify statically; surface for manual check
-        info(`${cfg.label}: MCP "${name}" uses PATH executable "${exe}" (verify with \`which ${exe}\`)`)
+        info(
+          `${cfg.label}: MCP "${name}" uses PATH executable "${exe}" (verify with \`which ${exe}\`)`,
+        )
         continue
       }
       if (!existsSync(exe)) {
@@ -467,7 +474,8 @@ function checkMcpConfig(args) {
   if (requiredMcpNames.length > 0) {
     const configured = new Set(configs.flatMap((cfg) => Object.keys(cfg.data.mcp ?? {})))
     for (const required of requiredMcpNames) {
-      if (configured.has(required)) pass(`Required MCP "${required}" configured in an available config`)
+      if (configured.has(required))
+        pass(`Required MCP "${required}" configured in an available config`)
       else error(`Required MCP "${required}" not configured in any available config`)
     }
   }
@@ -535,12 +543,17 @@ function mcpInitializeSmoke(command, cwd, timeoutMs) {
         const msg = JSON.parse(line.trim())
         if (msg.id === 1 && msg.result) {
           const info = msg.result.serverInfo
-          const label = info?.name ? `${info.name}${info.version ? ` ${info.version}` : ''}` : undefined
+          const label = info?.name
+            ? `${info.name}${info.version ? ` ${info.version}` : ''}`
+            : undefined
           finish({ ok: true, serverName: label })
           return
         }
         if (msg.error) {
-          finish({ ok: false, reason: `initialize error: ${msg.error.code ?? ''} ${msg.error.message ?? ''}` })
+          finish({
+            ok: false,
+            reason: `initialize error: ${msg.error.code ?? ''} ${msg.error.message ?? ''}`,
+          })
         }
       } catch {
         /* not JSON yet — keep buffering */
@@ -592,7 +605,9 @@ async function checkMcpRuntimeSmoke(args) {
   for (const { name, command, cwd, source } of local) {
     const result = await mcpInitializeSmoke(command, cwd, 10000)
     if (result.ok) {
-      pass(`MCP "${name}" (${source}): initialize handshake OK${result.serverName ? ` — ${result.serverName}` : ''}`)
+      pass(
+        `MCP "${name}" (${source}): initialize handshake OK${result.serverName ? ` — ${result.serverName}` : ''}`,
+      )
     } else {
       error(`MCP "${name}" (${source}): ${result.reason}`)
     }
@@ -645,7 +660,9 @@ function checkPermissionMismatches(args) {
   // Locate the validation script
   const validator = join(ROOT, 'scripts', 'validate-agent-frontmatter.py')
   if (!existsSync(validator)) {
-    info(`validate-agent-frontmatter.py not found — optional helper skipped (${args.profile} profile)`)
+    info(
+      `validate-agent-frontmatter.py not found — optional helper skipped (${args.profile} profile)`,
+    )
     return
   }
 
@@ -876,12 +893,24 @@ function checkRequirementLine(line, installed) {
   const cmp = compareVersions(have, want)
   let ok = false
   switch (op) {
-    case '==': ok = cmp === 0; break
-    case '>=': ok = cmp >= 0; break
-    case '<=': ok = cmp <= 0; break
-    case '>': ok = cmp > 0; break
-    case '<': ok = cmp < 0; break
-    case '!=': ok = cmp !== 0; break
+    case '==':
+      ok = cmp === 0
+      break
+    case '>=':
+      ok = cmp >= 0
+      break
+    case '<=':
+      ok = cmp <= 0
+      break
+    case '>':
+      ok = cmp > 0
+      break
+    case '<':
+      ok = cmp < 0
+      break
+    case '!=':
+      ok = cmp !== 0
+      break
     case '~=': {
       const spec = parseVersion(want)
       const got = parseVersion(have)
@@ -961,12 +990,12 @@ function checkVenvLayer(args) {
  */
 export function summaryMessage(summaryCounts, summaryExitCode) {
   if (summaryCounts.error > 0 || summaryExitCode !== 0) {
-    const errorText = summaryCounts.error > 0
-      ? `${summaryCounts.error} blocking error(s) found`
-      : 'Blocking check failure'
-    const warningText = summaryCounts.warn > 0
-      ? `; ${summaryCounts.warn} warning(s) remain advisory`
-      : ''
+    const errorText =
+      summaryCounts.error > 0
+        ? `${summaryCounts.error} blocking error(s) found`
+        : 'Blocking check failure'
+    const warningText =
+      summaryCounts.warn > 0 ? `; ${summaryCounts.warn} warning(s) remain advisory` : ''
     return `❌ ${errorText}${warningText} — exit code ${summaryExitCode}`
   }
 
@@ -1005,6 +1034,11 @@ async function main() {
     process.exit(0)
   }
 
+  // Report the resolved validation profile up front (auto → global/sandbox)
+  // so callers — including the `doctor` CLI wrapper — can see which policy
+  // gate applied before any check output.
+  console.log(`Validation profile: ${args.profile}`)
+
   if (!existsSync(args.target)) {
     console.error(`❌ Target directory does not exist: ${args.target}`)
     process.exit(2)

package/scripts/hooks/on-subagent-delegation-stop.sh

@@ -383,12 +383,27 @@ fi
 # Emit a schema-compatible line: {event, timestamp, agent, status, reason,
 # session_id, result, delegation_id, task_id, duration_ms} — P0-2: the
 # delegation_id joins this record to the matching SubagentStart; task_id and
-# duration_ms ride in their OWN fields. Built with json.dumps so arbitrary
+# duration_ms ride in their OWN fields. 1.3.4: task_id is OMITTED when empty
+# (never "" — the real child id is always present when a job exists) and
+# duration_ms is emitted as a NUMBER (the plugin computes it; stringifying it
+# broke downstream aggregation). Built with json.dumps so arbitrary
 # reason/result text cannot break the JSON.
 LOG_LINE=$(python3 -c '
 import json
 import sys
-print(json.dumps({
+
+
+def _num(v):
+    """Best-effort numeric parse — the plugin duration_ms is a number; a
+    non-numeric value (e.g. unset) becomes null, never a string."""
+    try:
+        return int(float(v))
+    except (TypeError, ValueError):
+        return None
+
+
+task_id = sys.argv[8] or ""
+line = {
     "event": "SubagentStop",
     "timestamp": sys.argv[1],
     "agent": sys.argv[2],
@@ -397,9 +412,11 @@ print(json.dumps({
     "session_id": sys.argv[5],
     "result": sys.argv[6],
     "delegation_id": sys.argv[7],
-    "task_id": sys.argv[8],
-    "duration_ms": sys.argv[9] or None,
-}, ensure_ascii=False))
+}
+if task_id:
+    line["task_id"] = task_id
+line["duration_ms"] = _num(sys.argv[9])
+print(json.dumps(line, ensure_ascii=False))
 ' "$TIMESTAMP" "$AGENT_NAME" "$STATUS" "$REASON" "$SESSION_ID" "$RESULT_SNIPPET" "$DELEGATION_ID" "$TASK_ID" "$DURATION_MS")
 
 LOG_FILE="$LOG_DIR/delegations.log"

package/scripts/install/opencode.mjs

@@ -3,15 +3,7 @@
  * opencode.mjs — OpenCode platform installer
  */
 
-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 +21,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,
@@ -84,6 +76,28 @@ function mergeMissing(target, source) {
   return target
 }
 
+/**
+ * Resolve a plugin ref from the packaged opencode.json to a path INSIDE the
+ * installed package.
+ *
+ * The packaged config may reference plugins via developer-machine absolute
+ * 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
+ * path that actually exists.
+ */
+export function resolveInstalledPlugin(plugin) {
+  // Map any ref whose path tail starts with `src/` to the matching file INSIDE
+  // the installed package. This preserves the ref's relative location, so both
+  // src/plugins/* (hooks) and the root-level src/plugin.ts (delegation plugin,
+  // PR #45) resolve correctly — nothing is forced into src/plugins/.
+  const srcIndex = plugin.indexOf('src/')
+  if (srcIndex === -1) return plugin
+  const packaged = join(ROOT, plugin.slice(srcIndex))
+  return existsSync(packaged) ? packaged : plugin
+}
+
 /**
  * Detect whether `target` is the user's global OpenCode installation directory
  * (~/.opencode or $XDG_CONFIG_HOME/opencode).
@@ -101,6 +115,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,
@@ -305,19 +410,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++
 
@@ -578,19 +671,15 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // B.5.1 Hermetic plugin resolution (packaging fix)
   // --------------------------------------------------------------------
-  // The packaged opencode.json may reference the pantheon-hooks plugin via a
-  // developer-machine absolute path (e.g. /home/<dev>/pantheon/src/plugins/...).
-  // Copying that verbatim into the user's config would break every global
-  // install on any other machine. Option A: rewrite the entry to the plugin
+  // The packaged opencode.json may reference plugins via developer-machine
+  // 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),
   // so both dev and global installs resolve to a path that actually exists.
   // The source opencode.json keeps its dev path for local development; the
   // transform happens at install/sync time only.
-  function resolveInstalledPlugin(plugin) {
-    const file = basename(plugin)
-    const packaged = join(ROOT, 'src', 'plugins', file)
-    return existsSync(packaged) ? packaged : plugin
-  }
 
   if (!Array.isArray(config.plugin)) {
     config.plugin = []
@@ -606,6 +695,17 @@ export async function installOpenCode(
     }
   }
 
+  // The runtime hooks plugin MUST always be registered. The packaged
+  // opencode.json no longer carries dev-machine plugin paths (removed in
+  // 3e552cc), so config.plugin would otherwise stay empty and the
+  // pantheon-hooks runtime would never load. Register it unconditionally,
+  // replacing any stale entry for the same file (same basename-dedup as
+  // above) so installs and upgrades are idempotent and hermetic.
+  const hooksPlugin = resolveInstalledPlugin('src/plugins/pantheon-hooks.ts')
+  const hooksFile = basename(hooksPlugin)
+  config.plugin = config.plugin.filter((p) => basename(p) !== hooksFile)
+  config.plugin.push(hooksPlugin)
+
   if (!config.provider && pantheonConfig.provider) {
     config.provider = deepClone(pantheonConfig.provider)
   } else if (config.provider && pantheonConfig.provider) {

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>