pantheon-opencode 1.3.5-beta.60.efa533f → 1.3.6

package/scripts/mcp_persistence_server.py

@@ -178,14 +178,15 @@ _global_root = (
 _global_db = _init_db(_global_root / "global.db")
 
 _project_db_instance = None
+_project_db_path: Path | None = None
 if args.project_db:
-    _project_db_instance = _init_db(Path(args.project_db))
+    _project_db_path = Path(args.project_db)
+    _project_db_instance = _init_db(_project_db_path)
 else:
     _proj = pantheon_project()
     if _proj:
-        _project_db_instance = _init_db(
-            _proj / ".pantheon" / "persistence" / "project.db"
-        )
+        _project_db_path = _proj / ".pantheon" / "persistence" / "project.db"
+        _project_db_instance = _init_db(_project_db_path)
 _project_db = _project_db_instance
 
 
@@ -262,7 +263,7 @@ async def kv_get(
     row = conn.execute(
         "SELECT value FROM kv_store "
         "WHERE namespace = ? AND key = ? "
-        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now')) "
         "AND deleted_at IS NULL",
         (namespace, key),
     ).fetchone()
@@ -289,13 +290,13 @@ async def kv_stats(
     total = conn.execute("SELECT COUNT(*) FROM kv_store WHERE deleted_at IS NULL").fetchone()[0]
     expired = conn.execute(
         "SELECT COUNT(*) FROM kv_store "
-        "WHERE expires_at IS NOT NULL AND expires_at < datetime('now') "
+        "WHERE expires_at IS NOT NULL AND datetime(expires_at) < datetime('now') "
         "AND deleted_at IS NULL"
     ).fetchone()[0]
 
     ns_rows = conn.execute(
         "SELECT namespace, COUNT(*) as cnt, "
-        "SUM(CASE WHEN expires_at IS NOT NULL AND expires_at < datetime('now') THEN 1 ELSE 0 END) as expired_count "
+        "SUM(CASE WHEN expires_at IS NOT NULL AND datetime(expires_at) < datetime('now') THEN 1 ELSE 0 END) as expired_count "
         "FROM kv_store WHERE deleted_at IS NULL GROUP BY namespace ORDER BY cnt DESC"
     ).fetchall()
 
@@ -372,7 +373,7 @@ async def kv_list(
     rows = conn.execute(
         "SELECT key, value, created_at, expires_at FROM kv_store "
         "WHERE namespace = ? AND key LIKE ? "
-        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now')) "
         "AND deleted_at IS NULL "
         "ORDER BY key LIMIT ?",
         (namespace, f"{prefix}%", limit),
@@ -426,7 +427,7 @@ async def kv_search(
         "JOIN kv_store ON kv_store_fts.rowid = kv_store.id "
         "WHERE kv_store_fts MATCH ? "
         "AND kv_store.deleted_at IS NULL "
-        "AND (kv_store.expires_at IS NULL OR kv_store.expires_at > datetime('now'))"
+        "AND (kv_store.expires_at IS NULL OR datetime(kv_store.expires_at) > datetime('now'))"
     )
     params: list[str | int] = [fts_query]
 
@@ -474,7 +475,7 @@ async def purge_expired(
     expired = conn.execute(
         "SELECT key FROM kv_store "
         "WHERE expires_at IS NOT NULL "
-        "AND expires_at < datetime('now') "
+        "AND datetime(expires_at) < datetime('now') "
         "AND deleted_at IS NULL",
     ).fetchall()
     expired_keys = [r[0] for r in expired]
@@ -490,7 +491,7 @@ async def purge_expired(
     conn.execute(
         "UPDATE kv_store SET deleted_at = datetime('now') "
         "WHERE expires_at IS NOT NULL "
-        "AND expires_at < datetime('now') "
+        "AND datetime(expires_at) < datetime('now') "
         "AND deleted_at IS NULL",
     )
     conn.commit()
@@ -516,7 +517,7 @@ def _opportunistic_auto_purge(conn: sqlite3.Connection, namespace: str, threshol
     conn.execute(
         "UPDATE kv_store SET deleted_at = datetime('now') "
         "WHERE namespace = ? AND expires_at IS NOT NULL "
-        "AND expires_at < datetime('now') AND deleted_at IS NULL",
+        "AND datetime(expires_at) < datetime('now') AND deleted_at IS NULL",
         (namespace,),
     )
     conn.commit()
@@ -659,7 +660,7 @@ async def context_get(
     row = conn.execute(
         "SELECT value FROM kv_store "
         "WHERE namespace = ? AND key = ? "
-        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now')) "
         "AND deleted_at IS NULL",
         (ns, key),
     ).fetchone()
@@ -691,7 +692,7 @@ async def context_list(
     rows = conn.execute(
         "SELECT key, created_at, expires_at FROM kv_store "
         "WHERE namespace = ? "
-        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now')) "
         "AND deleted_at IS NULL "
         "ORDER BY created_at DESC LIMIT 50",
         (ns,),
@@ -737,7 +738,7 @@ async def context_stats(
 
     expired = conn.execute(
         "SELECT COUNT(*) FROM kv_store "
-        "WHERE namespace = ? AND expires_at < datetime('now') "
+        "WHERE namespace = ? AND datetime(expires_at) < datetime('now') "
         "AND deleted_at IS NULL",
         (ns,),
     ).fetchone()[0]
@@ -773,15 +774,15 @@ async def context_stats(
     }
 
 def _resolve_db_path(scope: str) -> Path | None:
-    """Resolve the database file path for a given scope."""
+    """Resolve the database file path for a given scope.
+
+    Returns the actual path used at init (honoring an explicit
+    ``--project-db``), so deletelog writes and db_size stats land next to
+    the real database file.
+    """
     if scope == "global":
         return _global_root / "global.db"
-    if _project_db_instance:
-        # Find the project root from the project DB path
-        proj_root = pantheon_project()
-        if proj_root:
-            return proj_root / ".pantheon" / "persistence" / "project.db"
-    return None
+    return _project_db_path
 
 
 # ── Main Entrypoint ─────────────────────────────────────────────────────────────

package/scripts/mcp_resources_server.py

@@ -1,4 +1,3 @@
-# Auto-generated: resolved symlink from ../src/mcp/mcp_resources_server.py
 #!/usr/bin/env python3
 """Pantheon MCP Resources Server.
 
@@ -19,6 +18,7 @@ from typing import Any
 
 import yaml
 from _pantheon_paths import pantheon_home, pantheon_project
+from eval_store import get_latest_eval, list_evals
 from mcp.server.fastmcp import FastMCP
 
 # ── Path Resolution ──────────────────────────────────────────────────────────
@@ -112,6 +112,8 @@ async def list_skills() -> str:
 async def get_routing() -> str:
     """Return the full content of routing.yml."""
     routing_file = _PANTHEON_HOME / "routing.yml"
+    if not routing_file.exists() and _PANTHEON_PROJECT:
+        routing_file = _PANTHEON_PROJECT / "src" / "routing.yml"
     if not routing_file.exists():
         return "routing.yml not found."
     return routing_file.read_text(encoding="utf-8")
@@ -200,6 +202,63 @@ async def get_memory_bank(path: str) -> str:
     return resolved.read_text(encoding="utf-8")
 
 
+# ── Plugin Eval Resources ─────────────────────────────────────────────────────
+
+
+def _valid_plugin_name(name: str) -> bool:
+    """Validate a plugin name for the eval resource (no traversal)."""
+    return bool(name) and "/" not in name and "\\" not in name and ".." not in name
+
+
+@mcp.resource(
+    "pantheon://eval",
+    description="List of evaluated plugins/skills with their latest "
+    "certification score (from the plugin_eval memory namespace)",
+)
+async def list_plugin_evals() -> str:
+    """Return a markdown list of evaluated plugins with latest scores."""
+    entries = list_evals()
+    if not entries:
+        return "No plugin evals recorded yet."
+
+    lines = ["# Plugin Eval Certification", ""]
+    for entry in entries:
+        name = entry.get("name", "?")
+        score = entry.get("metadata", {}).get("score", "?")
+        created = entry.get("created_at", "")
+        lines.append(f"- **{name}** — score {score} (evaluated {created})")
+    return "\n".join(lines)
+
+
+@mcp.resource(
+    "pantheon://eval/{plugin}",
+    description="Latest certification report for a plugin/skill "
+    "(from the plugin_eval memory namespace)",
+)
+async def get_plugin_eval(plugin: str) -> str:
+    """Return the latest eval certification report for a plugin.
+
+    Security: plugin names containing path separators or traversal
+    sequences are rejected before any lookup.
+    """
+    if not _valid_plugin_name(plugin):
+        return "Invalid plugin name: blocked."
+
+    entry = get_latest_eval(plugin)
+    if entry is None:
+        return f"No eval found for plugin '{plugin}'."
+
+    score = entry.get("metadata", {}).get("score", "?")
+    created = entry.get("created_at", "")
+    value = entry.get("value", "{}")
+    return (
+        f"# Eval Report: {plugin}\n\n"
+        f"**Score:** {score}\n"
+        f"**Evaluated:** {created}\n\n"
+        f"```json\n{value}\n```"
+    )
+
+
 # ── Main Entrypoint ───────────────────────────────────────────────────────────
 
 if __name__ == "__main__":

package/scripts/memory_mcp_server.py

@@ -1,4 +1,3 @@
-# Auto-generated: resolved symlink from ../src/mcp/memory_mcp_server.py
 #!/usr/bin/env python3
 """Pantheon Memory MCP Server — lightweight, zero heavy deps.
 
@@ -26,6 +25,7 @@ import json
 import os
 import sqlite3
 import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -187,10 +187,55 @@ def _parse_metadata(row: dict[str, Any]) -> dict[str, Any]:
 _RRF_CONST = 60
 
 
+def _parse_iso_ts(value: str) -> float:
+    """Parse an ISO 8601 UTC timestamp to epoch seconds.
+
+    Handles both aware ISO strings (``2026-08-21T10:00:00Z`` /
+    ``...+00:00``) and legacy naive rows from ``DEFAULT (datetime('now'))``
+    (``YYYY-MM-DD HH:MM:SS``, space separator, no TZ). Naive timestamps are
+    assumed UTC — SQLite's ``datetime('now')`` is UTC, so interpreting them
+    in the local timezone would skew freshness decay.
+    """
+    dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.timestamp()
+
+
+def _fetch_created_at_map(
+    db: sqlite3.Connection, ids: list[int]
+) -> dict[int, str]:
+    """Fetch created_at timestamps for the given memory IDs.
+
+    Args:
+        db: Active SQLite connection.
+        ids: Memory row IDs to look up.
+
+    Returns:
+        Mapping of id -> created_at ISO string. Empty on failure.
+    """
+    created_at_map: dict[int, str] = {}
+    if not ids:
+        return created_at_map
+    try:
+        placeholders = ",".join("?" * len(ids))
+        rows = db.execute(
+            f"SELECT id, created_at FROM memories "
+            f"WHERE id IN ({placeholders})",
+            ids,
+        ).fetchall()
+        created_at_map = {r["id"]: r["created_at"] for r in rows}
+    except Exception:
+        created_at_map = {}
+    return created_at_map
+
+
 def _rrf_fuse(
     vec_ids: list[int],
     fts_ids: list[int],
     top_k: int,
+    created_at_map: dict[int, str] | None = None,
+    decay_days: float | None = None,
 ) -> list[tuple[int, float]]:
     """Reciprocal Rank Fusion of vector and FTS5 result ID lists.
 
@@ -198,6 +243,12 @@ def _rrf_fuse(
         vec_ids: Ordered list of IDs from vector search (most relevant first).
         fts_ids: Ordered list of IDs from FTS5 search (most relevant first).
         top_k: Maximum number of fused results to return.
+        created_at_map: Optional mapping of doc_id -> created_at ISO string,
+            used to compute freshness when ``decay_days`` is set.
+        decay_days: Optional freshness half-life in days. When set, each fused
+            score is multiplied by ``freshness = 2^(-days/decay_days)`` so
+            older entries rank lower. Default None = no decay (backward
+            compatible).
 
     Returns:
         List of (id, rrf_score) tuples sorted by descending score.
@@ -207,6 +258,19 @@ def _rrf_fuse(
         scores[doc_id] = 1.0 / (_RRF_CONST + rank)
     for rank, doc_id in enumerate(fts_ids, start=1):
         scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (_RRF_CONST + rank)
+
+    if decay_days is not None and decay_days > 0 and created_at_map:
+        now = time.time()
+        for doc_id in list(scores):
+            created = created_at_map.get(doc_id)
+            if not created:
+                continue
+            try:
+                days = max(0.0, (now - _parse_iso_ts(created)) / 86400.0)
+            except (ValueError, TypeError):
+                continue
+            scores[doc_id] *= 2.0 ** (-days / decay_days)
+
     ranked = sorted(scores.items(), key=lambda x: (-x[1], x[0]))
     return ranked[:top_k]
 
@@ -283,12 +347,15 @@ def memory_store(
 @mcp.tool(
     description="Hybrid semantic search across memories. "
     "Combines vector cosine similarity and FTS5 BM25 keyword search "
-    "via Reciprocal Rank Fusion (RRF).",
+    "via Reciprocal Rank Fusion (RRF). Optional decay_days applies a "
+    "freshness half-life (2^(-days/decay_days)) so recent entries rank "
+    "higher; default None keeps the original rank-only behavior.",
 )
 def memory_search(  # noqa: PLR0912
     query: str,
     namespace: str | None = None,
     top_k: int = 5,
+    decay_days: float | None = None,
 ) -> list[dict[str, Any]]:
     """Hybrid search: vector + keyword fused via RRF.
 
@@ -300,6 +367,9 @@ def memory_search(  # noqa: PLR0912
         query: Search query text.
         namespace: Optional namespace filter.
         top_k: Maximum results (default 5, max 50).
+        decay_days: Optional freshness half-life in days. When set, fused
+            scores are multiplied by ``2^(-days_since_created/decay_days)``
+            so older entries rank lower. Default None = no decay.
 
     Returns:
         List of memory entries with score and metadata.
@@ -365,8 +435,14 @@ def memory_search(  # noqa: PLR0912
     except Exception:
         fts_ids = []
 
-    # 4. RRF fusion
-    fused = _rrf_fuse(vec_ids, fts_ids, top_k)
+    # 4. RRF fusion (optionally freshness-decayed)
+    candidate_ids = list(dict.fromkeys([*vec_ids, *fts_ids]))
+    created_at_map = (
+        _fetch_created_at_map(db, candidate_ids)
+        if decay_days is not None and decay_days > 0
+        else {}
+    )
+    fused = _rrf_fuse(vec_ids, fts_ids, top_k, created_at_map, decay_days)
 
     if not fused:
         return []

package/scripts/postinstall.mjs

@@ -5,43 +5,45 @@
  * Runs after `npm install` completes. Validates environment and prints
  * setup instructions. Does NOT install Pantheon platform components.
  */
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const ROOT = join(__dirname, '..');
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const _ROOT = join(__dirname, '..')
 
-const REQUIRED_NODE_MAJOR = 18;
-const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+const REQUIRED_NODE_MAJOR = 18
+const nodeMajor = parseInt(process.versions.node.split('.')[0], 10)
 
 try {
   // Validate Node.js version
   if (nodeMajor < REQUIRED_NODE_MAJOR) {
-    console.error(`❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`);
-    process.exit(1);
+    console.error(
+      `❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`,
+    )
+    process.exit(1)
   }
 
   // Validate js-yaml is available
   try {
-    await import('js-yaml');
+    await import('js-yaml')
   } catch {
-    console.warn('⚠️  js-yaml not found — run `npm install` to install dependencies');
+    console.warn('⚠️  js-yaml not found — run `npm install` to install dependencies')
   }
 
-  console.log('');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('  Pantheon OpenCode — npm dependencies installed ✅');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('');
-  console.log('  Next steps:');
-  console.log('  1. Configure Pantheon:');
-  console.log('     npm run setup');
-  console.log('     # or: npx pantheon-opencode init');
-  console.log('  2. Verify installation:');
-  console.log('     npm run doctor');
-  console.log('');
+  console.log('')
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+  console.log('  Pantheon OpenCode — npm dependencies installed ✅')
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+  console.log('')
+  console.log('  Next steps:')
+  console.log('  1. Configure Pantheon:')
+  console.log('     npm run setup')
+  console.log('     # or: npx pantheon-opencode init')
+  console.log('  2. Verify installation:')
+  console.log('     npm run doctor')
+  console.log('')
 } catch (err) {
-  console.error(`❌ Post-install check failed: ${err.message}`);
-  process.exit(1);
+  console.error(`❌ Post-install check failed: ${err.message}`)
+  process.exit(1)
 }

package/scripts/prune.mjs

@@ -34,7 +34,7 @@ import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const ROOT = join(__dirname, '..')
+const _ROOT = join(__dirname, '..')
 const DEFAULT_BACKUP_AGE_DAYS = 30
 
 // ---------------------------------------------------------------------------

package/scripts/redaction-gate.mjs

@@ -30,7 +30,9 @@ function scanFile(path) {
 }
 
 function scanTarball(path) {
-  const entries = execFileSync('tar', ['-tzf', path], { encoding: 'utf8' }).split('\n').filter(Boolean)
+  const entries = execFileSync('tar', ['-tzf', path], { encoding: 'utf8' })
+    .split('\n')
+    .filter(Boolean)
   const result = []
   for (const entry of entries) {
     const content = execFileSync('tar', ['-xOzf', path, entry])

package/scripts/uninstall.mjs

@@ -37,13 +37,11 @@ const PANTHEON_AGENT_NAMES = [
   'prometheus',
   'hephaestus',
 
-
   'nyx',
   'gaia',
   'iris',
   'mnemosyne',
   'talos',
-
 ]
 
 const PLATFORM_LABELS = {

package/scripts/validation-policy.mjs

@@ -1,5 +1,10 @@
 /** 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 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

package/scripts/version-check.mjs

@@ -26,7 +26,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 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' },
+  {
+    name: 'src/plugins/tui/package.json',
+    file: join('src', 'plugins', 'tui', 'package.json'),
+    kind: 'json',
+  },
 ]
 
 function readTomlVersion(filePath) {
@@ -109,8 +113,7 @@ function printDivergenceTable(result) {
   console.log('')
 }
 
-const isDirectRun =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+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
@@ -138,7 +141,9 @@ if (isDirectRun) {
       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`)
+    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)')

package/src/agents/aphrodite.md

@@ -14,7 +14,7 @@ permission:
   task:
     "*": deny
 temperature: 0.3
-steps: 50
+steps: 70
 skills:
   - tdd-with-agents
   - visual-review-pipeline

package/src/agents/apollo.md

@@ -2,6 +2,9 @@
 name: apollo
 description: "Read-only investigation scout — 3-10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands."
 mode: subagent
+visible: false
+tools:
+  task: false
 reasoning_effort: low
 permission:
   read: allow

package/src/agents/demeter.md

@@ -12,7 +12,7 @@ permission:
   task:
     "*": deny
 temperature: 0.2
-steps: 40
+steps: 60
 skills:
   - tdd-with-agents
   - incremental-implementation

package/src/agents/gaia.md

@@ -2,6 +2,9 @@
 name: gaia
 description: "Remote sensing domain specialist — satellite image processing, spectral analysis, SAR, change detection, time series, ML/DL classification. Read-only analysis of geospatial data."
 mode: subagent
+visible: false
+tools:
+  task: false
 reasoning_effort: low
 permission:
   read: allow

package/src/agents/hephaestus.md

@@ -12,7 +12,7 @@ permission:
   task:
     "*": deny
 temperature: 0.3
-steps: 40
+steps: 60
 skills:
   - tdd-with-agents
   - auto-continue

package/src/agents/hermes.md

@@ -11,7 +11,7 @@ mcp_tools:
   pantheon-memory: [memory_search]
   pantheon-code-mode: [execute_code_script]
 temperature: 0.3
-steps: 50
+steps: 70
 skills:
   - tdd-with-agents
   - file-prompts

package/src/agents/themis.md

@@ -97,6 +97,10 @@ Verificacoes rapidas de estilo e sanidade:
 - [ ] Formatacao consistente (mesmo style guide)
 - [ ] Nomes de variaveis/funcoes descritivos
 - [ ] Comentarios TODO ou FIXME sem resolucao
+- [ ] Comment Checker: codigo gerado indistinguivel de humano
+      - Flag comentarios obvios/excessivos (ex: `// increment i`, `# set x to 5`)
+      - Flag codigo morto comentado (blocos inteiros desativados)
+      - Flag cabecalhos boilerplate (autor/data/licenca repetitivos)
 
 Tempo estimado: ~10% do esforco de review
 

package/src/agents/zeus.md

@@ -37,7 +37,7 @@ skills:
 
 ## Golden Rule
 
-**Coordenador APENAS.** Leu arquivo → delegue. Nunca implemente, nunca edite, nunca debugue.
+**Coordenador APENAS. Zeus NUNCA lê arquivos de código-fonte.** Toda leitura de `src/`, `tests/`, `scripts/` vai para @apollo. Leia apenas: config, docs, memory bank, delegação.
 
 
 ## 🔒 Fusion-Style Enforcement
@@ -324,6 +324,10 @@ 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 `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