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

package/scripts/run-node-tests.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * Run `node --test` over an explicit file list, and FAIL when zero tests are collected.
+ *
+ * Why this exists: `node --test <glob>` exits 0 when the glob matches nothing (Node >= 22).
+ * A test script whose file set is absent from the checkout -- or absent from the published
+ * package, because the `files` allow-list omits it -- therefore reports success while
+ * collecting nothing. That is the worst possible failure mode for a release gate: it
+ * manufactures confidence.
+ *
+ * This runner closes that hole from two independent sides:
+ *   1. It expands the globs ITSELF and refuses to start the runner with zero files, so the
+ *      runner is never handed an unexpanded pattern that silently matches nothing.
+ *   2. After a run that exited 0, it re-reads the collected count from the machine-readable
+ *      TAP summary and fails closed when that count is 0, unparseable, or missing.
+ *
+ * Side 2 is deliberately independent of side 1: a future Node change to `--test` glob
+ * handling, a glob that expands to a directory of empty files, or an emptied test file all
+ * still get caught.
+ *
+ * Human-readable output is unchanged: the default `spec` reporter still goes to stdout, and
+ * the TAP reporter is diverted to a scratch file that is read once and deleted.
+ *
+ * Usage:
+ *   node scripts/run-node-tests.mjs [--label <name>] [-- <node flags...>] <glob>...
+ *
+ * Examples:
+ *   node scripts/run-node-tests.mjs 'tests/*.mjs' 'tests/pantheon/*.mjs'
+ *   node scripts/run-node-tests.mjs -- --experimental-test-coverage 'tests/*.mjs'
+ */
+import { spawnSync } from 'node:child_process'
+import { globSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = join(fileURLToPath(new URL('.', import.meta.url)), '..')
+
+function usage(message) {
+  console.error(`zero-test-guard: ${message}`)
+  console.error(
+    'usage: node scripts/run-node-tests.mjs [--label <name>] [-- <node flags...>] <glob>...',
+  )
+  process.exit(1)
+}
+
+/** Parse `[--label <name>] [-- <node flags...>] <glob>...`. */
+function parseArgs(argv) {
+  const separator = argv.indexOf('--')
+  const own = separator === -1 ? argv : argv.slice(0, separator)
+  const nodeFlags = separator === -1 ? [] : argv.slice(separator + 1)
+
+  let label = 'node tests'
+  const globs = []
+  for (let i = 0; i < own.length; i++) {
+    if (own[i] === '--label') {
+      const value = own[i + 1]
+      if (value === undefined) usage('--label requires a value')
+      label = value
+      i += 1
+      continue
+    }
+    if (own[i].startsWith('-')) usage(`unknown option ${own[i]}`)
+    globs.push(own[i])
+  }
+  if (globs.length === 0) usage('at least one glob is required')
+  return { label, globs, nodeFlags }
+}
+
+/**
+ * Expand globs to a deduped, ordered file list.
+ * Order follows the positional order of the globs so that the suite runs in the same order
+ * as the shell used to; within a glob, matches are sorted for determinism.
+ */
+function expand(globs) {
+  const files = []
+  const seen = new Set()
+  for (const pattern of globs) {
+    const matches = globSync(pattern, { cwd: ROOT })
+      .filter((match) => !match.includes('node_modules') && !match.includes('__pycache__'))
+      .sort()
+    for (const match of matches) {
+      if (seen.has(match)) continue
+      seen.add(match)
+      files.push(match)
+    }
+  }
+  return files
+}
+
+function reportMissingFiles(label, globs) {
+  console.error(`zero-test-guard: ${label} matched 0 test files — refusing to report success.`)
+  console.error(`  globs: ${globs.join(' ')}`)
+  console.error('  This is the "test suite silently passes when it collects nothing" failure.')
+  console.error('  Either the test files are missing from this checkout, or they are missing')
+  console.error('  from the published package (check the "files" allow-list in package.json).')
+}
+
+function reportZeroCollected(label, files) {
+  console.error(`zero-test-guard: ${label} collected 0 tests — refusing to report success.`)
+  console.error(`  ${files.length} file(s) matched, but not one test case was collected:`)
+  for (const file of files) console.error(`    ${file}`)
+}
+
+/**
+ * Count the real test cases collected in a TAP summary.
+ *
+ * Node counts a test FILE that declares no test cases as one passing "test"
+ * (`ok 1 - tests/foo.test.mjs`), so the summary's `# tests N` is >= the file count and
+ * can never reach 0 once any file matched. Relying on it alone would let a suite whose
+ * every test file was emptied out report success.
+ *
+ * The reliable discriminator is the subtest NAME: a file-level placeholder is named with
+ * the file path that was passed to the runner, a real test case is named with its test
+ * name. So a top-level subtest whose name is one of our matched paths is a placeholder
+ * and is not counted as a collected case.
+ *
+ * Returns null when the summary cannot be read or parsed -- the caller fails closed.
+ */
+function countCollectedTests(tapPath, files) {
+  let tap = ''
+  try {
+    tap = readFileSync(tapPath, 'utf8')
+  } catch {
+    return null
+  }
+  // The summary count is still asserted to exist: without it the stream is not TAP.
+  if (!/^#\s*tests\s+\d+\s*$/m.test(tap)) return null
+
+  const placeholders = new Set(files)
+  let collected = 0
+  for (const match of tap.matchAll(/^# Subtest: (.+)$/gm)) {
+    if (placeholders.has(match[1].trim())) continue
+    collected += 1
+  }
+  return collected
+}
+
+const { label, globs, nodeFlags } = parseArgs(process.argv.slice(2))
+const files = expand(globs)
+
+if (files.length === 0) {
+  reportMissingFiles(label, globs)
+  process.exit(1)
+}
+
+const scratch = mkdtempSync(join(tmpdir(), 'pantheon-node-tests-'))
+const tapPath = join(scratch, 'summary.tap')
+
+try {
+  const run = spawnSync(
+    process.execPath,
+    [
+      '--test',
+      '--test-reporter=spec',
+      '--test-reporter-destination=stdout',
+      '--test-reporter=tap',
+      `--test-reporter-destination=${tapPath}`,
+      ...nodeFlags,
+      ...files,
+    ],
+    { cwd: ROOT, stdio: 'inherit' },
+  )
+
+  if (run.error) {
+    console.error(`zero-test-guard: could not start the test runner: ${run.error.message}`)
+    process.exit(1)
+  }
+  if (run.signal) {
+    console.error(`zero-test-guard: the test runner was killed by ${run.signal}`)
+    process.exit(1)
+  }
+  // Real failures keep the runner's own exit code; the guard only speaks up when the
+  // runner claimed success it cannot justify.
+  if (run.status !== 0) process.exit(run.status)
+
+  const collected = countCollectedTests(tapPath, files)
+  if (collected === null) {
+    console.error('zero-test-guard: could not read the collected test count from the TAP summary.')
+    console.error('  Failing closed: an unreadable summary cannot certify that any test ran.')
+    process.exit(1)
+  }
+  if (collected === 0) {
+    reportZeroCollected(label, files)
+    process.exit(1)
+  }
+} finally {
+  rmSync(scratch, { recursive: true, force: true })
+}

package/scripts/sync-artifacts.mjs

@@ -19,10 +19,10 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
 import { join } from 'node:path'
+import { copyAgentPrompts, writeAgentsMdManaged } from './build-agents-md.mjs'
 
 import {
   collectSkillNames,
-  copyFiles,
   installSkills,
   ROOT,
   syncDir,
@@ -31,15 +31,16 @@ import {
 
 /** Canonical MCP script sources — mirrors installOpenCode phase 2.10. */
 const MCP_SCRIPTS = {
-  'mcp_resources_server.py': () => join(ROOT, 'src', 'mcp', 'mcp_resources_server.py'),
-  'code_mode_server.py': () => join(ROOT, 'src', 'mcp', 'code_mode_server.py'),
-  'memory_mcp_server.py': () => join(ROOT, 'src', 'mcp', 'memory_mcp_server.py'),
-  'mcp_persistence_server.py': () => join(ROOT, 'src', 'mcp', 'mcp_persistence_server.py'),
+  'mcp_resources.py': () => join(ROOT, 'src', 'mcp', 'mcp_resources.py'),
+  'code_mode.py': () => join(ROOT, 'src', 'mcp', 'code_mode.py'),
+  'memory_mcp.py': () => join(ROOT, 'src', 'mcp', 'memory_mcp.py'),
+  'mcp_persistence.py': () => join(ROOT, 'src', 'mcp', 'mcp_persistence.py'),
   '_pantheon_paths.py': () => join(ROOT, 'src', 'mcp', '_pantheon_paths.py'),
   'mcp_codemap_module.py': () => join(ROOT, 'src', 'mcp', 'mcp_codemap_module.py'),
-  'pantheon_vision_server.py': () => join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py'),
+  'pantheon_vision.py': () => join(ROOT, 'src', 'mcp', 'pantheon_vision.py'),
   'eval_store.py': () => join(ROOT, 'src', 'mcp', 'eval_store.py'),
   'scrub-secrets.py': () => join(ROOT, 'scripts', 'scrub-secrets.py'),
+  'themis_heuristic_scan.py': () => join(ROOT, 'scripts', 'themis_heuristic_scan.py'),
 }
 
 /**
@@ -59,7 +60,7 @@ export function syncCopyArtifacts(configDir) {
     const dstAgents = join(configDir, 'agents')
     if (existsSync(join(ROOT, 'src', 'agents'))) {
       mkdirSync(dstAgents, { recursive: true })
-      bump(copyFiles(join(ROOT, 'src', 'agents'), dstAgents, false))
+      bump(copyAgentPrompts(join(ROOT, 'src', 'agents'), dstAgents, false))
       const routing = join(ROOT, 'src', 'routing.yml')
       if (existsSync(routing)) {
         if (
@@ -82,15 +83,27 @@ export function syncCopyArtifacts(configDir) {
     result.errors.push(`skills: ${err.message}`)
   }
 
-  // ── instructions (AGENTS.md) ──
+  // ── instructions (global AGENTS.md artifact) ──
+  // The config dir is GLOBAL context: it receives the repo-agnostic global
+  // artifact, never the repository artifact. Managed-region writer keeps any
+  // user content around the markers intact.
   try {
-    const src = join(ROOT, 'AGENTS.md')
+    const src = join(ROOT, 'AGENTS.global.md')
     if (existsSync(src)) {
-      if (
-        writeIfChanged(join(configDir, 'AGENTS.md'), readFileSync(src, 'utf8'), false) === 'created'
-      ) {
+      const status = writeAgentsMdManaged(
+        join(configDir, 'AGENTS.md'),
+        readFileSync(src, 'utf8'),
+        false,
+      )
+      if (status === 'skipped') result.skipped++
+      else {
         result.created++
-      } else result.skipped++
+        if (status === 'merged') {
+          result.errors.push(
+            'instructions: non-generated content found in AGENTS.md — preserved around the Pantheon managed region',
+          )
+        }
+      }
     }
   } catch (err) {
     result.errors.push(`instructions: ${err.message}`)

package/scripts/sync-tui.mjs

@@ -14,6 +14,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
+import { resolveOpenCodeVersion } from './install/opencode-version.mjs'
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
 const ROOT = join(__dirname, '..')
@@ -63,7 +64,7 @@ function resolveConfigDir() {
  * The raw TSX source is never copied — the loader consumes only the bundle.
  * @returns {{ created: number, skipped: number }}
  */
-function copyPluginFiles(srcDir, dstDir) {
+function copyPluginFiles(srcDir, dstDir, version) {
   const result = { created: 0, skipped: 0 }
 
   mkdirSync(dstDir, { recursive: true })
@@ -87,11 +88,30 @@ function copyPluginFiles(srcDir, dstDir) {
   // package.json
   const pkgSrc = join(srcDir, 'package.json')
   if (existsSync(pkgSrc)) {
-    const content = readFileSync(pkgSrc, 'utf8')
+    const packageJson = JSON.parse(readFileSync(pkgSrc, 'utf8'))
+    if (version === 'v2' && packageJson.exports?.['./tui-v2']) {
+      packageJson.exports['./tui'] = packageJson.exports['./tui-v2']
+    }
+    const content = `${JSON.stringify(packageJson, null, 2)}\n`
     if (writeIfChanged(join(dstDir, 'package.json'), content)) result.created++
     else result.skipped++
   }
 
+  const tuiEntry = join(srcDir, version === 'v2' ? 'tui-v2.ts' : 'tui.ts')
+  if (existsSync(tuiEntry)) {
+    if (writeIfChanged(join(dstDir, 'tui.ts'), readFileSync(tuiEntry, 'utf8'))) result.created++
+    else result.skipped++
+  }
+
+  const v2ServerEntry = join(srcDir, 'index-v2.ts')
+  const v2ServerDestination = join(dstDir, 'index.ts')
+  if (version === 'v2' && existsSync(v2ServerEntry)) {
+    if (writeIfChanged(v2ServerDestination, readFileSync(v2ServerEntry, 'utf8'))) result.created++
+    else result.skipped++
+  } else if (existsSync(v2ServerDestination)) {
+    rmSync(v2ServerDestination, { force: true })
+  }
+
   // Keep the copied plugin installable with deterministic npm ci.
   const lockSrc = join(srcDir, 'package-lock.json')
   if (existsSync(lockSrc)) {
@@ -169,7 +189,8 @@ async function main() {
     const sourceVersion = readVersion(join(tuiSrcDir, 'package.json'))
 
     // Copy fresh files
-    const { created } = copyPluginFiles(tuiSrcDir, tuiCopyDir)
+    const version = resolveOpenCodeVersion('auto', { warn: (message) => console.warn(message) })
+    const { created } = copyPluginFiles(tuiSrcDir, tuiCopyDir, version)
 
     // Lockfile installation is the only accepted dependency path. Strip
     // global-context npm vars so a global postinstall can't trigger ECIGLOBAL.

package/scripts/test-opencode-v2-sandbox.sh

@@ -34,7 +34,7 @@
 # Env overrides:
 #   PANTHEON_SANDBOX_ROOT    Sandbox root (default: ~/pantheon-sandbox)
 #   OPENCODE_V2_SPEC         npm spec providing the V2 binary
-#                            (default: @opencode-ai/cli@beta). NOTE: this is an
+#                            (default: @opencode/cli@latest). NOTE: this is an
 #                            install spec only — it is not a dependency of this
 #                            package, and no code imports it.
 #   PANTHEON_REPO            Repository the sandbox is built from (default: the
@@ -63,7 +63,7 @@ SANDBOX_ROOT="${PANTHEON_SANDBOX_ROOT:-$HOME/pantheon-sandbox}"
 SANDBOX_HOME="$SANDBOX_ROOT/home"
 NPM_PREFIX="$SANDBOX_HOME/.npm-global"
 
-OPENCODE_V2_SPEC="${OPENCODE_V2_SPEC:-@opencode-ai/cli@beta}"
+OPENCODE_V2_SPEC="${OPENCODE_V2_SPEC:-@opencode/cli@latest}"
 PANTHEON_SANDBOX_MODEL="${PANTHEON_SANDBOX_MODEL:-opencode-go/mimo-v2.5}"
 PANTHEON_PROMPT_TIMEOUT="${PANTHEON_PROMPT_TIMEOUT:-300}"
 
@@ -241,11 +241,11 @@ try:
 except OSError:
     raise SystemExit(1)
 expected = {
-    "code_mode_server.py",
-    "memory_mcp_server.py",
-    "mcp_persistence_server.py",
-    "mcp_resources_server.py",
-    "pantheon_vision_server.py",
+    "code_mode.py",
+    "memory_mcp.py",
+    "mcp_persistence.py",
+    "mcp_resources.py",
+    "pantheon_vision.py",
 }
 pattern = re.compile(
     r"spawning process \{\s*"
@@ -265,7 +265,10 @@ for record in records:
     if command != python_bin or cwd != runtime_dir or script not in expected:
         raise SystemExit(1)
     registered.add(script)
-if len(records) != len(expected) or registered != expected:
+# OpenCode can initialize the same configured workspace more than once during
+# service startup and `mcp list`. Count the logical server set here; the later
+# `mcp list` assertion still requires exactly five connected MCP names.
+if registered != expected:
     raise SystemExit(1)
 PY
     then
@@ -418,6 +421,7 @@ V2_DB="${PANTHEON_V2_DB:-$SANDBOX_DIR/opencode-v2.db}"
 V2_PORT="${PANTHEON_V2_PORT:-49376}"
 V2_LOOPBACK_HOST="${PANTHEON_V2_HOST:-127.0.0.1}"
 V2_HANDSHAKE_TIMEOUT="${PANTHEON_V2_HANDSHAKE_TIMEOUT:-60}"
+V2_MCP_LIST_TIMEOUT="${PANTHEON_V2_MCP_LIST_TIMEOUT:-15}"
 V2_SERVER_LOG="$SANDBOX_DIR/v2-server.log"
 V2_SERVICE_STATE="$SANDBOX_HOME/.local/state/opencode/service.json"
 V2_SERVER_PID=""
@@ -515,11 +519,11 @@ try:
 except OSError:
     raise SystemExit(1)
 expected = {
-    "code_mode_server.py",
-    "memory_mcp_server.py",
-    "mcp_persistence_server.py",
-    "mcp_resources_server.py",
-    "pantheon_vision_server.py",
+    "code_mode.py",
+    "memory_mcp.py",
+    "mcp_persistence.py",
+    "mcp_resources.py",
+    "pantheon_vision.py",
 }
 pattern = re.compile(
     r"spawning process \{\s*"
@@ -642,11 +646,11 @@ config_path = Path(os.environ["CONFIG_PATH"])
 runtime_dir = os.environ["RUNTIME_DIR"]
 python_bin = os.environ["MCP_PYTHON"]
 managed = {
-    "pantheon-code-mode": "code_mode_server.py",
-    "pantheon-memory": "memory_mcp_server.py",
-    "pantheon-persistence": "mcp_persistence_server.py",
-    "pantheon-resources": "mcp_resources_server.py",
-    "pantheon-vision": "pantheon_vision_server.py",
+    "pantheon-code-mode": "code_mode.py",
+    "pantheon-memory": "memory_mcp.py",
+    "pantheon-persistence": "mcp_persistence.py",
+    "pantheon-resources": "mcp_resources.py",
+    "pantheon-vision": "pantheon_vision.py",
 }
 try:
     config = json.loads(config_path.read_text(encoding="utf-8"))
@@ -735,7 +739,8 @@ check_mcp() { # label binary project
   if ! wait_for_v2_mcp_registrations "$project/.opencode" "$project/.venv/bin/python3"; then
     kill "$list_pid" 2>/dev/null || true
     wait "$list_pid" 2>/dev/null || true
-    rm -f "$list_file"
+    echo "--- mcp list output (preserved at $list_file) ---" >&2
+    cat "$list_file" >&2 || true
     record_status "$label MCP" "FAIL" "MCP registrations did not match the active sandbox"
     return 0
   fi
@@ -744,7 +749,8 @@ check_mcp() { # label binary project
   else
     kill "$list_pid" 2>/dev/null || true
     wait "$list_pid" 2>/dev/null || true
-    rm -f "$list_file"
+    echo "--- mcp list output (preserved at $list_file) ---" >&2
+    cat "$list_file" >&2 || true
     record_status "$label MCP" "FAIL" "MCP handshakes did not become ready after mcp list started"
     return 0
   fi
@@ -809,6 +815,11 @@ if ! git -C "$REPO_DIR" ls-files --error-unmatch -- "$TGZ" >/dev/null 2>&1; then
 echo "--- Init (headless) ---"
 pantheon-opencode init --headless -y
 rewrite_v2_mcp_config
+node "$REPO_DIR/scripts/validate-sandbox-install.mjs" \
+  --repo "$REPO_DIR" \
+  --install "$NPM_PREFIX/lib/node_modules/pantheon-opencode" \
+  --project-config "$V2_CONFIG" \
+  --config "$PANTHEON_GLOBAL/opencode.json"
 
 echo "--- MCP Validation ---"
 check_mcp "V2" opencode2 "$SANDBOX_DIR/project-v2"
@@ -829,7 +840,7 @@ else
 fi
 
 echo "--- Gate (b): pantheon://agents CONTENT check ---"
-RESOURCES_SRV="$PANTHEON_GLOBAL/scripts/mcp_resources_server.py"
+RESOURCES_SRV="$PANTHEON_GLOBAL/scripts/mcp_resources.py"
 if [ ! -f "$RESOURCES_SRV" ]; then
   record_status "pantheon://agents resource" "FAIL" "resources server not found at $RESOURCES_SRV"
 else
@@ -871,6 +882,139 @@ fi
 echo "Next: open the isolated TUI with: $SANDBOX_DIR/start-pantheon.sh"
 RUNTEST
   chmod +x "$SANDBOX_ROOT/run-test.sh"
+
+  cat > "$SANDBOX_ROOT/start-pantheon.sh" <<'STARTPANTHEON'
+#!/usr/bin/env bash
+# Generated by pantheon-opencode scripts/test-opencode-v2-sandbox.sh --prepare
+# Launches the installed OpenCode beta with only this sandbox's HOME/config/db.
+set -euo pipefail
+
+SANDBOX_DIR="$(cd "$(dirname "$0")" && pwd)"
+SANDBOX_HOME="$SANDBOX_DIR/home"
+NPM_PREFIX="$SANDBOX_HOME/.npm-global"
+SANDBOX_VENV="$SANDBOX_HOME/.config/opencode/.venv"
+V2_PORT="${PANTHEON_V2_PORT:-49376}"
+if [[ ! "$V2_PORT" =~ ^[0-9]{1,5}$ ]]; then
+  echo "ERROR: PANTHEON_V2_PORT must be an integer from 1 through 65535 (got '$V2_PORT')" >&2
+  exit 1
+fi
+V2_PORT=$((10#$V2_PORT))
+if [ "$V2_PORT" -lt 1 ] || [ "$V2_PORT" -gt 65535 ]; then
+  echo "ERROR: PANTHEON_V2_PORT must be an integer from 1 through 65535 (got '$V2_PORT')" >&2
+  exit 1
+fi
+if ! python3 - "$V2_PORT" "$NPM_PREFIX" <<'CHECKPORT'
+import errno
+import os
+import socket
+import sys
+from urllib.request import urlopen
+
+port = int(sys.argv[1])
+cli_prefix = os.path.realpath(
+    os.path.join(sys.argv[2], "lib", "node_modules", "@opencode", "cli")
+)
+try:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        # A just-stopped service can leave a harmless TIME_WAIT socket behind.
+        # SO_REUSEADDR permits the new service to bind that port without
+        # masking a live listener or an unrelated server.
+        probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        probe.bind(("127.0.0.1", port))
+except OSError as exc:
+    if exc.errno != errno.EADDRINUSE:
+        print(f"ERROR: cannot reserve dedicated V2 port 127.0.0.1:{port}: {exc}", file=sys.stderr)
+        raise SystemExit(1)
+
+    # OpenCode intentionally keeps its managed service alive after the TUI exits.
+    # Reuse it only when /proc proves the listener is this sandbox's CLI binary.
+    inodes = set()
+    for table in ("/proc/net/tcp", "/proc/net/tcp6"):
+        try:
+            with open(table, encoding="ascii") as entries:
+                next(entries, None)
+                for line in entries:
+                    fields = line.split()
+                    if len(fields) >= 10 and int(fields[1].rsplit(":", 1)[1], 16) == port and fields[3] == "0A":
+                        inodes.add(fields[9])
+        except OSError:
+            pass
+
+    listener_pids = set()
+    for pid in (entry for entry in os.listdir("/proc") if entry.isdigit()):
+        fd_dir = f"/proc/{pid}/fd"
+        try:
+            for fd in os.listdir(fd_dir):
+                try:
+                    target = os.readlink(os.path.join(fd_dir, fd))
+                except OSError:
+                    continue
+                if target.startswith("socket:[") and target[8:-1] in inodes:
+                    listener_pids.add(pid)
+                    break
+        except OSError:
+            continue
+
+    owns_listener = False
+    for pid in listener_pids:
+        try:
+            with open(f"/proc/{pid}/cmdline", "rb") as command_line:
+                args = [arg.decode(errors="replace") for arg in command_line.read().split(b"\0") if arg]
+        except OSError:
+            continue
+        executable = os.path.realpath(args[0]) if args else ""
+        if (
+            executable.startswith(cli_prefix + os.sep)
+            and "serve" in args
+            and "--service" in args
+            and len(listener_pids) == 1
+        ):
+            owns_listener = True
+            break
+
+    healthy = False
+    if owns_listener:
+        try:
+            scheme = "http"
+            loopback = ".".join(("127", "0", "0", "1"))
+            with urlopen(f"{scheme}://{loopback}:{port}/global/health", timeout=2) as response:
+                healthy = response.status == 200
+        except Exception:
+            pass
+
+    if not healthy:
+        print(
+            f"ERROR: dedicated V2 port 127.0.0.1:{port} is occupied by a different or unverifiable service; no service was stopped",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    print(f"Reusing the existing beta sandbox OpenCode service on 127.0.0.1:{port} (PID {next(iter(listener_pids))}).")
+CHECKPORT
+then
+  exit 1
+fi
+
+export HOME="$SANDBOX_HOME"
+export PATH="$NPM_PREFIX/bin:$SANDBOX_VENV/bin:$PATH"
+export npm_config_prefix="$NPM_PREFIX"
+export XDG_CONFIG_HOME="$SANDBOX_HOME/.config"
+export XDG_CONFIG_DIRS="$SANDBOX_HOME/.config/xdg"
+export XDG_DATA_HOME="$SANDBOX_HOME/.local/share"
+export XDG_DATA_DIRS="$SANDBOX_HOME/.local/share/xdg"
+export XDG_STATE_HOME="$SANDBOX_HOME/.local/state"
+export XDG_CACHE_HOME="$SANDBOX_HOME/.cache"
+export OPENCODE_CONFIG_DIR="$SANDBOX_DIR/project-v2"
+export OPENCODE_DB="${PANTHEON_V2_DB:-$SANDBOX_DIR/opencode-v2.db}"
+export PANTHEON_V2_PORT="$V2_PORT"
+export PORT="$PANTHEON_V2_PORT"
+unset OPENCODE_CONFIG OPENCODE_CONFIG_CONTENT OPENCODE_CONFIG_PROJECT_DISABLE \
+  OPENCODE_DATA_DIR OPENCODE_STATE_DIR OPENCODE_CACHE_DIR OPENCODE_STORAGE_PATH
+
+"$NPM_PREFIX/bin/opencode2" service set port "$V2_PORT"
+cd "$SANDBOX_DIR/project-v2"
+exec "$NPM_PREFIX/bin/opencode2" "$@"
+STARTPANTHEON
+  chmod +x "$SANDBOX_ROOT/start-pantheon.sh"
 }
 
 # ── Reset / Prepare ───────────────────────────────────────────────────────────
@@ -990,6 +1134,7 @@ prepare_project() {
   (cd "$dir" && "$pan" init --project --version "$TARGET_VERSION" --model "$PANTHEON_SANDBOX_MODEL" -y) \
     || die "init --project --version $TARGET_VERSION failed in $dir"
   rewrite_v2_mcp_config
+  validate_sandbox_install
 }
 
 # The installer merges an existing project config. A reused sandbox can
@@ -1013,11 +1158,11 @@ config_path = Path(os.environ["CONFIG_PATH"])
 runtime_dir = os.environ["RUNTIME_DIR"]
 python_bin = os.environ["MCP_PYTHON"]
 managed = {
-    "pantheon-code-mode": "code_mode_server.py",
-    "pantheon-memory": "memory_mcp_server.py",
-    "pantheon-persistence": "mcp_persistence_server.py",
-    "pantheon-resources": "mcp_resources_server.py",
-    "pantheon-vision": "pantheon_vision_server.py",
+    "pantheon-code-mode": "code_mode.py",
+    "pantheon-memory": "memory_mcp.py",
+    "pantheon-persistence": "mcp_persistence.py",
+    "pantheon-resources": "mcp_resources.py",
+    "pantheon-vision": "pantheon_vision.py",
 }
 
 try:
@@ -1077,6 +1222,15 @@ for name, script in managed.items():
 PY
 }
 
+validate_sandbox_install() {
+  node "$REPO_DIR/scripts/validate-sandbox-install.mjs" \
+    --repo "$REPO_DIR" \
+    --install "$NPM_PREFIX/lib/node_modules/pantheon-opencode" \
+    --project-config "$V2_CONFIG" \
+    --config "$SANDBOX_HOME/.config/opencode/opencode.json" \
+    || die "sandbox package/config validation failed"
+}
+
 cmd_prepare() {
   mkdir -p "$SANDBOX_HOME" "$NPM_PREFIX"
   write_run_test_sh

package/scripts/validate-routing.mjs

@@ -19,7 +19,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import yaml from 'js-yaml'
+import { load } from 'js-yaml'
 import { validatePresetDefs } from '../src/pantheon/presets.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -52,7 +52,7 @@ if (!existsSync(routingPath)) {
   console.error('❌ routing.yml not found')
   process.exit(1)
 }
-const routing = yaml.load(readFileSync(routingPath, 'utf8'))
+const routing = load(readFileSync(routingPath, 'utf8'))
 
 console.log('🔍 Validating routing.yml...\n')
 
@@ -253,7 +253,7 @@ function parseFrontmatter(filePath) {
   const match = content.match(FRONTMATTER_RE)
   if (!match) return null
   try {
-    return yaml.load(match[1])
+    return load(match[1])
   } catch {
     return null
   }