pantheon-opencode 1.1.3-beta.0 → 1.2.0

package/opencode.json

@@ -40,41 +40,8 @@
     "themis": {
       "model": "opencode-go/deepseek-v4-pro"
     },
-    "zeus": {
-      "model": "opencode-go/deepseek-v4-pro"
-    },
     "hephaestus": {
       "model": "opencode-go/deepseek-v4-pro"
-    },
-    "hermes": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "aphrodite": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "demeter": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "prometheus": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "apollo": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "nyx": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "gaia": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "iris": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "mnemosyne": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "talos": {
-      "model": "opencode-go/deepseek-v4-flash"
     }
   }
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.1.3-beta.0",
-  "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
+  "version": "1.2.0",
+  "description": "Multi-agent orchestration for OpenCode \u2014 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -15,7 +15,7 @@
     "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "prepublishOnly": "node scripts/validate-routing.mjs",
-    "postpublish": "node -e \"console.log('✅ Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
+    "postpublish": "node -e \"console.log('\u2705 Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
     "version:status": "node scripts/versioning.mjs status",
     "version:apply": "node scripts/versioning.mjs apply",
     "release:dry-run": "node scripts/versioning.mjs status && npm pack --dry-run",
@@ -80,4 +80,4 @@
     "node": ">=18"
   },
   "preferGlobal": true
-}
+}

package/scripts/mcp_persistence_server.py

@@ -1,4 +1,3 @@
-# Auto-generated: resolved symlink from ../src/mcp/mcp_persistence_server.py
 #!/usr/bin/env python3
 """Pantheon Persistence MCP Server.
 
@@ -36,6 +35,9 @@ CREATE TABLE IF NOT EXISTS kv_store (
     UNIQUE(namespace, key)
 );
 
+CREATE INDEX IF NOT EXISTS idx_kv_namespace_expires
+ON kv_store(namespace, expires_at);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS kv_store_fts USING fts5(
     namespace, key, value,
     content='kv_store', content_rowid='id',
@@ -52,6 +54,14 @@ CREATE TRIGGER IF NOT EXISTS kv_store_ad AFTER DELETE ON kv_store BEGIN
     VALUES('delete', old.id, old.namespace, old.key, old.value);
 END;
 
+CREATE TRIGGER IF NOT EXISTS kv_store_softdelete_ad
+AFTER UPDATE OF deleted_at ON kv_store
+WHEN new.deleted_at IS NOT NULL AND old.deleted_at IS NULL
+BEGIN
+    INSERT INTO kv_store_fts(kv_store_fts, rowid)
+    VALUES('delete', old.id);
+END;
+
 CREATE TRIGGER IF NOT EXISTS kv_store_au AFTER UPDATE ON kv_store BEGIN
     INSERT INTO kv_store_fts(kv_store_fts, rowid, namespace, key, value)
     VALUES('delete', old.id, old.namespace, old.key, old.value);
@@ -220,6 +230,10 @@ async def kv_store(
         (namespace, key, value, expires_at),
     )
     conn.commit()
+
+    # Opportunistic auto-purge: if namespace has >500 entries, purge expired
+    _opportunistic_auto_purge(conn, namespace)
+    
     return {"status": "stored", "namespace": namespace, "key": key}
 
 
@@ -254,6 +268,52 @@ async def kv_get(
     return str(row[0]) if row else None
 
 
+@mcp.tool(
+    name="kv_stats",
+    description="Return storage statistics: total entries, expired count, per-namespace breakdown, DB file size.",
+)
+async def kv_stats(
+    scope: str = "project",
+) -> dict:
+    """Return storage statistics for the given scope.
+
+    Args:
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Dict with total_entries, expired_entries, namespaces breakdown, db_size_bytes.
+    """
+    conn = _db(scope)
+
+    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') "
+        "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 "
+        "FROM kv_store WHERE deleted_at IS NULL GROUP BY namespace ORDER BY cnt DESC"
+    ).fetchall()
+
+    namespaces = {
+        r[0]: {"count": r[1], "expired": r[2]}
+        for r in ns_rows
+    }
+
+    db_path = _resolve_db_path(scope)
+    db_size = db_path.stat().st_size if db_path and db_path.exists() else 0
+
+    return {
+        "scope": scope,
+        "total_entries": total,
+        "expired_entries": expired,
+        "namespaces": namespaces,
+        "db_size_bytes": db_size,
+    }
+
 @mcp.tool(
     name="kv_delete",
     description="Delete a key-value pair by namespace and key. "
@@ -353,6 +413,7 @@ async def kv_search(
 
     # Sanitize: extract up to 10 word tokens, wrap each in quotes
     terms = re.findall(r"\w+", query)[:10]
+    terms = [re.escape(t) for t in terms]
     if not terms:
         return []
     fts_query = " OR ".join(f'"{t}"' for t in terms)
@@ -441,6 +502,275 @@ async def purge_expired(
     return {"purged": count, "dry_run": False}
 
 
+
+def _opportunistic_auto_purge(conn: sqlite3.Connection, namespace: str, threshold: int = 500) -> None:
+    """Lightweight auto-purge: if namespace exceeds threshold, soft-delete expired entries."""
+    count = conn.execute(
+        "SELECT COUNT(*) FROM kv_store WHERE namespace = ? AND deleted_at IS NULL",
+        (namespace,),
+    ).fetchone()[0]
+    if count <= threshold:
+        return
+
+    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",
+        (namespace,),
+    )
+    conn.commit()
+
+
+@mcp.tool(
+    name="kv_delete_namespace",
+    description="Delete all entries in a namespace. Optionally limit to entries older than N days.",
+)
+async def kv_delete_namespace(
+    namespace: str,
+    scope: str = "project",
+    older_than_days: int | None = None,
+) -> dict:
+    """Delete all entries in a namespace, optionally old entries only.
+
+    Args:
+        namespace: Namespace to clear.
+        scope: 'project' (default) or 'global'.
+        older_than_days: If set, only delete entries older than this many days.
+
+    Returns:
+        Dict with deleted count.
+    """
+    conn = _db(scope)
+
+    if older_than_days is not None:
+        cursor = conn.execute(
+            "DELETE FROM kv_store WHERE namespace = ? "
+            "AND datetime(created_at) < datetime('now', ? || ' days')",
+            (namespace, f"-{older_than_days}"),
+        )
+    else:
+        cursor = conn.execute(
+            "DELETE FROM kv_store WHERE namespace = ?",
+            (namespace,),
+        )
+    conn.commit()
+
+    return {"deleted": cursor.rowcount}
+
+
+# ── Context Checkpoint Tools ────────────────────────────────────────────────────
+# Session-scoped context storage for deepwork checkpoints, phase state,
+# tool call history, and reasoning chains. All entries use namespace
+# "checkpoint:{slug}" with auto-TTL of 4 hours (session duration).
+
+DEFAULT_CONTEXT_TTL: int = 14400  # 4 hours
+
+
+@mcp.tool(
+    name="context_save",
+    description="Save a context checkpoint for a session/phase. "
+    "Stores structured JSON in persistence KV with auto-TTL of 4h.",
+)
+async def context_save(
+    slug: str,
+    key: str,
+    content: str,
+    session_id: str | None = None,
+    ttl: int | None = None,
+    scope: str = "project",
+) -> dict:
+    """Save a context checkpoint with session-level isolation.
+
+    If session_id is provided, namespace becomes "checkpoint:{slug}:{session_id}"
+    preventing cross-session reads. If omitted, a random UUID is auto-generated
+    and returned so the caller can pass it to subsequent calls.
+
+    Args:
+        slug: Session identifier (e.g. "auth-refactor").
+        key: Checkpoint key (e.g. "phase:3", "latest", "heartbeat").
+        content: JSON-serializable string or any text content.
+        session_id: Unique session ID for namespace isolation (auto-generated if None).
+        ttl: TTL in seconds (default 4h / 14400). None = session duration.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Status dict with namespace, key, and session_id for subsequent calls.
+    """
+    actual_session = session_id or uuid.uuid4().hex[:12]
+    ns = f"checkpoint:{slug}:{actual_session}"
+    actual_ttl = ttl if ttl is not None else DEFAULT_CONTEXT_TTL
+
+    conn = _db(scope)
+    expires_at = (datetime.now(timezone.utc) + timedelta(seconds=actual_ttl)).isoformat()
+
+    conn.execute(
+        "INSERT INTO kv_store (namespace, key, value, expires_at, "
+        "created_at, updated_at) VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))"
+        "ON CONFLICT(namespace, key) DO UPDATE SET "
+        "  value = excluded.value, "
+        "  expires_at = excluded.expires_at, "
+        "  updated_at = datetime('now')",
+        (ns, key, content, expires_at),
+    )
+    conn.commit()
+
+    # Also always update "latest" pointer
+    if key != "latest":
+        # Use a larger TTL for "latest" to outlive individual phase entries
+        conn.execute(
+            "INSERT INTO kv_store (namespace, key, value, expires_at, "
+            "created_at, updated_at) VALUES (?, 'latest', ?, ?, datetime('now'), datetime('now'))"
+            "ON CONFLICT(namespace, key) DO UPDATE SET "
+            "  value = excluded.value, "
+            "  expires_at = excluded.expires_at, "
+            "  updated_at = datetime('now')",
+            (ns, content, expires_at),
+        )
+        conn.commit()
+
+    return {"status": "stored", "namespace": ns, "key": key, "session_id": actual_session, "ttl": actual_ttl}
+
+
+@mcp.tool(
+    name="context_get",
+    description="Retrieve a context checkpoint by session slug and key. "
+    "Returns the raw content string or null if expired/not found.",
+)
+async def context_get(
+    slug: str,
+    key: str = "latest",
+    session_id: str | None = None,
+    scope: str = "project",
+) -> str | None:
+    """Get a context checkpoint with session isolation.
+
+    Args:
+        slug: Session identifier.
+        key: Checkpoint key (default "latest").
+        session_id: Required for isolation. If None, searches without session scope.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Content string or None if not found/expired.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    row = conn.execute(
+        "SELECT value FROM kv_store "
+        "WHERE namespace = ? AND key = ? "
+        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND deleted_at IS NULL",
+        (ns, key),
+    ).fetchone()
+    return row[0] if row else None
+
+
+@mcp.tool(
+    name="context_list",
+    description="List all context checkpoints for a session slug. "
+    "Returns keys, timestamps, and TTL info.",
+)
+async def context_list(
+    slug: str,
+    session_id: str | None = None,
+    scope: str = "project",
+) -> list[dict]:
+    """List all checkpoints for a session.
+
+    Args:
+        slug: Session identifier.
+        session_id: Optional. If provided, narrows to specific session.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        List of dicts with key, created_at, expires_at.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    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 deleted_at IS NULL "
+        "ORDER BY created_at DESC LIMIT 50",
+        (ns,),
+    ).fetchall()
+    return [
+        {
+            "key": r[0],
+            "created_at": r[1],
+            "expires_at": r[2],
+        }
+        for r in rows
+    ]
+
+
+@mcp.tool(
+    name="context_stats",
+    description="Return session context statistics: "
+    "checkpoint count, TTL remaining, total size per slug.",
+)
+async def context_stats(
+    slug: str,
+    session_id: str | None = None,
+    scope: str = "project",
+) -> dict:
+    """Return storage statistics for a session's context.
+
+    Args:
+        slug: Session identifier.
+        session_id: Optional. If provided, narrows to specific session.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Dict with entry_count, total_bytes, ttl_remaining.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+
+    count = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    expired = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND expires_at < datetime('now') "
+        "AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    size = conn.execute(
+        "SELECT COALESCE(SUM(LENGTH(value)), 0) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    # Check TTL of latest entry
+    remaining: int | None = None
+    row = conn.execute(
+        "SELECT expires_at FROM kv_store "
+        "WHERE namespace = ? AND key = 'latest' AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()
+    if row and row[0]:
+        try:
+            exp = datetime.fromisoformat(row[0])
+            now = datetime.now(timezone.utc)
+            remaining = max(0, int((exp - now).total_seconds()))
+        except (ValueError, TypeError):
+            pass
+
+    return {
+        "slug": slug,
+        "namespace": ns,
+        "entry_count": count,
+        "expired_entries": expired,
+        "total_bytes": size,
+        "ttl_remaining_seconds": remaining,
+    }
+
 def _resolve_db_path(scope: str) -> Path | None:
     """Resolve the database file path for a given scope."""
     if scope == "global":

package/src/agents/aphrodite.md

@@ -118,3 +118,10 @@ Compress working context with the `context-compression` skill (L1, Pantheon-nati
 
 ## Skills
 Frontend: `tdd-with-agents`, `visual-review-pipeline`, `incremental-implementation`
+
+
+## Session Context Retrieval
+When dispatched by Zeus, call context_get(slug, "latest", session_id=SESSION_ID)
+if session_slug is provided in dispatch metadata. Apply any "remaining_tasks",
+"current_phase", or "gotchas" from the retrieved context.
+If context_get returns None, proceed fresh (first phase or expired session).

package/src/agents/demeter.md

@@ -107,3 +107,10 @@ Compress working context with the `context-compression` skill (L1, Pantheon-nati
 
 ## Skills
 `tdd-with-agents`, `incremental-implementation`
+
+
+## Session Context Retrieval
+When dispatched by Zeus, call context_get(slug, "latest", session_id=SESSION_ID)
+if session_slug is provided in dispatch metadata. Apply any "remaining_tasks",
+"current_phase", or "gotchas" from the retrieved context.
+If context_get returns None, proceed fresh (first phase or expired session).

package/src/agents/hephaestus.md

@@ -60,3 +60,10 @@ Compress working context with the `context-compression` skill (L1, Pantheon-nati
 **How**: call `execute_code_script("compress-inline.py", args=["compress", "--text", "<content>"])`. Use `score` to preview priority, `batch` for multiple files. See the `context-compression` skill for the full protocol.
 
 **Note**: scrubbing is automatic in the MCP layer; never embed raw secrets in the `--text` argument beyond what the tool scrubs.
+
+
+## Session Context Retrieval
+When dispatched by Zeus, call context_get(slug, "latest", session_id=SESSION_ID)
+if session_slug is provided in dispatch metadata. Apply any "remaining_tasks",
+"current_phase", or "gotchas" from the retrieved context.
+If context_get returns None, proceed fresh (first phase or expired session).

package/src/agents/hermes.md

@@ -265,3 +265,10 @@ Compress working context with the `context-compression` skill (L1, Pantheon-nati
 
 ## Skills
 Implementação: `tdd-with-agents`, `incremental-implementation`, `code-review-checklist`, `git-workflow-and-versioning`
+
+
+## Session Context Retrieval
+When dispatched by Zeus, call context_get(slug, "latest", session_id=SESSION_ID)
+if session_slug is provided in dispatch metadata. Apply any "remaining_tasks",
+"current_phase", or "gotchas" from the retrieved context.
+If context_get returns None, proceed fresh (first phase or expired session).

package/src/agents/zeus.md

@@ -4,10 +4,9 @@ mode: primary
 reasoning_effort: medium
 permission:
   edit: deny
-  bash: allow
+  bash: deny
   task:
     "*": allow
-  pantheon-code-mode_*: ask
 temperature: 0.2
 steps: 45
 mcp_tools:
@@ -16,8 +15,6 @@ mcp_tools:
     - memory_recall
     - memory_store
     - memory_search
-  pantheon-code-mode:
-    - execute_code_script
   pantheon-persistence:
     - kv_get
     - kv_store
@@ -42,6 +39,34 @@ skills:
 
 **Coordenador APENAS.** Leu arquivo → delegue. Nunca implemente, nunca edite, nunca debugue.
 
+
+## 🔒 Fusion-Style Enforcement
+
+**Zeus NUNCA edita arquivos.** Esta é uma trava de PERMISSÃO, não só instrução:
+- `edit: deny` — OpenCode bloqueia qualquer tentativa de edição
+- `bash: deny` — Zero acesso a shell. Nem leitura, nem diagnóstico.
+- `execute_code_script` removido — Zeus não executa scripts
+
+O fluxo é SEMPRE: **Planejar → Especificar → Delegar → Revisar**. Zeus nunca toca no código.
+
+### Bloqueios explícitos
+| Ação | Status | Como fazer |
+|------|--------|------------|
+| Editar arquivo | ❌ BLOQUEADO | Delegar para @hermes, @aphrodite, @talos |
+| Bash shell | ❌ BLOQUEADO | Usar task() com subagente apropriado |
+| Executar script | ❌ BLOQUEADO | Delegar para @prometheus |
+| Instalar dep | ❌ BLOQUEADO | Delegar para @prometheus |
+| Git commit/push | ❌ BLOQUEADO | Delegar para @iris |
+| Ler arquivo | ✅ Permitido | Via Read/Glob/Grep tools |
+| task() delegar | ✅ Permitido | Única ferramenta de ação de Zeus |
+| memory MCP | ✅ Permitido | memory_search, memory_store, memory_recall |
+| skill() | ✅ Permitido | Carregar skills |
+
+### Se algo precisar ser feito e não houver subagente apropriado
+1. Consulte a árvore de roteamento (pantheon://routing)
+2. Pergunte ao usuário qual agente usar
+3. NUNCA tente fazer você mesmo
+
 **Approval gates** (via `agent/askQuestions`):
 0. Council -> FULL STOP -> AGUARDAR approve/changes/discard
 1. Planejamento -> "Plan approved?"
@@ -50,18 +75,6 @@ skills:
 
 **Auto-continue** só com pedido explícito do usuário.
 
-## ⚠️ Bash Scoping
-
-**`bash: allow` é para leitura e diagnóstico APENAS.**
-NUNCA use bash para:
-- Editar arquivos (use sed/echo/redirect → delegue para @hermes)
-- Instalar dependências (delegue para @prometheus)
-- Executar comandos que modificam o sistema
-
-Comandos permitidos: `ls`, `git status`, `git log`, `ps`, `python3 -c`, `cat` (leitura), `npm test` (para verificar).
-
----
-
 ## Delegation Cache (Otimizacao de Tokens)
 
 Antes de usar a arvore de roteamento, consulte o memory:
@@ -159,7 +172,7 @@ Limite maximo de 2 niveis de nesting: Zeus -> subagente -> sub-subagente.
 
 ```
 depth = kv_get("deleg:depth") ?? 0
-if depth >= 2 → NAO delegar, execute voce mesmo
+if depth >= 2 → NAO delegar, ESCALAR para o usuario
 else → kv_store("deleg:depth", depth + 1)
 
 Quando subagente retornar:
@@ -177,7 +190,7 @@ Zeus (nivel 0) -> Apollo/Hermes (nivel 1) -> sub-subagente (nivel 2 max).
 
 ## MCP Tools
 
-`memory_recall()` inicio, `memory_store()` apos cada fase. `pantheon://routing` para consultar. `execute_code_script()` para sequencias.
+`memory_recall()` inicio, `memory_store()` apos cada fase. `pantheon://routing` para consultar.
 
 ### References
 - Routing: `pantheon://routing`

package/src/instructions/agent-return-format.instructions.md

@@ -13,6 +13,7 @@ All implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) M
 **summary:** What was done, in 2-3 sentences
 **tests:** ✅ All passing / ⚠️ X failing / ❌ Not run (reason)
 **coverage:** X% (if applicable)
+**tokens:** ~N input / ~M output (estimated)
 **status:** complete | partial (reason) | escalated (reason)
 **blockers:** [list any blockers or null]
 

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

@@ -54,14 +54,52 @@ On tasks expected to run > 5 turns:
 
 ## Heartbeat & Checkpoint Integration
 
+All session state lives in **pantheon-persistence** (namespace `checkpoint:<slug>`).
+No file I/O, no checkpoint_session.py — TTL (4h) handles cleanup automatically.
+
 ### 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
+- If `context_get(slug, "heartbeat")` returns a checkin older than 300s, log a stall warning and resume
+- Write heartbeat after every anti-stall recovery action:
+  ```
+  context_save(slug, "heartbeat", json({"status": "alive", "last_action": "...", "turn_count": N}))
+  ```
 
-### Checkpoint Auto-Save
+### Checkpoint Auto-Save (Pré-Compactação)
 Before ANY delegate dispatch, save a checkpoint:
-```bash
-python .pantheon/code-mode/checkpoint_session.py save <slug>
+```
+context_save(slug, "phase:N", json({
+  "phase": N, "turn_count": N, "agent": "...", "summary": "..."
+}), session_id=SESSION_ID)
+```
+All checkpoints auto-expire after 4h (TTL=14400).
+
+### Gatilho de Pré-Compactação (Anti-perda de estado)
+Antes da compactação nativa do OpenCode disparar (75-96% do context window),
+o Zeus DEVE salvar o estado atual:
+1. Capture session_id do primeiro `context_save` da sessão
+2. Salve heartbeat + phase atual + tarefas pendentes
+3. Só então permita que a compactação prossiga
+```
+# Ao iniciar sessão:
+result = context_save(slug, "init", session_state)
+SESSION_ID = result.session_id   # ← guarde para toda a sessão
+
+# Antes de CADA delegação:
+context_save(slug, f"pre:{agent}", current_state, session_id=SESSION_ID)
+
+# Após retorno do agente:
+context_save(slug, f"post:{agent}", result_state, session_id=SESSION_ID)
+```
+Isso garante que o estado sobreviva à compactação — o "latest" pointer
+sempre aponta para o checkpoint mais recente, mesmo após compactação.
+
+
+### Context Retrieval
+Next-phase agents retrieve previous context via:
+```
+context_get(slug, "latest")        # most recent checkpoint
+context_get(slug, "phase:3")      # specific phase
+context_list(slug)                 # all checkpoints
 ```
 
 ### Long-Session Progress

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

@@ -10,24 +10,61 @@ When a delegated agent does not respond in time, enforce the timeout policy from
 
 ## Timeout Behavior by Agent Role
 
-| Agent Role | Timeout | Retry Policy | Fallback | Partial Results OK? | Reasoning Effort |
+| Agent Role | Timeout | Retry Policy | Fallback Chain | 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 |
+| 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 |
 
 ## 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
+  ├─ 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"
 ```
 
+
+
+## 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 |
+
+### 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
+
 ### Session Reuse Check
 Before dispatching a task, check if a reusable session exists:
 

package/src/mcp/mcp_persistence_server.py

@@ -35,6 +35,9 @@ CREATE TABLE IF NOT EXISTS kv_store (
     UNIQUE(namespace, key)
 );
 
+CREATE INDEX IF NOT EXISTS idx_kv_namespace_expires
+ON kv_store(namespace, expires_at);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS kv_store_fts USING fts5(
     namespace, key, value,
     content='kv_store', content_rowid='id',
@@ -51,6 +54,14 @@ CREATE TRIGGER IF NOT EXISTS kv_store_ad AFTER DELETE ON kv_store BEGIN
     VALUES('delete', old.id, old.namespace, old.key, old.value);
 END;
 
+CREATE TRIGGER IF NOT EXISTS kv_store_softdelete_ad
+AFTER UPDATE OF deleted_at ON kv_store
+WHEN new.deleted_at IS NOT NULL AND old.deleted_at IS NULL
+BEGIN
+    INSERT INTO kv_store_fts(kv_store_fts, rowid)
+    VALUES('delete', old.id);
+END;
+
 CREATE TRIGGER IF NOT EXISTS kv_store_au AFTER UPDATE ON kv_store BEGIN
     INSERT INTO kv_store_fts(kv_store_fts, rowid, namespace, key, value)
     VALUES('delete', old.id, old.namespace, old.key, old.value);
@@ -219,6 +230,10 @@ async def kv_store(
         (namespace, key, value, expires_at),
     )
     conn.commit()
+
+    # Opportunistic auto-purge: if namespace has >500 entries, purge expired
+    _opportunistic_auto_purge(conn, namespace)
+    
     return {"status": "stored", "namespace": namespace, "key": key}
 
 
@@ -253,6 +268,52 @@ async def kv_get(
     return str(row[0]) if row else None
 
 
+@mcp.tool(
+    name="kv_stats",
+    description="Return storage statistics: total entries, expired count, per-namespace breakdown, DB file size.",
+)
+async def kv_stats(
+    scope: str = "project",
+) -> dict:
+    """Return storage statistics for the given scope.
+
+    Args:
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Dict with total_entries, expired_entries, namespaces breakdown, db_size_bytes.
+    """
+    conn = _db(scope)
+
+    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') "
+        "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 "
+        "FROM kv_store WHERE deleted_at IS NULL GROUP BY namespace ORDER BY cnt DESC"
+    ).fetchall()
+
+    namespaces = {
+        r[0]: {"count": r[1], "expired": r[2]}
+        for r in ns_rows
+    }
+
+    db_path = _resolve_db_path(scope)
+    db_size = db_path.stat().st_size if db_path and db_path.exists() else 0
+
+    return {
+        "scope": scope,
+        "total_entries": total,
+        "expired_entries": expired,
+        "namespaces": namespaces,
+        "db_size_bytes": db_size,
+    }
+
 @mcp.tool(
     name="kv_delete",
     description="Delete a key-value pair by namespace and key. "
@@ -352,6 +413,7 @@ async def kv_search(
 
     # Sanitize: extract up to 10 word tokens, wrap each in quotes
     terms = re.findall(r"\w+", query)[:10]
+    terms = [re.escape(t) for t in terms]
     if not terms:
         return []
     fts_query = " OR ".join(f'"{t}"' for t in terms)
@@ -440,6 +502,275 @@ async def purge_expired(
     return {"purged": count, "dry_run": False}
 
 
+
+def _opportunistic_auto_purge(conn: sqlite3.Connection, namespace: str, threshold: int = 500) -> None:
+    """Lightweight auto-purge: if namespace exceeds threshold, soft-delete expired entries."""
+    count = conn.execute(
+        "SELECT COUNT(*) FROM kv_store WHERE namespace = ? AND deleted_at IS NULL",
+        (namespace,),
+    ).fetchone()[0]
+    if count <= threshold:
+        return
+
+    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",
+        (namespace,),
+    )
+    conn.commit()
+
+
+@mcp.tool(
+    name="kv_delete_namespace",
+    description="Delete all entries in a namespace. Optionally limit to entries older than N days.",
+)
+async def kv_delete_namespace(
+    namespace: str,
+    scope: str = "project",
+    older_than_days: int | None = None,
+) -> dict:
+    """Delete all entries in a namespace, optionally old entries only.
+
+    Args:
+        namespace: Namespace to clear.
+        scope: 'project' (default) or 'global'.
+        older_than_days: If set, only delete entries older than this many days.
+
+    Returns:
+        Dict with deleted count.
+    """
+    conn = _db(scope)
+
+    if older_than_days is not None:
+        cursor = conn.execute(
+            "DELETE FROM kv_store WHERE namespace = ? "
+            "AND datetime(created_at) < datetime('now', ? || ' days')",
+            (namespace, f"-{older_than_days}"),
+        )
+    else:
+        cursor = conn.execute(
+            "DELETE FROM kv_store WHERE namespace = ?",
+            (namespace,),
+        )
+    conn.commit()
+
+    return {"deleted": cursor.rowcount}
+
+
+# ── Context Checkpoint Tools ────────────────────────────────────────────────────
+# Session-scoped context storage for deepwork checkpoints, phase state,
+# tool call history, and reasoning chains. All entries use namespace
+# "checkpoint:{slug}" with auto-TTL of 4 hours (session duration).
+
+DEFAULT_CONTEXT_TTL: int = 14400  # 4 hours
+
+
+@mcp.tool(
+    name="context_save",
+    description="Save a context checkpoint for a session/phase. "
+    "Stores structured JSON in persistence KV with auto-TTL of 4h.",
+)
+async def context_save(
+    slug: str,
+    key: str,
+    content: str,
+    session_id: str | None = None,
+    ttl: int | None = None,
+    scope: str = "project",
+) -> dict:
+    """Save a context checkpoint with session-level isolation.
+
+    If session_id is provided, namespace becomes "checkpoint:{slug}:{session_id}"
+    preventing cross-session reads. If omitted, a random UUID is auto-generated
+    and returned so the caller can pass it to subsequent calls.
+
+    Args:
+        slug: Session identifier (e.g. "auth-refactor").
+        key: Checkpoint key (e.g. "phase:3", "latest", "heartbeat").
+        content: JSON-serializable string or any text content.
+        session_id: Unique session ID for namespace isolation (auto-generated if None).
+        ttl: TTL in seconds (default 4h / 14400). None = session duration.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Status dict with namespace, key, and session_id for subsequent calls.
+    """
+    actual_session = session_id or uuid.uuid4().hex[:12]
+    ns = f"checkpoint:{slug}:{actual_session}"
+    actual_ttl = ttl if ttl is not None else DEFAULT_CONTEXT_TTL
+
+    conn = _db(scope)
+    expires_at = (datetime.now(timezone.utc) + timedelta(seconds=actual_ttl)).isoformat()
+
+    conn.execute(
+        "INSERT INTO kv_store (namespace, key, value, expires_at, "
+        "created_at, updated_at) VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))"
+        "ON CONFLICT(namespace, key) DO UPDATE SET "
+        "  value = excluded.value, "
+        "  expires_at = excluded.expires_at, "
+        "  updated_at = datetime('now')",
+        (ns, key, content, expires_at),
+    )
+    conn.commit()
+
+    # Also always update "latest" pointer
+    if key != "latest":
+        # Use a larger TTL for "latest" to outlive individual phase entries
+        conn.execute(
+            "INSERT INTO kv_store (namespace, key, value, expires_at, "
+            "created_at, updated_at) VALUES (?, 'latest', ?, ?, datetime('now'), datetime('now'))"
+            "ON CONFLICT(namespace, key) DO UPDATE SET "
+            "  value = excluded.value, "
+            "  expires_at = excluded.expires_at, "
+            "  updated_at = datetime('now')",
+            (ns, content, expires_at),
+        )
+        conn.commit()
+
+    return {"status": "stored", "namespace": ns, "key": key, "session_id": actual_session, "ttl": actual_ttl}
+
+
+@mcp.tool(
+    name="context_get",
+    description="Retrieve a context checkpoint by session slug and key. "
+    "Returns the raw content string or null if expired/not found.",
+)
+async def context_get(
+    slug: str,
+    key: str = "latest",
+    session_id: str | None = None,
+    scope: str = "project",
+) -> str | None:
+    """Get a context checkpoint with session isolation.
+
+    Args:
+        slug: Session identifier.
+        key: Checkpoint key (default "latest").
+        session_id: Required for isolation. If None, searches without session scope.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Content string or None if not found/expired.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    row = conn.execute(
+        "SELECT value FROM kv_store "
+        "WHERE namespace = ? AND key = ? "
+        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND deleted_at IS NULL",
+        (ns, key),
+    ).fetchone()
+    return row[0] if row else None
+
+
+@mcp.tool(
+    name="context_list",
+    description="List all context checkpoints for a session slug. "
+    "Returns keys, timestamps, and TTL info.",
+)
+async def context_list(
+    slug: str,
+    session_id: str | None = None,
+    scope: str = "project",
+) -> list[dict]:
+    """List all checkpoints for a session.
+
+    Args:
+        slug: Session identifier.
+        session_id: Optional. If provided, narrows to specific session.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        List of dicts with key, created_at, expires_at.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    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 deleted_at IS NULL "
+        "ORDER BY created_at DESC LIMIT 50",
+        (ns,),
+    ).fetchall()
+    return [
+        {
+            "key": r[0],
+            "created_at": r[1],
+            "expires_at": r[2],
+        }
+        for r in rows
+    ]
+
+
+@mcp.tool(
+    name="context_stats",
+    description="Return session context statistics: "
+    "checkpoint count, TTL remaining, total size per slug.",
+)
+async def context_stats(
+    slug: str,
+    session_id: str | None = None,
+    scope: str = "project",
+) -> dict:
+    """Return storage statistics for a session's context.
+
+    Args:
+        slug: Session identifier.
+        session_id: Optional. If provided, narrows to specific session.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Dict with entry_count, total_bytes, ttl_remaining.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+
+    count = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    expired = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND expires_at < datetime('now') "
+        "AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    size = conn.execute(
+        "SELECT COALESCE(SUM(LENGTH(value)), 0) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    # Check TTL of latest entry
+    remaining: int | None = None
+    row = conn.execute(
+        "SELECT expires_at FROM kv_store "
+        "WHERE namespace = ? AND key = 'latest' AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()
+    if row and row[0]:
+        try:
+            exp = datetime.fromisoformat(row[0])
+            now = datetime.now(timezone.utc)
+            remaining = max(0, int((exp - now).total_seconds()))
+        except (ValueError, TypeError):
+            pass
+
+    return {
+        "slug": slug,
+        "namespace": ns,
+        "entry_count": count,
+        "expired_entries": expired,
+        "total_bytes": size,
+        "ttl_remaining_seconds": remaining,
+    }
+
 def _resolve_db_path(scope: str) -> Path | None:
     """Resolve the database file path for a given scope."""
     if scope == "global":

package/src/routing.yml

@@ -354,6 +354,37 @@ handoffs:
         with priority-scored entries, write compressed entries to 01-active-context.md
         (priority-aware, budget-allocated), archive IMPL/REVIEW to 02-progress-log.md,
         update _xref/index.md cross-references.'
+
+fallback_chains:
+  apollo:
+    - athena
+    - hermes
+  hermes:
+    - talos
+    - athena
+  aphrodite:
+    - talos
+    - hermes
+  demeter:
+    - hermes
+    - athena
+  themis:
+    - zeus
+  prometheus:
+    - hermes
+    - zeus
+  talos:
+    - hermes
+  hephaestus:
+    - nyx
+    - hermes
+  nyx:
+    - hermes
+  iris:
+    - zeus
+  mnemosyne:
+    - zeus
+
 platforms:
   opencode:
     display_name: OpenCode