pantheon-opencode 1.1.3-beta.0 → 1.2.0-beta.9.7bef03e

package/README.md

@@ -172,6 +172,9 @@ npx pantheon-opencode init
 # Headless mode — for CI and automation
 npx pantheon-opencode init --headless
 
+# (Optional) Install + activate a model routing preset
+npx pantheon-opencode init --preset go-fast
+
 # (Optional) Install MCP servers + skills + TUI plugin
 npm run setup
 
@@ -182,7 +185,7 @@ opencode
 
 > **Modes:** Interactive TUI with checkbox selection (default TTY), or `--headless` for scripts/CI.
 > **Minimal:** `--headless --no-mcp` installs only agents (~2s).
-> **Full:** `--headless` also creates Python venv + MCP servers (memory, persistence, KV).
+> **Full:** `--headless` also creates Python venv + MCP servers (memory, persistence, KV, vision).
 
 ---
 
@@ -418,6 +421,76 @@ subscription (OpenCode Go, Copilot Pro, Claude Pro, etc.).
 
 ---
 
+## Model Routing Presets
+
+The abstract tiers above are pinned to concrete `provider/model` IDs by **6 built-in model presets**. Each preset maps all 14 agents to a specific model plus a reasoning effort per role (planners/reviewers, implementers, scouts). **Zero-mutation default**: without an active preset, agents run on OpenCode's default model — behavior is unchanged.
+
+### Presets
+
+| Preset | Provider | Planners/Reviewers | Implementers | Scouts |
+|--------|----------|--------------------|--------------|--------|
+| `go-deepseek` | opencode (Zen) | `opencode/deepseek-v4-pro` | `opencode/deepseek-v4-flash` | `opencode/deepseek-v4-flash-free` |
+| `go-fast` | opencode-go | `opencode-go/deepseek-v4-flash` — all 14 agents, effort `low` | | |
+| `go-claude` | anthropic | `anthropic/claude-opus-4-8` | `anthropic/claude-sonnet-5` | `anthropic/claude-haiku-4-5` |
+| `go-openai` | openai | `openai/gpt-5.6-sol` | `openai/gpt-5.6-terra` | `openai/gpt-5.6-luna-fast` |
+| `go-premium` | opencode-go | GLM-5.1 (zeus), DeepSeek V4 Pro (athena), Qwen3.7 Max (themis) | MiniMax M2.7 (hermes, hephaestus), Kimi K2.6 (aphrodite), Qwen3.7 Plus (demeter), GLM-5.2 (prometheus) | DeepSeek V4 Flash (scouts) |
+| `go-free` | opencode (Zen free, $0) | Big Pickle (zeus), Nemotron 3 Ultra Free (athena) | DeepSeek V4 Flash Free | North Mini Code Free (scouts) |
+
+The exact per-agent mapping (model + reasoning effort + fallbacks) lives in the `presets:` block of [src/routing.yml](src/routing.yml).
+
+### Requirements
+
+- **Env vars** — checked fail-fast (CLI and plugin) when the selected preset uses the provider:
+  - `PANTHEON_OPENCODE_API_KEY` — `opencode` + `opencode-go` providers (`go-deepseek`, `go-fast`, `go-premium`, `go-free`)
+  - `PANTHEON_ANTHROPIC_API_KEY` — `anthropic` provider (`go-claude`)
+  - `PANTHEON_OPENAI_API_KEY` — `openai` provider (`go-openai`)
+- **OpenCode Go subscription** required for `go-fast` / `go-premium`.
+- **OpenCode Zen free tier** for `go-free` — note `nemotron-3-ultra-free` has known intermittent failures ([opencode#38028](https://github.com/opencode/opencode/issues/38028)); fall back to `go-fast` if flaky.
+
+### Commands
+
+```bash
+# Install + activate a preset
+npx pantheon-opencode init --preset go-fast
+
+# Switch preset (global config; --project for project-local; --dry-run to preview)
+pantheon-opencode set-tier go-deepseek
+pantheon-opencode set-tier go-fast --project
+pantheon-opencode set-tier go-fast --dry-run
+
+# Clear preset — back to the zero-mutation default
+pantheon-opencode set-tier none
+
+# No name → lists available presets (none, go-deepseek, go-fast, go-claude, go-openai, go-premium, go-free)
+pantheon-opencode set-tier
+```
+
+**Env override (CI/headless)** — wins over the file:
+
+```bash
+export PANTHEON_MODEL_PRESET=go-deepseek
+```
+
+### How it works
+
+- The active selection is persisted to `.pantheon/active-preset.json` — `{version, preset, source, updated_at}` — written atomically (tmp file + rename) with a `.bak` backup of the previous file. It applies on the next OpenCode startup (no hot-swap); the plugin's `hooks.config` injects it.
+- **Resolution precedence**: `PANTHEON_MODEL_PRESET` env → first existing `.pantheon/active-preset.json` (project → `~/.config/opencode` → `~/.opencode`) → **none** (defaults).
+- **Partial semantics**: a preset overrides only the agents it lists; unlisted agents inherit the invoking primary agent's model.
+- Interactive picker during `init`: one prompt listing the 6 presets (select by number or name, blank to skip). It never touches your `opencode.json` — the choice is injected at startup instead. The file format also supports an optional `overrides` block (per-agent `model`/`variant`, per-provider `baseURL`/`apiKeyEnv`) merged over the preset definition.
+- **Capability normalization**: requested reasoning effort is clamped to each model family's ceiling (`deepseek-v4-flash` max `medium`; claude models strip the variant entirely — Anthropic uses thinking).
+- **fallback_models**: per-agent ordered fallback list where configured (e.g. `go-deepseek` sets `[opencode/mimo-v2.5]` for every agent).
+
+### Quick smoke test
+
+```bash
+export PANTHEON_OPENCODE_API_KEY=...
+pantheon-opencode set-tier go-fast --project
+opencode run "hello" 2>&1 | grep "Pantheon"
+# expect: [Pantheon Plugin] Model preset active: go-fast (source: file)
+```
+
+---
+
 ## Quick Start
 
 ### 1. Install Pantheon

package/bin/pantheon-init.mjs

@@ -8,6 +8,7 @@
  * installOpenCode() from scripts/install/opencode.mjs.
  */
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
@@ -33,6 +34,9 @@ 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 --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 set-tier <name> --project  # Set active model preset (project)');
   console.log('  npx pantheon-opencode --help              # Show this help');
 }
 
@@ -42,6 +46,78 @@ async function main() {
 
   if (args.includes('--help')) { printUsage(); process.exit(0); }
 
+  if (command === 'set-tier') {
+    const isProject = args.includes('--project');
+    const isDryRun = args.includes('--dry-run');
+    const name = args[1];
+
+    const { loadPresetDefs } = await import('../src/pantheon/presets.mjs');
+    const { writeActivePreset } = await import('../scripts/install/model-picker.mjs');
+    const presets = loadPresetDefs();
+    const presetList = `none, ${Object.keys(presets).join(', ')}`;
+
+    if (!name) {
+      console.error('❌ set-tier requires a preset name');
+      console.error(`   Available: ${presetList}`);
+      process.exit(1);
+    }
+    if (name !== 'none' && !presets[name]) {
+      console.error(`❌ Unknown preset "${name}"`);
+      console.error(`   Available: ${presetList}`);
+      process.exit(1);
+    }
+
+    // Fail-fast: every provider's API key env var must be set before writing
+    if (name !== 'none') {
+      for (const [pid, provider] of Object.entries(presets[name].providers || {})) {
+        if (!process.env[provider.apiKeyEnv]) {
+          console.error(`❌ Missing required API key configuration for provider "${pid}"`);
+          console.error('   Set the provider API key environment variable and retry.');
+          process.exit(1);
+        }
+      }
+    }
+
+    const presetDir = isProject
+      ? process.cwd()
+      : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'opencode');
+    const filePath = path.join(presetDir, '.pantheon', 'active-preset.json');
+    const bakPath = path.join(presetDir, '.pantheon', 'active-preset.json.bak');
+
+    let prevName = '(none)';
+    if (fs.existsSync(filePath)) {
+      try {
+        prevName = JSON.parse(fs.readFileSync(filePath, 'utf8')).preset || '(unknown)';
+      } catch { prevName = '(unknown)'; }
+    }
+
+    if (name === 'none') {
+      if (isDryRun) {
+        console.log('[dry-run] Would clear model preset');
+      } else {
+        if (fs.existsSync(filePath)) {
+          fs.mkdirSync(path.dirname(bakPath), { recursive: true });
+          fs.copyFileSync(filePath, bakPath);
+          fs.rmSync(filePath, { force: true });
+        }
+        console.log('Model preset cleared. Using opencode defaults.');
+        console.log(`   Backup: ${bakPath}`);
+      }
+      return;
+    }
+
+    const result = writeActivePreset(presetDir, name, { dryRun: isDryRun, source: 'cli' });
+
+    console.log(`Model preset set: ${prevName} → ${name}`);
+    for (const [agent, spec] of Object.entries(presets[name].agents || {})) {
+      console.log(`   ${agent}: ${spec.model} [${spec.reasoning_effort}]`);
+    }
+    const providerNames = Object.keys(presets[name].providers || {});
+    console.log(`   Providers: ${providerNames.join(', ') || 'none'}`);
+    if (result.backupPath) console.log(`   Backup: ${result.backupPath}`);
+    return;
+  }
+
   if (command === 'init' || !command) {
     const isProject = args.includes('--project');
     const isDryRun = args.includes('--dry-run');
@@ -51,6 +127,8 @@ async function main() {
     const forceInteractive = args.includes('--interactive');
     const forceHeadless = args.includes('--headless');
     const autoYes = args.includes('--yes') || args.includes('-y');
+    const presetIndex = args.indexOf('--preset');
+    const presetOpt = presetIndex >= 0 ? (args[presetIndex + 1] ?? null) : null;
 
     const components = ['agents', 'skills', 'instructions', 'commands', 'plugins'];
     if (!skipMCP) components.push('runtime');
@@ -75,6 +153,7 @@ async function main() {
         interactive: forceInteractive,
         headless: forceHeadless,
         yes: autoYes,
+        preset: presetOpt,
       });
     } 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`);

package/commands/pantheon-vision.md

@@ -0,0 +1,67 @@
+---
+description: "Configure Pantheon vision interactively: auth check, mode (native|tool|auto), vision model, tool fallback. Saves to opencode-vision.json. Usage: /pantheon-vision"
+agent: hermes
+---
+# /pantheon-vision — Configure Vision
+
+**What:** Walks the user through configuring Pantheon's image-vision plugin
+(native multimodal model via the opencode Zen endpoint, or MCP tool fallback).
+**Usage:** `/pantheon-vision [--global]`
+**When:** First-time setup, changing the vision model, troubleshooting images
+not being described, switching between native and tool mode.
+
+## Steps
+
+1. **Check connectivity & key source**
+   - Read the opencode auth store: `<data dir>/auth.json`
+     (default `~/.local/share/opencode/auth.json`, provider entries
+     `opencode-go` then `opencode`) via `readOpencodeAuthToken`.
+   - Report whether the user is connected (`opencode auth login`) or has an
+     env key (`PANTHEON_OPENCODE_API_KEY` / `OPENCODE_API_KEY`).
+   - **Never log or echo the token itself** — only connected/not connected.
+
+2. **Show current status**
+   - Effective mode precedence: env `PANTHEON_VISION_MODE` > config file
+     `mode` > default `auto`.
+   - Read the current config file if present (project `.opencode/opencode-vision.json`
+     then user `~/.config/opencode/opencode-vision.json`).
+
+3. **Ask what to set (interactive)**
+   - **Mode:** `native` | `tool` | `auto`
+     - `native` — describe images via the multimodal model directly (needs key)
+      - `tool` — always use the MCP tool fallback (`imageAnalysisTool`)
+     - `auto` — try native first, fall back to the tool (default)
+   - **Vision model:** e.g. `opencode-go/mimo-v2.5`, `opencode-go/minimax-m3`,
+     or an explicit override (precedence: env `PANTHEON_VISION_MODEL` > config
+     `visionModel` > active preset `vision.model` > default `opencode-go/mimo-v2.5`).
+    - **Tool fallback:** `imageAnalysisTool` (default
+      `pantheon_vision_vision_describe`). Bifrost is opt-in only when
+      explicitly selected here or through `PANTHEON_VISION_TOOL`.
+
+4. **Save the config**
+   - Default: project config `.opencode/opencode-vision.json`
+     (merged with the user config `~/.config/opencode/opencode-vision.json`;
+     project wins on conflicts).
+   - `--global` → write to `~/.config/opencode/opencode-vision.json`.
+   - Shape:
+     ```json
+     {
+       "mode": "auto",
+       "visionModel": "opencode-go/mimo-v2.5",
+        "imageAnalysisTool": "pantheon_vision_vision_describe"
+     }
+     ```
+   - Optional fields also supported: `models` (model wildcard patterns),
+     `promptTemplate` (with `{imageList}`/`{imageCount}`/`{toolName}`/`{userText}`).
+
+5. **Wrap up**
+   - Tell the user to restart opencode (config is read at startup / per turn)
+     and test by pasting an image with a question.
+   - If no key and no auth store entry exist, recommend `opencode auth login`
+     (native mode) or leaving the tool fallback enabled.
+
+## Rules
+
+- Do NOT print tokens or auth.json contents.
+- Do NOT overwrite existing config keys not being changed — merge.
+- If the config file is corrupted JSON, warn and ask before overwriting.

package/opencode.json

@@ -1,5 +1,15 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "opencode-go": {
+      "models": {
+        "mimo-v2.5": {
+          "attachment": true,
+          "modalities": { "input": ["text", "image"] }
+        }
+      }
+    }
+  },
   "default_agent": "zeus",
   "subagent_depth": 2,
   "model": "opencode-go/deepseek-v4-flash",
@@ -18,19 +28,13 @@
       "pip *": "allow"
     }
   },
-  "instructions": [
-    "AGENTS.md",
-    "src/instructions/*.instructions.md"
-  ],
+  "instructions": ["AGENTS.md", "src/instructions/*.instructions.md"],
   "plugin": [],
   "mcp": {
     "bifrost": {
       "type": "remote",
       "url": "https://llm.ofertachina.cloud/mcp",
-      "enabled": true,
-      "headers": {
-        "x-bf-vk": "sk-bf-a5a9b5b0-45fc-414d-8e4d-f9beb8c49a6d"
-      }
+      "enabled": true
     }
   },
   "agent": {
@@ -40,41 +44,8 @@
     "themis": {
       "model": "opencode-go/deepseek-v4-pro"
     },
-    "zeus": {
-      "model": "opencode-go/deepseek-v4-pro"
-    },
     "hephaestus": {
       "model": "opencode-go/deepseek-v4-pro"
-    },
-    "hermes": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "aphrodite": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "demeter": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "prometheus": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "apollo": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "nyx": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "gaia": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "iris": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "mnemosyne": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "talos": {
-      "model": "opencode-go/deepseek-v4-flash"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.1.3-beta.0",
+  "version": "1.2.0-beta.9.7bef03e",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
@@ -23,6 +23,8 @@
     "lint": "npx biome ci .",
     "typecheck": "npx tsc --noEmit",
     "audit": "npm audit --audit-level=high",
+    "secret-scan": "node scripts/secret-scan.mjs",
+    "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs",
     "test": "python3 -m pytest tests/ -q 2>&1 || echo \"No tests found\"",
     "test:ci": "python3 -m pytest tests/ -q --tb=short 2>&1 || true"
   },
@@ -50,6 +52,7 @@
     "scripts/*.mjs",
     "src/mcp/*.sh",
     "src/routing.yml",
+    "src/pantheon/**",
     "src/mcp/requirements*",
     "src/plugins/tui/**",
     "src/skills/**"
@@ -60,6 +63,7 @@
   "devDependencies": {
     "@commitlint/cli": "^19.8.0",
     "@commitlint/config-conventional": "^19.8.0",
+    "@opencode-ai/plugin": "1.18.11",
     "husky": "^9.1.7"
   },
   "repository": {

package/scripts/doctor.mjs

@@ -44,8 +44,6 @@ const _ALL_PLATFORMS = ['opencode']
 const PLATFORM_LABELS = {
   opencode: 'OpenCode',
 }
-  opencode: 'OpenCode',
-}
 
 // ---------------------------------------------------------------------------
 // State
@@ -236,6 +234,10 @@ function checkAgentFiles(args) {
   pass(`${canonical.length} canonical agents found in agents/`)
 
   // Determine which platforms to check
+  if (!existsSync(PLATFORM_DIR)) {
+    warn('Platform component not distributed in this package — skipping platform agent check')
+    return
+  }
   const platformDirs = readdirSync(PLATFORM_DIR, { withFileTypes: true })
     .filter((d) => d.isDirectory() && d.name !== '_template' && d.name !== 'plans')
     .map((d) => d.name)

package/scripts/install/health-check.mjs

@@ -9,7 +9,7 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 /**
@@ -24,6 +24,7 @@ import { join } from 'node:path'
 export function healthCheck(target, { dryRun = false } = {}) {
   const results = { passed: [], failed: [], warnings: [] }
   const python = findPython(target)
+  const visionServer = resolveVisionServer(target)
 
   // Check 1: Critical runtime scripts exist
   const scripts = ['mcp_persistence_server.py', '_pantheon_paths.py']
@@ -38,9 +39,70 @@ export function healthCheck(target, { dryRun = false } = {}) {
       })
     }
   }
+  if (visionServer) {
+    results.passed.push({
+      check: visionServer.check,
+      detail: visionServer.detail,
+    })
+    const installedVisionServer = join(target, 'scripts', 'pantheon_vision_server.py')
+    const canonicalVisionServer = join(target, 'src', 'mcp', 'pantheon_vision_server.py')
+    if (existsSync(installedVisionServer) && existsSync(canonicalVisionServer)) {
+      try {
+        if (
+          readFileSync(installedVisionServer, 'utf8') !==
+          readFileSync(canonicalVisionServer, 'utf8')
+        ) {
+          results.failed.push({
+            check: 'pantheon-vision source drift',
+            detail: 'installed script differs from src/mcp/pantheon_vision_server.py',
+          })
+        }
+      } catch {
+        results.failed.push({
+          check: 'pantheon-vision source drift',
+          detail: 'could not compare installed script with src/mcp source',
+        })
+      }
+    }
+  } else {
+    results.failed.push({
+      check: 'src/mcp/pantheon_vision_server.py',
+      detail: 'NOT FOUND — canonical vision server source is unavailable',
+    })
+  }
 
   if (dryRun) return results
 
+  // Check 1.5: Vision keeps a small, isolated dependency manifest.
+  const visionRequirements = [
+    join(target, 'src', 'mcp', 'requirements-vision.txt'),
+    join(target, 'requirements-vision.txt'),
+    join(target, '.opencode', 'requirements-vision.txt'),
+  ].find((path) => existsSync(path))
+  if (!visionRequirements) {
+    results.failed.push({
+      check: 'requirements-vision.txt',
+      detail: 'NOT FOUND — vision dependency isolation is incomplete',
+    })
+  } else {
+    const requirements = readFileSync(visionRequirements, 'utf8').toLowerCase()
+    const forbidden = ['pillow', 'paddle', 'gemini', 'torch']
+    const unwanted = forbidden.filter((name) =>
+      new RegExp(`^${name}(?:[<>=!~]|$)`, 'm').test(requirements),
+    )
+    if (unwanted.length > 0) {
+      results.failed.push({
+        check: 'requirements-vision.txt',
+        detail: `forbidden MVP dependencies: ${unwanted.join(', ')}`,
+      })
+    } else {
+      results.passed.push({
+        check: 'requirements-vision.txt',
+        detail: 'isolated and free of heavyweight vision runtimes',
+      })
+    }
+  }
+
   // Check 2: Syntax check on each MCP server script
   const mcpScripts = [
     'mcp_persistence_server.py',
@@ -67,6 +129,22 @@ export function healthCheck(target, { dryRun = false } = {}) {
       }
     }
   }
+  if (visionServer && python) {
+    const result = spawnSync(python, ['-m', 'py_compile', visionServer.path], {
+      stdio: 'pipe',
+    })
+    if (result.status === 0) {
+      results.passed.push({
+        check: 'syntax:pantheon_vision_server.py',
+        detail: 'valid',
+      })
+    } else {
+      results.failed.push({
+        check: 'syntax:pantheon_vision_server.py',
+        detail: result.stderr.toString().trim().split('\n').slice(-1)[0],
+      })
+    }
+  }
 
   // Check 3: _pantheon_paths import works
   if (python) {
@@ -150,6 +228,28 @@ export function healthCheck(target, { dryRun = false } = {}) {
   return results
 }
 
+/**
+ * Resolve the canonical source when checking the repository, or the generated
+ * runtime copy when checking an installed target.
+ * @param {string} target
+ * @returns {{path: string, check: string, detail: string}|null}
+ */
+function resolveVisionServer(target) {
+  const candidates = [
+    {
+      path: join(target, 'src', 'mcp', 'pantheon_vision_server.py'),
+      check: 'src/mcp/pantheon_vision_server.py',
+      detail: 'canonical source exists',
+    },
+    {
+      path: join(target, 'scripts', 'pantheon_vision_server.py'),
+      check: 'scripts/pantheon_vision_server.py',
+      detail: 'installed copy exists (deployed from src/mcp)',
+    },
+  ]
+  return candidates.find(({ path }) => existsSync(path)) ?? null
+}
+
 /**
  * Find the target's venv python, falling back to system python3.
  * @param {string} target

package/scripts/install/model-picker.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * model-picker.mjs — interactive model preset selection + persistence
+ *
+ * Used by the installer (interactive prompt) and the `pantheon-opencode`
+ * CLI. Writes the active preset marker to <presetDir>/.pantheon/active-preset.json
+ * which the plugin (src/plugin.ts) reads on startup via resolveActivePreset().
+ */
+import { copyFileSync, existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { loadPresetDefs } from '../../src/pantheon/presets.mjs'
+
+/**
+ * Build the active-preset.json payload (version 1).
+ *
+ * @param {string} presetName
+ * @param {string} [source] 'cli' | 'interactive'
+ * @returns {{version: number, preset: string, source: string, updated_at: string}}
+ */
+export function buildActivePresetFile(presetName, source = 'cli') {
+  return {
+    version: 1,
+    preset: presetName,
+    source,
+    updated_at: new Date().toISOString(),
+  }
+}
+
+/**
+ * Persist the active preset marker, backing up any previous file to .bak.
+ *
+ * @param {string} presetDir install target (project root or global opencode dir)
+ * @param {string} presetName
+ * @param {{dryRun?: boolean, source?: string, logger?: object}} [opts]
+ * @returns {{written: boolean, path: string, backupPath: string|null}}
+ */
+export function writeActivePreset(
+  presetDir,
+  presetName,
+  { dryRun = false, source = 'cli', logger = console } = {},
+) {
+  const dir = join(presetDir, '.pantheon')
+  const filePath = join(dir, 'active-preset.json')
+  const backupPath = join(dir, 'active-preset.json.bak')
+
+  if (dryRun) {
+    logger.log?.(`[dry-run] Would write model preset "${presetName}" to ${filePath}`)
+    return { written: false, path: filePath, backupPath: null }
+  }
+
+  mkdirSync(dir, { recursive: true })
+  let backupMade = false
+  if (existsSync(filePath)) {
+    copyFileSync(filePath, backupPath)
+    backupMade = true
+  }
+  writeFileSync(`${filePath}.tmp-${process.pid}`, `${JSON.stringify(buildActivePresetFile(presetName, source), null, 2)}\n`)
+  renameSync(`${filePath}.tmp-${process.pid}`, filePath)
+  return { written: true, path: filePath, backupPath: backupMade ? backupPath : null }
+}
+
+/**
+ * Interactive model preset picker. Asks the user to choose a preset; persists
+ * the choice unless dryRun. `rl` may be injected for tests; otherwise a
+ * readline/promises interface on stdin/stdout is created and closed.
+ *
+ * @param {{presetDir?: string, presets?: object, dryRun?: boolean, logger?: object, rl?: object}} [opts]
+ * @returns {Promise<string|null>} chosen preset name or null (skipped/unknown)
+ */
+export async function runModelPicker({
+  presetDir,
+  presets,
+  dryRun = false,
+  logger = console,
+  rl,
+} = {}) {
+  const defs = presets ?? loadPresetDefs()
+  const names = Object.keys(defs)
+  if (names.length === 0) {
+    logger.warn?.('Model presets: no presets defined in routing.yml')
+    return null
+  }
+
+  const list = names.map((n, i) => `  ${i + 1}) ${n} — ${defs[n].description ?? ''}`).join('\n')
+  const rli = rl ?? createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const answer = await rli.question(
+      `\nModel presets (number or name; blank to skip):\n${list}\n> `,
+    )
+    const trimmed = (answer ?? '').trim()
+    if (trimmed === '' || trimmed.toLowerCase() === 'none') {
+      logger.log?.('Skipping model preset selection.')
+      return null
+    }
+    let name = null
+    if (names.includes(trimmed)) {
+      name = trimmed
+    } else {
+      const idx = Number(trimmed)
+      if (Number.isInteger(idx) && idx >= 1 && idx <= names.length) {
+        name = names[idx - 1]
+      }
+    }
+    if (!name) {
+      logger.warn?.(`Unknown preset "${trimmed}" — skipping model preset selection.`)
+      return null
+    }
+    if (!dryRun) {
+      writeActivePreset(presetDir, name, { dryRun: false, source: 'interactive', logger })
+    } else {
+      logger.log?.(`[dry-run] Would set model preset "${name}"`)
+    }
+    return name
+  } finally {
+    if (!rl) rli.close()
+  }
+}