pantheon-opencode 1.6.0-beta.7 → 1.6.0-beta.8

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

@@ -6,7 +6,7 @@ agents: ["*"]
 
 # Agent Return Format
 
-Implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) return:
+All implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) MUST return results to Zeus in this format:
 
 ## subtask_summary
 **files_changed:** [list of file paths, one per line]
@@ -17,10 +17,55 @@ Implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) retur
 **status:** complete | partial (reason) | escalated (reason)
 **blockers:** [list any blockers or null]
 
-Investigation agents (Apollo, Athena) return structured findings with:
+For investigation agents (Apollo, Athena), return structured findings with:
 - Key findings as bullet points
 - File paths with line numbers
 - Relevant code snippets (max 3 lines each)
 
+## Council Specialist Response Format
+
+When responding to a `/pantheon` council synthesis invocation, specialists MUST return this structured format:
+
+```
+## specialist_response
+**position:** <clear one-sentence position answering the question>
+**reasoning:** <2-4 sentences with logical chain>
+**trade_offs:** <what's gained vs lost, specific>
+**risks:** <what could go wrong, max 3 items>
+**confidence:** High | Medium | Low
+**agreement_signals:** agree:@agent1 on <issue>, agree:@agent2 on <issue> | disagree:@agent3 on <issue>
+**specific_claims:** <count of specific factual claims in response>
+```
+
+### Field Rules
+
+| Field | Required | Validation |
+|-------|----------|------------|
+| position | ✅ | Single sentence, must directly answer the question |
+| reasoning | ✅ | 2-4 sentences with logical chain |
+| trade_offs | ✅ | At least one gain and one loss, specific to context |
+| risks | ✅ | Max 3 bullet points |
+| confidence | ✅ | One of: High, Medium, Low |
+| agreement_signals | Optional | Format: `agree:@agent on issue \| disagree:@agent on issue`. Use only when you can reference other specialists expected positions. |
+| specific_claims | ✅ | Integer count of verifiable factual statements in the response |
+
+### Confidence Guidelines
+
+- **High**: Position backed by 3+ specific claims with evidence or direct experience
+- **Medium**: Position backed by 1-2 specific claims
+- **Low**: Position is opinion-based or speculative
+
+### Example
+```
+## specialist_response
+**position:** The BackgroundJobBoard should be used for council crash recovery
+**reasoning:** The board already supports running→completed→reconciled state machine with persistence. Registering council dispatches there adds ~50ms overhead but prevents total session loss on context crash. The WAL pattern ensures no data loss on restart.
+**trade_offs:** Gain: crash recovery for multi-minute council sessions. Lose: ~50ms registration overhead per council.
+**risks:** Board persistence failure could block council start — implement with fire-and-forget error handling
+**confidence:** High
+**agreement_signals:** agree:@themis on persist-before-notify
+**specific_claims:** 3
+```
+
 ## Memory Context
-If this agent used `memory_recall` or `memory_search`, include the relevant memory entries used as context for the response.
+If memory affected the result, state the takeaway briefly; do not repeat the entry or task context.

package/src/instructions/memory-protocol.instructions.md

@@ -10,15 +10,14 @@ These rules apply to all agents; each agent file may add domain-specific rules.
 
 ## Universal Rules
 
-### Task-start search
-**Before any file reads, call exactly once at task start:** `memory_search(query=task_prompt, top_k=2)`.
-- Reuse the same result for task context and delegation routing. A KV cache hit does not skip this search or trigger another task FTS search.
-- Council-precedent lookup is separate. Use domain-relevant context; do not issue another task-memory search for routing.
-- Agents have read-only memory access: only `memory_search()` is available.
+### Retrieval
+- Search only when prior project history could change the outcome; skip self-contained questions and bounded changes.
+- For delegated work, Zeus searches at most once and passes useful hits to the specialist. Reuse supplied results; search separately only if relevant history is needed but missing.
+- Use a targeted query (`top_k=2`); do not search the whole prompt by default. Missing or irrelevant results never block current work.
 
-### Summary persistence and WAL
-`memory_store()` is called automatically by Zeus when an agent returns a `subtask_summary`; include a clear `summary`. This is the only persistence path, for implementers and read-only agents alike.
-Before storing, Zeus writes `.pantheon/memory-wal/<agent>/<timestamp>.json` with `{agent, phase, summary, files_changed, status, timestamp}`. The WAL precedes storage, is recovered next session if storage fails, and expires after 7 days.
+### Persistence
+- `memory_store()` is manual, not automatic. Store at most one concise, reusable top-level result; never persist routine child summaries, phase updates, test logs, or temporary state.
+- Confirm the store succeeded before claiming persistence. There is no automatic memory WAL or recovery. Add ADRs to the memory bank only when explicitly requested.
 
 ### Relevance and permanent records
-Skip `memory_search()` results below 0.3 relevance. Delegate ADR-level architecture decisions, significant trade-offs, and pattern changes to @mnemosyne; routine summaries use auto-store.
+Ignore weak matches; routine summaries do not belong in durable memory.

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

@@ -1,13 +1,61 @@
 ---
-description: "Minimal stall recovery and progress guidance for Zeus"
+description: "Stall detection, phase reminders, delegate retry, and progress checkpoints for Zeus"
 name: "Zeus Anti-Stall"
 agents: [zeus]
 fallback: shared
 ---
 
-# Stall recovery
+# 🛑 ANTI-STALL & STALL DETECTION
 
-- For a known background task, wait only on its returned task ID; do not poll or start dependent work before it completes.
-- For transient dispatch failures, use the single retry and fallback policy in `Zeus Timeout & Retry`. A refusal or failed check is information to act on, not a reason to repeat the same attempt.
-- If the same task makes no progress after one corrected route, stop and report the blocker or ask one focused question. Do not invent task IDs, session APIs, or recovery state.
-- Use progress checkpoints only for work expected to span more than five turns. State what is complete, what remains, and any blocker; do not create a status file for bounded work.
+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`, then follow the fallback chain in `## ⏱️ Timeout & Retry Enforcement` |
+| 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 has a transient dispatch failure (timeout, crash, or empty
+response), check known causes first and allow at most one corrected retry per
+agent/task. Do not retry a scope refusal or a failed test/validation; reroute
+only when the correct specialist is clear, otherwise diagnose or escalate.
+After a transient retry fails, follow the canonical fallback chain once and
+escalate rather than restarting it. See `## ⏱️ Timeout & Retry Enforcement`.
+
+## Progress Checkpoint
+
+For long-running or multi-phase tasks expected to run > 5 turns only:
+- 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
+
+Use checkpoints only for long-running or multi-phase work when `context_save` and `context_get` are available. Never add persistence calls for a bounded task.
+
+### Checkpoint / Pre-Compaction
+Checkpoint only when context loss is plausible and both checkpoint tools are present. Save once at a meaningful boundary using `content=JSON.stringify(state)` and an explicit session ID; `state` must be an object with object-valued `phase`/`goal`/`delegations`/`heartbeat` fields and an array `tail`, and omit an unset `goal`. A successful save needs no immediate read. Checkpoints expire after 4h.
+
+### Context Retrieval
+Read a checkpoint only when resuming a workflow with a known session ID. Do not retrieve it after every dispatch; carry ordinary handoffs in the task context.
+
+### Long-Session Progress
+For long-lived multi-phase work, update an existing/requested progress record every 5 turns with completed and pending work and blockers. Do not create STATUS.md for a bounded task.

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

@@ -0,0 +1,71 @@
+---
+description: "Council synthesis — dispatch 2-3 specialists inline for multi-perspective decisions with precedent fast-path, confidence cross-validation, rebuttal rounds, and Themis audit gate"
+name: "Zeus Council Synthesis"
+agents: [zeus]
+fallback: shared
+---
+
+# 🏛️ INLINE COUNCIL SYNTHESIS — /pantheon
+
+Use an inline specialist council for material trade-offs, architecture/security choices, technology selection, cost/quality decisions, or multi-stakeholder questions. Do not use it for ordinary implementation tasks.
+
+## Dispatch and Synthesis
+
+1. **Precedent:** Run the separate `council_decisions` search defined in `## Memory Protocol`. Apply its age/score rules; if no fast-path decision applies, continue.
+2. **Research (optional):** For `/pantheon --research <question>`, ask @apollo for a 30s pre-scan and pass findings as `shared_context` to every specialist.
+3. **Register:** Before dispatch, call `board.registerLaunch` with a council task ID, parent session, Zeus, question, and synthesis objective. This enables crash recovery.
+4. **Select and dispatch:** Choose at most 3 agents using the domain map below. Send all `task()` calls in one message. Each prompt includes the question, shared context, required response format, and role timeout (120s reviewers; 60s explorers/implementers).
+5. **Collect:** Wait for all responses and note timeouts. Partial responses are acceptable only from read-only @apollo or @gaia.
+6. **Validate confidence:** High requires at least 3 verifiable claims; otherwise downgrade to Medium and state why. Medium requires at least 1 claim; Low needs no minimum. Opinions alone are not specific claims.
+7. **Resolve divergence:** Compute agreement rate as `min(agreements, divergences) / total_points` from structured `agreement_signals`. Below 50%, and only if no agent timed out, run one rebuttal round with all responses and the current synthesis draft. Treat revised responses as final. If disagreement remains below 50%, research factual divergence points with official docs, benchmarks, or issues (max 3 searches; seek 2 independent sources per point when possible). Skip research for subjective-only disagreements. Send responses and a cited evidence brief to @themis as moderator; request verdicts, overall direction, confidence, and unresolved issues. Low confidence or unresolved points remain explicit in the synthesis. Moderator and audit roles are separate.
+8. **Synthesize and audit:** Use the output format below, then ask @themis to compare raw responses with the synthesis. Check representation of every specialist, preserved divergences, accurate attribution, and confidence specificity. Fix any issue before delivery.
+9. **Persist:** Store the decision using the `council_decisions` write format in `## Memory Protocol`, then call `board.markReconciled(task_id)`.
+
+If context is lost, use `board.recoverRunningJobs()` and `board.formatForPrompt()` to find unreconciled work. Re-dispatch a crashed council with the same question and label it as a retry.
+
+## Specialist Response Format
+
+Require `## specialist_response` from `## Agent Return Format`: `position`, `reasoning`, `trade_offs`, `risks`, `confidence`, `agreement_signals`, and `specific_claims`.
+
+## Domain Map
+
+| Domain | Candidate agents |
+|---|---|
+| Architecture | athena, hermes, demeter, themis |
+| 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 |
+
+## User-Facing Synthesis
+
+```text
+## 🏛️ Council Synthesis
+Question / date / response rate / timed-out agents / precedent / research context
+
+### Specialist Perspectives
+| Agent | Position | Trade-offs | Confidence |
+
+### Agreements
+- Points shared by multiple specialists
+
+### Divergences
+| Issue | Sides | Resolution |
+
+### Evidence & Moderation (when used)
+Research points, evidence, moderator verdict, cited sources, unresolved issues
+
+### Recommendation
+Decisive conclusion
+
+### Audit Gate
+Themis approved, or issues corrected
+
+### Decision Gate
+Confidence adjusted for response rate
+```
+
+The user invokes this flow with `/pantheon <question>`; `--research` enables the Apollo pre-scan. Preserve actual specialist timeout or unresolved-tie details in the response.

package/src/instructions/zeus-memory-operations.instructions.md

@@ -9,11 +9,11 @@ fallback: shared
 
 ## Routing
 
-Use the task-start memory result for context and static agent descriptions for routing. Do not add KV/cache calls to ordinary dispatches.
+Reuse relevant memory already present in the request or task context. If prior project history matters and no result is present, Zeus may do one targeted search and pass useful hits with the delegation. Do not search on every turn or add KV/cache calls to ordinary dispatches.
 
 ## Council Decisions
 
-Before a council, search separately from the required task-start search:
+Before a council, search separately from the task-level lookup only when a past council decision could affect the recommendation:
 `memory_search(query=question, top_k=2, namespace="council_decisions")`.
 Use a recent, directly matching decision only after checking current context;
 otherwise treat it as background, never as authority to skip a needed review.
@@ -22,5 +22,5 @@ Persist only reusable, material decisions. Use
 `key="council:<yyyy-mm-dd>:<slug>"`; JSON-stringify both `value` and
 `metadata` for `memory_store(namespace="council_decisions", ...)`. Keep the
 record concise: question, recommendation, specialists, confidence, unresolved
-trade-off, and timestamp. Use `default` for routine summaries and @mnemosyne
-for ADRs.
+trade-off, and timestamp. Do not store routine subtask summaries or status
+updates. Use the memory bank for ADRs only when explicitly requested.

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

@@ -1,18 +1,92 @@
 ---
-description: "Bounded retries and lightweight subtask routing for Zeus"
+description: "Timeout enforcement, retry policies, subtask dispatch, and timeout tracking for Zeus"
 name: "Zeus Timeout & Retry"
 agents: [zeus]
 fallback: shared
 ---
 
-# Bounded delegation
+# ⏱️ TIMEOUT & RETRY ENFORCEMENT
 
-Use the native `task()` result as the source of truth. Do not simulate per-agent timers, poll without a known background task ID, or check for reusable sessions through APIs that are not available. `routing.yml` defines the concurrency limit, retry count, and canonical fallback chains.
+When a delegated agent does not respond in time, enforce the timeout policy from `routing.yml`.
 
-For a transient dispatch failure (timeout, crash, or empty response), retry that agent once. If it fails again, follow its configured fallback chain left-to-right once; if none is configured or the chain is exhausted, report what failed and stop. Never retry a refusal, failed test, validation, or migration as though it were a dispatch error. Do not restart an exhausted chain.
+## Timeout Behavior by Agent Role
 
-Fallbacks for auth/security/data/schema work must preserve specialist competence, Themis review, and human approval. Full-auto does not bypass these gates.
+| 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 |
 
-## Lightweight subtask
+## Retry Flow
 
-For clear, bounded, reversible, low-risk work, dispatch directly to one specialist. Skip routine plan/artifact phases and discovery; ask the specialist to inspect only relevant context, make the change, run focused verification, and return `subtask_summary`. Add planning, artifacts, Themis review, or approval only when scope or risk requires them.
+```
+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
+
+`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.
+
+### Refusal Is a Routing Error
+
+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 for the corrected route,
+including `reroute_from`, `reroute_to`, and `delegation_id` when available.
+
+### 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.
+
+### Session Reuse Check
+Check for a reusable session before dispatch and obey `session_max` in `routing.yml`.
+
+---
+
+# 📦 SUBTASK DISPATCH (Lightweight Delegation)
+
+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
+
+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)
+
+```
+□ Is the scope clear, bounded, and reversible?                 [YES→continue | NO→clarify/plan]
+□ Does it avoid auth/security, data/schema, and destructive risk? [YES→continue | NO→full review/gates]
+□ Is there no required Themis/audit handoff for this change?     [YES→continue | NO→preserve that review]
+
+ALL YES → direct/lightweight execution; no routine plan or artifact
+ANY NO  → add only the planning, artifact, specialist review, and approval gates the risk requires
+```
+
+### Safety Rules
+1. **Bounded scope** — can be a small multi-file change or a read-only investigation
+2. **Low risk** — no security implications, no data loss, no breaking changes
+3. **No required Themis dependency** — sensitive/material output retains its review gate
+
+## Subtask Return Format
+Return the required `## subtask_summary` fields defined in `## Agent Return Format`; include `memory_context` when memory was used.
+
+## Timeout Parcial (Partial Results)
+
+Only agents marked ✅ in the Timeout Behavior table above may return partial results: @apollo (partial file list, e.g. "found 7 of 12 files before timeout"), @gaia (partial literature findings) and @talos (confirm progress if a hotfix times out). Never for implementers or reviewers — they must complete or fail. When dispatching with partial-OK, set the expectation: `@apollo Search for auth files. Timeout parcial OK — return whatever you have.`
+
+---
+
+# 📊 TIMEOUT TRACKING
+
+Track in-flight delegations against the Timeout Behavior table above. Log timeouts to `/memories/session/timeout-log.md` for later analysis.

package/src/pantheon/v2-delegation-enforce.ts

@@ -22,8 +22,9 @@ export interface V2PermissionEvent {
   resources?: unknown
   /** Optional event identity is checked but never used as authority. */
   agent?: unknown
-  /** Permission effect reported by the V2 host event. */
+  /** Mutable decision fields exposed by OpenCode V2's evaluate hook. */
   effect?: unknown
+  message?: unknown
 }
 
 export interface AuthoritativeSession {