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

package/README.md

@@ -183,6 +183,39 @@ export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 opencode
 ```
 
+### OpenCode V1/V2 — Dual Version
+
+Pantheon's shared config is **V1-shaped and valid under both OpenCode versions**:
+
+| | V1 | V2 (beta) |
+|---|---|---|
+| Binary | `opencode` (1.18.18) | `opencode2` (v0.0.0-next-17444) |
+| Config locations | `~/.config/opencode/`, `<project>/opencode.json`, `.opencode/` | Same — V2 reads the same locations |
+| Config handling | Loads V1 shape directly | Normalizes V1 fields **in memory** — no rewrite, no native V2 conversion |
+| State DB | `~/.local/share/opencode/opencode.db` | `~/.local/share/opencode/opencode-v2.db` (isolated via `OPENCODE_DB`) |
+| Service port | 49374 | 49375 (must differ from V1) |
+
+The `pantheon_cost` report preserves the V1 database default. Set
+`PANTHEON_OPENCODE_VERSION=v1` or `v2` to select the corresponding state DB
+explicitly (`opencode.db` or `opencode-v2.db`). For custom installations,
+`PANTHEON_COST_DB=/absolute/path/to/opencode.db` takes precedence over the
+version selector; an explicit `dbPath` supplied by the tool caller takes
+precedence over both. The resolver never probes the other version's database,
+and reports an actionable error when the selected DB is missing or has an
+incompatible schema.
+
+**What changed for V2 compatibility (Phase 3):**
+
+- `subagent_depth` moved from top-level to `experimental.subagent_depth` — V2 silently ignores the top-level key. The installer migrates existing configs automatically.
+- Instruction content consolidated into `AGENTS.md` (generated by `scripts/build-agents-md.mjs` from `src/instructions/*.instructions.md`) — V2 accepts but does **not** load the `instructions` config key; both versions auto-load `AGENTS.md`.
+- `npx pantheon-opencode init --version v2` labels an install for V2 (informational — the config is shared).
+
+**Known V2 beta gaps:**
+
+- `instructions` config key accepted but not loaded → content lives in `AGENTS.md`.
+- `formatter` / `lsp` config not executed.
+- `--subtask` delegation flag is a no-op.
+
 ### Background Delegation
 
 Zeus (and other root sessions) can dispatch agents as **background child sessions**
@@ -853,9 +886,15 @@ to Mnemosyne so counts stay accurate and consistent.
 
 ### What CI enforces automatically
 
-`release.yml` validates version consistency across all manifests (`package.json`,
-`plugin.json`, `CHANGELOG.md`, and the README badge) before publishing. If they diverge,
-the release is blocked until Mnemosyne reconciles them.
+`release.yml` validates version consistency across the package manifests
+(`package.json`, `plugin.json`, `pyproject.toml`, and the TUI package) before
+publishing. If they diverge, the release is blocked until they are reconciled.
+
+Beta releases are calculated from npm's published `latest` at workflow runtime:
+the default is the next patch, formatted as
+`<next-stable>-beta.<PR>.<short-sha>`. Labels `release:beta:minor` and
+`release:beta:major` request minor or major calculation. The workflow owns the
+manifest update, tag, and publish; it does not assume a fixed future version.
 
 ### Anti-patterns
 

package/bin/pantheon-init.mjs

@@ -6,6 +6,13 @@
  *
  * Thin CLI wrapper that parses arguments and delegates to
  * installOpenCode() from scripts/install/opencode.mjs.
+ *
+ * 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 — no native V2 conversion. `--version v2` labels the
+ * install for the operator; state isolation is a runtime concern
+ * (OPENCODE_DB ~/.local/share/opencode/opencode-v2.db, service port 49375).
  */
 import fs from 'fs'
 import os from 'os'
@@ -43,6 +50,7 @@ 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 --version v2    # Label install for OpenCode V2 (beta)')
   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(
@@ -182,6 +190,14 @@ async function main() {
     const autoYes = args.includes('--yes') || args.includes('-y')
     const presetIndex = args.indexOf('--preset')
     const presetOpt = presetIndex >= 0 ? (args[presetIndex + 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.
+    const versionIndex = args.indexOf('--version')
+    const versionOpt = versionIndex >= 0 ? (args[versionIndex + 1] ?? null) : null
+    if (versionOpt !== null && versionOpt !== 'v1' && versionOpt !== 'v2') {
+      console.error(`❌ Invalid --version "${versionOpt}" — expected v1 or v2`)
+      process.exit(1)
+    }
 
     const components = ['agents', 'skills', 'instructions', 'commands', 'plugins']
     if (!skipMCP) components.push('runtime')
@@ -203,6 +219,7 @@ async function main() {
         headless: forceHeadless,
         yes: autoYes,
         preset: presetOpt,
+        version: versionOpt ?? 'v1',
       })
     } catch (err) {
       console.error(

package/opencode.json

@@ -11,7 +11,9 @@
     }
   },
   "default_agent": "zeus",
-  "subagent_depth": 2,
+  "experimental": {
+    "subagent_depth": 2
+  },
   "model": "opencode-go/deepseek-v4-flash",
   "small_model": "opencode-go/deepseek-v4-flash",
   "permission": {
@@ -28,7 +30,6 @@
       "pip *": "allow"
     }
   },
-  "instructions": ["AGENTS.md", "src/instructions/*.instructions.md"],
   "mcp": {
     "bifrost": {
       "type": "remote",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.3.4",
+  "version": "1.3.5-beta.52.c75b04d",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
@@ -10,6 +10,7 @@
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "husky",
     "setup": "node bin/pantheon-init.mjs init",
+    "build:agents-md": "node scripts/build-agents-md.mjs",
     "setup:lite": "node bin/pantheon-init.mjs init --clean --components agents,skills,instructions",
     "doctor": "node scripts/doctor.mjs",
     "prune": "node scripts/prune.mjs",

package/scripts/build-agents-md.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * build-agents-md.mjs — Generate the repo AGENTS.md from canonical sources.
+ *
+ * AGENTS.md is the single instruction file BOTH OpenCode V1 and V2 load
+ * (V1 auto-discovers it, V2 loads it explicitly; the `instructions` config
+ * key is accepted-but-ignored by V2). To keep instruction content in parity
+ * across both versions without duplication, this script consolidates:
+ *
+ *   (a) a static header (project description + agent table + setup notes)
+ *   (b) every src/instructions/*.instructions.md body, embedded under a
+ *       `## <name>` section marker (name taken from frontmatter)
+ *
+ * into one generated AGENTS.md. src/instructions/*.instructions.md remains
+ * the source of truth — AGENTS.md is a committed build artifact, never
+ * hand-edited.
+ *
+ * Usage:
+ *   node scripts/build-agents-md.mjs            # write AGENTS.md to repo root
+ *   node scripts/build-agents-md.mjs --check    # exit 1 if AGENTS.md is stale
+ *
+ * No runtime dependencies (Node >= 18, stdlib only). Idempotent: running it
+ * twice produces byte-identical output.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const ROOT = join(__dirname, '..')
+const INSTRUCTIONS_DIR = join(ROOT, 'src', 'instructions')
+const AGENTS_MD_PATH = join(ROOT, 'AGENTS.md')
+
+// ---------------------------------------------------------------------------
+// Static header — preserved verbatim from the original AGENTS.md (agent table,
+// setup notes, sandbox rules, conventions). Backticks are escaped for the
+// template literal.
+// ---------------------------------------------------------------------------
+const STATIC_HEADER = `# Pantheon Agent System — OpenCode
+
+This project uses the Pantheon multi-agent framework with 14 specialized agents.
+
+## Available Agents
+
+| Agent | Role |
+|-------|------|
+| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Calls apollo for discovery, sends to themis for review. |
+| @apollo | Read-only investigation scout — 3–10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands. |
+| @athena | Strategic planner & architect — research-first, plan-only, never implements. Plans include quality gates (ruff/Biome, dep detection, LTS policy). Calls apollo for discovery. |
+| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Calls apollo for discovery, sends to themis. |
+| @gaia | Remote sensing domain specialist — satellite image processing, spectral analysis, SAR, change detection, time series, ML/DL classification. Read-only analysis of geospatial data. |
+| @hephaestus | AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Calls apollo, sends to themis. |
+| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Calls apollo for discovery, sends to themis. |
+| @iris | GitHub operations specialist — branches, pull requests, issues, releases, tags. Called by zeus after review. Never pushes or merges without explicit human approval. Integrates with VS Code GitHub Pull Requests extension. |
+| @mnemosyne | Memory bank quality owner — initializes .pantheon/memory-bank/, writes ADRs and task records on explicit request. Called by zeus. Never invoked automatically after phases. |
+| @nyx | Observability & monitoring specialist — OpenTelemetry tracing, token/cost tracking, agent performance analytics, LangSmith integration. Calls apollo for discovery, sends to themis. |
+| @prometheus | Infrastructure + model provider specialist — Docker, CI/CD, multi-model routing, cost optimization, provider abstraction |
+| @talos | Hotfix express lane — direct fixes for small bugs, CSS, typos, minor logic. No TDD ceremony, no orchestration overhead. Standalone, no subagents. Escalates complex issues to zeus. |
+| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, coverage >80%, correctness, deprecation audit. Called by implementers; escalates blockers to zeus. |
+| @zeus | Central orchestrator — never implements. Delegates to: athena, apollo, hermes, aphrodite, demeter, prometheus, themis, iris, mnemosyne, talos, hephaestus, nyx |
+
+## OpenCode Setup
+
+See [INSTALLATION.md](docs/INSTALLATION.md) for setup instructions.
+
+- Build: \`npm test\`
+- Test: \`npm test\`
+- Lint: \`npm run lint\`
+
+## Teste de Instalação Global (sandbox)
+
+Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO REAL, use o sandbox isolado em \`~/pantheon-sandbox/\` (fora do repo, HOME + prefix npm + venv próprios). O ambiente de dev mistura 3 instalações + config global + venv — NÃO serve para testar instalação/empacotamento.
+
+- Rodar: \`bash ~/pantheon-sandbox/run-test.sh\` (opencode mcp list 5/5 connected + doctor 0 erros + abre TUI isolado)
+- Regra para agentes: ao validar instalação global (npm pack, \`init\`, MCPs, hooks), usar o sandbox — NUNCA testar no ambiente de dev
+- Descarte: \`rm -rf ~/pantheon-sandbox\`
+- Detalhes: ver \`~/pantheon-sandbox/README.md\`
+
+## Conventions
+
+- TDD: Write failing test first, then implement
+- Coverage minimum: 80%
+- Async/await on all I/O
+- Type hints on all functions
+- PRs always update the README — every pull request must document newly added features, behaviors, env vars, or commands in the README before being opened.
+`
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing (stdlib only — no yaml dependency)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML-ish frontmatter from an instruction file.
+ *
+ * Only the `name` field is extracted (single-line scalar). The frontmatter
+ * block itself is stripped from the embedded body.
+ *
+ * @param {string} content - Raw file content
+ * @returns {{ name: string, body: string } | null}
+ */
+function parseInstruction(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (!match) return null
+  const fm = match[1]
+  const nameMatch = fm.match(/^name:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  if (!nameMatch) return null
+  return {
+    name: nameMatch[1].trim(),
+    body: content.slice(match[0].length).trimEnd() + '\n',
+  }
+}
+
+/**
+ * Read all src/instructions/*.instructions.md files, sorted by filename for
+ * deterministic output.
+ *
+ * @returns {Array<{ file: string, name: string, body: string }>}
+ */
+export function readInstructions() {
+  if (!existsSync(INSTRUCTIONS_DIR)) return []
+  const files = readdirSync(INSTRUCTIONS_DIR)
+    .filter((f) => f.endsWith('.instructions.md'))
+    .sort()
+  const out = []
+  for (const file of files) {
+    const content = readFileSync(join(INSTRUCTIONS_DIR, file), 'utf8')
+    const parsed = parseInstruction(content)
+    if (parsed) out.push({ file, ...parsed })
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate the full AGENTS.md content.
+ *
+ * @param {Array<{ file: string, name: string, body: string }>} instructions
+ * @returns {string}
+ */
+export function generateAgentsMd(instructions) {
+  const sections = [
+    '<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->',
+    '<!-- Source of truth: src/instructions/*.instructions.md (AGENTS.md is a committed build artifact). -->',
+    '',
+    STATIC_HEADER.trimEnd(),
+    '',
+    '---',
+    '',
+    '# Agent Instructions',
+    '',
+    'The following sections are consolidated from `src/instructions/*.instructions.md`',
+    'so both OpenCode V1 (auto-loads AGENTS.md) and V2 (loads AGENTS.md, ignores the',
+    '`instructions` config key) receive identical instruction content.',
+    '',
+  ]
+  for (const instr of instructions) {
+    sections.push(
+      `<!-- Source: src/instructions/${instr.file} -->`,
+      `## ${instr.name}`,
+      '',
+      instr.body.trimEnd(),
+      '',
+    )
+  }
+  return sections.join('\n').trimEnd() + '\n'
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+function main() {
+  const checkOnly = process.argv.includes('--check')
+  const instructions = readInstructions()
+  const content = generateAgentsMd(instructions)
+
+  if (checkOnly) {
+    const existing = existsSync(AGENTS_MD_PATH) ? readFileSync(AGENTS_MD_PATH, 'utf8') : ''
+    if (existing !== content) {
+      console.error(`❌ AGENTS.md is stale — run: node scripts/build-agents-md.mjs`)
+      process.exit(1)
+    }
+    console.log(`✅ AGENTS.md is up to date (${instructions.length} instruction sections)`)
+    return
+  }
+
+  writeFileSync(AGENTS_MD_PATH, content, 'utf8')
+  const lines = content.split('\n').length
+  console.log(`✅ Generated AGENTS.md (${instructions.length} instruction sections, ${lines} lines)`)
+}
+
+main()

package/scripts/cost.mjs

@@ -26,6 +26,22 @@ function fail(message) {
   process.exitCode = 1
 }
 
+function assertCompatibleSchema(db) {
+  const table = db
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'message'")
+    .get()
+  if (!table)
+    throw new Error('incompatible opencode.db schema: required "message" table is missing')
+  const columns = db.prepare('PRAGMA table_info(message)').all()
+  const names = new Set(columns.map((column) => column.name))
+  const missing = ['data', 'time_created'].filter((name) => !names.has(name))
+  if (missing.length > 0) {
+    throw new Error(
+      `incompatible opencode.db schema: message table is missing ${missing.join(', ')}; select the matching V1/V2 database`,
+    )
+  }
+}
+
 function main() {
   const [, , dbPath, daysArg] = process.argv
   const days = Number(daysArg ?? '7')
@@ -35,6 +51,7 @@ function main() {
 
   try {
     const db = new DatabaseSync(dbPath, { readOnly: true })
+    assertCompatibleSchema(db)
     const since = Date.now() - days * 86_400_000
     const rows = db.prepare('SELECT data FROM message WHERE time_created >= ?').all(since)
     db.close()

package/scripts/install/opencode.mjs

@@ -1,6 +1,16 @@
 #!/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 } from 'node:fs'
@@ -221,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
@@ -333,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
@@ -346,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
-    }
   }
 
   // -----------------------------------------------------------------------
@@ -661,11 +682,36 @@ 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
   }
 
   // --------------------------------------------------------------------
@@ -695,16 +741,24 @@ 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)
+  // 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)
@@ -747,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/release-beta-version.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/** Compute and optionally apply the beta version for a release PR. */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const MANIFESTS = [
+  { file: 'package.json', kind: 'json' },
+  { file: 'pyproject.toml', kind: 'toml' },
+  { file: 'plugin.json', kind: 'json' },
+  { file: 'src/plugins/tui/package.json', kind: 'json' },
+]
+
+const STABLE = /^(\d+)\.(\d+)\.(\d+)$/
+
+export function nextStableVersion(latest, intent = 'patch') {
+  const match = STABLE.exec(String(latest))
+  if (!match) throw new Error(`npm latest is not a stable semver: "${latest}"`)
+  const [major, minor, patch] = match.slice(1).map(Number)
+  if (!['patch', 'minor', 'major'].includes(intent)) {
+    throw new Error(`release intent must be patch, minor, or major: "${intent}"`)
+  }
+  if (intent === 'major') return `${major + 1}.0.0`
+  if (intent === 'minor') return `${major}.${minor + 1}.0`
+  return `${major}.${minor}.${patch + 1}`
+}
+
+export function betaVersion(latest, intent, pr, sha) {
+  if (!/^\d+$/.test(String(pr)) || Number(pr) < 1) throw new Error(`invalid PR number: "${pr}"`)
+  const shortSha = String(sha).slice(0, 7)
+  if (!/^[0-9a-f]{7,}$/i.test(shortSha)) throw new Error(`invalid commit SHA: "${sha}"`)
+  return `${nextStableVersion(latest, intent)}-beta.${pr}.${shortSha}`
+}
+
+function writeVersion(root, { file, kind }, version) {
+  const path = join(root, file)
+  const raw = readFileSync(path, 'utf8')
+  if (kind === 'toml') {
+    const updated = raw.replace(/^(version\s*=\s*")[^"]+("\s*)$/m, `$1${version}$2`)
+    if (updated === raw) throw new Error(`no version field in ${file}`)
+    writeFileSync(path, updated)
+    return
+  }
+  const content = JSON.parse(raw)
+  content.version = version
+  writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`)
+}
+
+export function applyBetaVersion(root, version) {
+  for (const manifest of MANIFESTS) writeVersion(root, manifest, version)
+  // Keep npm's lockfile metadata consistent without changing dependency data.
+  const lockPath = join(root, 'package-lock.json')
+  const lock = JSON.parse(readFileSync(lockPath, 'utf8'))
+  lock.version = version
+  if (lock.packages?.['']) lock.packages[''].version = version
+  writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`)
+}
+
+const args = new Map(
+  process.argv.slice(2).map((arg) => {
+    const [key, ...value] = arg.split('=')
+    return [key.replace(/^--/, ''), value.join('=')]
+  }),
+)
+
+if (args.has('latest')) {
+  try {
+    const version = betaVersion(
+      args.get('latest'),
+      args.get('intent') || 'patch',
+      args.get('pr'),
+      args.get('sha'),
+    )
+    if (args.has('apply')) applyBetaVersion(process.cwd(), version)
+    console.log(version)
+  } catch (error) {
+    console.error(`release-beta-version: ${error.message}`)
+    process.exit(1)
+  }
+}