pantheon-opencode 1.2.1 → 1.2.2

package/AGENTS.md

@@ -29,6 +29,15 @@ See [INSTALLATION.md](docs/INSTALLATION.md) for setup instructions.
 - 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

package/README.md

@@ -737,19 +737,18 @@ Edit README.md line 11: agents-17 → agents-18
 - Hardcoded secret detection
 - Minimum 80% test coverage (hard block)
 
-**Agent hooks enforce at runtime (`scripts/hooks/` + `.opencode/plugins/pantheon-hooks.ts`):**
-- `scan-secrets.sh` — detects hardcoded secrets and credentials (PreToolUse)
-- `validate-tool-safety.sh` — blocks destructive operations (PreToolUse)
-- `validate-talos-scope.sh` — restricts Talos hotfix scope (PreToolUse)
-- `on-subagent-delegation-start.sh` — tracks delegation start (PreToolUse)
-- `format-multi-language.sh` — auto-formats modified files (PostToolUse)
-- `log-session-start.sh` — audit trail of sessions (PostToolUse)
-- `on-subagent-delegation-stop.sh` — delegation cleanup (PostToolUse)
-- `validate-post-conditions.sh` — post-condition validation (event)
-- `audit-imports.sh` — detects wildcard imports and suspicious patterns (PostToolUse)
-- `run-type-check.sh` — runs mypy/tsc if config exists (PostToolUse)
-
-The `.opencode/plugins/pantheon-hooks.ts` plugin bridges these shell scripts to OpenCode events. OpenCode auto-discovers plugins from `.opencode/plugins/` when running from the project directory.
+**Agent hooks enforce at runtime (`scripts/hooks/` + `src/plugins/pantheon-hooks.ts`):**
+- `scan-secrets.sh` — detects hardcoded secrets and credentials (tool.execute.before)
+- `validate-tool-safety.sh` — blocks destructive operations (tool.execute.before)
+- `validate-talos-scope.sh` — restricts Talos hotfix scope (tool.execute.before)
+- `on-subagent-delegation-start.sh` — tracks delegation start (tool.execute.before, delegation tools only)
+- `format-multi-language.sh` — auto-formats modified files (tool.execute.after)
+- `log-session-start.sh` — audit trail of sessions (tool.execute.after + event session.created)
+- `on-subagent-delegation-stop.sh` — delegation cleanup (tool.execute.after, delegation tools only)
+- `validate-post-conditions.sh` — post-condition validation (event session.created)
+- `audit-imports.sh` and `run-type-check.sh` also live in `scripts/hooks/` but are not wired into the plugin.
+
+The `src/plugins/pantheon-hooks.ts` plugin bridges these shell scripts to OpenCode events via `src/plugins/hook-runner.ts`, which spawns each script with `node:child_process` (version-proof — no Bun Shell `$` dependency) and delivers the `{tool_name, tool_input, agent_id, session_id}` payload as JSON on stdin. Register it explicitly in `opencode.json`: `"plugin": ["<path>/src/plugins/pantheon-hooks.ts"]` (absolute path). It is **not** auto-discovered from `.opencode/plugins/`.
 
 ### Pre-commit hooks (local secret gate)
 

package/bin/pantheon-init.mjs

@@ -37,6 +37,8 @@ function printUsage() {
   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 prune               # List legacy artifacts (dry-run)');
+  console.log('  npx pantheon-opencode prune --apply       # Remove stale backups');
   console.log('  npx pantheon-opencode --help              # Show this help');
 }
 
@@ -44,6 +46,18 @@ async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
+  // prune handles its own --help (delegated to scripts/prune.mjs), so its
+  // dispatch must run BEFORE the generic --help check.
+  if (command === 'prune') {
+    const { spawnSync } = await import('child_process');
+    const pruneScript = path.join(ROOT, 'scripts', 'prune.mjs');
+    const result = spawnSync(process.execPath, [pruneScript, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: ROOT,
+    });
+    process.exit(result.status ?? 1);
+  }
+
   if (args.includes('--help')) { printUsage(); process.exit(0); }
 
   if (command === 'set-tier') {

package/opencode.json

@@ -29,7 +29,7 @@
     }
   },
   "instructions": ["AGENTS.md", "src/instructions/*.instructions.md"],
-  "plugin": [],
+  "plugin": ["/home/ils15/pantheon/src/plugins/pantheon-hooks.ts"],
   "mcp": {
     "bifrost": {
       "type": "remote",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
@@ -8,9 +8,11 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
+    "prepare": "husky",
     "setup": "node bin/pantheon-init.mjs init",
     "setup:lite": "node bin/pantheon-init.mjs init --clean --components agents,skills,instructions",
     "doctor": "node scripts/doctor.mjs",
+    "prune": "node scripts/prune.mjs",
     "init": "node bin/pantheon-init.mjs init",
     "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
@@ -18,6 +20,7 @@
     "postpublish": "node -e \"console.log('✅ Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
     "version:status": "node scripts/versioning.mjs status",
     "version:apply": "node scripts/versioning.mjs apply",
+    "version:check": "node scripts/version-check.mjs",
     "release:dry-run": "node scripts/versioning.mjs status && npm pack --dry-run",
     "publish:next": "npm publish --tag next --access public",
     "lint": "npx biome ci .",
@@ -26,7 +29,8 @@
     "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",
+    "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs && node tests/test_doctor_layers.mjs",
+    "test:node": "node --test tests/*.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"
   },
@@ -55,6 +59,8 @@
     "src/mcp/*.sh",
     "src/routing.yml",
     "src/pantheon/**",
+    "src/plugins/**",
+    "scripts/hooks/**",
     "src/mcp/requirements*",
     "src/plugins/tui/**",
     "src/skills/**"
@@ -66,13 +72,16 @@
     "@commitlint/cli": "^19.8.0",
     "@commitlint/config-conventional": "^19.8.0",
     "@opencode-ai/plugin": "1.18.11",
-    "husky": "^9.1.7",
-    "pantheon-opencode": "^1.2.0-beta.9.7bef03e"
+    "husky": "^9.1.7"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/ils15/pantheon-opencode.git"
   },
+  "homepage": "https://github.com/ils15/pantheon-opencode",
+  "bugs": {
+    "url": "https://github.com/ils15/pantheon-opencode/issues"
+  },
   "keywords": [
     "github",
     "copilot",

package/scripts/changelog-extract.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * changelog-extract.mjs — print a version section from CHANGELOG.md
+ *
+ * The release workflow needs the CHANGELOG entry for the version it is about
+ * to tag. This script extracts the body of `## [<version>] - YYYY-MM-DD`
+ * (leading `v` tolerated, date optional) and prints it to stdout. When the
+ * section is missing it exits 1, so the workflow fails loudly: "add the
+ * section in the version-bump PR".
+ *
+ * Usage:
+ *   node scripts/changelog-extract.mjs 1.2.1
+ *   node scripts/changelog-extract.mjs v1.2.1 --changelog /path/to/CHANGELOG.md
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const DEFAULT_CHANGELOG = join(dirname(fileURLToPath(import.meta.url)), '..', 'CHANGELOG.md')
+
+/** Escape regex metacharacters so a version like 1.0.0 matches literally. */
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Extract the body of a version section from changelog text.
+ *
+ * Finds the heading `## [<version>] - YYYY-MM-DD` (leading `v` and the date
+ * are optional) and returns everything after the heading line up to the next
+ * `## [` heading (or end of text). The `## [Unreleased]` heading is never
+ * matched, even when asked for explicitly.
+ *
+ * @param {string} changelogText - full CHANGELOG.md content
+ * @param {string} version - e.g. "1.2.1" or "v1.2.1"
+ * @returns {{found: boolean, body: string|null}} body is null when not found
+ */
+export function extractSection(changelogText, version) {
+  const normalized = String(version).trim().replace(/^v/i, '')
+  if (!normalized || /^unreleased$/i.test(normalized)) {
+    return { found: false, body: null }
+  }
+
+  const escaped = escapeRegExp(normalized)
+  // Single-line heading: `## [v?1.2.1]` optionally followed by ` - YYYY-MM-DD`.
+  // [ \t] (not \s) keeps the match from crossing newlines; the lookahead
+  // requires end-of-line or whitespace so `[1.0.0-beta]` can never match `1.0.0`.
+  const headingRe = new RegExp(
+    `^##[ \\t]+\\[v?${escaped}\\](?:[ \\t]*-[ \\t]*\\d{4}-\\d{2}-\\d{2})?(?=[ \\t]|$)`,
+    'm',
+  )
+  const match = headingRe.exec(changelogText)
+  if (!match) return { found: false, body: null }
+
+  // Advance past the heading line (match.index may point mid-line).
+  const newline = changelogText.indexOf('\n', match.index)
+  const start = newline === -1 ? changelogText.length : newline + 1
+
+  // Body ends at the next `## [` heading or end of text.
+  const nextHeading = /^##[ \t]+\[/m.exec(changelogText.slice(start))
+  const end = nextHeading ? start + nextHeading.index : changelogText.length
+
+  return { found: true, body: changelogText.slice(start, end).trim() }
+}
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (isDirectRun) {
+  const args = process.argv.slice(2)
+  let changelogPath = DEFAULT_CHANGELOG
+  let version = null
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--changelog') {
+      changelogPath = args[i + 1]
+      i += 1
+      continue
+    }
+    if (arg.startsWith('--changelog=')) {
+      changelogPath = arg.slice('--changelog='.length)
+      continue
+    }
+    version = arg
+  }
+
+  if (!version) {
+    console.error('Usage: node scripts/changelog-extract.mjs <version> [--changelog <path>]')
+    process.exitCode = 2
+  } else {
+    let text
+    try {
+      text = readFileSync(changelogPath, 'utf-8')
+    } catch {
+      console.error(`changelog-extract: cannot read ${changelogPath}`)
+      process.exitCode = 1
+    }
+
+    if (text !== undefined) {
+      const { found, body } = extractSection(text, version)
+      if (!found) {
+        console.error(`changelog-extract: section [${version}] not found in ${changelogPath}`)
+        console.error('Add the section in the version-bump PR — the release workflow requires it.')
+        process.exitCode = 1
+      } else {
+        process.stdout.write(`${body}\n`)
+        process.exitCode = 0
+      }
+    }
+  }
+}

package/scripts/doctor.mjs

@@ -24,9 +24,10 @@
  *   2 = errors (needs attention)
  */
 
-import { spawnSync } from 'node:child_process'
+import { spawn as spawnAsync, spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 // ---------------------------------------------------------------------------
@@ -158,10 +159,13 @@ function showHelp() {
 
  Checks:
    A. Agent Files          — canonical vs platform sync
-   B. MCP Configuration    — opencode.json MCP settings
+   B. MCP Configuration    — opencode.json MCP settings (Config layer)
+   B.5 MCP Spawn Paths     — local MCP exe/args resolve to existing files
+   B.6 MCP Runtime Smoke   — spawn each local MCP + JSON-RPC initialize handshake
    C. Permission Checks    — frontmatter validation
    D. Sync Status          — npm run sync freshness
    E. Git Status           — uncommitted changes
+   F. Runtime Layer        — venv python + pinned pip dependencies
 
  Exit codes:
    0  — all checks pass
@@ -314,12 +318,12 @@ function checkAgentFiles(args) {
 // Check B: MCP Configuration
 // ---------------------------------------------------------------------------
 
-function checkMcpConfig(args) {
-  section('B. MCP Configuration')
-
-  // Determine which opencode.json to check:
-  // 1. Target project's opencode.json
-  // 2. Pantheon ROOT opencode.json
+/**
+ * Collect every reachable opencode.json (project → repository → user config)
+ * with its parsed content, for the config, spawn-path and runtime layers.
+ * @returns {{label:string, path:string, data:object}[]}
+ */
+function collectMcpConfigs(args) {
   const candidates = [
     { label: 'project root', path: join(args.target, 'opencode.json') },
     { label: 'repository root', path: join(ROOT, 'opencode.json') },
@@ -336,7 +340,6 @@ function checkMcpConfig(args) {
     candidates.push({ label: 'user config', path: homeConfig })
   }
 
-  /** @type {{label:string, data:object}[]} */
   const configs = []
   for (const c of candidates) {
     const data = readJson(c.path)
@@ -344,6 +347,13 @@ function checkMcpConfig(args) {
       configs.push({ label: c.label, data, path: c.path })
     }
   }
+  return configs
+}
+
+function checkMcpConfig(args) {
+  section('B. MCP Configuration')
+
+  const configs = collectMcpConfigs(args)
 
   if (configs.length === 0) {
     warn('No opencode.json found in target or user config')
@@ -412,6 +422,155 @@ function checkMcpConfig(args) {
     if (args.verbose) {
       checkAgentMcpReferences(cfg)
     }
+
+    // 5. Hermetic spawn check — every local MCP command must resolve to an
+    // existing executable and existing absolute script paths. Catches the
+    // ENOENT-on-spawn failure class (dead hardcoded path, ambiguous relative
+    // path) before opencode tries to spawn the server.
+    for (const [name, mcpEntry] of Object.entries(mcp)) {
+      if (!mcpEntry || mcpEntry.type !== 'local') continue
+      const cmd = mcpEntry.command
+      if (!Array.isArray(cmd) || cmd.length === 0) {
+        warn(`${cfg.label}: MCP "${name}" has no command array`)
+        continue
+      }
+      const exe = cmd[0]
+      if (!exe.includes('/')) {
+        // PATH-resolved executable — cannot verify statically; surface for manual check
+        info(`${cfg.label}: MCP "${name}" uses PATH executable "${exe}" (verify with \`which ${exe}\`)`)
+        continue
+      }
+      if (!existsSync(exe)) {
+        error(`${cfg.label}: MCP "${name}" executable does not exist: ${exe}`)
+        continue
+      }
+      const deadArgs = cmd.slice(1).filter((a) => a.startsWith('/') && !existsSync(a))
+      if (deadArgs.length > 0) {
+        error(`${cfg.label}: MCP "${name}" has missing script path(s): ${deadArgs.join(', ')}`)
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check B.6: MCP Runtime Smoke (JSON-RPC initialize handshake)
+// ---------------------------------------------------------------------------
+// The static spawn-path check (B.5) proves the files exist; this layer proves
+// the server actually STARTS and answers the JSON-RPC initialize handshake.
+// Catches ENOENT-on-spawn, Python import errors and runtime crashes that the
+// static check cannot see — with a hard timeout so a hung server fails the
+// check instead of blocking the doctor run.
+
+/**
+ * Spawn one local MCP server, send a JSON-RPC `initialize` request and wait
+ * for a well-formed response.
+ * @param {string[]} command - argv of the MCP server (exe + args)
+ * @param {string} cwd - working directory (relative script args resolve here)
+ * @param {number} timeoutMs - hard timeout for the handshake
+ * @returns {Promise<{ok:boolean, serverName?:string, reason?:string}>}
+ */
+function mcpInitializeSmoke(command, cwd, timeoutMs) {
+  const payload = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'pantheon-doctor', version: '0.0.0' },
+    },
+  })
+  return new Promise((resolve) => {
+    let proc
+    try {
+      proc = spawnAsync(command[0], command.slice(1), { cwd, stdio: ['pipe', 'pipe', 'pipe'] })
+    } catch (err) {
+      resolve({ ok: false, reason: `spawn threw: ${err.message}` })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    let done = false
+    const finish = (result) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      try {
+        proc.kill('SIGKILL')
+      } catch {
+        /* already gone */
+      }
+      resolve(result)
+    }
+    const timer = setTimeout(
+      () => finish({ ok: false, reason: `timeout after ${timeoutMs}ms (no initialize response)` }),
+      timeoutMs,
+    )
+    proc.stdout.on('data', (chunk) => {
+      stdout += chunk.toString()
+      const line = stdout.split('\n').find((l) => l.includes('"id":1'))
+      if (!line) return
+      try {
+        const msg = JSON.parse(line.trim())
+        if (msg.id === 1 && msg.result) {
+          const info = msg.result.serverInfo
+          const label = info?.name ? `${info.name}${info.version ? ` ${info.version}` : ''}` : undefined
+          finish({ ok: true, serverName: label })
+          return
+        }
+        if (msg.error) {
+          finish({ ok: false, reason: `initialize error: ${msg.error.code ?? ''} ${msg.error.message ?? ''}` })
+        }
+      } catch {
+        /* not JSON yet — keep buffering */
+      }
+    })
+    proc.stderr.on('data', (chunk) => {
+      stderr += chunk.toString()
+      if (stderr.length > 4096) stderr = stderr.slice(-4096)
+    })
+    proc.on('error', (err) =>
+      finish({ ok: false, reason: `spawn failed: ${err.code ?? err.message}` }),
+    )
+    proc.on('exit', (code, signal) => {
+      if (done) return
+      const tail = stderr.trim().split('\n').filter(Boolean).slice(-3).join(' | ')
+      finish({
+        ok: false,
+        reason: `process exited early (code=${code} signal=${signal})${tail ? ` — ${tail}` : ''}`,
+      })
+    })
+    proc.stdin.write(`${payload}\n`)
+    proc.stdin.end()
+  })
+}
+
+async function checkMcpRuntimeSmoke(args) {
+  section('B.6 MCP Runtime Smoke')
+
+  const local = []
+  for (const cfg of collectMcpConfigs(args)) {
+    for (const [name, entry] of Object.entries(cfg.data.mcp ?? {})) {
+      if (!entry || entry.type !== 'local') continue
+      if (!Array.isArray(entry.command) || entry.command.length === 0) continue
+      local.push({ name, command: entry.command, cwd: dirname(cfg.path), source: cfg.label })
+    }
+  }
+
+  if (local.length === 0) {
+    warn('No local MCP servers found in any config — nothing to smoke-test')
+    return
+  }
+
+  info(`Smoke-testing ${local.length} local MCP server(s) via JSON-RPC initialize`)
+
+  for (const { name, command, cwd, source } of local) {
+    const result = await mcpInitializeSmoke(command, cwd, 10000)
+    if (result.ok) {
+      pass(`MCP "${name}" (${source}): initialize handshake OK${result.serverName ? ` — ${result.serverName}` : ''}`)
+    } else {
+      error(`MCP "${name}" (${source}): ${result.reason}`)
+    }
   }
 }
 
@@ -635,6 +794,132 @@ function checkGitStatus(args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Check F: Runtime Layer — Venv, Python & pinned dependencies
+// ---------------------------------------------------------------------------
+// The MCP servers run on the venv Python under ~/.config/opencode/.venv
+// (same resolution as scripts/install-mcp.mjs). This layer verifies the venv
+// exists, the interpreter responds, and the installed packages satisfy the
+// EXACT pins in src/mcp/requirements-mcp.txt and requirements-vision.txt
+// (issue #18 / #21).
+
+/** Parse `pip freeze` output into a normalized name → version map. */
+function parsePipFreeze(text) {
+  const map = {}
+  for (const line of text.split('\n')) {
+    const m = line.trim().match(/^([A-Za-z0-9_.-]+)==(\S+)/)
+    if (!m) continue
+    map[m[1].toLowerCase().replace(/-/g, '_')] = m[2]
+  }
+  return map
+}
+
+/** Split a version string into comparable numeric segments. */
+function parseVersion(v) {
+  const m = String(v).match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?/)
+  if (!m) return []
+  return [m[1], m[2] ?? '0', m[3] ?? '0', m[4] ?? '0'].map(Number)
+}
+
+/** Compare two versions numerically. Returns <0, 0 or >0. */
+function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  for (let i = 0; i < 4; i++) {
+    const da = pa[i] ?? 0
+    const db = pb[i] ?? 0
+    if (da !== db) return da - db
+  }
+  return 0
+}
+
+/**
+ * Check one requirement line (name + operator + version) against installed.
+ * Emits pass/error through the doctor counters.
+ */
+function checkRequirementLine(line, installed) {
+  const m = line.match(/^\s*([A-Za-z0-9_.-]+)\s*(==|>=|<=|>|<|~=|!=)\s*([^\s#]+)/)
+  if (!m) return
+  const name = m[1].toLowerCase().replace(/-/g, '_')
+  const op = m[2]
+  const want = m[3]
+  const have = installed[name]
+  if (have === undefined) {
+    error(`Dependency "${m[1]}" not installed (required ${op}${want})`)
+    return
+  }
+  const cmp = compareVersions(have, want)
+  let ok = false
+  switch (op) {
+    case '==': ok = cmp === 0; break
+    case '>=': ok = cmp >= 0; break
+    case '<=': ok = cmp <= 0; break
+    case '>': ok = cmp > 0; break
+    case '<': ok = cmp < 0; break
+    case '!=': ok = cmp !== 0; break
+    case '~=': {
+      const spec = parseVersion(want)
+      const got = parseVersion(have)
+      ok = got[0] === spec[0] && got[1] === spec[1] && cmp >= 0
+      break
+    }
+  }
+  if (ok) {
+    pass(`Dependency ${m[1]}==${have} satisfies ${m[1]}${op}${want}`)
+  } else {
+    error(`Dependency ${m[1]} version mismatch: installed ${have}, required ${op}${want}`)
+  }
+}
+
+function checkVenvLayer() {
+  section('F. Runtime Layer — Venv, Python & Dependencies')
+
+  const configDir = join(homedir(), '.config', 'opencode')
+  const venvPython = join(configDir, '.venv', 'bin', 'python3')
+
+  if (!existsSync(venvPython)) {
+    error(`Venv python not found: ${venvPython} (run \`pantheon-opencode init\` to create it)`)
+    return
+  }
+  pass(`Venv python exists: ${venvPython}`)
+
+  const probe = spawn(venvPython, ['-c', 'import sys; print(sys.version.split()[0])'])
+  if (probe.status !== 0) {
+    error(`Venv python does not respond (exit ${probe.status}): ${probe.stderr}`)
+    return
+  }
+  pass(`Venv python responds (Python ${probe.stdout})`)
+
+  const freeze = spawn(venvPython, ['-m', 'pip', 'freeze'])
+  if (freeze.status !== 0) {
+    warn(`pip freeze failed (exit ${freeze.status}) — cannot verify pinned versions`)
+    return
+  }
+  const installed = parsePipFreeze(freeze.stdout)
+
+  const reqFiles = [
+    join(ROOT, 'src', 'mcp', 'requirements-mcp.txt'),
+    join(ROOT, 'src', 'mcp', 'requirements-vision.txt'),
+  ]
+  for (const reqFile of reqFiles) {
+    if (!existsSync(reqFile)) {
+      warn(`requirements file not found: ${reqFile}`)
+      continue
+    }
+    const base = basename(reqFile)
+    info(`Checking ${base} pins against installed packages`)
+    const lines = readFileSync(reqFile, 'utf8').split('\n')
+    let checked = 0
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      checked++
+      checkRequirementLine(trimmed, installed)
+    }
+    if (checked === 0) warn(`${base}: no requirement entries found`)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------
@@ -665,7 +950,7 @@ function printSummary(targetPath) {
 // Main
 // ---------------------------------------------------------------------------
 
-function main() {
+async function main() {
   const args = parseArgs(process.argv)
 
   if (args.help) {
@@ -695,9 +980,11 @@ function main() {
     join(args.target, 'scripts', 'doctor.mjs') === join(ROOT, 'scripts', 'doctor.mjs') ||
     existsSync(join(args.target, 'scripts', 'doctor.mjs')) === false
 
-  // Run checks
+  // Run checks (layer order: Config → Venv → spawn paths → runtime smoke)
   checkAgentFiles(args)
   checkMcpConfig(args)
+  checkVenvLayer(args)
+  await checkMcpRuntimeSmoke(args)
   checkPermissionMismatches(args)
   checkSyncStatus(args)
   checkGitStatus(args)
@@ -707,4 +994,7 @@ function main() {
   process.exit(exitCode)
 }
 
-main()
+main().catch((err) => {
+  console.error(`❌ Doctor crashed: ${err.stack ?? err.message}`)
+  process.exit(2)
+})