pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.11

package/src/instructions/zeus-timeout-retry.instructions.md

@@ -1,132 +1,100 @@
 ---
 description: "Timeout enforcement, retry policies, subtask dispatch, and timeout tracking for Zeus"
 name: "Zeus Timeout & Retry"
-applyTo: "agents/zeus.agent.md"
+agents: [zeus]
+fallback: shared
 ---
 
 # ⏱️ TIMEOUT & RETRY ENFORCEMENT
 
 When a delegated agent does not respond in time, enforce the timeout policy from `routing.yml`.
 
+Use the root `subagent` dispatch observed in the Beta 10 runtime. `task()` is
+host/API terminology; the active runtime determines the callable schema and any
+background options. Do not assume root `task_status`, `cancel_task`, or board
+tracking/recovery tools. Prefer synchronous dispatch unless background completion
+is observable through the host, and keep any retry list in the current context
+only; do not claim persistent job tracking.
+
 ## Timeout Behavior by Agent Role
 
-| Agent Role | Timeout | Retry Policy | Fallback Chain | Partial Results OK? | Reasoning Effort |
-|------------|---------|-------------|----------|---------------------|------------------|
-| Explorer (@apollo) | 60s | 2 retries, exp backoff | @athena (plan) → @hermes (impl) | ✅ Yes | low |
-| Implementer (@hermes, @aphrodite, @demeter) | 180s | 3 retries, exp backoff | @talos (hotfix) → @athena (replan) | ❌ No | medium |
-| Reviewer (@themis) | 120s | 3 retries, exp backoff | @zeus (escalate) → user | ❌ No | high |
-| Infrastructure (@prometheus) | 300s | 3 retries, exp backoff | @hermes (config) → @zeus (escalate) | ❌ No | medium |
-| Hotfix (@talos) | 30s | 2 retries, no backoff | @hermes (full fix) | ✅ Yes | low |
-| Remote Sensing (@gaia) | 120s | 2 retries, exp backoff | @hermes (generic) | ✅ Yes | high |
+| Agent Role | Timeout | Retry Policy | Partial Results OK? | Reasoning Effort |
+|------------|---------|--------------|---------------------|------------------|
+| Explorer (@apollo) | 60s | 1 retry | ✅ Yes | low |
+| Implementer (@hermes, @aphrodite, @demeter) | 180s | 1 retry | ❌ No | medium |
+| Reviewer (@themis) | 120s | 1 retry | ❌ No | high |
+| Infrastructure (@prometheus) | 300s | 1 retry | ❌ No | medium |
+| Hotfix (@talos) | 30s | 1 retry | ✅ Yes | low |
+| Remote Sensing (@gaia) | 120s | 1 retry | ✅ Yes | high |
 
 ## Retry Flow
 
 ```
-Task dispatch → timeout elapsed → log timeout
-  ├─ retry_count > 0 → retry with exponential backoff → decrement retry_count
-  │    └─ still failing? → retry again (up to retry_count limit)
-  │
-  ├─ retries exhausted → FALLBACK CHAIN:
-  │    ├─ fallback[0] exists? → dispatch to fallback agent
-  │    │    └─ keep original task spec + context; add error context
-  │    ├─ fallback[1] exists? → dispatch to second fallback
-  │    └─ all fallbacks failed? → ESCALATE
-  │
-  ├─ no fallbacks defined → return TIMEOUT error to user
-  │
-  └─ ESCALATE: "Agent X failed after N retries. Fallbacks Y, Z also failed.
-                 Options: (a) try different agent, (b) simplify scope, (c) manual"
+Initial attempt → timeout/failure → log it → make at most one retry
+  └─ retry fails → try fallback agents left-to-right with original task/context
+       └─ all fallbacks fail (or none exist) → report the chain and escalate
 ```
+`background_delegation.retry_count: 1` means one retry after the initial attempt, not one total attempt. Never restart an exhausted chain automatically.
 
-
+Apply the retry only to a transient dispatch failure (timeout, crash, or empty response). A failed test, validation, or migration is a result to diagnose, not a reason to repeat the same command or agent blindly. Track agents already tried: each agent may be retried at most once and each listed fallback may be tried at most once. For auth/security/data/schema work, a fallback must preserve specialist competence, Themis review, and human approval; otherwise stop and escalate. Never let full-auto bypass these gates.
+An agent refusal or scope-boundary response is not a transient failure: do not retry it with a rephrased prompt. Correct the route once if the right specialist is clear; otherwise stop and ask.
 
 ## Fallback Chain Definitions
 
-Each fallback chain is evaluated left-to-right: if the first fallback fails, try the second, etc.
-
-| Agent | Fallback[0] | Fallback[1] | Escalate To |
-|-------|------------|------------|-------------|
-| @apollo | @athena (plan scoped task) | @hermes (implement search) | @zeus |
-| @hermes | @talos (minimal fix) | @athena (replan + simplify) | @zeus |
-| @aphrodite | @talos (CSS/UX fix) | @hermes (generic fallback) | @zeus |
-| @demeter | @hermes (generic backend) | @athena (replan schema) | @zeus |
-| @themis | @zeus (direct escalation) | — | user |
-| @prometheus | @hermes (config/deploy) | @zeus | user |
-| @talos | @hermes (full implementation) | — | @zeus |
-| @hephaestus | @nyx (observability debug) | @hermes (generic) | @zeus |
-| @nyx | @hermes (generic) | — | @zeus |
-| @iris | @zeus (manual override) | — | user |
-| @mnemosyne | @zeus (manual) | — | user |
+`routing.yml` → `fallback_chains` is the canonical agent-by-agent mapping. Evaluate
+the configured chain left-to-right; if an agent has no configured chain, stop
+and escalate rather than guessing a fallback. Each listed fallback may be tried
+at most once, and an exhausted chain is never restarted automatically.
 
-### Escalation Protocol
-When ALL fallbacks fail:
-1. Log the full failure chain: which agents were tried, what error each returned
-2. Report to user: "Task [X] failed. Tried: [agent list]. Error: [summary]."
-3. Offer options: (a) try different approach, (b) simplify scope, (c) manual fix
-4. NEVER retry the same chain automatically — break the cycle
+### Refusal Is a Routing Error
 
-### Session Reuse Check
-Before dispatching a task, check if a reusable session exists:
+For a domain/scope refusal, do not retry with a rephrased prompt. Correct the
+route once only when the right specialist is clear; otherwise stop and ask.
+Record one `DelegationCacheDecision` telemetry item only when telemetry recording
+is actually exposed; otherwise keep the corrected route in the current handoff
+and do not claim telemetry was persisted. Include `reroute_from`, `reroute_to`,
+and `delegation_id` when available.
 
-```
-@hermes — continuing from previous session.
-Files already explored: backend/routers/auth.py, backend/services/auth_service.py.
-New task: add refresh token rotation.
-```
+### Escalation Protocol
+When all fallbacks fail, report the tried agents and errors, offer a different approach/simpler scope/manual fix, and stop. Never retry the same chain automatically.
 
-Use `session_max` from routing.yml to determine how many sessions to keep per agent.
+### Session Reuse Check
+Reuse a prior specialist session only when the active host exposes that capability;
+otherwise dispatch through `subagent` with necessary context. Treat `session_max`
+as policy context, not as a claim that Zeus can enumerate sessions.
 
 ---
 
 # 📦 SUBTASK DISPATCH (Lightweight Delegation)
 
-Subtask is a bounded, low-risk delegation mode that **skips** the standard artifact lifecycle. Use it for focused work that doesn't need Themis review.
+Subtask is a bounded, low-risk delegation mode that **skips** the standard artifact lifecycle. Choose it by risk and need for review, not by a fixed file/line count.
 
 ## When to Use Subtask vs Full Task
 
-> **REGRA DE OURO:** Quando em dúvida, use full task. Subtask é para o que você tem 100% de certeza que é seguro pular revisão.
+Use the lightest path that safely meets the request. A multi-file but bounded low-risk change does not automatically need a plan/artifact phase.
 
 ### Subtask Decision Tree (run BEFORE every delegation)
 
 ```
-□ Scope: ≤2 files AND ≤10 lines changed?         [YES→continue | NO→full task]
-□ Risk: No schema change, no security impact?      [YES→continue | NO→full task]
-□ Auth: No authentication/authorization logic?      [YES→continue | NO→full task]
-□ Data: No data loss risk, no migration?            [YES→continue | NO→full task]
-□ Review: Output does NOT feed into Themis review?  [YES→continue | NO→full task]
-
-ALL YES → subtask (skip artifact + Themis)
-ANY NO  → full task (IMPL artifact + Themis review mandatory)
-```
-
-### Comparison Table
-
-| Aspect | Subtask | Full Task |
-|--------|---------|-----------|
-| Scope | Single file, <10 lines, read-only | Feature, multi-file, schema change |
-| Risk | Low (no security/data implications) | Any risk level |
-| Artifact | ❌ No IMPL artifact | ✅ IMPL artifact required |
-| Themis review | ❌ None | ✅ Mandatory |
-| Use case | Apollo discovery, Talos hotfix, bounded fix | Feature implementation, migration, API change |
+□ Is the scope clear, bounded, reversible, and low-uncertainty?  [YES→continue | NO→clarify/plan]
+□ Does it avoid auth/security, data/schema, destructive, broad/material, and user-visible API risk? [YES→continue | NO→relevant gates]
+□ Is there no required Themis/audit handoff for this change?      [YES→continue | NO→preserve that review]
 
-### Concrete Examples
-
-| Task | Scope | Risk | Subtask? | Why |
-|------|-------|------|----------|-----|
-| Fix typo in CSS class | 1 file, 1 line | None | ✅ | Bounded, no security impact |
-| Add error handling to existing endpoint | 1 file, 5 lines | Low | ✅ | No schema change |
-| Implement login endpoint | 2+ files, 50+ lines | High (auth) | ❌ | Security-critical, needs Themis |
-| Database migration | 1 file, 15 lines | High (data) | ❌ | Data loss risk, needs rollback |
-| Apollo codebase search | 0 files | None | ✅ | Read-only investigation |
-| Update README | 1 file, 3 lines | None | ✅ | Documentation only |
+ALL YES → one correct domain specialist; they inspect needed context, implement, and verify; no routine plan/artifact, separate discovery, council, or review
+ANY NO  → add only the planning, artifact, specialist review, and approval gates the risk requires
+```
 
 ### Safety Rules
-1. **Bounded scope** — single file or read-only investigation
-2. **Low risk** — no security implications, no data loss, no breaking changes
-3. **No Themis dependency** — output doesn't feed into a phase that requires review
+1. **Bounded scope** — can be a small multi-file change or a read-only investigation
+2. **Low risk and uncertainty** — no security implications, data loss, breaking/user-visible API impact, broad material scope, or unresolved high uncertainty
+3. **No required Themis dependency** — sensitive/material output retains its review gate
+
+The selected specialist, not a routine Apollo discovery pass, inspects the relevant
+local context for a lightweight implementation. Keep specialist roles available for
+on-demand routing; do not remove an agent based on one task or one overhead observation.
 
 ## Subtask Return Format
-Return the standard `## subtask_summary` defined in `## Agent Return Format` (files_changed, summary, tests, coverage, tokens, status, blockers).
+Return the required `## subtask_summary` fields defined in `## Agent Return Format`; include `memory_context` when memory was used.
 
 ## Timeout Parcial (Partial Results)
 
@@ -136,4 +104,8 @@ Only agents marked ✅ in the Timeout Behavior table above may return partial re
 
 # 📊 TIMEOUT TRACKING
 
-Track in-flight delegations against the Timeout Behavior table above. Log timeouts to `/memories/session/timeout-log.md` for later analysis.
+Keep only an in-context list of active delegations and already-tried agents when
+needed. Use results returned by `subagent` or host completion notifications; do
+not poll, cancel, or write a timeout log unless the corresponding tool is exposed.
+Report any timeout and the retry/fallback taken in the user-facing handoff; do
+not claim persistent tracking or recovery.

package/src/mcp/{code_mode_server.py → code_mode.py}

@@ -5,12 +5,12 @@ Provides a confined execution environment for orchestration scripts
 via MCP tools and resources.
 
 Usage:
-    python scripts/code_mode_server.py
+    python scripts/code_mode.py
 
 Or via MCP client (stdio transport):
     pantheon-code-mode:
         command: python
-        args: ["scripts/code_mode_server.py"]
+        args: ["scripts/code_mode.py"]
 """
 
 from __future__ import annotations
@@ -36,7 +36,7 @@ from typing import Any
 
 import yaml
 from _pantheon_paths import pantheon_home, pantheon_project
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 
 # ── Constants ─────────────────────────────────────────────────────────────────
 ALLOWED_EXTENSIONS: frozenset[str] = frozenset({".sh", ".py"})

package/src/mcp/eval_store.py

@@ -2,7 +2,7 @@
 """Plugin eval certification storage — ``plugin_eval`` memory namespace.
 
 Thin stdlib-only wrapper around the memory SQLite DB (same schema as
-``src/mcp/memory_mcp_server.py``) for plugin-eval certification results.
+``src/mcp/memory_mcp.py``) for plugin-eval certification results.
 
 Namespace: ``plugin_eval``
 Key format: ``eval:<name>:<date>``  (e.g. ``eval:tdd-with-agents:2026-08-21``)
@@ -30,7 +30,7 @@ from typing import Any
 
 NAMESPACE = "plugin_eval"
 
-# Minimal schema — matches memory_mcp_server.SCHEMA_SQL for the memories
+# Minimal schema — matches memory_mcp.SCHEMA_SQL for the memories
 # table (vec/FTS tables are initialized by the memory MCP server on first
 # run; eval entries remain readable via list/recall regardless).
 _SCHEMA_SQL = """

package/src/mcp/{mcp_persistence_server.py → mcp_persistence.py}

@@ -5,7 +5,7 @@ Key-Value store with FTS5 full-text search, TTL-based expiration,
 and namespace isolation. Uses SQLite with zero external dependencies.
 
 Usage:
-    python scripts/mcp_persistence_server.py
+    python scripts/mcp_persistence.py
 """
 
 from __future__ import annotations
@@ -25,7 +25,7 @@ from pathlib import Path
 from typing import Annotated
 
 from _pantheon_paths import pantheon_home, pantheon_project
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 from pydantic import Field
 
 # ── Schema ──────────────────────────────────────────────────────────────────────
@@ -914,15 +914,35 @@ def _validate_delegations(delegations: object) -> None:
 
 def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
     """Validate bounded serialized tail lines."""
-    if not isinstance(tail, list) or len(tail) > MAX_TAIL_ITEMS:
-        raise ValueError("tail exceeds its size limit")
+    if not isinstance(tail, list):
+        raise ValueError("tail must be an array")
+    if len(tail) > MAX_TAIL_ITEMS:
+        raise ValueError(
+            f"tail has {len(tail)} items; maximum is {MAX_TAIL_ITEMS}; "
+            "remove tail entries or omit tail"
+        )
     for line in tail:
-        if not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH:
-            raise ValueError("tail entries exceed their size limit")
+        if not isinstance(line, str):
+            raise ValueError("tail entries must be strings")
+        line_bytes = len(line.encode())
+        if line_bytes > MAX_TAIL_LINE_LENGTH:
+            raise ValueError(
+                f"tail entries are {line_bytes:,} UTF-8 bytes; maximum is "
+                f"{MAX_TAIL_LINE_LENGTH:,}; remove or shorten tail entries, "
+                "or omit tail"
+            )
     if payload_bytes is not None and payload_bytes > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
-    if sum(len(line.encode()) for line in tail) > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
+        raise ValueError(
+            f"tail payload is {payload_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,}; remove tail entries or omit tail"
+        )
+    tail_bytes = sum(len(line.encode()) for line in tail)
+    if tail_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError(
+            f"tail contains {tail_bytes:,} UTF-8 bytes across strings; maximum "
+            f"is {MAX_CONTEXT_CONTENT_BYTES:,} bytes; remove tail entries or "
+            "omit tail"
+        )
     return tail
 
 
@@ -1020,8 +1040,14 @@ def _collect_context_content_errors(
     if not isinstance(content, str):
         errors.shape(prefix, "a string", content)
         return
-    if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
-        errors.add(prefix, f"exceeds the {MAX_CONTEXT_CONTENT_BYTES}-byte limit")
+    content_bytes = len(content.encode())
+    if content_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        errors.add(
+            prefix,
+            f"is {content_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,} bytes. Reduce content or omit "
+            "optional tail if it contributes",
+        )
         return
     try:
         parsed = json.loads(content)
@@ -1030,11 +1056,10 @@ def _collect_context_content_errors(
         # it as a checkpoint. It is still bounded above.
         return
     if isinstance(parsed, list) and key == "tail":
-        if len(parsed) > MAX_TAIL_ITEMS or any(
-            not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH
-            for line in parsed
-        ):
-            errors.add(f"{prefix}.tail", "exceeds its size limit")
+        try:
+            _validate_tail(parsed)
+        except ValueError as exc:
+            errors.reroot(prefix, str(exc))
         return
     if not isinstance(parsed, dict):
         # The message already names 'content': do not prepend the path again.
@@ -1164,6 +1189,11 @@ def _upsert_context_entry(
     name="context_save",
     description="Save a context checkpoint for a session/phase. "
     "Stores structured JSON in persistence KV with a key-specific TTL. "
+    "The serialized content is limited to 65,536 UTF-8 bytes. An included "
+    "tail may contain at most 100 strings, each at most 4,096 UTF-8 bytes, "
+    "with at most 65,536 UTF-8 bytes across all tail strings. Oversized "
+    "content or tail is rejected, never truncated; remove or omit optional "
+    "tail data when applicable. "
     "content is a JSON STRING; when it parses to an object, 'goal', 'phase', "
     "'delegations' and 'heartbeat' must each be JSON OBJECTS and 'tail' must "
     "be a JSON ARRAY. 'phase' is an object {current,total,name} — NOT a phase "
@@ -1180,7 +1210,12 @@ async def context_save(
         str,
         Field(
             description=(
-                "JSON checkpoint string. When it parses to an object, 'goal', "
+                "JSON checkpoint string, limited to 65,536 UTF-8 bytes. An "
+                "included 'tail' may contain at most 100 strings, each at "
+                "most 4,096 UTF-8 bytes, with at most 65,536 UTF-8 bytes "
+                "across all tail strings. Oversized input is rejected, never "
+                "truncated; remove or omit optional 'tail' when applicable. "
+                "When it parses to an object, 'goal', "
                 "'phase', 'delegations' and 'heartbeat' must be objects and "
                 "'tail' must be an array; all are optional. 'phase' is an "
                 "object {current,total,name}, not a counter. Example: "

package/{scripts/mcp_resources_server.py → src/mcp/mcp_resources.py}

@@ -7,7 +7,7 @@ Provides MCP resources for the Pantheon agent framework:
   plans/status, memory-bank files
 
 Usage:
-    python scripts/mcp_resources_server.py
+    python scripts/mcp_resources.py
 """
 
 from __future__ import annotations
@@ -19,7 +19,7 @@ from typing import Any
 import yaml
 from _pantheon_paths import has_symlink_component, pantheon_home, pantheon_project
 from eval_store import get_latest_eval, list_evals
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 
 # ── Path Resolution ──────────────────────────────────────────────────────────
 _PANTHEON_HOME: Path = pantheon_home()

package/src/mcp/{memory_mcp_server.py → memory_mcp.py}

@@ -19,7 +19,7 @@ Tools:
     memory_stats   — DB statistics
 
 Usage:
-    python scripts/memory_mcp_server.py
+    python scripts/memory_mcp.py
 """
 
 from __future__ import annotations
@@ -34,7 +34,7 @@ from pathlib import Path
 from typing import Annotated, Any
 
 from _pantheon_paths import pantheon_home
-from mcp.server.fastmcp import FastMCP
+from fastmcp import FastMCP
 from pydantic import BeforeValidator, Field
 
 try: