pantheon-opencode 1.0.7 → 1.1.1-beta.0

package/scripts/install/opencode.mjs

@@ -264,6 +264,14 @@ export function installOpenCode(
       writeIfChanged(join(dstPluginDir, "package.json"), readFileSync(pkgSrc, "utf8"), dryRun)
       stats.created++
     }
+    // Install plugin dependencies (@opentui/core, @opentui/solid, solid-js)
+    if (!dryRun) {
+      try {
+        execSync('npm install --production --no-audit --no-fund', { cwd: dstPluginDir, stdio: 'pipe' })
+      } catch (e) {
+        console.warn('    ⚠️  Failed to install TUI plugin dependencies:', e.message)
+      }
+    }
 
   }
 
@@ -687,7 +695,7 @@ export function installOpenCode(
   // -----------------------------------------------------------------------
   if (componentSet.has('runtime')) {
     try {
-      setupVenv(target, { dryRun })
+      setupVenv(target, { dryRun, force: clean })
       const health = healthCheck(target, { dryRun })
 
       // Print health summary
@@ -702,7 +710,7 @@ export function installOpenCode(
       }
     } catch (err) {
       console.error(`  ❌ Setup failed: ${err.message}`)
-      stats.errors++
+      throw err  // Fatal — abort installation
     }
   }
 }

package/scripts/install/venv.mjs

@@ -10,7 +10,7 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -21,14 +21,23 @@ const ROOT = join(__dirname, '..', '..')
  * Set up a Python virtual environment and install MCP dependencies.
  *
  * @param {string} target - Target installation directory (e.g. ~/.config/opencode)
- * @param {{ dryRun?: boolean, skipInstall?: boolean }} [options]
+ * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean }} [options]
  * @returns {{ venvPath: string, python: string }}
  */
-export function setupVenv(target, { dryRun = false, skipInstall = false } = {}) {
+export function setupVenv(target, { dryRun = false, skipInstall = false, force = false } = {}) {
   const venvPath = join(target, '.venv')
   const pythonBin = join(venvPath, 'bin', 'python3')
 
-  // Step 1: Create venv if not exists
+  // Step 1: Force recreate venv if --force
+  if (force && existsSync(venvPath)) {
+    if (!dryRun) {
+      console.log('  Removing existing .venv (--force)...')
+      rmSync(venvPath, { recursive: true })
+    }
+    console.log('  ✅ .venv removed')
+  }
+
+  // Step 1b: Create venv if not exists
   if (!existsSync(pythonBin)) {
     if (!dryRun) {
       console.log('  Creating .venv...')
@@ -58,28 +67,34 @@ export function setupVenv(target, { dryRun = false, skipInstall = false } = {})
 
     if (!dryRun) {
       // Upgrade pip first (avoids resolver warnings)
+      // Ensure PIP_USER=0 to install into venv, not user site-packages
+      const pipEnv = { ...process.env, PIP_USER: '0' }
+
       spawnSync(pip, ['install', '--upgrade', 'pip'], {
         stdio: 'ignore',
         timeout: 30_000,
+        env: pipEnv,
       })
 
-      // Install requirements
+      // Install requirements — attempt 1: normal
       const r = spawnSync(pip, ['install', '-r', reqFile], {
         stdio: 'inherit',
         timeout: 120_000,
+        env: pipEnv,
       })
 
       if (r.status !== 0) {
-        // If failed, try with --break-system-packages (PEP 668 workaround)
+        // Attempt 2: --break-system-packages (PEP 668 / externally-managed)
         console.log('  ⚠️  First attempt failed, retrying with --break-system-packages...')
         const r2 = spawnSync(pip, ['install', '-r', reqFile, '--break-system-packages'], {
           stdio: 'inherit',
           timeout: 120_000,
+          env: pipEnv,
         })
         if (r2.status !== 0) {
           throw new Error(
             'Failed to install MCP dependencies. ' +
-            'Try: pip install -r src/mcp/requirements-mcp.txt --break-system-packages'
+            'Try: PIP_USER=0 ' + pip + ' install -r ' + reqFile + ' --break-system-packages'
           )
         }
       }
@@ -101,9 +116,10 @@ function main() {
   const target = targetIdx !== -1 ? args[targetIdx + 1] : process.cwd()
   const dryRun = args.includes('--dry-run')
   const skipInstall = args.includes('--skip-install')
+  const force = args.includes('--force')
 
   try {
-    const result = setupVenv(target, { dryRun, skipInstall })
+    const result = setupVenv(target, { dryRun, skipInstall, force })
     console.log(`  📍 Python: ${result.python}`)
   } catch (err) {
     console.error(`\n  ❌ ${err.message}`)

package/scripts/validate-routing.mjs

@@ -60,7 +60,7 @@ console.log(`  Agents in routing.yml: ${routingAgents.length}`)
 // Get canonical agent files
 const agentsDir = join(ROOT, 'src', 'agents')
 const canonicalFiles = readdirSync(agentsDir)
-  .filter((f) => f.endsWith('.md'))
+  .filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md')
   .map((f) => f.replace('.md', ''))
   .sort()
 

package/src/agents/README.md

@@ -0,0 +1,26 @@
+# Agent Reference — Pantheon
+
+This directory contains the definitions for all 14 Pantheon agents. Each agent is defined in a `.agent.md` file with YAML frontmatter specifying tools, model tier, capabilities, and delegation rules.
+
+## Agents
+
+| Agent | File | Role |
+|-------|------|------|
+| @zeus | [zeus.agent.md](zeus.agent.md) | Central orchestrator |
+| @athena | [athena.agent.md](athena.agent.md) | Strategic planner |
+| @apollo | [apollo.agent.md](apollo.agent.md) | Investigation scout |
+| @hermes | [hermes.agent.md](hermes.agent.md) | Backend specialist |
+| @aphrodite | [aphrodite.agent.md](aphrodite.agent.md) | Frontend specialist |
+| @demeter | [demeter.agent.md](demeter.agent.md) | Database specialist |
+| @themis | [themis.agent.md](themis.agent.md) | Quality & security gate |
+| @prometheus | [prometheus.agent.md](prometheus.agent.md) | Infrastructure specialist |
+| @hephaestus | [hephaestus.agent.md](hephaestus.agent.md) | AI pipelines |
+| @nyx | [nyx.agent.md](nyx.agent.md) | Observability |
+| @gaia | [gaia.agent.md](gaia.agent.md) | Remote sensing |
+| @iris | [iris.agent.md](iris.agent.md) | GitHub operations |
+| @mnemosyne | [mnemosyne.agent.md](mnemosyne.agent.md) | Memory bank |
+| @talos | [talos.agent.md](talos.agent.md) | Hotfix agent |
+
+## Full Reference
+
+See [AGENTS.md](../../AGENTS.md) for the complete agent reference with roles, capabilities, and invocation patterns.

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

@@ -21,6 +21,51 @@ For investigation agents (Apollo, Athena), return structured findings with:
 - 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.

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

@@ -65,3 +65,55 @@ Para otimizar decisoes de delegacao e reduzir gasto de tokens:
 5. **kv_get("deleg:<pattern>")** para reusar decisoes ja tomadas
 
 Isso elimina ~300 tokens de reasoning por delegacao quando o cache acerta.
+
+## Council Decisions Namespace
+
+Council synthesis decisions are persisted in a dedicated `council_decisions` namespace for precedent fast-path retrieval:
+
+### Write Path
+After every `/pantheon` council synthesis completes, Zeus stores:
+```
+memory_store({
+  namespace: "council_decisions",
+  key: "council:<yyyy-mm-dd>:<slug>",
+  value: {
+    question: "original question",
+    specialists: ["@agent1", "@agent2"],
+    recommendation: "final recommendation",
+    confidence: "High|Medium|Low",
+    agreements: ["point1", "point2"],
+    divergences: [{"issue": "...", "resolution": "..."}],
+    response_rate: "X of Y",
+    themis_audit: "approved|issues"
+  },
+  metadata: {
+    type: "council_decision",
+    specialist_count: N,
+    model_tier_used: "premium|default|fast"
+  }
+})
+```
+
+### Read Path (Precedent Fast-Path)
+Before dispatching a new council, Zeus runs:
+```
+memory_search(question, top_k=2, namespace="council_decisions")
+```
+
+Result interpretation:
+| Score | Age | Action |
+|-------|-----|--------|
+| > 0.85 | < 30 days | Return precedent as fast-path answer. Skip council dispatch entirely. |
+| > 0.85 | >= 30 days | Return with warning "Reavaliar se contexto mudou" + proceed with council |
+| 0.5 - 0.85 | Any | Include as context for specialists but still dispatch council |
+| < 0.5 | Any | Ignore, proceed with fresh council |
+
+### TTL & Maintenance
+- Council decisions are LONG-TERM (no TTL or TTL = 365 days)
+- Stale decisions (age > 90 days) should be flagged but NOT deleted — they remain as historical record
+- Purge only via explicit namespace cleanup when decisions are superseded by ADRs
+
+### When NOT to Use
+- Routine task summaries → use `default` namespace (auto-store by Zeus)
+- Sprint/progress tracking → use `session` namespace
+- ADR-level architecture decisions → delegate to @mnemosyne for permanent documentation

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

@@ -1,5 +1,5 @@
 ---
-description: "Council synthesis — dispatch 2-4 specialists inline for multi-perspective decisions"
+description: "Council synthesis — dispatch 2-4 specialists inline for multi-perspective decisions with precedent fast-path, confidence cross-validation, rebuttal rounds, and Themis audit gate"
 name: "Zeus Council Synthesis"
 applyTo: "agents/zeus.agent.md"
 ---
@@ -26,39 +26,197 @@ config:
 sequenceDiagram
     participant U as User
     participant Z as Zeus
+    participant M as Memory (Precedent)
+    participant A as Apollo (Research)
+    participant B as BackgroundJobBoard
     participant S1 as Specialist 1
     participant S2 as Specialist 2
     participant S3 as Specialist 3
+    participant W as Web Search
+    participant T as Themis (Audit + Moderator)
 
-    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
+    U->>Z: /pantheon [--research] question
+    Z->>M: memory_search(council_decisions)
+    alt Precedent found (score > 0.85)
+        M-->>Z: ⚠️ Cached decision
+        Z->>U: Fast-path precedent
+    else No precedent
+        opt --research flag
+            Z->>A: 30s pre-scan
+            A-->>Z: Context brief
+        end
+        Z->>B: registerLaunch({council session})
+        par Dispatch all specialists
+            Z->>S1: Domain query + shared context
+            Z->>S2: Domain query + shared context
+            Z->>S3: Domain query + shared context
+        end
+        par Collect responses
+            S1-->>Z: Structured response
+            S2-->>Z: Structured response
+            S3-->>Z: Structured response
+        end
+        Note over Z: Cross-validate confidence
+        alt Agreement rate < 50%
+            Z->>S1: Rebuttal round
+            Z->>S2: Rebuttal round
+            Z->>S3: Rebuttal round
+            S1-->>Z: Refined response
+            S2-->>Z: Refined response
+            S3-->>Z: Refined response
+            Note over Z: Ainda divergência?
+            alt Agreement rate STILL < 50%
+                Z->>W: browser_search() for each divergence point
+                W-->>Z: Evidence brief with sources
+                Z->>T: Dispatches as moderator
+                Note over T: Reviews evidence + specialist responses
+                T-->>Z: Moderator verdict
+            end
+        end
+        Z->>Z: Synthesize (with evidence if tie-broken)
+        Z->>T: Audit synthesis fidelity
+        T-->>Z: ✅ / ⚠️ Issues
+        Z->>M: Store decision
+        Z->>B: Mark reconciled
+        Z->>U: 🏛️ Council Synthesis
     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
+## Dispatch Sequence (9-Step Protocol)
+
+### Step 0 — Precedent Fast-Path (Fase 1)
+Before any dispatch: `memory_search(query, top_k=2, namespace="council_decisions")`
+- Score > 0.85 AND age < 30 days → return precedent verbatim with note "⚠️ Decisão de [data] — reavaliar se contexto mudou". SKIP entire dispatch.
+- Score > 0.85 AND age > 30 days → return precedent with ⚠️ "Reavaliar se contexto mudou — decisão tem mais de 30 dias"
+- Else → proceed to Step 0b
+
+### Step 0b — Apollo Pre-Scan (Fase 2, --research flag)
+If `/pantheon --research <question>`: dispatch @apollo with 30s timeout. Inject findings as `shared_context` into ALL specialist prompts. Skip if flag absent.
+
+### Step 1 — Register on BackgroundJobBoard (Fase 1)
+Before dispatching specialists:
+```
+board.registerLaunch({
+  taskID: "council:<uuid>",
+  parentSessionID: "<session-id>",
+  agent: "zeus",
+  description: "Council: <question>",
+  objective: "Synthesize specialist recommendations"
+})
+```
+Enables crash recovery — if context is lost mid-synthesis, the board preserves session state.
+
+### Step 2 — Select Specialists
+Use domain-to-specialist mapping table (below). Max 3 specialists.
+
+### Step 3 — Dispatch ALL task() calls in ONE message
+Each specialist prompt MUST include:
+- Structured output template (see Specialist Output Format below)
+- `shared_context` if Apollo pre-scan was done
+- Timeout per role: 120s for reviewers, 60s for explorers/implementers
+
+### Step 4 — Collect Responses
+Wait for all responses. Note TIMEOUT agents. Partial results OK only for read-only specialists (@apollo, @gaia).
+
+### Step 5 — Confidence Cross-Validation (Fase 2)
+For each specialist response, validate confidence claims:
 
-Send ALL `task()` calls in a single message. Each specialist must respond concisely (2-4 sentences).
+| Reported | Minimum Required | Action |
+|----------|-----------------|--------|
+| High | ≥ 3 specific claims | If fewer → downgrade to Medium, annotate "(auto-downgraded from High: only N specific claims)" |
+| Medium | ≥ 1 specific claim | Pass |
+| Low | Any response | Pass |
 
-⚠️ **TIMEOUT RULE:** If a specialist does not respond after other specialists have responded, proceed with partial results. Do NOT wait indefinitely.
+"Specific claim" = statement with evidence, data point, or verifiable fact (not opinion).
 
-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
+### Step 6 — Divergence-Gated Rebuttal Round (Fase 2, conditional)
+Calculate agreement rate = `min(agreements, divergences) / total_points` from structured `agreement_signals`. If < 50% agreement:
+- Dispatch ONE rebuttal round: specialists see ALL other responses and refine their own
+- Updated responses treated as final
+- Hard cap: MAX 3 total rounds (initial + 2 rebuttals)
+- Skip if any TIMEOUT occurred (can't rebuttal without all voices)
+
+### Step 6b — Modo Desempate com Evidência (Fase 2, conditional)
+
+If after Step 6 the agreement rate is STILL < 50% (rebuttal did not resolve divergence):
+
+1. **Identify divergence points** — Parse all specialist responses (initial + rebuttal) and extract specific issues where positions differ
+2. **Web research** — For EACH divergence point, Zeus calls `browser_search()` or `webfetch()` to find factual evidence:
+   - Benchmarks, documentation, GitHub issues, official sources
+   - At least 2 independent sources per point when possible
+   - Focus on factual data, not opinion
+3. **Compile Evidence Brief** — Structure findings as:
+   ```
+   ## evidence_brief
+   **divergence_point_1:** <description>
+   **evidence_found:** <facts from web, max 3 sentences>
+   **sources:** [URL1, URL2]
+
+   **divergence_point_2:** ...
+   ```
+4. **Dispatch @themis as moderator** — Send ONE task with:
+   - All specialist responses (initial + rebuttal)
+   - The evidence brief
+   - Prompt: "Act as impartial moderator. These specialists disagree on [points]. Here is web evidence on each point. Issue a final verdict for each divergence point, citing specific evidence. Return structured verdict."
+5. **Themis returns moderator verdict** in this format:
+   ```
+   ## moderator_verdict
+   **divergence_points_analyzed:** <count>
+   **verdicts:**
+     - <point 1>: <decision> — evidence: <citation>
+     - <point 2>: <decision> — evidence: <citation>
+   **overall_direction:** <which approach is better supported by evidence>
+   **confidence:** High | Medium | Low
+   **unresolved:** <any points still unclear despite evidence>
+   ```
+6. **Zeus incorporates verdict** into synthesis (Step 7), showing which evidence supported which conclusion
+
+**Rules:**
+- Only triggers when agreement rate < 50% AFTER rebuttal round
+- Skip if NO divergence points are web-researchable (purely subjective/opinion-based disagreements)
+- Max 3 web searches per council (prevents runaway)
+- If Themis confidence is Low or points remain unresolved, note this explicitly in synthesis
+- Themis moderator role is SEPARATE from the Themis Audit Gate (Step 8) — they serve different functions
+
+### Step 7 — Zeus Synthesize
+Use structured `agreement_signals` to auto-detect agreements/divergences. Output synthesis template (see below).
+
+### Step 8 — Themis Audit Gate (Fase 1)
+Post-synthesis, dispatch @themis:
+```
+task(subagent_type: "themis", prompt: "Audit this council synthesis for fidelity. Compare raw specialist responses against the synthesized output. Check: (1) Any specialist misrepresented? (2) Divergences hidden or softened? (3) Confidence claims match response specificity? Return ✅ or list specific issues.")
+```
+- If ✅ → proceed
+- If issues → fix each issue before delivering to user
+
+### Step 9 — Persist & Reconcile (Fase 1)
+```
+memory_store({
+  namespace: "council_decisions",
+  key: "council:<yyyy-mm-dd>:<slug>",
+  value: JSON.stringify({
+    question, specialists, recommendation, confidence,
+    agreements, divergences, precedent_used, timestamp
+  }),
+  metadata: {type: "council_decision", specialist_count: N}
+})
+board.markReconciled("<task-id>")
+```
+
+## Specialist Output Format (Fase 1 — machine-parseable structured fields)
+
+Specialists MUST return these structured fields in their response:
+
+```
+## specialist_response
+**position:** <clear one-sentence position>
+**reasoning:** <2-4 sentences>
+**trade_offs:** <what's gained vs lost>
+**risks:** <what could go wrong>
+**confidence:** High | Medium | Low
+**agreement_signals:** agree: @agent1, @agent2 on [issue] | disagree: @agent3 on [issue]
+**specific_claims:** <count of specific factual claims in response>
+```
 
 ## Domain-to-Specialist Mapping
 
@@ -73,7 +231,7 @@ Send ALL `task()` calls in a single message. Each specialist must respond concis
 | Observability | nyx, hermes |
 | General | athena, themis, hermes |
 
-## Synthesis Output Template
+## Synthesis Output Template (enhanced)
 
 ```
 ## 🏛️ Council Synthesis
@@ -82,6 +240,8 @@ Send ALL `task()` calls in a single message. Each specialist must respond concis
 **Date:** <date>
 **Response rate:** X of Y specialists responded
 **Timed out:** @agent1, @agent2 (if any)
+**Precedent used:** yes/no (which one, date)
+**Research context:** <shared_context summary> (if --research)
 
 ### Specialist Perspectives
 | Agent | Position | Trade-offs | Confidence |
@@ -95,11 +255,70 @@ Send ALL `task()` calls in a single message. Each specialist must respond concis
 | Issue | Side A | Side B | Resolution |
 |-------|--------|--------|------------|
 
+### Evidence & Moderation (if tie-break activated)
+**Divergence points researched:** <list>
+**Evidence summary:** <key findings from web>
+**Moderator verdict:** <Themis final determination>
+**Sources:** <citations>
+
 ### Recommendation
 <decisive conclusion>
 
+### Audit Gate
+**Status:** ✅ Themis approved | ⚠️ Issues corrected
+
 ### 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.
+## Themis Audit Gate Rules (Fase 1)
+
+1. Every specialist mentioned in synthesis? → ✅
+2. Divergences from raw responses preserved (not softened/hidden)? → ✅
+3. No specialist attributed a position they didn't state? → ✅
+4. Confidence claims match response specificity? → ✅
+5. If any ❌, list specific issues for Zeus to fix before delivery
+
+## Rebuttal Round Rules (Fase 2)
+
+1. Only triggers when agreement rate < 50%
+2. MAX 3 rounds total (including initial dispatch)
+3. Skip if any TIMEOUT (can't rebuttal without all voices)
+4. Each rebuttal round: specialist sees ALL other responses + current synthesis draft
+5. Refined responses replace originals for the final synthesis
+6. If agreement rate STILL < 50% after rebuttal → Step 6b (Modo Desempate com Evidência)
+
+## Crash Recovery via BackgroundJobBoard (Fase 1)
+
+If Zeus context crashes mid-council:
+1. On restart, `board.recoverRunningJobs()` marks running jobs as error
+2. Check `board.formatForPrompt()` for unreconciled terminal jobs
+3. Re-dispatch council with same question, noting: "⚠️ Retry — previous council session crashed. Using same question."
+
+## Performance Budget
+
+| Step | Latency | Phase |
+|------|---------|-------|
+| Precedent fast-path | < 500ms | Fase 1 |
+| Apollo pre-scan | +30s (optional, --research) | Fase 2 |
+| Specialist dispatch | bounded by slowest (60-120s) | — |
+| Rebuttal round | +60s (conditional, < 50% agreement) | Fase 2 |
+| Web search (tie-break) | +15s (conditional, < 50% after rebuttal) | Fase 2 |
+| Themis moderator | +15s (conditional, tie-break activated) | Fase 2 |
+| Themis audit | +15s | Fase 1 |
+| **Total worst case** (research + rebuttal + tie-break) | ~255s | — |
+| **Total typical** (no research, no rebuttal, no tie-break) | ~45-90s | — |
+
+> **Note**: The user can explicitly invoke this via `/pantheon <question>`. The `--research` flag adds Apollo pre-scan. All decisions are stored in `council_decisions` memory namespace for fast-path retrieval on future councils.
+
+## Modo Desempate Rules (Fase 2)
+
+1. Only triggers when agreement rate < 50% AFTER rebuttal round
+2. If no divergence points are web-researchable (pure opinion disagreement), skip — Zeus synthesizes with lower confidence
+3. Max 3 web searches per council invocation
+4. Themis moderator role is DISTINCT from Themis audit gate:
+   - Moderator: resolves substantive disagreement between specialists (reads evidence, gives verdict)
+   - Audit gate: checks synthesis fidelity against raw responses (quality assurance)
+   Both run in the same council invocation, at different steps
+5. If Themis moderator confidence is Low, mark as "unresolved tie" in the synthesis output
+6. Evidence from web search must be cited with source URL or document reference — no anonymous claims

package/src/plugin.ts

@@ -1,4 +1,42 @@
 import type { PluginConfig } from 'opencode'
+import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
+import { FilePersistenceAdapter } from './pantheon/file-persistence.ts'
+
+// ─── Background Job Board Singleton ────────────────────────────────────
+
+const board = new BackgroundJobBoard({
+  maxConcurrentPerAgent: 3,
+  signalDir: '.pantheon/deepwork/board-signals',
+})
+
+// Wire up file-based persistence and recover orphaned jobs from crashes
+const persistence = new FilePersistenceAdapter('.pantheon/board/state.json')
+board.setPersistence(persistence)
+
+// Recover on startup — any jobs left in "running" state become "error"
+board.recoverRunningJobs().catch((err) =>
+  console.error('[Pantheon Plugin] Failed to recover running jobs:', err),
+)
+
+// Log board state changes to console for observability
+board.onTerminal((taskID: string) => {
+  const job = board.get(taskID)
+  if (job) {
+    console.log(
+      `[Pantheon Plugin] Board terminal: [${job.alias}] ${job.description} → ${job.state}${job.resultSummary ? ` — ${job.resultSummary}` : ''}`,
+    )
+  }
+})
+
+/**
+ * Get the global BackgroundJobBoard singleton.
+ *
+ * All modules (Zeus, auto-wake, etc.) should access the board through this
+ * function to ensure a single consistent state machine across the plugin.
+ */
+export function getBackgroundJobBoard(): BackgroundJobBoard {
+  return board
+}
 
 export default {
   name: 'pantheon',