pantheon-opencode 1.2.1 → 1.3.0

package/scripts/prune.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * prune.mjs — Pantheon legacy cleanup CLI (issue #22)
+ *
+ * Finds and (with explicit flags) removes legacy artifacts left by previous
+ * Pantheon versions — old global installs, stale config backups, dead
+ * legacy config directories — following the XDG Base Directory spec.
+ *
+ * SAFETY: prune NEVER touches the active config, the active venv, the package
+ * repo, or the installed package. It only:
+ *   - lists old global `pantheon` installs (suggests `npm uninstall -g pantheon`)
+ *   - removes stale `opencode.json.bak*` backups (age > threshold) with --apply
+ *   - lists legacy directories whose opencode.json references dead/relative
+ *     paths (removal requires --apply --remove-dirs as explicit confirmation)
+ *
+ * Usage:
+ *   node scripts/prune.mjs                        # dry-run (default): list only
+ *   node scripts/prune.mjs --apply                # remove stale backups
+ *   node scripts/prune.mjs --apply --remove-dirs  # also remove legacy dirs
+ *   node scripts/prune.mjs --target <dir>         # override config dir (tests)
+ *   node scripts/prune.mjs --age 30               # backup age threshold (days)
+ *   node scripts/prune.mjs --help
+ *
+ * Exit codes:
+ *   0 = nothing to clean (or everything cleaned)
+ *   1 = findings remain (dry-run listed items, or items kept)
+ *   2 = usage error
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, '..')
+const DEFAULT_BACKUP_AGE_DAYS = 30
+
+// ---------------------------------------------------------------------------
+// XDG config resolution — parity with _pantheon_paths.py and bin/pantheon-init
+//   PANTHEON_HOME → $XDG_CONFIG_HOME/opencode → ~/.config/opencode
+// ---------------------------------------------------------------------------
+
+export function resolveConfigDir(target) {
+  if (target) return resolve(target)
+  if (process.env.PANTHEON_HOME) return resolve(process.env.PANTHEON_HOME)
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  return join(base, 'opencode')
+}
+
+// ---------------------------------------------------------------------------
+// Finding model
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ type: string, target: string, detail: string, action: 'suggest'|'remove'|'list'|'keep' }} Finding
+ */
+
+/** @type {Finding[]} */
+const findings = []
+
+function add(type, target, detail, action) {
+  findings.push({ type, target, detail, action })
+}
+
+// ---------------------------------------------------------------------------
+// (a) Old global `pantheon` install (private package, never published)
+//     → suggestion only: NEVER remove node_modules directly (npm-managed).
+// ---------------------------------------------------------------------------
+
+export function findLegacyGlobalInstalls() {
+  const nodeModulesDirs = new Set()
+  const knownLegacy = join(homedir(), '.npm-global', 'lib', 'node_modules')
+  if (existsSync(knownLegacy)) nodeModulesDirs.add(knownLegacy)
+  try {
+    const npmPrefix = execSync('npm prefix -g', { encoding: 'utf8' }).trim()
+    if (npmPrefix) nodeModulesDirs.add(join(npmPrefix, 'lib', 'node_modules'))
+  } catch {
+    // npm unavailable — fall back to the known legacy location only
+  }
+
+  for (const dir of nodeModulesDirs) {
+    // `pantheon` (legacy name) — NOT `pantheon-opencode` (current package)
+    const pkgDir = join(dir, 'pantheon')
+    const pkgJsonPath = join(pkgDir, 'package.json')
+    if (!existsSync(pkgJsonPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
+      if (pkg.name === 'pantheon' && pkg.private === true) {
+        add(
+          'global-install',
+          pkgDir,
+          `legacy private package pantheon@${pkg.version || '?'} — bin 'pantheon' conflicts with pantheon-opencode`,
+          'suggest',
+        )
+      }
+    } catch {
+      // unreadable package.json — skip
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// (b) Stale opencode.json.bak* backups (age > threshold) in the config dir
+//     → removable with --apply. Fresh backups are listed as kept.
+// ---------------------------------------------------------------------------
+
+export function findStaleBackups(configDir, maxAgeDays = DEFAULT_BACKUP_AGE_DAYS) {
+  if (!existsSync(configDir)) return
+  const cutoffMs = Date.now() - maxAgeDays * 86_400_000
+  for (const name of readdirSync(configDir)) {
+    if (!name.startsWith('opencode.json.bak')) continue
+    const full = join(configDir, name)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+    const ageDays = Math.floor((Date.now() - st.mtimeMs) / 86_400_000)
+    if (st.mtimeMs < cutoffMs) {
+      add('backup', full, `age ~${ageDays}d > ${maxAgeDays}d threshold`, 'remove')
+    } else {
+      add('backup-fresh', full, `age ~${ageDays}d ≤ ${maxAgeDays}d — kept`, 'keep')
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// (c) Legacy directories with dead config (relative/nonexistent paths)
+//     → listed only; removal needs --apply --remove-dirs (explicit confirm).
+// ---------------------------------------------------------------------------
+
+const LEGACY_DIR_NAMES = ['pantheon-legacy', 'legacy', 'old', 'backup', 'backups']
+
+/** Collect opencode.json candidates inside a dir (depth ≤ 2). */
+function collectConfigCandidates(dir) {
+  const candidates = []
+  const walk = (d, depth) => {
+    if (depth > 2) return
+    let entries
+    try {
+      entries = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) walk(full, depth + 1)
+      else if (entry.isFile() && entry.name === 'opencode.json') candidates.push(full)
+    }
+  }
+  walk(dir, 0)
+  return candidates
+}
+
+/** True when an opencode.json references relative or non-existent paths. */
+export function configHasDeadPaths(configPath) {
+  let cfg
+  try {
+    cfg = JSON.parse(readFileSync(configPath, 'utf8'))
+  } catch {
+    return true // unparseable config in a legacy dir counts as dead
+  }
+
+  const check = (value, where) => {
+    if (typeof value !== 'string' || value === '') return
+    if (value.startsWith('file://')) return
+    if (!value.startsWith('/')) return true // relative path in a config
+    if (!existsSync(value)) return true // absolute but missing
+    return false
+  }
+
+  // agent sources
+  for (const agent of Object.values(cfg.agent || {})) {
+    if (agent && typeof agent === 'object' && check(agent.source, 'agent.source')) return true
+  }
+  // instructions
+  for (const instr of cfg.instructions || []) {
+    if (check(instr, 'instructions')) return true
+  }
+  // mcp cwd + command[0] (when not a bare command name like python3)
+  for (const [key, mcp] of Object.entries(cfg.mcp || {})) {
+    if (!mcp || typeof mcp !== 'object') continue
+    if (mcp.cwd && check(mcp.cwd, `mcp.${key}.cwd`)) return true
+    const cmd = Array.isArray(mcp.command) ? mcp.command[0] : undefined
+    if (cmd && typeof cmd === 'string' && cmd.includes('/') && check(cmd, `mcp.${key}.command`)) {
+      return true
+    }
+  }
+  return false
+}
+
+export function findLegacyDirs(configDir) {
+  if (!existsSync(configDir)) return
+  for (const entry of readdirSync(configDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !LEGACY_DIR_NAMES.includes(entry.name)) continue
+    const dir = join(configDir, entry.name)
+    const deadConfigs = collectConfigCandidates(dir).filter(configHasDeadPaths)
+    if (deadConfigs.length > 0) {
+      add(
+        'legacy-dir',
+        dir,
+        `dead config(s): ${deadConfigs.map((c) => c.replace(dir + '/', '')).join(', ')}`,
+        'list',
+      )
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Extra: legacy `~/.opencode` install dir (pre-XDG location)
+//     → listed only, manual review.
+// ---------------------------------------------------------------------------
+
+export function findLegacyInstallDir(configDir) {
+  const legacyDir = join(homedir(), '.opencode')
+  if (legacyDir === configDir) return
+  if (!existsSync(join(legacyDir, 'opencode.json'))) return
+  add(
+    'legacy-install',
+    legacyDir,
+    'pre-XDG install location — review manually; not removed automatically',
+    'list',
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+function format(f) {
+  const icon =
+    f.action === 'remove' ? '🗑️' : f.action === 'suggest' ? '💡' : f.action === 'keep' ? '✅' : '🔎'
+  return `${icon} [${f.type}] ${f.target} — ${f.detail}`
+}
+
+export function runPrune({ configDir, maxAgeDays, apply, removeDirs }) {
+  findLegacyGlobalInstalls()
+  findStaleBackups(configDir, maxAgeDays)
+  findLegacyDirs(configDir)
+  findLegacyInstallDir(configDir)
+
+  console.log(`Pantheon prune — config dir: ${configDir}`)
+  console.log(`  mode: ${apply ? 'APPLY' : 'DRY-RUN'}${removeDirs ? ' + REMOVE-DIRS' : ''}`)
+  console.log('')
+
+  if (findings.length === 0) {
+    console.log('  ✅ Nothing to clean.')
+    return { removed: 0, remain: 0 }
+  }
+
+  let removed = 0
+  let remain = 0
+  for (const f of findings) {
+    console.log(`  ${format(f)}`)
+    if (f.action === 'remove' && apply) {
+      try {
+        rmSync(f.target, { force: true })
+        console.log(`     → removed`)
+        removed++
+        continue
+      } catch (err) {
+        console.log(`     → ⚠️ failed: ${err.message}`)
+        remain++
+        continue
+      }
+    }
+    if (f.action === 'remove' && !apply) {
+      // dry-run: count as "would remove"
+      removed++
+      continue
+    }
+    if (f.action === 'list' && apply && removeDirs) {
+      try {
+        rmSync(f.target, { recursive: true, force: true })
+        console.log(`     → removed (--remove-dirs)`)
+        removed++
+        continue
+      } catch (err) {
+        console.log(`     → ⚠️ failed: ${err.message}`)
+        remain++
+        continue
+      }
+    }
+    if (f.action === 'list' && apply && !removeDirs) {
+      console.log('     → kept: directory removal requires --apply --remove-dirs')
+      remain++
+    } else if (f.action === 'suggest') {
+      console.log('     → action: npm uninstall -g pantheon (not run automatically)')
+      remain++
+    } else if (f.action === 'keep' || f.action === 'list') {
+      remain++
+    }
+  }
+
+  console.log('')
+  const hint = apply ? '' : ' — run with --apply to remove stale backups'
+  console.log(
+    `  ${apply ? 'Removed' : 'Would remove'}: ${removed} item(s); remaining: ${remain}${hint}`,
+  )
+  return { removed, remain }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function printUsage() {
+  console.log(`Pantheon prune — legacy cleanup (issue #22)
+
+Usage:
+  node scripts/prune.mjs [options]
+
+Options:
+  --apply            Remove stale backups (default: dry-run, list only)
+  --remove-dirs      With --apply, also remove legacy directories
+                     (explicit confirmation; default: list only)
+  --target <dir>     Override the config directory (XDG-aware by default)
+  --age <days>       Backup age threshold in days (default: ${DEFAULT_BACKUP_AGE_DAYS})
+  --help             Show this help
+
+Safety:
+  Never removes: active opencode.json, active .venv, package repo, or the
+  installed pantheon-opencode package. Old global 'pantheon' installs are
+  only suggested for manual 'npm uninstall -g pantheon'.
+
+Exit codes: 0 = clean, 1 = findings remain, 2 = usage error`)
+}
+
+function main() {
+  const args = process.argv.slice(2)
+  if (args.includes('--help') || args.includes('-h')) {
+    printUsage()
+    process.exit(0)
+  }
+
+  const apply = args.includes('--apply') || args.includes('-y')
+  const removeDirs = args.includes('--remove-dirs')
+  const targetIdx = args.indexOf('--target')
+  const target = targetIdx >= 0 ? args[targetIdx + 1] : undefined
+  const ageIdx = args.indexOf('--age')
+  const age = ageIdx >= 0 ? Number(args[ageIdx + 1]) : DEFAULT_BACKUP_AGE_DAYS
+  if (!Number.isFinite(age) || age < 0) {
+    console.error('❌ --age must be a non-negative number of days')
+    process.exit(2)
+  }
+
+  const configDir = resolveConfigDir(target)
+  const result = runPrune({ configDir, maxAgeDays: age, apply, removeDirs })
+
+  // 0 = clean/cleaned; 1 = findings remain; 2 = usage error (handled above)
+  process.exit(result.remain > 0 ? 1 : 0)
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/version-check.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * version-check.mjs — Single source of truth enforcement
+ *
+ * package.json is the SOURCE OF TRUTH for the Pantheon version.
+ * Every other manifest (pyproject.toml, plugin.json, src/plugins/tui/package.json)
+ * MUST carry the same version. This script:
+ *
+ *   - compares every manifest against package.json and prints a divergence
+ *     table when they differ (exit code 1),
+ *   - with --fix, rewrites each divergent manifest to the package.json version.
+ *
+ * Mirrors the MANIFEST_FILES list in scripts/versioning.mjs so `apply`
+ * and `check` can never drift apart.
+ *
+ * Usage:
+ *   node scripts/version-check.mjs          # verify (exit 0 = in sync)
+ *   node scripts/version-check.mjs --fix    # sync all manifests
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+/** Same set of manifests as versioning.mjs (minus package.json itself). */
+export const MANIFESTS = [
+  { name: 'pyproject.toml', file: 'pyproject.toml', kind: 'toml' },
+  { name: 'plugin.json', file: 'plugin.json', kind: 'json' },
+  { name: 'src/plugins/tui/package.json', file: join('src', 'plugins', 'tui', 'package.json'), kind: 'json' },
+]
+
+function readTomlVersion(filePath) {
+  const text = readFileSync(filePath, 'utf-8')
+  const match = text.match(/^version\s*=\s*"([^"]+)"/m)
+  if (!match) throw new Error(`no version field in ${filePath}`)
+  return match[1]
+}
+
+function readJsonVersion(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf-8')).version
+}
+
+function readManifestVersion(filePath, kind) {
+  try {
+    return kind === 'toml' ? readTomlVersion(filePath) : readJsonVersion(filePath)
+  } catch {
+    return null
+  }
+}
+
+function writeManifestVersion(filePath, kind, version) {
+  if (kind === 'toml') {
+    const text = readFileSync(filePath, 'utf-8')
+    const updated = text.replace(/^(version\s*=\s*")[^"]+(")/m, `$1${version}$2`)
+    writeFileSync(filePath, updated)
+  } else {
+    const content = JSON.parse(readFileSync(filePath, 'utf-8'))
+    content.version = version
+    writeFileSync(filePath, `${JSON.stringify(content, null, 2)}\n`)
+  }
+}
+
+/**
+ * Compare every manifest version against package.json (source of truth).
+ *
+ * @param {string} root - repository root containing package.json + manifests
+ * @returns {{source: string, manifests: Array<{name: string, version: string|null, ok: boolean}>, ok: boolean}}
+ *   - source: version read from package.json
+ *   - manifests: per-manifest {name, version (null when unreadable), ok}
+ *   - ok: true when every manifest matches the source version
+ */
+export function compareVersions(root) {
+  const source = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version
+  const manifests = MANIFESTS.map(({ name, file, kind }) => {
+    const version = readManifestVersion(join(root, file), kind)
+    return { name, version, ok: version === source }
+  })
+  return { source, manifests, ok: manifests.every((m) => m.ok) }
+}
+
+/**
+ * Rewrite every divergent manifest to the package.json version.
+ *
+ * @param {string} root - repository root
+ * @returns {number} count of manifests rewritten
+ */
+export function syncToSource(root) {
+  const { source, manifests } = compareVersions(root)
+  let changed = 0
+  for (const manifest of manifests) {
+    if (manifest.ok) continue
+    const def = MANIFESTS.find((m) => m.name === manifest.name)
+    writeManifestVersion(join(root, def.file), def.kind, source)
+    changed += 1
+  }
+  return changed
+}
+
+function printDivergenceTable(result) {
+  const rows = [
+    ['manifest', 'version', 'status'],
+    ...result.manifests.map((m) => [m.name, m.version ?? 'MISSING', m.ok ? 'ok' : 'DIVERGENT']),
+  ]
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((row) => row[i].length)))
+  console.log(`Source of truth: package.json → v${result.source}\n`)
+  for (const row of rows) {
+    console.log(row.map((cell, i) => cell.padEnd(widths[i])).join('  '))
+  }
+  console.log('')
+}
+
+const isDirectRun =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (isDirectRun) {
+  // npm scripts run from the package root, so the working directory is the
+  // repository root to check. Explicit cwd keeps the CLI testable.
+  const root = process.cwd()
+  const fix = process.argv.includes('--fix')
+  let result
+  try {
+    result = compareVersions(root)
+  } catch (error) {
+    console.error(`version-check: cannot read package.json — ${error.message}`)
+    process.exit(1)
+  }
+
+  if (result.ok) {
+    console.log(`✓ All manifests match package.json v${result.source}`)
+    process.exit(0)
+  }
+
+  printDivergenceTable(result)
+  if (fix) {
+    const changed = syncToSource(root)
+    const after = compareVersions(root)
+    if (after.ok) {
+      console.log(`✓ Synced ${changed} manifest(s) to v${after.source}`)
+      process.exit(0)
+    }
+    console.error(`version-check: sync incomplete — ${after.manifests.filter((m) => !m.ok).length} manifest(s) still divergent`)
+    process.exit(1)
+  }
+  console.error('version-check: manifests out of sync (run with --fix to sync)')
+  process.exit(1)
+}

package/scripts/versioning.mjs

@@ -29,7 +29,7 @@ const MANIFEST_FILES = [
   'pyproject.toml',
   'package.json',
   'plugin.json',
-  '.github/plugin/plugin.json',
+  'src/plugins/tui/package.json',
 ]
 
 const CHANGELOG_PATH = join(ROOT, 'CHANGELOG.md')
@@ -47,8 +47,11 @@ function run(cmd) {
 }
 
 function getLatestTag() {
-  // Use numerically highest tag, not just nearest git ancestor
-  const tag = run("git tag -l 'v[0-9]*.[0-9]*.[0-9]*' | sort -V | tail -1")
+  // Stable tags only: strict vX.Y.Z with NO pre-release suffix.
+  // The loose glob `v[0-9]*.[0-9]*.[0-9]*` ALSO matches v1.2.0-beta.9.*
+  // (the trailing `*` swallows the -beta suffix), which would poison the
+  // version gate — so filter strictly before sorting.
+  const tag = run("git tag -l 'v*' | grep -E '^v[0-9]+\\.[0-9]+\\.[0-9]+$' | sort -V | tail -1")
   return tag || 'v0.0.0'
 }
 
@@ -207,13 +210,15 @@ switch (command) {
     const latestVer = latestTag.replace(/^v/, '')
 
     // If package.json is already ahead of the latest tag, someone bumped
-    // without tagging — warn and use the current version as-is.
+    // without tagging — warn and use the current version as-is. Tags are
+    // workflow-owned, so there is nothing to create here.
     if (current !== latestVer) {
       console.log(`⚠ package.json (${current}) already ahead of latest tag (${latestTag}).`)
       console.log(`  Syncing all manifests to ${current} and promoting CHANGELOG.`)
       updateManifests(current)
       const date = new Date().toISOString().slice(0, 10)
       promoteUnreleased(current, date)
+      console.log(`Tag v${current} will be created by the release workflow after merge to main.`)
       break
     }
 
@@ -226,16 +231,10 @@ switch (command) {
     promoteUnreleased(newVersion, date)
     console.log(`\nDone. Commit with: git add -A && git commit -m "chore(release): v${newVersion}"`)
 
-    // Create git tag
-    try {
-      const tag = `v${newVersion}`
-      execSync(`git tag -a ${tag} -m "chore(release): ${tag}"`, { stdio: 'inherit' })
-      console.log(`Tag ${tag} created locally. Push: git push origin ${tag}`)
-      console.log(`Auto-release will trigger on main after merge.`)
-    } catch (e) {
-      console.warn(`Tag creation failed: ${e.message}`)
-      console.log('Create manually: git tag -a v' + newVersion + ' -m "chore(release): v' + newVersion + '"')
-    }
+    // Tags are owned by the release workflow — never create them locally.
+    // A local tag on a pre-merge commit drifts from the merged main state
+    // (the untagged-v1.2.1 root cause) and would desync the version gate.
+    console.log(`Tag v${newVersion} will be created by the release workflow after merge to main.`)
     break
   }
 

package/src/agents/zeus.md

@@ -95,6 +95,13 @@ kv_store("delegation:<pattern>", "{agent: ..., background: true/false}")
 kv_get("delegation:<pattern>") → reusa decisao sem memory_search
 ```
 
+### Telemetria de delegacao (Nyx P1-3)
+
+Toda decisao de delegacao grava UM registro `DelegationCacheDecision` no
+namespace `delegation-telemetry` via kv_store: {hit|miss|writeback|corrected,
+pattern, agent, source: cache|routing|user}. Em re-roteamento (recusa P0-3),
+adicione {reroute_from, reroute_to, delegation_id, source}. Uma linha por delegacao.
+
 ## REGRA DE OURO: NUNCA USE general
 
 **`subagent_type: general` e `subagent_type: explore` sao PROIBIDOS.** Nao existem no Pantheon.
@@ -113,13 +120,16 @@ Tarefa envolve:
    AI, RAG, LangChain, embeddings, vetores -> @hephaestus
    observabilidade, tracing, monitoramento -> @nyx
    GitHub, PR, issues, releases, branches -> @iris
-   documentacao, memory-bank, ADRs -> @mnemosyne
+   documentacao de PROJETO (README, docs/, changelog) -> @talos (trivial) | implementador (tecnica) | @iris (changelog/release)
+   documentacao de SISTEMA (.pantheon/memory-bank/, ADRs, task records) -> @mnemosyne
    hotfix rapido, bug pequeno, typo, CSS -> @talos
 
 NENHUMA das acima? -> E descoberta? @apollo. E planejamento? @athena.
 Ainda assim sem match? -> Pergunte ao usuario qual agente usar. NUNCA use general.
 ```
 
+REGRA: "fora de .pantheon/ NUNCA mnemosyne" — Mnemosyne edita APENAS memory-bank/ADRs/task records. Docs de projeto (README, docs/) vão para talos/implementador/iris.
+
 ## Background Delegation (PADRAO: background=true)
 
 **Requer:** `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` (env var)
@@ -199,6 +209,15 @@ Zeus (nivel 0) -> Apollo/Hermes (nivel 1) -> sub-subagente (nivel 2 max).
 - Env var: `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`
 - Guards: `instructions/zeus-timeout-retry.instructions.md`
 
+## Taxonomia de Recusa (P0-3)
+
+Quando um subagente RECUSA ou retorna "escopo fora do meu dominio" (ex: edit: deny, scope boundary):
+
+- **Causa provavel:** agente errado selecionado no roteamento (match por palavra-chave, nao por capacidade).
+- **ACAO:** RE-ROTEAR imediatamente para o agente correto — NAO retry com prompt reformulado.
+- Registre o caso no cache de delegacao (`kv_store("deleg:<pattern>", ...)` para aprendizado futuro).
+- Recusa legitima do agente = comportamento correto do guard; o defeito esta na selecao (zeus), nao no agente.
+
 ## TODO Enforcer (Auto-Retry)
 
 **Se um agente delegado falhar ou travar, recupere automaticamente.**
@@ -207,13 +226,22 @@ Zeus (nivel 0) -> Apollo/Hermes (nivel 1) -> sub-subagente (nivel 2 max).
 ```
 Apos task_status(wait=true), verifique:
   result.state == "error" ou timeout?
-    SIM → retry 1x com prompt rephrased (diferente, mais especifico)
-    Ainda erro → escalate: "Agente X falhou 2x. Opcoes: (a) tentar outro, (b) simplificar, (c) pular"
+    SIM → ANTES de retry: detecte a CAUSA na mensagem de erro
+
+    RECUSA / scope-boundary (result contem "edit: deny", "escopo fora do meu dominio",
+    "reviewer-only", "fora do meu dominio", ou similar negativa de dominio)?
+      SIM → NAO retry com prompt rephrased.
+            RE-ROTEAR para o agente correto (ver "Taxonomia de Recusa (P0-3)").
+            Registre o caso: kv_store("deleg:<pattern>", "{agente_correto, ...}").
+
+    FALHA REAL (timeout, crash, resposta vazia, context exceeded)?
+      SIM → retry 1x com prompt rephrased (diferente, mais especifico)
+      Ainda erro → escalate: "Agente X falhou 2x. Opcoes: (a) tentar outro, (b) simplificar, (c) pular"
 ```
 
 ### Regras
-- **1 retry automatico** — 2a falha = escalate, nao loop infinito
-- **Rephrase o prompt** — nao mande o mesmo texto. Mais especifico, menos escopo
+- **1 retry automatico APENAS para falha real** — recusa/scope-boundary NUNCA gera retry; gera re-roteamento
+- **Rephrase o prompt** — so em falha real (timeout/crash/vazio), nao em recusa de dominio
 - **Timeout** — sempre `timeout_ms=120000` em task_status(). Pesquisa leva tempo
 - **Stall** — 3+ turns sem progresso util? Troque de agente ou abordagem
 

package/src/mcp/requirements-mcp.txt

@@ -1,5 +1,8 @@
-mcp>=1.28.0
-fastmcp>=3.4.0
-pyyaml>=6.0
-sqlite-vec>=0.1.7
-fastembed>=0.5.0
+# Pantheon MCP runtime dependencies — EXACT pins (issue #21)
+# Pinned to the versions validated in the sandbox venv (2026-08-05).
+# Update deliberately via: pip install -U <pkg> && pip freeze | grep -iE '^(mcp|fastmcp|pyyaml|sqlite-vec|fastembed)'
+mcp==1.29.0
+fastmcp==3.4.6
+pyyaml==6.0.3
+sqlite-vec==0.1.9
+fastembed==0.8.0

package/src/mcp/requirements-vision.txt

@@ -1,3 +1,3 @@
-mcp>=1.28.0
-fastmcp>=3.4.0
-httpx>=0.27.0
+mcp==1.29.0
+fastmcp==3.4.6
+httpx==0.28.1