pantheon-opencode 1.3.0 → 1.3.1

package/README.md

@@ -187,6 +187,17 @@ opencode
 > **Minimal:** `--headless --no-mcp` installs only agents (~2s).
 > **Full:** `--headless` also creates Python venv + MCP servers (memory, persistence, KV, vision).
 
+### Doctor validation statuses
+
+The doctor reports each check as **PASS**, **WARN**, **ERROR**, or **SKIP**. WARN is
+advisory and exits 0; ERROR is blocking and exits 2. The `global` and `sandbox`
+profiles require the core `pantheon-memory` and `pantheon-resources` MCPs, while
+`lite` treats MCPs and optional helpers (`platform`, `gh_grep`, Context7, and
+`validate-agent-frontmatter.py`) as informational/skipped. Optional warnings are
+never used to hide missing required MCPs. When ERROR and WARN coexist, the final
+summary explicitly reports the blocking error and exit code 2; it never reports a
+positive “no blocking errors” result.
+
 ---
 
 ### Approval Gates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",

package/scripts/doctor.mjs

@@ -18,16 +18,14 @@
  *   node scripts/doctor.mjs --verbose
  *   node scripts/doctor.mjs --help
  *
- * Exit codes:
- *   0 = all green
- *   1 = warnings only
- *   2 = errors (needs attention)
+ * Result classification: PASS, WARN (advisory), ERROR (blocking), or SKIP.
+ * Exit codes: 0 = no blocking errors (warnings are allowed), 2 = errors.
  */
 
 import { spawn as spawnAsync, spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { basename, dirname, join } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 // ---------------------------------------------------------------------------
@@ -67,6 +65,7 @@ function parseArgs(argv) {
     fix: false,
     verbose: false,
     help: false,
+    profile: process.env.PANTHEON_PROFILE ?? 'auto',
   }
 
   for (let i = 2; i < argv.length; i++) {
@@ -83,6 +82,9 @@ function parseArgs(argv) {
       case '--verbose':
         args.verbose = true
         break
+      case '--profile':
+        args.profile = argv[++i] ?? 'auto'
+        break
       case '--help':
       case '-h':
         args.help = true
@@ -97,6 +99,10 @@ function parseArgs(argv) {
     args.target = process.cwd()
   }
 
+  if (args.profile === 'auto') {
+    args.profile = args.target.includes('pantheon-sandbox') ? 'sandbox' : 'global'
+  }
+
   // Resolve to absolute
   if (!args.target.startsWith('/')) {
     args.target = join(process.cwd(), args.target)
@@ -129,7 +135,6 @@ function pass(msg) {
 }
 function warn(msg) {
   emit('warn', msg)
-  if (exitCode < 1) exitCode = 1
 }
 function error(msg) {
   emit('error', msg)
@@ -153,6 +158,7 @@ function showHelp() {
    node scripts/doctor.mjs                              auto-detect, cwd
    node scripts/doctor.mjs --target /path/to/project     target project
    node scripts/doctor.mjs --platform opencode           specific platform
+   node scripts/doctor.mjs --profile global|lite|sandbox profile policy
    node scripts/doctor.mjs --fix                         attempt auto-fixes
    node scripts/doctor.mjs --verbose                     detailed output
    node scripts/doctor.mjs --help                        show this help
@@ -168,9 +174,10 @@ function showHelp() {
    F. Runtime Layer        — venv python + pinned pip dependencies
 
  Exit codes:
-   0  — all checks pass
-   1  — warnings
-   2  — errors
+   0  — no blocking errors (warnings are advisory)
+    2  — blocking errors
+
+  Profiles: global (core MCPs required), lite (MCPs optional), sandbox (core MCPs required)
 
  Report bugs: https://github.com/ils15/pantheon/issues
 `)
@@ -239,7 +246,7 @@ function checkAgentFiles(args) {
 
   // Determine which platforms to check
   if (!existsSync(PLATFORM_DIR)) {
-    warn('Platform component not distributed in this package — skipping platform agent check')
+    info(`Platform component not distributed in this package — platform check skipped (${args.profile} profile)`)
     return
   }
   const platformDirs = readdirSync(PLATFORM_DIR, { withFileTypes: true })
@@ -248,7 +255,7 @@ function checkAgentFiles(args) {
     .filter((name) => !args.platform || name === args.platform)
 
   if (platformDirs.length === 0) {
-    warn(`No platform directories found in platform/`)
+    info(`No platform directories found in platform/ — platform check skipped (${args.profile} profile)`)
     return
   }
 
@@ -354,9 +361,14 @@ function checkMcpConfig(args) {
   section('B. MCP Configuration')
 
   const configs = collectMcpConfigs(args)
+  const requiredMcpNames = args.profile === 'lite' ? [] : ['pantheon-memory', 'pantheon-resources']
 
   if (configs.length === 0) {
-    warn('No opencode.json found in target or user config')
+    if (requiredMcpNames.length > 0) {
+      error(`No opencode.json found; required MCPs missing: ${requiredMcpNames.join(', ')}`)
+    } else {
+      info(`No opencode.json found for ${args.profile} profile — MCP check skipped`)
+    }
     return
   }
 
@@ -365,11 +377,12 @@ function checkMcpConfig(args) {
 
     const mcp = cfg.data.mcp
     if (!mcp || typeof mcp !== 'object') {
-      warn(`${cfg.label}: no "mcp" section`)
+      if (requiredMcpNames.length > 0) error(`${cfg.label}: required MCPs missing — no "mcp" section`)
+      else info(`${cfg.label}: no "mcp" section (${args.profile} profile — optional)`)
       continue
     }
 
-    // 1. gh_grep MCP check
+    // 1. gh_grep MCP check (optional in every supported profile)
     const ghGrep = mcp.gh_grep
     if (ghGrep) {
       if (ghGrep.type === 'remote' && ghGrep.url === 'https://mcp.grep.app') {
@@ -383,7 +396,7 @@ function checkMcpConfig(args) {
         warn(`${cfg.label}: gh_grep MCP may need review — ${detail}`)
       }
     } else {
-      warn(`${cfg.label}: gh_grep MCP not configured`)
+      info(`${cfg.label}: optional gh_grep MCP not configured (${args.profile} profile)`)
     }
 
     // 2. Context7 MCP check
@@ -406,7 +419,7 @@ function checkMcpConfig(args) {
         warn(`${cfg.label}: Context7 MCP issues — ${details.join(', ')}`)
       }
     } else {
-      warn(`${cfg.label}: Context7 MCP not configured`)
+      info(`${cfg.label}: optional Context7 MCP not configured (${args.profile} profile)`)
     }
 
     // 3. Check for deprecated "tools" field format
@@ -450,6 +463,14 @@ function checkMcpConfig(args) {
       }
     }
   }
+
+  if (requiredMcpNames.length > 0) {
+    const configured = new Set(configs.flatMap((cfg) => Object.keys(cfg.data.mcp ?? {})))
+    for (const required of requiredMcpNames) {
+      if (configured.has(required)) pass(`Required MCP "${required}" configured in an available config`)
+      else error(`Required MCP "${required}" not configured in any available config`)
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -558,7 +579,11 @@ async function checkMcpRuntimeSmoke(args) {
   }
 
   if (local.length === 0) {
-    warn('No local MCP servers found in any config — nothing to smoke-test')
+    if (args.profile === 'lite') {
+      info('No local MCP servers found in lite profile — smoke test skipped')
+    } else {
+      error('No local MCP servers found in any config — required runtime MCPs are missing')
+    }
     return
   }
 
@@ -620,7 +645,7 @@ function checkPermissionMismatches(args) {
   // Locate the validation script
   const validator = join(ROOT, 'scripts', 'validate-agent-frontmatter.py')
   if (!existsSync(validator)) {
-    warn('validate-agent-frontmatter.py not found — cannot check permissions')
+    info(`validate-agent-frontmatter.py not found — optional helper skipped (${args.profile} profile)`)
     return
   }
 
@@ -871,14 +896,18 @@ function checkRequirementLine(line, installed) {
   }
 }
 
-function checkVenvLayer() {
+function checkVenvLayer(args) {
   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)`)
+    if (args.profile === 'lite') {
+      info(`Venv python not found — runtime layer skipped for lite profile`)
+    } else {
+      error(`Venv python not found: ${venvPython} (run \`pantheon-opencode init\` to create it)`)
+    }
     return
   }
   pass(`Venv python exists: ${venvPython}`)
@@ -924,6 +953,30 @@ function checkVenvLayer() {
 // Summary
 // ---------------------------------------------------------------------------
 
+/**
+ * Return the final doctor status message without masking blocking errors.
+ * @param {{ error: number; warn: number }} summaryCounts
+ * @param {number} summaryExitCode
+ * @returns {string}
+ */
+export function summaryMessage(summaryCounts, summaryExitCode) {
+  if (summaryCounts.error > 0 || summaryExitCode !== 0) {
+    const errorText = summaryCounts.error > 0
+      ? `${summaryCounts.error} blocking error(s) found`
+      : 'Blocking check failure'
+    const warningText = summaryCounts.warn > 0
+      ? `; ${summaryCounts.warn} warning(s) remain advisory`
+      : ''
+    return `❌ ${errorText}${warningText} — exit code ${summaryExitCode}`
+  }
+
+  if (summaryCounts.warn > 0) {
+    return `⚠️ Checks passed with ${summaryCounts.warn} warning(s) — warnings are advisory`
+  }
+
+  return '✅ All checks passed!'
+}
+
 function printSummary(targetPath) {
   console.log(`\n${'='.repeat(60)}`)
   console.log('  Summary')
@@ -934,13 +987,7 @@ function printSummary(targetPath) {
   console.log(`  ${ICON.info} ${counts.info} info`)
   console.log('')
 
-  if (exitCode === 0) {
-    console.log('  ✅ All checks passed!')
-  } else if (exitCode === 1) {
-    console.log('  ⚠️  Warnings found — review above (some may be auto-fixable with --fix)')
-  } else {
-    console.log('  ❌ Errors found — needs attention')
-  }
+  console.log(`  ${summaryMessage(counts, exitCode)}`)
 
   console.log(`\n  Target: ${process.argv.includes('--target') ? targetPath : 'current directory'}`)
   console.log('')
@@ -994,7 +1041,9 @@ async function main() {
   process.exit(exitCode)
 }
 
-main().catch((err) => {
-  console.error(`❌ Doctor crashed: ${err.stack ?? err.message}`)
-  process.exit(2)
-})
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`❌ Doctor crashed: ${err.stack ?? err.message}`)
+    process.exit(2)
+  })
+}

package/scripts/validation-policy.mjs

@@ -0,0 +1,18 @@
+/** Status/exit policy shared by installation validation and its tests. */
+export const VALIDATION_STATUS = Object.freeze({ PASS: 'PASS', WARN: 'WARN', ERROR: 'ERROR', SKIP: 'SKIP' })
+
+export function classifyDoctorExit(exitStatus, output = '') {
+  if (exitStatus === 0) return VALIDATION_STATUS.PASS
+  if (exitStatus === 1 && !/(?:❌\s*)?[1-9]\d*\s+errors?/i.test(output)) {
+    return VALIDATION_STATUS.WARN
+  }
+  return VALIDATION_STATUS.ERROR
+}
+
+export function classifyTuiExit(exitStatus) {
+  return exitStatus === 0 ? VALIDATION_STATUS.PASS : VALIDATION_STATUS.ERROR
+}
+
+export function validationExitCode(doctorStatus, tuiStatus) {
+  return doctorStatus === VALIDATION_STATUS.ERROR || tuiStatus === VALIDATION_STATUS.ERROR ? 1 : 0
+}

package/src/plugins/hook-runner.ts

@@ -98,21 +98,37 @@ export function runHook(
   const scriptPath = path.join(opts.cwd ?? resolveHooksDir(), script)
   const timeout = opts.timeout ?? HOOK_TIMEOUT_MS
 
+  let serializedPayload: string
+  try {
+    serializedPayload = JSON.stringify(payload)
+  } catch (err) {
+    // Fail closed: a scanner hook must not run without the payload it is
+    // supposed to inspect, and serialization errors must never reject.
+    return Promise.resolve({
+      code: 1,
+      stdout: '',
+      stderr: `payload serialization failed: ${err instanceof Error ? err.message : String(err)}`,
+      signal: null,
+      timedOut: false,
+    })
+  }
+
   return new Promise<HookResult>((resolve) => {
     const stdoutBuf: { value: string } = { value: '' }
     const stderrBuf: { value: string } = { value: '' }
     let settled = false
+    let timedOut = false
+    let timeoutHandle: NodeJS.Timeout | undefined
 
     const settle = (result: HookResult) => {
       if (!settled) {
         settled = true
+        if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)
         resolve(result)
       }
     }
 
     const spawnOpts = {
-      timeout,
-      killSignal: 'SIGKILL' as const,
       env: hookEnv(payload, opts.env),
       // stdio:'pipe' is equivalent to ['pipe','pipe','pipe'] — it guarantees
       // the child's stdin is OUR pipe, NEVER the opencode TUI's terminal
@@ -120,6 +136,10 @@ export function runHook(
       // the opencode core hook timeout).
       stdio: 'pipe' as const,
       windowsHide: true,
+      // A process group lets the timeout kill shell descendants too. Without
+      // this, a shell hook can leave `sleep` holding stdout/stderr open after
+      // the shell itself receives SIGKILL, so the Promise would not settle.
+      ...(process.platform !== 'win32' ? { detached: true } : {}),
       ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
     }
 
@@ -172,15 +192,35 @@ export function runHook(
         stdout: stdoutBuf.value,
         stderr: stderrBuf.value,
         signal,
-        timedOut: code === null && signal === 'SIGKILL',
+        timedOut,
       })
     })
 
+    timeoutHandle = setTimeout(() => {
+      timedOut = true
+      try {
+        // Negative PIDs target the process group created by `detached`.
+        if (process.platform !== 'win32' && child.pid !== undefined) {
+          process.kill(-child.pid, 'SIGKILL')
+        } else {
+          child.kill('SIGKILL')
+        }
+      } catch {
+        // The child may have exited between the timer and kill call. The
+        // close/error handlers still produce the structured result.
+        try {
+          child.kill('SIGKILL')
+        } catch {
+          // Hooks must never leak a kill failure to the plugin host.
+        }
+      }
+    }, timeout)
+
     // Deliver the Claude Code protocol JSON on stdin. stdin.end() runs
     // UNCONDITIONALLY — even for an empty payload {} or a script that never
     // reads stdin — so the child can never block waiting for input and hit
     // the runtime hook timeout (reported as "Hook X timed out after 30000ms").
-    child.stdin.write(JSON.stringify(payload))
+    child.stdin.write(serializedPayload)
     child.stdin.end()
   })
 }

package/src/plugins/tui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pantheon-tui",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pantheon-tui",
-      "version": "1.0.0",
+      "version": "1.3.0",
       "license": "MIT",
       "dependencies": {
         "@opencode-ai/plugin": ">=1.14.0",
@@ -1526,9 +1526,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.2.tgz",
-      "integrity": "sha512-w5JZcKgdhDOgOwm8H+KgbosopHMuGcl6qbulwjtz3SM7I7P3yW1eAjzMPLrIE+NQ9vjgANKHWeMHnrT0OXW1oA==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.4.tgz",
+      "integrity": "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0"
@@ -2703,6 +2703,20 @@
       "license": "0BSD",
       "optional": true
     },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "license": "Apache-2.0",
+      "peer": true,
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
     "node_modules/unconfig-core": {
       "version": "7.5.0",
       "resolved": "https://registry.npmjs.org/unconfig-core/-/unconfig-core-7.5.0.tgz",
@@ -2773,6 +2787,21 @@
         "url": "https://github.com/sponsors/sxzz"
       }
     },
+    "node_modules/web-tree-sitter": {
+      "version": "0.25.10",
+      "resolved": "https://registry.npmjs.org/web-tree-sitter/-/web-tree-sitter-0.25.10.tgz",
+      "integrity": "sha512-Y09sF44/13XvgVKgO2cNDw5rGk6s26MgoZPXLESvMXeefBf7i6/73eFurre0IsTW6E14Y0ArIzhUMmjoc7xyzA==",
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "@types/emscripten": "^1.40.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/emscripten": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",

package/src/plugins/tui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon-tui",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Pantheon TUI plugin — sidebar (agents, sessions, commands, config, memory, active preset) + AI subscription usage gauges incl. OpenCode Go/Zen dollar limits (vendored, MIT)",
   "license": "MIT",
   "exports": {