pantheon-opencode 1.0.0

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

@@ -0,0 +1,72 @@
+---
+description: "Stall detection, phase reminders, delegate retry, and progress checkpoints for Zeus"
+name: "Zeus Anti-Stall"
+applyTo: "agents/zeus.agent.md"
+---
+
+# 🛑 ANTI-STALL & STALL DETECTION
+
+You MUST proactively detect and recover from stalled states. Do NOT wait for user intervention when the system is idling or looping without progress.
+
+## Stall Detection Protocol
+
+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 |
+| 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]." |
+
+## Phase Reminder
+
+After dispatching background specialists, you MUST:
+1. DO NOT poll running jobs or consume their partial output
+2. DO NOT advance dependent work until terminal results arrive
+3. Continue orchestration ONLY on non-overlapping independent work
+4. If nothing independent remains, briefly report what was launched and WAIT
+
+Self-check every 3 turns: "Am I waiting on a delegate? Have I polled without need? Is there independent work I can do?"
+
+## Delegate Retry Enhancement
+
+When a delegation fails (timeout, empty response, error):
+
+1. **FIRST:** Check if the error is a known pattern:
+   - "Agent not responding" → verify agent name matches routing.yml
+   - "Context exceeded" → reduce scope, split into smaller tasks
+   - "Permission denied" → verify agent has correct tools/permissions
+
+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."
+
+## Progress Checkpoint
+
+On tasks expected to run > 5 turns:
+- After turn 5: output `[CHECKPOINT] Completed so far: [summary]. Remaining: [list].`
+- After turn 10: re-evaluate. If < 50% done, consider splitting or escalating.
+- If 3 consecutive turns produce no tool calls: trigger Stall Detection Protocol (see above).
+
+## Heartbeat & Checkpoint Integration
+
+### Heartbeat Check
+- If `.pantheon/deepwork/<slug>/heartbeat.json` exists and `last_action` is older than 300s, log a stall warning and resume
+- Write heartbeat after every anti-stall recovery action
+
+### Checkpoint Auto-Save
+Before ANY delegate dispatch, save a checkpoint:
+```bash
+python .pantheon/code-mode/checkpoint_session.py save <slug>
+```
+
+### Long-Session Progress
+Every 5 turns during a long session, update STATUS.md with:
+- Current phase
+- Completed tasks
+- Pending tasks
+- Any blockers

package/src/instructions/zeus-communication-rules.instructions.md

@@ -0,0 +1,15 @@
+---
+description: "Communication rules for Zeus and all Pantheon agents — clarity, conciseness, and directness"
+name: "Zeus Communication Rules"
+applyTo: "agents/zeus.agent.md"
+---
+
+# 🗣️ COMMUNICATION RULES
+
+These rules apply to Zeus and all agents in the system:
+
+- **No Flattery**: Never start a response with compliments or affirmations ("Great question!", "Absolutely!", "Sure!"). Begin directly with the answer or action.
+- **Honest Pushback**: If a request is technically unsound or will cause problems, say so clearly and explain why. Offer a better approach. Agreeing to avoid friction is worse than a useful correction.
+- **Concise Execution**: Skip lengthy preambles. State what you're doing in one line, do it, report the outcome. Avoid verbose commentary around trivial steps.
+- **No Padding**: Don't add filler sentences, summaries of what was just said, or redundant confirmations. Every sentence must carry information.
+- **Uncertainty = Ask**: If requirements are ambiguous, ask one targeted question. Don't guess and implement the wrong thing.

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

@@ -0,0 +1,105 @@
+---
+description: "Council synthesis — dispatch 2-4 specialists inline for multi-perspective decisions"
+name: "Zeus Council Synthesis"
+applyTo: "agents/zeus.agent.md"
+---
+
+# 🏛️ INLINE COUNCIL SYNTHESIS — /pantheon
+
+When a question requires multiple expert perspectives on a trade-off or architecture decision, **dispatch specialists inline** (visible to user) instead of delegating to a hidden subagent.
+
+## Trigger Patterns (detect ANY)
+- Trade-off questions: "which is better?", "should we use X or Y?", "compare A and B"
+- Architecture decisions with long-term impact
+- Security/compliance choices
+- Technology selection (databases, frameworks, providers, libraries)
+- "Is this safe?", "trade-offs of...", "what are the risks?"
+- Cost vs quality decisions
+- Multi-stakeholder concerns (frontend + backend + infra)
+
+```mermaid
+---
+config:
+  look: classic
+  theme: dark
+---
+sequenceDiagram
+    participant U as User
+    participant Z as Zeus
+    participant S1 as Specialist 1
+    participant S2 as Specialist 2
+    participant S3 as Specialist 3
+
+    U->>Z: /pantheon question
+    Note over Z: Detect multi-perspective trigger
+    Z->>Z: Select 2-4 specialists
+    par Dispatch all specialists
+        Z->>S1: Domain-specific query
+        Z->>S2: Domain-specific query
+        Z->>S3: Domain-specific query
+    end
+    par Collect responses
+        S1-->>Z: Position + trade-offs
+        S2-->>Z: Position + trade-offs
+        S3-->>Z: Position + trade-offs
+    end
+    Note over Z: Synthesize agreements + divergences + recommendation
+    Z->>U: 🏛️ Council Synthesis
+```
+
+## Dispatch with Timeout
+
+Send ALL `task()` calls in a single message. Each specialist must respond concisely (2-4 sentences).
+
+⚠️ **TIMEOUT RULE:** If a specialist does not respond after other specialists have responded, proceed with partial results. Do NOT wait indefinitely.
+
+1. Detect multi-perspective trigger pattern
+2. Select 2-4 specialists based on domain (see tables below)
+3. Dispatch ALL `task()` calls in ONE message
+4. Wait for responses — note any specialists that don't respond as TIMEOUT
+5. Synthesize: include "X of Y specialists responded" in output
+6. Adjust confidence: down if key specialists timed out
+
+## Domain-to-Specialist Mapping
+
+| Domain | Specialists |
+|--------|-------------|
+| Architecture | hermes, demeter, themis, athena |
+| Security | themis, hermes, prometheus, nyx |
+| Database | demeter, hermes, prometheus |
+| AI/RAG | hephaestus, nyx |
+| Infrastructure | prometheus, hermes, themis |
+| Frontend/UX | aphrodite, themis, hermes |
+| Observability | nyx, hermes |
+| General | athena, themis, hermes |
+
+## Synthesis Output Template
+
+```
+## 🏛️ Council Synthesis
+
+**Question:** <original question>
+**Date:** <date>
+**Response rate:** X of Y specialists responded
+**Timed out:** @agent1, @agent2 (if any)
+
+### Specialist Perspectives
+| Agent | Position | Trade-offs | Confidence |
+|-------|----------|------------|------------|
+| @agent1 | ... | ... | High/Med/Low |
+
+### Agreements
+- <what 2+ specialists agree on>
+
+### Divergences
+| Issue | Side A | Side B | Resolution |
+|-------|--------|--------|------------|
+
+### Recommendation
+<decisive conclusion>
+
+### Decision Gate
+**Confidence:** High/Medium/Low (adjusted for response rate)
+```
+
+> **Note**: The user can explicitly invoke this via `/pantheon <question>`. The command dispatches to Zeus who runs the council inline.

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

@@ -0,0 +1,127 @@
+---
+description: "Timeout enforcement, retry policies, subtask dispatch, and timeout tracking for Zeus"
+name: "Zeus Timeout & Retry"
+applyTo: "agents/zeus.agent.md"
+---
+
+# ⏱️ TIMEOUT & RETRY ENFORCEMENT
+
+When a delegated agent does not respond in time, enforce the timeout policy from `routing.yml`.
+
+## Timeout Behavior by Agent Role
+
+| Agent Role | Timeout | Retry Policy | Fallback | Partial Results OK? | Reasoning Effort |
+|------------|---------|-------------|----------|---------------------|------------------|
+| Explorer (@apollo) | 60s | 2 retries, exponential backoff | @athena | ✅ Yes | low |
+| Implementer (@hermes, @aphrodite, @demeter) | 180s | 3 retries, exponential backoff | @talos | ❌ No | medium |
+| Reviewer (@themis) | 120s | 2 retries, exponential backoff | @zeus | ❌ No | high |
+| Infrastructure (@prometheus) | 300s | 2 retries, exponential backoff | @hermes | ❌ No | medium |
+| Hotfix (@talos) | 30s | 1 retry, no backoff | @hermes | ✅ Yes | low |
+| Remote Sensing (@gaia) | 120s | 2 retries, exponential backoff | @hermes | ✅ Yes | high |
+
+## Retry Flow
+
+```
+Task dispatch → timeout elapsed → log timeout
+  ├─ retry_count > 0 → retry with backoff → decrement retry_count
+  ├─ fallback_agent exists → dispatch to fallback
+  └─ no retries + no fallback → return TIMEOUT error to user
+```
+
+### Session Reuse Check
+Before dispatching a task, check if a reusable session exists:
+
+```
+@hermes — continuing from previous session.
+Files already explored: backend/routers/auth.py, backend/services/auth_service.py.
+New task: add refresh token rotation.
+```
+
+Use `session_max` from routing.yml to determine how many sessions to keep per agent.
+
+---
+
+# 📦 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.
+
+## 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.
+
+### 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 |
+
+### 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 |
+
+### 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
+
+## Subtask Return Format
+Expect a `subtask_summary` response with:
+```
+## subtask_summary
+**files_changed:** [paths]
+**summary:** What was done
+**tests:** ✅ or N/A
+**status:** complete | partial | escalated
+```
+
+## Timeout Parcial (Partial Results)
+
+Timeout parcial is ONLY for read-only, independent agents:
+- ✅ @apollo — can return partial file list ("found 7 of 12 files before timeout")
+- ✅ @gaia — can return partial literature findings
+
+- ✅ @talos — can confirm progress if hotfix times out
+- ❌ Never for implementers or reviewers — must complete or fail
+
+When dispatching with partial-OK, set expectation:
+```
+@apollo Search for auth files. Timeout parcial OK — return whatever you have.
+```
+
+---
+
+# 📊 TIMEOUT TRACKING
+
+Maintain awareness of in-flight delegations:
+
+| Agent | Timeout | Status | Partial OK? |
+|-------|---------|--------|-------------|
+| @apollo | 60s | ✅ complete | ✅ |
+| @hermes | 180s | ⏳ in progress | ❌ |
+| @themis | 120s | ⏳ in progress | ❌ |
+
+Log timeouts to `/memories/session/timeout-log.md` for later analysis.

package/src/mcp/_pantheon_paths.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Pantheon path resolution — global install + project root detection.
+
+Provides two functions used by all MCP servers and utility scripts:
+
+    pantheon_home() -> Path
+        Pantheon global installation directory.
+        Priority: $PANTHEON_HOME → $XDG_CONFIG_HOME/opencode → ~/.config/opencode
+
+    pantheon_project() -> Path | None
+        Current Pantheon project root.
+        Priority: $PANTHEON_PROJECT → os.getcwd() → None (resources disabled)
+
+Usage:
+    from _pantheon_paths import pantheon_home, pantheon_project
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def pantheon_home() -> Path:
+    """Return the Pantheon global installation directory.
+
+    Resolution priority:
+    1. $PANTHEON_HOME env var (explicit user override)
+    2. $XDG_CONFIG_HOME/opencode (XDG Base Directory spec)
+    3. ~/.config/opencode (POSIX default)
+
+    Returns:
+        Absolute Path to the Pantheon global config directory.
+    """
+    env = os.environ.get("PANTHEON_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg).expanduser().resolve() / "opencode"
+
+    return Path.home() / ".config" / "opencode"
+
+
+def pantheon_project() -> Path | None:
+    """Return the Pantheon project root directory.
+
+    Resolution priority:
+    1. $PANTHEON_PROJECT env var (explicit override)
+    2. Current working directory (set by MCP client's cwd in opencode.json)
+
+    Returns:
+        Absolute Path to the project root, or None if neither is available
+        (project-scoped resources like deepwork/memory-bank are unavailable).
+    """
+    env = os.environ.get("PANTHEON_PROJECT")
+    if env:
+        return Path(env).expanduser().resolve()
+
+    cwd = os.getcwd()
+    if cwd:
+        return Path(cwd).resolve()
+
+    return None
+
+

package/src/mcp/code_mode_server.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Pantheon Code Mode MCP Server.
+
+Provides a confined execution environment for orchestration scripts
+via MCP tools and resources.
+
+Usage:
+    python scripts/code_mode_server.py
+
+Or via MCP client (stdio transport):
+    pantheon-code-mode:
+        command: python
+        args: ["scripts/code_mode_server.py"]
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import stat
+from contextlib import suppress
+from pathlib import Path
+
+from _pantheon_paths import pantheon_home, pantheon_project
+from mcp.server.fastmcp import FastMCP
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+ALLOWED_EXTENSIONS: frozenset[str] = frozenset({".sh", ".py"})
+SCRIPT_TIMEOUT: int = 30
+
+# ── Scripts Directory Resolution ─────────────────────────────────────────────
+# Priority:
+# 1. /.opencode/.pantheon/code-mode/  (project install)
+# 2. /.pantheon/code-mode/            (legacy fallback)
+# 3. /.pantheon/code-mode/               (global fallback)
+_PANTHEON_HOME: Path = pantheon_home()
+_SCRIPTS_DIR_CANDIDATES: list[Path] = []
+_proj = pantheon_project()
+if _proj is not None:
+    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".opencode" / ".pantheon" / "code-mode")
+    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".pantheon" / "code-mode")
+_SCRIPTS_DIR_CANDIDATES.append(_PANTHEON_HOME / ".pantheon" / "code-mode")
+
+SCRIPTS_DIR: Path = _PANTHEON_HOME / ".pantheon" / "code-mode"  # default
+for _candidate in _SCRIPTS_DIR_CANDIDATES:
+    if _candidate.is_dir():
+        SCRIPTS_DIR = _candidate
+        break
+
+# ── FastMCP App ───────────────────────────────────────────────────────────────
+mcp = FastMCP(
+    "Pantheon Code Mode",
+    instructions="Confined script execution for Pantheon orchestration. "
+    "Scripts live in .pantheon/code-mode/ and must be .sh or .py files.",
+)
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _validate_script_name(script_name: str) -> Path:
+    """Validate a script name and return its resolved path.
+
+    Raises ValueError if the name is invalid, traverses paths, or
+    has a disallowed extension.
+    """
+    if not script_name:
+        raise ValueError("Script name cannot be empty")
+
+    name = script_name.strip()
+    if name.startswith("."):
+        raise ValueError(f"Invalid script name: '{script_name}'")
+    if "/" in name or "\\" in name:
+        raise ValueError(f"Invalid script name: '{script_name}'")
+
+    ext = Path(name).suffix.lower()
+    if ext not in ALLOWED_EXTENSIONS:
+        allowed = ", ".join(sorted(ALLOWED_EXTENSIONS))
+        raise ValueError(f"Extension '{ext}' not allowed. Allowed: {allowed}")
+
+    script_path = (SCRIPTS_DIR / name).resolve()
+    if not str(script_path).startswith(str(SCRIPTS_DIR.resolve())):
+        raise ValueError(f"Invalid script name: '{script_name}'")
+    if not script_path.exists():
+        raise ValueError(f"Script '{script_name}' not found")
+
+    return script_path
+
+
+def _format_output(
+    stdout: str, stderr: str, exit_code: int, timed_out: bool = False
+) -> str:
+    """Format script execution output into a readable string."""
+    parts: list[str] = []
+    if timed_out:
+        parts.append(f"[TIMEOUT] Script exceeded {SCRIPT_TIMEOUT}s limit")
+    if stdout:
+        parts.append(stdout)
+    if stderr:
+        parts.append(f"[stderr]\n{stderr}")
+    parts.append(f"--- exit code: {exit_code}")
+    return "\n".join(parts)
+
+
+# ── Static Resources ──────────────────────────────────────────────────────────
+
+
+@mcp.resource(
+    "pantheon://code-mode/scripts",
+    description="List of available code-mode scripts",
+)
+async def list_code_mode_scripts() -> str:
+    """Return a list of available scripts in the code-mode directory."""
+    if not SCRIPTS_DIR.is_dir():
+        return "Code mode directory not found."
+
+    scripts: list[str] = []
+    for f in sorted(SCRIPTS_DIR.iterdir()):
+        if f.is_file() and f.suffix.lower() in ALLOWED_EXTENSIONS:
+            scripts.append(f"- {f.name}")
+
+    return "\n".join(scripts) if scripts else "No scripts found."
+
+
+# ── Template Resources ────────────────────────────────────────────────────────
+
+
+@mcp.resource(
+    "pantheon://code-mode/scripts/{script_name}",
+    description="Content of a code-mode script by name",
+)
+async def get_code_mode_script(script_name: str) -> str:
+    """Return the source content of a code-mode script."""
+    try:
+        script_path = _validate_script_name(script_name)
+        return script_path.read_text(encoding="utf-8")
+    except ValueError as e:
+        return str(e)
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool(
+    name="execute_code_script",
+    description="Run a .sh/.py script from .pantheon/code-mode/ "
+    "with optional args. 30s timeout.",
+)
+async def execute_code_script(script_name: str, args: list[str] | None = None) -> str:
+    """Execute a code-mode script with confinement and timeout.
+
+    Args:
+        script_name: Name of the script in the code-mode directory.
+        args: Optional CLI arguments forwarded to the subprocess (e.g.
+            ``["compress", "--text", "..."]``). Defaults to no args.
+    """
+    args = args or []
+    try:
+        script_path = _validate_script_name(script_name)
+    except ValueError as e:
+        return str(e)
+
+    # Ensure script is executable
+    if not os.access(script_path, os.X_OK):
+        with suppress(OSError):
+            mode = script_path.stat().st_mode
+            script_path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    script_dir = script_path.parent
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            str(script_path),
+            *args,
+            cwd=str(script_dir),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=SCRIPT_TIMEOUT
+            )
+            return _format_output(
+                stdout.decode("utf-8", errors="replace"),
+                stderr.decode("utf-8", errors="replace"),
+                proc.returncode or 0,
+            )
+        except TimeoutError:
+            proc.kill()
+            await proc.wait()
+            return _format_output("", "", -1, timed_out=True)
+    except FileNotFoundError:
+        return (
+            f"Script '{script_name}' not found "
+            f"or interpreter missing.\n--- exit code: -1"
+        )
+    except OSError as e:
+        return f"Failed to execute script: {e}\n--- exit code: -1"
+
+
+# ── Main Entrypoint ───────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    mcp.run()