pantheon-opencode 1.4.3 → 1.5.0-beta.10

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/scripts/zenodo-artifact.mjs

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+export function sha256File(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
+
+export function findZenodoFile(record, filename, checksum) {
+  if (!record || typeof record !== 'object' || !Array.isArray(record.files)) {
+    throw new Error('Zenodo record did not contain a files array.')
+  }
+  const matches = record.files.filter((file) => file?.filename === filename)
+  if (matches.length > 1) throw new Error(`Zenodo record contains duplicate file: ${filename}.`)
+  if (matches.length === 0) return null
+  const file = matches[0]
+  const expected = `sha256:${checksum}`
+  if (file.checksum !== expected) {
+    throw new Error(`Zenodo checksum mismatch for ${filename}.`)
+  }
+  return file
+}

package/scripts/zenodo-release-state.mjs

@@ -0,0 +1,53 @@
+const DOI_PATTERN = /^10\.\d{4,9}\/\S+$/
+const MARKER_PATTERN =
+  /<!-- zenodo-deposition:(?:id=(\d+);)?(?:doi=([^;\s]+);)?state=(pending|created|published)(?:;claim=([^\s]+))? -->/
+
+export function extractZenodoDoi(response) {
+  if (!response || typeof response !== 'object') return null
+  const candidates = [response.doi, response.metadata?.doi, response.links?.doi]
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && DOI_PATTERN.test(candidate.trim())) return candidate.trim()
+  }
+  return null
+}
+
+export function validateZenodoResponse(response, { requireDoi = false } = {}) {
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    throw new Error('Zenodo response must be a JSON object.')
+  }
+  if (!Number.isSafeInteger(response.id) || response.id <= 0) {
+    throw new Error('Zenodo response did not contain a valid deposition id.')
+  }
+  const doi = extractZenodoDoi(response)
+  if (requireDoi && !doi) throw new Error('Zenodo response did not contain a valid DOI.')
+  return { id: response.id, doi }
+}
+
+export function parseZenodoMarker(body) {
+  const text = String(body ?? '')
+  const match = text.match(MARKER_PATTERN)
+  if (!match) {
+    const legacy = text.match(/<!-- zenodo-deposition-id:(\d+) -->/)
+    if (!legacy) return null
+    const id = Number(legacy[1])
+    if (!Number.isSafeInteger(id) || id <= 0)
+      throw new Error('Zenodo marker has an invalid deposition id.')
+    return { id, doi: null, state: 'created', claim: null }
+  }
+  const id = match[1] ? Number(match[1]) : null
+  if (match[1] && (!Number.isSafeInteger(id) || id <= 0))
+    throw new Error('Zenodo marker has an invalid deposition id.')
+  if (match[2] && !DOI_PATTERN.test(match[2])) throw new Error('Zenodo marker has an invalid DOI.')
+  return { id, doi: match[2] ?? null, state: match[3], claim: match[4] ?? null }
+}
+
+export function zenodoMarker({ id = null, doi = null, state, claim = null }) {
+  if (!['pending', 'created', 'published'].includes(state))
+    throw new Error('Zenodo marker state is invalid.')
+  if (id !== null && (!Number.isSafeInteger(id) || id <= 0))
+    throw new Error('Zenodo marker id is invalid.')
+  if (doi !== null && !DOI_PATTERN.test(doi)) throw new Error('Zenodo marker DOI is invalid.')
+  if (state !== 'pending' && id === null)
+    throw new Error('Created or published Zenodo markers require an id.')
+  return `<!-- zenodo-deposition:${id === null ? '' : `id=${id};`}${doi === null ? '' : `doi=${doi};`}state=${state}${claim === null ? '' : `;claim=${claim}`} -->`
+}

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,23 +144,33 @@ task_status(task_id="ses_xxx", wait=true)
   -> bloqueia ate completar: { state: "completed", task_result: "..." }
 ```
 
-### Pantheon Delegation — BackgroundJobBoard (plugin)
+### Pantheon Delegation Tools (plugin) — 3-tool API
 
-O plugin Pantheon mantém um **BackgroundJobBoard** persistente
-(`.pantheon/board/state.json`) que rastreia trabalho em voo e o carrega para o
-contexto de compactação. O toolset de delegação do plugin
-(`pantheon_delegate`, `pantheon_delegation_read`, `pantheon_delegation_list`)
-foi **removido em 1.4.3** — dispatch e coleta usam a API nativa
-`task(background=true)` / `task_status(wait=true)`.
+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 (native task path)
+### DELEGATION_RULES (plugin path)
 
-1. **NUNCA** polle `task_status` para checar se um job terminou — use `wait=true` para fan-in explicito.
-2. Voce NAO recebe notificacao injetada no chat — politica do usuario: ZERO `task-notification` no transcript. Visibilidade de conclusao: marcador `[unread]` no board, toasts TUI (pantheon-hooks) e carry-forward de compactacao.
-3. Use `task_status({task_id, wait: true})` APENAS para fan-in explicito / recuperacao de resultado sob demanda (bloqueia ate o fim).
-4. `task_status` sem `wait` e para diagnostico, nao para polling.
+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.
 
 ### Background (sempre usar)
 - **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
@@ -314,12 +324,13 @@ out = await guard.maybeRetry(result, async () => { ...task() de novo... })
 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 `dispatch-guard`** (`src/pantheon/dispatch-guard.ts`) — encapsula `task → classify → retry 1x → escalate` com cap duro 1; se ainda vazio throw `ZeusEscalationError` (escale: tente outro agente, simplifique, manual).
-> Uso alto-nível: `import { createDispatchGuard } from './pantheon/dispatch-guard.ts'` → `await guard.maybeRetry(result, () => task(...))`.
+> **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).
 
 ### /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.