pantheon-opencode 1.5.0-beta.4 → 1.5.0-beta.5

package/CHANGELOG.md

@@ -18,6 +18,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.5.0-beta.5] - 2026-09-12
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🆕 What's New
+
+- **Native background tasks in the delegation panel:** tasks dispatched via
+  the native `task(background=true)` tool are now mirrored onto the shared
+  BackgroundJobBoard, so the TUI delegation panel tracks them while running
+  and the existing finalize path writes their terminal report.
+- **`pantheon-opencode update`:** one command updates the global package
+  (beta or stable channel) and re-runs init to refresh config, venv and MCP
+  entries. The installer stamps the installed version and `doctor` warns when
+  the package is newer than the last sync.
+- **Always-fresh artifacts:** the package postinstall now refreshes all
+  copy-only artifacts (agents, skills, AGENTS.md, commands, MCP scripts,
+  code-mode payload) into existing installations on every `npm install`; a CI
+  gate rebuilds the TUI bundle and fails if the committed `dist/` is stale.
+- **More resilient installer:** preflight checks for python3/npm before any
+  file is written, atomic `opencode.json` writes with a `.bak` backup,
+  non-fatal Python runtime setup (a venv failure now omits MCP entries with a
+  warning instead of pointing at a broken interpreter), `--components` /
+  `--clean` / `--opencode-version auto` flags, unknown-flag warnings and
+  pt-BR/EN message auto-detection via `LANG`.
+- **Roadmap zerado:** o plano ativo não tem mais itens pendentes. Sprints
+  nunca implementados dos planos v1.0/v1.0+ foram removidos; o contrato atual
+  passou a documentar o code-mode (manifest SHA-256, resolução project-first).
+
+## 🐞 Fixed
+
+- **Code-mode project resolution (#112):** the MCP now resolves project code-mode
+  scripts before global scripts, honors `PANTHEON_PROJECT`, and fails closed on
+  project manifest errors; the installer sets `cwd: "."`.
+- **Code-mode manifest doctor check (#113):** `doctor` validates manifest shape,
+  script membership, and SHA-256 hashes without regenerating the manifest.
 ## [v1.5.0-beta.4] - 2026-09-11
 
 <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -30,7 +30,7 @@ way to plan work, make progress, check results, and keep useful project context.
 
 ## Start in 2 minutes
 
-Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js 18+.
+Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js 22+.
 
 From the project where you want to use Pantheon:
 
@@ -127,6 +127,14 @@ contract (`OK`, `UNSUPPORTED`, `UNAVAILABLE`, `INVALID_INPUT`, `INVALID_STATE`,
 `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`, `ESCALATE`); with `json_output=true`,
 results carry a `status` field.
 
+Code-mode resolves project-first: `.opencode/.pantheon/code-mode` is preferred,
+then `.pantheon/code-mode`. `PANTHEON_PROJECT` overrides the working directory,
+and the installed MCP uses `cwd: "."` so OpenCode supplies the workspace. A
+global directory is used only when no usable project directory is available;
+once a project directory is selected, a missing or corrupt manifest fails
+closed instead of falling back. `doctor` validates the manifest and every
+script's SHA-256 without regenerating it.
+
 
 ## What's new in 1.5.0-beta.2
 
@@ -205,6 +213,36 @@ The installer still writes the compatibility settings required by the selected
 OpenCode host, such as `experimental.subagent_depth`; this does not convert a
 V1 plugin into V2 or provide V2 with V1 hooks.
 
+## Updating between releases (beta.5+)
+
+One command keeps an existing installation current:
+
+```bash
+npx pantheon-opencode update            # npm beta channel + config refresh
+npx pantheon-opencode update --stable   # stable channel instead
+```
+
+`update` compares your installed version with the npm dist-tag, runs
+`npm install -g pantheon-opencode@<channel>`, then re-runs `init --yes
+--headless` so config merges, the venv and MCP entries match the new package.
+Two freshness guarantees back it up:
+
+- **Postinstall artifact sync** — after any `npm install`, copy-only artifacts
+  (agents, skills, AGENTS.md, commands, MCP scripts, code-mode payload) are
+  refreshed into the existing config dir automatically; you never have to
+  re-run `init` just for file copies.
+- **Drift detection** — the installer stamps the installed version in
+  `.pantheon/install-state.json` and `doctor` warns when the package is newer
+  than the last sync, pointing at `update`.
+
+`init` also gained `--components agents,skills,...` (narrow install),
+`--clean` (alias of `--force`), `--opencode-version auto`, atomic config
+writes with an `opencode.json.bak` backup, preflight checks for python3/npm
+before any file is written, and a non-fatal Python runtime: if the venv fails,
+the install completes but MCP entries are omitted (with a warning) instead of
+pointing at a broken interpreter. Installer messages auto-detect pt-BR via
+`LANG`/`LC_ALL`.
+
 ## Releases
 
 Publication is authorized **only** by an explicit `workflow_dispatch` of the

package/README.pt-BR.md

@@ -94,6 +94,14 @@ seguem o contrato de nove códigos (`OK`, `UNSUPPORTED`, `UNAVAILABLE`,
 `INVALID_INPUT`, `INVALID_STATE`, `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`,
 `ESCALATE`) e, com `json_output=true`, incluem o campo `status`.
 
+O code-mode resolve primeiro o projeto: `.opencode/.pantheon/code-mode` vem
+antes de `.pantheon/code-mode`. `PANTHEON_PROJECT` sobrescreve o diretório de
+trabalho, e o MCP instalado usa `cwd: "."` para receber o workspace do
+OpenCode. O diretório global só é usado sem um diretório de projeto utilizável;
+depois de selecionar um diretório de projeto, manifest ausente ou corrompido
+falha fechado, sem fallback silencioso. O `doctor` valida o manifest e o
+SHA-256 de cada script sem regenerá-lo.
+
 
 ## Novidades da 1.5.0-beta.2
 
@@ -171,6 +179,35 @@ O instalador continua gravando as configurações de compatibilidade exigidas
 pelo host OpenCode selecionado, como `experimental.subagent_depth`; isso não
 converte um plugin V1 em V2 nem dá hooks V1 ao V2.
 
+## Atualizando entre releases (beta.5+)
+
+Um comando mantém uma instalação existente em dia:
+
+```bash
+npx pantheon-opencode update            # canal beta do npm + refresh do config
+npx pantheon-opencode update --stable   # canal estável
+```
+
+O `update` compara a versão instalada com o dist-tag do npm, roda
+`npm install -g pantheon-opencode@<canal>` e re-executa `init --yes
+--headless` para alinhar merge de config, venv e entradas de MCP com o novo
+pacote. Duas garantias de freshness sustentam isso:
+
+- **Sync de artifacts no postinstall** — depois de qualquer `npm install`, os
+  artefatos de cópia (agents, skills, AGENTS.md, commands, scripts MCP,
+  payload code-mode) são atualizados automaticamente no config dir existente;
+  você nunca precisa re-rodar `init` só para atualizar arquivos.
+- **Detecção de drift** — o instalador grava a versão instalada em
+  `.pantheon/install-state.json` e o `doctor` avisa quando o pacote é mais
+  novo que o último sync, apontando para o `update`.
+
+O `init` também ganhou `--components agents,skills,...` (instalação enxuta),
+`--clean` (alias de `--force`), `--opencode-version auto`, escrita atômica do
+config com backup em `opencode.json.bak`, pré-checagens de python3/npm antes
+de escrever qualquer arquivo e runtime Python não-fatal: se a venv falha, a
+instalação completa mas as entradas MCP ficam de fora (com aviso) em vez de
+apontar para um interpretador quebrado.
+
 ## Releases
 
 A publicação é autorizada **somente** por um `workflow_dispatch` explícito do

package/bin/pantheon-init.mjs

@@ -22,9 +22,10 @@ import { fileURLToPath } from 'node:url'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ROOT = path.resolve(__dirname, '..')
 
-const REQUIRED_NODE_MAJOR = 18
+const REQUIRED_NODE_MAJOR = 22
 if (parseInt(process.versions.node.split('.')[0], 10) < REQUIRED_NODE_MAJOR) {
   console.error(`❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`)
+  console.error('   Install a newer Node via nvm: https://github.com/nvm-sh/nvm')
   process.exit(1)
 }
 
@@ -50,9 +51,13 @@ function printUsage() {
   console.log('  npx pantheon-opencode init --interactive  # Force interactive TUI mode')
   console.log('  npx pantheon-opencode init --headless     # Force non-interactive mode')
   console.log('  npx pantheon-opencode init -y             # Skip confirmations, use defaults')
+  console.log('  npx pantheon-opencode init --components agents,skills,instructions')
   console.log('  npx pantheon-opencode init --opencode-version v1|v2|auto')
   console.log('  npx pantheon-opencode init --preset <name> # Install and activate model preset')
   console.log('  npx pantheon-opencode set-tier <name>      # Set active model preset (global)')
+  console.log(
+    '  npx pantheon-opencode update [--stable]    # Update package + re-run init (default: beta channel)',
+  )
   console.log(
     '  npx pantheon-opencode set-tier <name> --project  # Set active model preset (project)',
   )
@@ -112,6 +117,78 @@ async function main() {
     process.exit(result.status ?? 1)
   }
 
+  // beta.5: one-command update — check npm dist-tag, install, re-init.
+  // Default channel is `beta` (the prerelease line); `--stable` uses `latest`.
+  if (command === 'update') {
+    const channel = args.includes('--stable') ? 'latest' : 'beta'
+    const current = readVersion()
+    const { spawnSync } = await import('node:child_process')
+    const _S = (await import('../scripts/install/strings.mjs')).strings()
+
+    console.log(`Pantheon OpenCode v${current} — checking the "${channel}" channel...`)
+    const view = spawnSync('npm', ['view', `pantheon-opencode@${channel}`, 'version'], {
+      encoding: 'utf8',
+      timeout: 30_000,
+    })
+    const latest = (view.stdout || '').trim().split('\n').filter(Boolean).pop()
+    if (view.status !== 0 || !latest) {
+      console.error(
+        `❌ Could not reach the npm registry: ${(view.stderr || view.stdout || '').trim() || 'no version returned'}`,
+      )
+      process.exit(1)
+    }
+
+    // Prerelease-aware compare: core (major.minor.patch) first, then the
+    // beta counter; a stable release outranks any beta of the same core.
+    const parsePantheonVersion = (v) => {
+      const m = String(v)
+        .trim()
+        .match(/^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/)
+      if (!m) return null
+      return {
+        core: [+m[1], +m[2], +m[3]],
+        beta: m[4] === undefined ? Number.POSITIVE_INFINITY : +m[4],
+      }
+    }
+    const cmp = (a, b) => {
+      const pa = parsePantheonVersion(a)
+      const pb = parsePantheonVersion(b)
+      if (!pa || !pb) return 0
+      for (let i = 0; i < 3; i++) {
+        if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i]
+      }
+      return pa.beta - pb.beta
+    }
+    if (cmp(latest, current) <= 0) {
+      console.log(`✅ Already up to date (installed v${current}; ${channel} channel: v${latest}).`)
+      return
+    }
+
+    console.log(`Updating v${current} → v${latest} (channel: ${channel})...`)
+    const install = spawnSync('npm', ['install', '-g', `pantheon-opencode@${channel}`], {
+      stdio: 'inherit',
+    })
+    if (install.status !== 0) {
+      console.error('❌ npm install failed — the previous installation is untouched.')
+      process.exit(install.status ?? 1)
+    }
+
+    // Refresh config/venv/MCP entries with the NEW package (resolved via
+    // PATH — the freshly installed global bin).
+    const init = spawnSync('pantheon-opencode', ['init', '--yes', '--headless'], {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    })
+    if (init.status !== 0 || init.error) {
+      console.error(
+        '⚠️  Updated, but the config refresh did not complete — run `npx pantheon-opencode init` manually.',
+      )
+      process.exit(init.status ?? 1)
+    }
+    console.log(`✅ Updated to v${latest}.`)
+    return
+  }
+
   if (args.includes('--help')) {
     printUsage()
     process.exit(0)
@@ -195,11 +272,49 @@ async function main() {
     const isProject = args.includes('--project')
     const isDryRun = args.includes('--dry-run')
     const skipMCP = args.includes('--no-mcp')
-    const forceReinstall = args.includes('--force')
+    // --clean is an alias of --force (both wipe component dirs + recreate venv).
+    const forceReinstall = args.includes('--force') || args.includes('--clean')
     const runDoctor = args.includes('--doctor')
     const forceInteractive = args.includes('--interactive')
     const forceHeadless = args.includes('--headless')
     const autoYes = args.includes('--yes') || args.includes('-y')
+
+    // beta.5: warn on unrecognized flags instead of silently ignoring them.
+    const VALUE_FLAGS = new Set([
+      '--preset',
+      '--model',
+      '--small-model',
+      '--version',
+      '--opencode-version',
+      '--components',
+    ])
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i]
+      if (!arg.startsWith('--') || arg === '--help') continue
+      if (VALUE_FLAGS.has(arg)) {
+        i++ // skip the flag's value
+        continue
+      }
+      const bare = arg.split('=', 1)[0]
+      if (
+        !VALUE_FLAGS.has(bare) &&
+        ![
+          '--project',
+          '--dry-run',
+          '--no-mcp',
+          '--force',
+          '--clean',
+          '--doctor',
+          '--interactive',
+          '--headless',
+          '--yes',
+          '-y',
+        ].includes(bare)
+      ) {
+        console.error(`⚠️  Unknown option ignored: ${arg}`)
+      }
+    }
+
     const presetIndex = args.indexOf('--preset')
     const presetOpt = presetIndex >= 0 ? (args[presetIndex + 1] ?? null) : null
     // Explicit top-level model overrides for the generated config.
@@ -207,8 +322,9 @@ async function main() {
     const modelOpt = modelIndex >= 0 ? (args[modelIndex + 1] ?? null) : null
     const smallModelIndex = args.indexOf('--small-model')
     const smallModelOpt = smallModelIndex >= 0 ? (args[smallModelIndex + 1] ?? null) : null
-    // --version v1|v2 labels the install target (informational; the config is
-    // shared and V1-shaped under both versions). Invalid values fail fast.
+    // --version v1|v2|auto labels the install target. `auto` resolves the
+    // generation from the opencode binary at install time (see
+    // scripts/install/opencode-version.mjs). Invalid values fail fast.
     const versionIndex = args.indexOf('--version')
     const legacyVersionIndex = args.indexOf('--opencode-version')
     const inlineVersion = args.find((arg) => arg.startsWith('--opencode-version='))
@@ -218,20 +334,61 @@ async function main() {
         : legacyVersionIndex >= 0
           ? (args[legacyVersionIndex + 1] ?? null)
           : (inlineVersion?.split('=', 2)[1] ?? null)
-    if (versionOpt !== null && versionOpt !== 'v1' && versionOpt !== 'v2') {
-      console.error(`❌ Invalid --version "${versionOpt}" — expected v1 or v2`)
+    if (
+      versionOpt !== null &&
+      versionOpt !== 'v1' &&
+      versionOpt !== 'v2' &&
+      versionOpt !== 'auto'
+    ) {
+      console.error(`❌ Invalid --version "${versionOpt}" — expected v1, v2 or auto`)
       process.exit(1)
     }
 
-    const components = ['agents', 'skills', 'instructions', 'commands', 'plugins']
-    if (!skipMCP) components.push('runtime')
+    // --components agents,skills,... narrows the install; --no-mcp drops the
+    // runtime component. Unknown component names fail fast (typo protection).
+    const KNOWN_COMPONENTS = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime']
+    const componentsIndex = args.indexOf('--components')
+    const inlineComponents = args.find((arg) => arg.startsWith('--components='))
+    const componentsOpt =
+      componentsIndex >= 0
+        ? (args[componentsIndex + 1] ?? null)
+        : (inlineComponents?.split('=', 2)[1] ?? null)
+    let requestedComponents = null
+    if (componentsOpt !== null) {
+      requestedComponents = componentsOpt
+        .split(',')
+        .map((c) => c.trim())
+        .filter(Boolean)
+      const unknown = requestedComponents.filter((c) => !KNOWN_COMPONENTS.includes(c))
+      if (requestedComponents.length === 0 || unknown.length > 0) {
+        console.error(
+          `❌ Invalid --components "${componentsOpt}" — expected comma-separated names from: ${KNOWN_COMPONENTS.join(', ')}`,
+        )
+        process.exit(1)
+      }
+    }
+
+    const components = requestedComponents ?? [
+      'agents',
+      'skills',
+      'instructions',
+      'commands',
+      'plugins',
+    ]
+    if (!skipMCP && !components.includes('runtime')) components.push('runtime')
+    if (skipMCP) {
+      const runtimeIndex = components.indexOf('runtime')
+      if (runtimeIndex >= 0) components.splice(runtimeIndex, 1)
+    }
 
     // Version info
     const version = readVersion()
+    const { strings } = await import('../scripts/install/strings.mjs')
+    const S = strings()
 
     console.log('')
     if (!forceInteractive || isDryRun) {
-      console.log(`Pantheon OpenCode v${version} — ${isDryRun ? 'DRY RUN' : 'Installing...'}`)
+      console.log(`Pantheon OpenCode v${version} — ${isDryRun ? S.dryRun : S.installing}`)
       console.log('')
     }
 
@@ -248,15 +405,17 @@ async function main() {
         version: versionOpt ?? 'v1',
       })
     } catch (err) {
-      console.error(
-        `❌ Installation failed: ${err.message}\n   Run with --no-mcp to skip Python dependencies:\n     npx pantheon-opencode init --no-mcp\n   Or retry with --force to recreate the venv:\n     npx pantheon-opencode init --force`,
-      )
+      if (err?.message === 'Canceled') {
+        console.error(S.canceled)
+        process.exit(130)
+      }
+      console.error(`${S.installFailed(err.message)}\n${S.failHintNoMcp}\n${S.failHintForce}`)
       process.exit(1)
     }
 
     if (runDoctor && !isDryRun) {
       console.log('')
-      console.log('  Running health check...')
+      console.log(`  ${S.runningHealthCheck}`)
       try {
         const { spawnSync } = await import('node:child_process')
         const doctorScript = path.join(ROOT, 'scripts', 'doctor.mjs')
@@ -268,16 +427,14 @@ async function main() {
 
     console.log('')
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
-    console.log(`  ✅ Pantheon OpenCode v${version} installed!`)
+    console.log(`  ${S.installedTitle(version)}`)
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
     console.log('')
-    console.log('  Next steps:')
-    console.log('  1. Verify installation:')
-    console.log('     npx pantheon-opencode doctor')
-    console.log('  2. Launch OpenCode')
-    console.log('  3. Invoke agents with @agent-name in chat')
-    console.log('  4. For project-local install:')
-    console.log('     npx pantheon-opencode init --project')
+    console.log(`  ${S.nextSteps}`)
+    console.log(`  ${S.nextVerify}`)
+    console.log(`  ${S.nextLaunch}`)
+    console.log(`  ${S.nextAgents}`)
+    console.log(`  ${S.nextProject}`)
     console.log('')
 
     return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.5.0-beta.4",
+  "version": "1.5.0-beta.5",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "publishConfig": {
@@ -32,15 +32,15 @@
     "package:evidence": "node scripts/package-evidence.mjs",
     "package:validate": "node scripts/validate-package.mjs",
     "publish:next": "npm publish --tag next --access public",
-    "lint": "npx biome ci .",
-    "typecheck": "npx tsc --noEmit",
+    "lint": "biome ci .",
+    "typecheck": "tsc --noEmit",
     "audit": "npm audit --audit-level=high",
     "secret-scan": "node scripts/secret-scan.mjs",
     "hooks:install": "pre-commit install",
     "hooks:update": "pre-commit autoupdate",
-    "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs && node tests/test_doctor_layers.mjs",
+    "test:security": "npm run secret-scan",
     "test:node": "node --test tests/*.mjs tests/pantheon/*.mjs",
-    "test:ts": "for f in tests/pantheon/*.test.ts; do if [ \"$f\" = tests/pantheon/plugin-v2-contract.test.ts ]; then NODE_OPTIONS=--conditions=import npx tsx \"$f\"; else npx tsx \"$f\"; fi || exit 1; done",
+    "test:ts": "for f in tests/pantheon/*.test.ts; do if [ \"$f\" = tests/pantheon/plugin-v2-contract.test.ts ]; then NODE_OPTIONS=--conditions=import tsx \"$f\"; else tsx \"$f\"; fi || exit 1; done",
     "test": "python3 -m pytest tests/ -q 2>&1; status=$?; if [ \"$status\" -eq 5 ]; then echo \"No tests found\"; fi; exit \"$status\"",
     "test:ci": "python3 -m pytest tests/ -q --tb=short 2>&1"
   },
@@ -88,14 +88,17 @@
     "!**/*.pyc"
   ],
   "dependencies": {
-    "@opencode-ai/plugin": "1.18.18",
+    "@opencode-ai/plugin": "1.18.30",
     "js-yaml": "^4.3.2",
     "zod": "4.1.8"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.8.0",
-    "@commitlint/config-conventional": "^19.8.0",
-    "husky": "^9.1.7"
+    "@biomejs/biome": "2.5.13",
+    "@commitlint/cli": "21.2.2",
+    "@commitlint/config-conventional": "21.2.2",
+    "husky": "^9.1.7",
+    "tsx": "4.23.13",
+    "typescript": "6.0.3"
   },
   "repository": {
     "type": "git",
@@ -116,7 +119,7 @@
   "author": "ils15",
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "preferGlobal": true
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.5.0-beta.4",
+  "version": "1.5.0-beta.5",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.5.0-beta.4"
+version = "1.5.0-beta.5"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []

package/scripts/code_mode_server.py

@@ -157,12 +157,9 @@ def _detect_prlimit() -> str | None:
 
 
 # ── Scripts Directory Resolution ─────────────────────────────────────────────
-# Priority:
-# 1. /.opencode/.pantheon/code-mode/  (project install)
-# 2. /.pantheon/code-mode/            (legacy fallback)
-# 3. /.pantheon/code-mode/               (global fallback)
-# 4. .pantheon/code-mode/ shipped inside the installed package (tarball
-#    fallback — package.json `files` includes .pantheon/code-mode/**)
+# Project directories are selected before global directories.  Once a usable
+# project directory is selected, manifest errors are deliberately fail-closed;
+# execution must never silently cross the project/global trust boundary.
 
 
 def _is_within(path: Path, root: Path) -> bool:
@@ -229,25 +226,38 @@ def _packaged_scripts_dir() -> Path | None:
     return None
 
 
-def _resolve_scripts_dir(candidates: list[Path]) -> Path | None:
-    """Select the first usable candidate, then try the packaged fallback."""
+def _resolve_scripts_dir(candidates: list[Path], *, allow_packaged: bool = True) -> Path | None:
+    """Select the first usable candidate, optionally trying the package copy."""
     for candidate in candidates:
         if _has_usable_scripts(candidate):
             return candidate
-    return _packaged_scripts_dir()
+    return _packaged_scripts_dir() if allow_packaged else None
+
+
+def _resolve_code_mode_dir() -> Path:
+    """Resolve code-mode scripts project-first, with a global-only fallback.
+
+    A project directory is a trust boundary: if one is selected, callers use
+    its manifest even when that manifest is missing or corrupt.  Global users
+    retain the packaged/global fallback when no usable project directory is
+    available.
+    """
+    project = pantheon_project()
+    if project is not None:
+        project_candidates = [
+            project / ".opencode" / ".pantheon" / "code-mode",
+            project / ".pantheon" / "code-mode",
+        ]
+        selected = _resolve_scripts_dir(project_candidates, allow_packaged=False)
+        if selected is not None:
+            return selected
+
+    global_dir = pantheon_home() / ".pantheon" / "code-mode"
+    return _resolve_scripts_dir([global_dir]) or global_dir
 
 
 _PANTHEON_HOME: Path = pantheon_home()
-_SCRIPTS_DIR_CANDIDATES: list[Path] = []
-_proj = pantheon_project()
-if _proj is not None:
-    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".opencode" / ".pantheon" / "code-mode")
-    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".pantheon" / "code-mode")
-_SCRIPTS_DIR_CANDIDATES.append(_PANTHEON_HOME / ".pantheon" / "code-mode")
-
-SCRIPTS_DIR: Path = _resolve_scripts_dir(_SCRIPTS_DIR_CANDIDATES) or (
-    _PANTHEON_HOME / ".pantheon" / "code-mode"
-)
+SCRIPTS_DIR: Path = _resolve_code_mode_dir()
 
 # ── FastMCP App ───────────────────────────────────────────────────────────────
 mcp = FastMCP(
@@ -371,6 +381,11 @@ def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
             "CORRUPT_DATA", "Code-mode manifest must be a JSON object."
         )
 
+    if data.get("version") != 1:
+        raise ManifestError(
+            "CORRUPT_DATA", "Code-mode manifest malformed: version must be 1."
+        )
+
     scripts = data.get("scripts")
     if not isinstance(scripts, dict):
         raise ManifestError(
@@ -384,6 +399,7 @@ def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
             not isinstance(name, str)
             or not isinstance(digest, str)
             or len(digest) != _SHA256_HEX_LEN
+            or any(char not in "0123456789abcdefABCDEF" for char in digest)
         ):
             raise ManifestError(
                 "CORRUPT_DATA",
@@ -877,4 +893,3 @@ def _cli() -> int:
 
 if __name__ == "__main__":
     raise SystemExit(_cli())
-