pantheon-opencode 1.5.0-beta.2 → 1.5.0-beta.20

package/scripts/versioning.mjs

@@ -6,45 +6,46 @@
  *   recommend            Analyze commits and suggest next version bump type
  *   apply [type]         Bump manifests + move [Unreleased] → [vX.Y.Z] in CHANGELOG
  *                        type: patch | minor | major | auto (default: auto)
+ *                        --beta: bump the committed beta line instead
+ *   beta                 Alias for `apply --beta`
  *   changelog [ver]      (Internal) Insert a versioned section into CHANGELOG
  *                        Normally called by `apply`; can be run standalone.
  *   status               Show current version, latest tag, and pending bump type
  *
- * Design: the release signal is "package.json version > latest git tag".
- * Developers (or AI agents) call `apply` to bump + update CHANGELOG, then push.
- * The auto-release workflow detects the version bump and creates the release.
- * No version bumping ever happens inside GitHub Actions.
+ * Design: the release signal is "package.json version > latest git tag" for
+ * stable, and "package.json version is a committed X.Y.Z-beta.N" for beta.
+ * Developers (or AI agents) call `apply` (or `apply --beta` / `beta`) to bump
+ * the manifests and promote CHANGELOG.md, then push. The dispatch-only release
+ * workflow reads the committed version and creates the release. No version
+ * bumping ever happens inside GitHub Actions.
  */
 
-import { execSync } from 'node:child_process'
-import { readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  commitPreparedUpdates,
+  prepareInventoryVersion,
+  SEMVER_PATTERN,
+  validateInventory,
+} from './manifest-inventory.mjs'
+import { nextBetaVersion } from './release-beta-version.mjs'
 import { collectEntries, groupCommits, parseCommitLine, renderChangelog } from './release-notes.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..')
 
-const MANIFEST_FILES = [
-  // 'platform/forge.json' removed in v1.0 — directory no longer exists
-  'pyproject.toml',
-  'package.json',
-  'plugin.json',
-  'src/plugins/tui/package.json',
-]
-
 const CHANGELOG_PATH = join(ROOT, 'CHANGELOG.md')
+const ZENODO_PATH = join(ROOT, '.zenodo.json')
+const CITATION_PATH = join(ROOT, 'CITATION.cff')
 
 // ---------------------------------------------------------------------------
 // Git helpers
 // ---------------------------------------------------------------------------
 
-function run(cmd) {
-  try {
-    return execSync(cmd, { cwd: ROOT, encoding: 'utf-8' }).trim()
-  } catch {
-    return ''
-  }
+function runGit(args) {
+  return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }).trim()
 }
 
 function getLatestTag() {
@@ -52,12 +53,15 @@ function getLatestTag() {
   // 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'
+  const tags = runGit(['tag', '-l', 'v*'])
+    .split('\n')
+    .filter((tag) => /^v\d+\.\d+\.\d+$/.test(tag))
+  tags.sort((left, right) => compareStable(left.slice(1), right.slice(1)))
+  return tags.at(-1) || 'v0.0.0'
 }
 
 function getCurrentVersion() {
-  return JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version
+  return validateInventory(ROOT).sourceVersion
 }
 
 // ---------------------------------------------------------------------------
@@ -65,7 +69,10 @@ function getCurrentVersion() {
 // ---------------------------------------------------------------------------
 
 function bumpVersion(version, type) {
-  const [major, minor, patch] = version.split('.').map(Number)
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(version)
+  if (!match) throw new Error(`cannot bump invalid semver: ${version}`)
+  if (!['major', 'minor', 'patch'].includes(type)) throw new Error(`invalid bump type: ${type}`)
+  const [major, minor, patch] = match.slice(1).map(Number)
   switch (type) {
     case 'major':
       return `${major + 1}.0.0`
@@ -76,8 +83,17 @@ function bumpVersion(version, type) {
   }
 }
 
+function compareStable(left, right) {
+  const a = left.split('.').map(Number)
+  const b = right.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index]
+  }
+  return 0
+}
+
 function analyzeConventionalCommits(since) {
-  const log = run(`git log ${since}..HEAD --format="%s"`)
+  const log = runGit(['log', `${since}..HEAD`, '--format=%s'])
   if (!log) return 'patch'
   let bump = 'patch'
   for (const msg of log.split('\n').filter(Boolean)) {
@@ -91,27 +107,94 @@ function analyzeConventionalCommits(since) {
 // Manifest updater
 // ---------------------------------------------------------------------------
 
-function updateManifests(newVersion) {
-  for (const file of MANIFEST_FILES) {
-    const path = join(ROOT, file)
-    try {
-      const raw = readFileSync(path, 'utf-8')
-      if (file.endsWith('.toml')) {
-        // TOML: replace version = "X.Y.Z"
-        const updated = raw.replace(/^(version\s*=\s*")[^"]+(")/m, `$1${newVersion}$2`)
-        writeFileSync(path, updated)
-        console.log(`  ✓ ${file} → ${newVersion}`)
-      } else {
-        // JSON
-        const content = JSON.parse(raw)
-        content.version = newVersion
-        writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`)
-        console.log(`  ✓ ${file} → ${newVersion}`)
+function prepareManifests(newVersion) {
+  if (!SEMVER_PATTERN.test(newVersion)) throw new Error(`invalid version: ${newVersion}`)
+  const inventory = validateInventory(ROOT, { allowVersionDivergence: true })
+  return { inventory, updates: prepareInventoryVersion(inventory, newVersion) }
+}
+
+/**
+ * Serialize `.zenodo.json` the way Biome 2.x formats it: objects stay expanded
+ * (matching `JSON.stringify(value, null, 2)`), while arrays containing only
+ * primitives are collapsed onto one line when they fit within the line width.
+ * A plain `JSON.stringify` emits the `keywords` array multiline, which Biome
+ * collapses — reintroducing a lint failure on the next release bump.
+ *
+ * @param {unknown} value parsed JSON document
+ * @param {number} [lineWidth] formatter line width (matches biome.json)
+ * @returns {string} Biome-compatible JSON with a trailing newline
+ */
+function formatZenodoJson(value, lineWidth = 100) {
+  const indent = (depth) => '  '.repeat(depth)
+  const render = (node, depth, column) => {
+    if (Array.isArray(node)) {
+      if (node.length === 0) return '[]'
+      const primitiveOnly = node.every((item) => item === null || typeof item !== 'object')
+      if (primitiveOnly) {
+        const inline = `[${node.map((item) => JSON.stringify(item)).join(', ')}]`
+        if (column + inline.length <= lineWidth) return inline
       }
-    } catch {
-      console.log(`  ⚠ ${file} not found — skipped`)
+      const body = node
+        .map((item) => `${indent(depth + 1)}${render(item, depth + 1, indent(depth + 1).length)}`)
+        .join(',\n')
+      return `[\n${body}\n${indent(depth)}]`
+    }
+    if (node !== null && typeof node === 'object') {
+      const entries = Object.entries(node)
+      if (entries.length === 0) return '{}'
+      const body = entries
+        .map(([key, item]) => {
+          const keyPrefix = `${indent(depth + 1)}${JSON.stringify(key)}: `
+          return `${keyPrefix}${render(item, depth + 1, keyPrefix.length)}`
+        })
+        .join(',\n')
+      return `{\n${body}\n${indent(depth)}}`
     }
+    return JSON.stringify(node)
   }
+  return `${render(value, 0, 0)}\n`
+}
+
+/**
+ * Keep the Zenodo deposition metadata (.zenodo.json) and the citation file
+ * (CITATION.cff) aligned with the version and date being released. Zenodo's
+ * release validator hard-fails when CITATION.cff version differs from the
+ * release tag, so these must be bumped together with the manifests.
+ */
+function prepareReleaseMetadata(newVersion, dateStr) {
+  if (!SEMVER_PATTERN.test(newVersion)) throw new Error(`invalid version: ${newVersion}`)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) throw new Error(`invalid date: ${dateStr}`)
+  const tagUrl = `https://github.com/ils15/pantheon-opencode/releases/tag/v${newVersion}`
+  const updates = []
+
+  if (existsSync(ZENODO_PATH)) {
+    const zenodo = JSON.parse(readFileSync(ZENODO_PATH, 'utf8'))
+    const zenodoPrevious = typeof zenodo.version === 'string' ? zenodo.version : null
+    if (zenodoPrevious && zenodoPrevious !== newVersion && typeof zenodo.description === 'string') {
+      zenodo.description = zenodo.description.replaceAll(zenodoPrevious, newVersion)
+    }
+    zenodo.version = newVersion
+    zenodo.publication_date = dateStr
+    zenodo.url = tagUrl
+    updates.push({ path: ZENODO_PATH, content: formatZenodoJson(zenodo) })
+  }
+
+  if (existsSync(CITATION_PATH)) {
+    const citationRaw = readFileSync(CITATION_PATH, 'utf8')
+    const citationMatch = /^version:\s*["']?([^"'\s]+)["']?\s*$/m.exec(citationRaw)
+    const citationPrevious = citationMatch ? citationMatch[1] : null
+    let citation = citationRaw
+    if (citationPrevious && citationPrevious !== newVersion) {
+      citation = citation.replaceAll(`Pantheon v${citationPrevious}`, `Pantheon v${newVersion}`)
+    }
+    citation = citation
+      .replace(/^version:.*$/m, `version: ${newVersion}`)
+      .replace(/^date-released:.*$/m, `date-released: ${dateStr}`)
+      .replace(/^url:.*$/m, `url: ${tagUrl}`)
+    updates.push({ path: CITATION_PATH, content: citation })
+  }
+
+  return updates
 }
 
 // ---------------------------------------------------------------------------
@@ -181,15 +264,17 @@ function stripEmptySections(body) {
   return keep.join('\n').replace(/\n{3,}/g, '\n\n')
 }
 
-function promoteUnreleased(newVersion, dateStr, notesBody = null) {
+function prepareUnreleased(newVersion, dateStr, notesBody = null) {
+  if (!SEMVER_PATTERN.test(newVersion)) throw new Error(`invalid changelog version: ${newVersion}`)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) throw new Error(`invalid changelog date: ${dateStr}`)
+  if (notesBody !== null && typeof notesBody !== 'string') {
+    throw new Error('generated release notes must be text')
+  }
   const content = readFileSync(CHANGELOG_PATH, 'utf-8')
 
   const unreleasedHeader = '## [Unreleased]'
   const idx = content.indexOf(unreleasedHeader)
-  if (idx === -1) {
-    console.log('  ⚠ [Unreleased] section not found in CHANGELOG — skipping')
-    return false
-  }
+  if (idx === -1) throw new Error('CHANGELOG.md is missing the [Unreleased] section')
 
   // Find the end of [Unreleased]: next ## header or end of file
   const afterHeader = idx + unreleasedHeader.length
@@ -211,15 +296,10 @@ function promoteUnreleased(newVersion, dateStr, notesBody = null) {
     .map((l) => l.trim())
     .filter((l) => l && !l.startsWith('###') && !l.startsWith('## '))
 
-  if (notesBody === null && realLines.length === 0) {
-    console.log('  ℹ [Unreleased] is empty — CHANGELOG not modified')
-    return false
-  }
+  if (notesBody === null && realLines.length === 0) return { changed: false, content }
 
   if (notesBody !== null && realLines.length > 0) {
-    console.log(
-      '  ⚠ --notes replaces the manual [Unreleased] content — review the diff before committing',
-    )
+    console.log('  --notes replaces the manual [Unreleased] content')
   }
 
   // Strip lines that are just empty subsections (### X or ## 🆕/🐞/⚠️/✅
@@ -239,13 +319,35 @@ function promoteUnreleased(newVersion, dateStr, notesBody = null) {
 
   const updated = `${before + unreleasedHeader + newTemplate}\n\n${newVersionHeader}${writtenBody}${after}`
 
-  writeFileSync(CHANGELOG_PATH, updated)
-  console.log(
-    notesBody !== null
-      ? `  ✓ CHANGELOG: [Unreleased] → [v${newVersion}] (notes generated from commits)`
-      : `  ✓ CHANGELOG: [Unreleased] → [v${newVersion}]`,
-  )
-  return true
+  if (!updated.includes('## [Unreleased]') || !updated.includes(newVersionHeader)) {
+    throw new Error('prepared CHANGELOG.md failed structural validation')
+  }
+  return { changed: true, content: updated, notesGenerated: notesBody !== null }
+}
+
+function contentHasUnreleased() {
+  return readFileSync(CHANGELOG_PATH, 'utf8').includes('## [Unreleased]')
+}
+
+function commitPreparedRelease(manifestPlan, changelogPlan, metadataUpdates = []) {
+  const updates = [...manifestPlan.updates, ...metadataUpdates]
+  if (changelogPlan.changed) {
+    updates.push({ path: CHANGELOG_PATH, content: changelogPlan.content })
+  }
+  commitPreparedUpdates(updates)
+  for (const document of manifestPlan.inventory.documents) {
+    console.log(`  ✓ ${document.entry.file} → ${manifestPlan.version}`)
+  }
+  for (const { path } of metadataUpdates) {
+    console.log(`  ✓ ${basename(path)} → ${manifestPlan.version}`)
+  }
+  if (changelogPlan.changed) {
+    console.log(
+      changelogPlan.notesGenerated
+        ? `  ✓ CHANGELOG: [Unreleased] → [v${manifestPlan.version}] (notes generated from commits)`
+        : `  ✓ CHANGELOG: [Unreleased] → [v${manifestPlan.version}]`,
+    )
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -282,9 +384,35 @@ switch (command) {
     break
   }
 
+  case 'beta':
   case 'apply': {
     const args = process.argv.slice(3)
     const useNotes = args.includes('--notes')
+    const useBeta = command === 'beta' || args.includes('--beta')
+
+    // Beta: advance the committed X.Y.Z-beta.N line and promote the
+    // [Unreleased] CHANGELOG section into [vX.Y.Z-beta.N], exactly like the
+    // stable path. The committed manifest is the single source of truth — no
+    // npm lookup, no git lookup, and no runtime version computation.
+    if (useBeta) {
+      if (!contentHasUnreleased())
+        throw new Error('CHANGELOG.md is missing the [Unreleased] section')
+      const current = getCurrentVersion()
+      const newVersion = nextBetaVersion(current)
+      const date = new Date().toISOString().slice(0, 10)
+      console.log(`Bumping ${current} → ${newVersion} (beta)`)
+      const changelogPlan = prepareUnreleased(newVersion, date)
+      const manifestPlan = prepareManifests(newVersion)
+      commitPreparedRelease(
+        { ...manifestPlan, version: newVersion },
+        changelogPlan,
+        prepareReleaseMetadata(newVersion, date),
+      )
+      console.log(`\nDone. Commit the version inventory and CHANGELOG as v${newVersion}.`)
+      console.log(`Tag v${newVersion} will be created by the release workflow after merge to main.`)
+      break
+    }
+
     const type = args.find((a) => !a.startsWith('--')) || 'auto'
     const latestTag = getLatestTag()
     const current = getCurrentVersion()
@@ -298,23 +426,25 @@ switch (command) {
       const since = latestTag === 'v0.0.0' ? null : latestTag
       const raw = collectEntries({ since, draft: since === null })
       const body = renderChangelog(groupCommits(raw.map(parseCommitLine)))
-      if (!body) {
-        console.log('  ⚠ --notes: no groupable commits — manual [Unreleased] content used')
-        return null
-      }
-      console.log(`  ℹ --notes: release notes generated from ${raw.length} commits`)
+      if (!body) return null
+      console.log(`  --notes generated from ${raw.length} commits`)
       return body
     }
 
-    // If package.json is already ahead of the latest tag, someone bumped
-    // without tagging — warn and use the current version as-is. Tags are
-    // workflow-owned, so there is nothing to create here.
+    if (!contentHasUnreleased()) throw new Error('CHANGELOG.md is missing the [Unreleased] section')
     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)
+      console.log(
+        `package.json (${current}) is ahead of latest tag (${latestTag}); synchronizing inventory.`,
+      )
       const date = new Date().toISOString().slice(0, 10)
-      promoteUnreleased(current, date, generateNotes())
+      const notesBody = generateNotes()
+      const changelogPlan = prepareUnreleased(current, date, notesBody)
+      const manifestPlan = prepareManifests(current)
+      commitPreparedRelease(
+        { ...manifestPlan, version: current },
+        changelogPlan,
+        prepareReleaseMetadata(current, date),
+      )
       console.log(`Tag v${current} will be created by the release workflow after merge to main.`)
       break
     }
@@ -324,13 +454,15 @@ switch (command) {
     const date = new Date().toISOString().slice(0, 10)
 
     console.log(`Bumping ${current} → ${newVersion} (${bumpType})`)
-    updateManifests(newVersion)
-    promoteUnreleased(newVersion, date, generateNotes())
-    console.log(`\nDone. Commit with: git add -A && git commit -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.
+    const notesBody = generateNotes()
+    const changelogPlan = prepareUnreleased(newVersion, date, notesBody)
+    const manifestPlan = prepareManifests(newVersion)
+    commitPreparedRelease(
+      { ...manifestPlan, version: newVersion },
+      changelogPlan,
+      prepareReleaseMetadata(newVersion, date),
+    )
+    console.log(`\nDone. Commit the version inventory and CHANGELOG as v${newVersion}.`)
     console.log(`Tag v${newVersion} will be created by the release workflow after merge to main.`)
     break
   }
@@ -339,7 +471,11 @@ switch (command) {
   case 'changelog': {
     const version = arg || getCurrentVersion()
     const date = new Date().toISOString().slice(0, 10)
-    promoteUnreleased(version, date)
+    const changelogPlan = prepareUnreleased(version, date)
+    if (changelogPlan.changed) {
+      commitPreparedUpdates([{ path: CHANGELOG_PATH, content: changelogPlan.content }])
+      console.log(`  ✓ CHANGELOG: [Unreleased] → [v${version}]`)
+    }
     break
   }
 
@@ -353,11 +489,19 @@ Commands:
                        type: patch | minor | major | auto (default: auto)
                        --notes: pre-fill the promoted entry with release
                        notes generated from conventional commits
+                       --beta: advance the committed X.Y.Z-beta.N line and
+                       promote [Unreleased] → [vX.Y.Z-beta.N] in CHANGELOG
+  beta                 Alias for 'apply --beta'
   changelog [version]  Promote [Unreleased] → [vX.Y.Z] without bumping
 
-Release flow:
+Release flow (stable):
   1. node scripts/versioning.mjs apply [minor]
-  2. git add -A && git commit -m "chore(release): vX.Y.Z"
-  3. git push     ← CI passes → auto-release fires because pkg > tag
+  2. Commit the version inventory and CHANGELOG.
+  3. Push after review; CI and the dispatch-only release workflow create the tag.
+
+Release flow (beta):
+  1. node scripts/versioning.mjs apply --beta   (or: node scripts/versioning.mjs beta)
+  2. Commit the version inventory and CHANGELOG.
+  3. Dispatch the release workflow with release_channel=beta.
 `)
 }

package/src/agents/apollo.md

@@ -12,6 +12,7 @@ permission:
   glob: allow
   webfetch: allow
   edit: deny
+  hashline_edit: deny
   bash: deny
   task:
     "*": deny

package/src/agents/gaia.md

@@ -11,6 +11,7 @@ permission:
   grep: allow
   webfetch: allow
   edit: deny
+  hashline_edit: deny
   bash: deny
   task:
     "*": deny

package/src/agents/mnemosyne.md

@@ -34,7 +34,7 @@ permission:
   bash: deny
   read: allow
   grep: allow
-  edit: deny
+  edit: allow
   task:
     "*": deny
 ---

package/src/agents/zeus.md

@@ -144,33 +144,11 @@ task_status(task_id="ses_xxx", wait=true)
   -> bloqueia ate completar: { state: "completed", task_result: "..." }
 ```
 
-### Pantheon Delegation Tools (plugin) — 3-tool API
+### DELEGATION_RULES (native task API)
 
-O plugin Pantheon adiciona 3 tools de delegacao gerenciada pelo BackgroundJobBoard:
-
-```
-pantheon_delegate({prompt, agent, description?, read_only?})
-  -> cria sessao filha, registra no board, retorna alias: [apo-1]
-pantheon_delegation_read({id: "apo-1"})
-  -> BLOQUEIA ate o job terminar, retorna o report markdown, marca reconciled
-  -> durante a espera, mostra o que o agente esta fazendo: seccao final "## Agent Activity"
-     (amostra as messages do child a cada ~2s; tool calls + args truncados / texto)
-pantheon_delegation_list()
-  -> lista jobs da sessao, com [unread] para jobs terminados nao lidos
-  -> jobs RUNNING mostram "last activity:" (ultima acao visivel do child)
-  -> fail-open: sem suporte a messages, formato atual inalterado
-```
-
-- **Read-only enforcement:** agentes read-only (apollo, gaia — `read_only_agents` no routing.yml) tem `edit`, `write`, `bash`, `task` NEGADOS dentro da sessao delegada (o guard de `tool.execute.before` THROW com mensagem acionavel). Use `read_only: true` no delegate para qualquer agente de investigacao.
-- **Depth-2 hard-enforced:** sessao read-only NAO cria subagentes (`task` bloqueado) — investigacao nunca vira arvore.
-- **Compactacao:** jobs em voo (running + unread terminal) sao injetados no contexto de compactacao via `experimental.session.compacting` — delegacao em andamento nao se perde ao compactar.
-
-### DELEGATION_RULES (plugin path)
-
-1. **NUNCA** polle `pantheon_delegation_list` para checar se um job terminou.
-2. Voce NAO recebe notificacao injetada no chat — politica do usuario: ZERO `task-notification` no transcript. Visibilidade de conclusao: marcador `[unread]` em `pantheon_delegation_list`, `pantheon_delegation_read({id})`, toasts TUI (pantheon-hooks) e carry-forward de compactacao.
-3. Use `pantheon_delegation_read({id})` APENAS para fan-in explicito / recuperacao de resultado sob demanda (bloqueia ate o fim).
-4. `pantheon_delegation_list` e para diagnostico, nao para polling.
+1. Todo dispatch usa `task(background=true, subagent_type=..., prompt=...)`.
+2. Recolha com `task_status(task_id=..., wait=true)` — bloqueia ate o fim, sem polling.
+3. Use `task_status(wait=true)` apenas para fan-in explicito / recuperacao sob demanda.
 
 ### Background (sempre usar)
 - **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
@@ -301,36 +279,15 @@ vão a idle com todos incompletos. Guards (todos no `src/pantheon/todo-enforcer.
 
 ## Wave 4 (PR #46): Empty-Result Retry + /cost + Themis Tier
 
-### Empty-Result Retry (dispatch-guard — MANUAL orchestration)
-OpenCode 1.18.x NAO permite interceptar a conclusao de `task()` via hooks,
-entao o `src/pantheon/dispatch-guard.ts` e uma lib pura usada POR VOCE na
-orquestracao (NAO esta wired no plugin):
-
-```
-import { createDispatchGuard } from '.../src/pantheon/dispatch-guard.ts'  # via code-mode ou subagente
-
-guard = createDispatchGuard({ retryOnEmpty: true, logger: { warn: console.warn } })
-
-# classificar resultado de task_status/wait:
-#   'content'      → tem texto, pronto
-#   'empty-mode1'  → SEM texto E SEM tokens (nada voltou)      → RETRY 1x
-#   'empty-mode2'  → SEM texto, MAS tokens (raciocinou, perdeu a parte de texto;
-#                    assinatura da falha themis Wave-2)         → RETRY 1x
-
-out = await guard.maybeRetry(result, async () => { ...task() de novo... })
-# out.retried=true se redisparou; CAP DURO de 1 retry — nunca 2x.
-# Se o retry voltar vazio, `out.retried=false` — NAO tente de novo: escale.
-```
-Regra: retry 1x APENAS em `empty-mode1`/`empty-mode2`. Resultado com conteudo
-nunca redispara. Apos 1 retry vazio → escalate (mesma regra do TODO Enforcer).
-
-> **Waves DEVEM usar `zeusDelegateWithRetry`** (`src/pantheon/zeus-delegate-with-retry.ts`) — encapsula `delegate → waitForTerminal → classify → retry 1x → escalate` com cap duro 1; se ainda vazio throw `ZeusEscalationError` (escale: tente outro agente, simplifique, manual).
-> Uso alto-nível: `import { zeusDelegateWithRetry } from './pantheon/zeus-delegate-with-retry.ts'` → `await zeusDelegateWithRetry({ board, client, sessionID, agent, prompt })`.
-> Uso baixo-nível: `createZeusRetryHelper().executeWithRetry(first, () => secondRead())` — classifica empty e decide retry/escalate (mesmo cap 1).
+### Empty-Result Retry (runtime — automatic)
+Empty-response detection for native `task()` subagent calls is wired at runtime
+in `task-result-guard.ts` (plugin `tool.execute.after` chain): an
+empty/whitespace-only result is converted into an explicit error so a silent
+child failure is never mistaken for success. No manual retry helper is required.
 
 ### /cost — pantheon_cost tool (WIRED no plugin)
-`pantheon_cost({ days?: number })` le o `opencode.db` READ-ONLY (node:sqlite;
-fallback `scripts/cost.mjs`) e devolve tabela markdown de custo + tokens por
+`pantheon_cost({ days?: number })` le o `opencode.db` READ-ONLY usando o backend
+unico `node:sqlite`; se indisponivel, retorna `UNSUPPORTED`, sem fallback. Devolve tabela markdown de custo + tokens por
 agente nos ultimos N dias (default 7). Uso: quando Nyx pedir visibilidade de
 custo, ou antes de escalar tier — decida se o batch valeu o preco.
 

package/src/instructions/memory-protocol.instructions.md

@@ -84,7 +84,9 @@ memory_store({
     agreements: ["point1", "point2"],
     divergences: [{"issue": "...", "resolution": "..."}],
     response_rate: "X of Y",
-    themis_audit: "approved|issues"
+    themis_audit: "approved|issues",
+    precedent_used: false,
+    timestamp: "<ISO-8601>"
   },
   metadata: {
     type: "council_decision",
@@ -93,6 +95,7 @@ memory_store({
   }
 })
 ```
+`value` is JSON-serialized before storing (the MCP `memory_store.value` argument is a string).
 
 ### Read Path (Precedent Fast-Path)
 Before dispatching a new council, Zeus runs:
@@ -103,8 +106,8 @@ memory_search(question, top_k=2, namespace="council_decisions")
 Result interpretation:
 | Score | Age | Action |
 |-------|-----|--------|
-| > 0.85 | < 30 days | Return precedent as fast-path answer. Skip council dispatch entirely. |
-| > 0.85 | >= 30 days | Return with warning "Reavaliar se contexto mudou" + proceed with council |
+| > 0.85 | < 30 days | Return precedent verbatim (note "⚠️ Decisão de [data] — reavaliar se contexto mudou") as fast-path answer. Skip council dispatch entirely. |
+| > 0.85 | >= 30 days | Return with warning "Reavaliar se contexto mudou — decisão tem mais de 30 dias" + proceed with council |
 | 0.5 - 0.85 | Any | Include as context for specialists but still dispatch council |
 | < 0.5 | Any | Ignore, proceed with fresh council |
 

package/src/instructions/zeus-anti-stall.instructions.md

@@ -15,7 +15,7 @@ You MUST self-monitor for these stall conditions:
 | Symptom | Detection Rule | Recovery Action |
 |---------|---------------|-----------------|
 | Silent loop | 3+ consecutive turns with no tool call AND no visible progress | Output `[STALL_DETECTED]` and re-read your task definition. If still stuck, escalate to user with: "I appear to be stuck on [task]. Options: (1) retry with different approach, (2) delegate to specialist, (3) simplify scope." |
-| Delegation black hole | Agent dispatched but no response after 2x the timeout from routing.yml | Log the hang, cancel via `cancel_task`, dispatch to fallback agent, report to user |
+| Delegation black hole | Agent dispatched but no response after 2x the timeout from routing.yml | Log the hang, cancel via `cancel_task`, then follow the fallback chain in `## ⏱️ Timeout & Retry Enforcement` |
 | Circular delegation | Same specialist re-dispatched for same task 2+ times without progress | Break cycle: dispatch to different specialist OR escalate to user |
 | Idle after completion | All background tasks completed but no synthesis/next step for 2+ turns | Force synthesis: summarize all completed results and propose next action |
 | Context thrash | Re-reading same files repeatedly without new action | Stop re-reading. State: "Already have context on [file]. Proceeding with [action]." |
@@ -41,9 +41,7 @@ When a delegation fails (timeout, empty response, error):
 
 2. **Retry ONCE** with rephrased prompt — add: "Previous attempt failed with: [error]. Adjusted approach: [what changed]."
 
-3. **If retry also fails** → DO NOT retry a third time blindly. Instead:
-   - Dispatch to fallback agent (from routing.yml)
-   - If no fallback, escalate to user with: "Task [X] failed after retry. Options: (a) simplify, (b) different agent, (c) manual intervention."
+3. **If retry also fails** → do NOT retry blindly; follow the fallback chain and escalation protocol in `## ⏱️ Timeout & Retry Enforcement`.
 
 ## Progress Checkpoint
 

package/src/instructions/zeus-council-synthesis.instructions.md

@@ -85,10 +85,7 @@ sequenceDiagram
 ## Dispatch Sequence (9-Step Protocol)
 
 ### Step 0 — Precedent Fast-Path (Fase 1)
-Before any dispatch: `memory_search(query, top_k=2, namespace="council_decisions")`
-- Score > 0.85 AND age < 30 days → return precedent verbatim with note "⚠️ Decisão de [data] — reavaliar se contexto mudou". SKIP entire dispatch.
-- Score > 0.85 AND age > 30 days → return precedent with ⚠️ "Reavaliar se contexto mudou — decisão tem mais de 30 dias"
-- Else → proceed to Step 0b
+Run the precedent read path defined in `## Memory Protocol > Council Decisions Namespace` (`memory_search(query, top_k=2, namespace="council_decisions")`). If no precedent applies, proceed to Step 0b.
 
 ### Step 0b — Apollo Pre-Scan (Fase 2, --research flag)
 If `/pantheon --research <question>`: dispatch @apollo with 30s timeout. Inject findings as `shared_context` into ALL specialist prompts. Skip if flag absent.
@@ -190,33 +187,11 @@ task(subagent_type: "themis", prompt: "Audit this council synthesis for fidelity
 - If issues → fix each issue before delivering to user
 
 ### Step 9 — Persist & Reconcile (Fase 1)
-```
-memory_store({
-  namespace: "council_decisions",
-  key: "council:<yyyy-mm-dd>:<slug>",
-  value: JSON.stringify({
-    question, specialists, recommendation, confidence,
-    agreements, divergences, precedent_used, timestamp
-  }),
-  metadata: {type: "council_decision", specialist_count: N}
-})
-board.markReconciled("<task-id>")
-```
+Persist the decision using the write path in `## Memory Protocol > Council Decisions Namespace`, then `board.markReconciled("<task-id>")`.
 
 ## Specialist Output Format (Fase 1 — machine-parseable structured fields)
 
-Specialists MUST return these structured fields in their response:
-
-```
-## specialist_response
-**position:** <clear one-sentence position>
-**reasoning:** <2-4 sentences>
-**trade_offs:** <what's gained vs lost>
-**risks:** <what could go wrong>
-**confidence:** High | Medium | Low
-**agreement_signals:** agree: @agent1, @agent2 on [issue] | disagree: @agent3 on [issue]
-**specific_claims:** <count of specific factual claims in response>
-```
+Specialists MUST return the structured `## specialist_response` format (position, reasoning, trade_offs, risks, confidence, agreement_signals, specific_claims) defined in `## Agent Return Format > Council Specialist Response Format`.
 
 ## Domain-to-Specialist Mapping