@heretek-ai/epistemic-swarm 0.7.0 → 0.7.3

package/runner/research_swarm.py

@@ -34,6 +34,103 @@ EXAMPLE_RUST_RAFT_URL = "https://github.com/example/rust-raft"
 # run_claude_process already enforces; injection is not possible here.
 KNOWN_BACKEND_BINARIES = {"claude", "opencode", "python", "python3", "node"}
 
+# Host-native default backends (parity spec section 8). Claude Code spawns
+# `claude -p`; OpenCode spawns `opencode run` (opencode.ai/docs/cli). The
+# OpenCode plugin exports IUMBTEMS_HOST=opencode into every MCP dispatch so
+# the default follows the host; explicit flags/env/config always win.
+OPENCODE_RUN_BASE = ["opencode", "run"]
+
+# Fenced JSON block marker shared by orchestrator/dossier stdout parsers.
+_JSON_FENCE = "```json"
+
+
+def _default_backend_cmd(config_host: Optional[str] = None) -> List[str]:
+    """Host-native default backend argv.
+
+    Precedence: explicit config_host ("claude"/"opencode") > IUMBTEMS_HOST env
+    > binary probe (opencode when claude is absent) > legacy ["claude", "-p"].
+    """
+    host = (config_host or "").strip().lower()
+    if host in ("", "auto"):
+        host = os.environ.get("IUMBTEMS_HOST", "").strip().lower()
+    if host == "opencode":
+        return list(OPENCODE_RUN_BASE)
+    if host == "claude":
+        return ["claude", "-p"]
+    if shutil.which("opencode") and not shutil.which("claude"):
+        return list(OPENCODE_RUN_BASE)
+    return ["claude", "-p"]
+
+
+def _backend_family(backend: List[str]) -> str:
+    return Path(backend[0]).name if backend else "claude"
+
+
+def _build_opencode_cmd(
+    backend: List[str],
+    prompt: str,
+    model: Optional[str],
+    agent: Optional[str],
+) -> List[str]:
+    """Argv for `opencode run` (docs: positional prompt, -m provider/model,
+    --agent <name>, --format json). No --tools/--system-prompt flags exist."""
+    cmd = list(backend) + [prompt]
+    if agent:
+        cmd.extend(["--agent", str(agent)])
+    if model:
+        cmd.extend(["-m", str(model)])
+    cmd.extend(["--format", "json"])
+    return cmd
+
+
+_TEXT_EVENT_KEYS = ("text", "content", "message", "output", "result")
+_TEXT_EVENT_MARKERS = ("message", "text", "result", "output", "content")
+
+
+def _event_text(obj: Dict[str, Any]) -> Optional[str]:
+    """Text payload of one parsed event line, or None.
+
+    Handles the real `opencode run --format json` shape
+    ({"type":"text", "part":{"type":"text","text":"..."}}) plus top-level
+    variants for tolerance.
+    """
+    part = obj.get("part")
+    if isinstance(part, dict):
+        val = part.get("text")
+        if isinstance(val, str) and val.strip():
+            return val
+    kind = str(obj.get("type", "")).lower()
+    if kind and not any(m in kind for m in _TEXT_EVENT_MARKERS):
+        return None
+    for key in _TEXT_EVENT_KEYS:
+        val = obj.get(key)
+        if isinstance(val, str) and val.strip():
+            return val
+    return None
+
+
+def _extract_opencode_text(raw: str) -> str:
+    """Best-effort final text from `opencode run --format json` event stream.
+
+    Tolerant by design: collects text fields from message/result/output style
+    events and falls back to the raw stream when nothing parses, so unknown
+    event shapes degrade to unparsed text rather than empty dossiers.
+    """
+    texts: List[str] = []
+    for line in (raw or "").splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError):
+            continue
+        if isinstance(obj, dict):
+            text = _event_text(obj)
+            if text:
+                texts.append(text)
+    return "\n".join(texts).strip() if texts else (raw or "").strip()
+
 
 def _validate_backend(backend: List[str]) -> List[str]:
     """Resolve-check a backend argv. Raises ValueError only if nothing can run it.
@@ -72,6 +169,14 @@ def _validate_backend(backend: List[str]) -> List[str]:
     return list(backend)
 
 
+def _first(*values):
+    """First truthy value (keeps config-precedence chains flat for S3776)."""
+    for v in values:
+        if v:
+            return v
+    return None
+
+
 class SwarmRunner:
     def __init__(
         self,
@@ -87,14 +192,15 @@ class SwarmRunner:
         self.base_dir = base_dir or Path(".research")
         self.mock_mode = mock_mode
         self.config = load_config(str(self.base_dir))
-        self.mode = mode or self.config.get("mode", "research")
-        self.engine = engine or self.config.get("search_engine", "duckduckgo")
-        self.depth = depth or self.config.get("max_iterations", 2)
+        cfg = self.config
+        self.mode = _first(mode, cfg.get("mode"), "research")
+        self.engine = _first(engine, cfg.get("search_engine"), "duckduckgo")
+        self.depth = _first(depth, cfg.get("max_iterations"), 2)
         # Stream F: "dag" (legacy default) or "auction" (Frontier Markets).
-        self.allocation = allocation or self.config.get("allocation", "dag")
+        self.allocation = _first(allocation, cfg.get("allocation"), "dag")
         # Stream G: optional Domain Pack (constitution) for the auditor.
         self.domain_pack = (
-            domain_pack if domain_pack is not None else self.config.get("domain_pack")
+            domain_pack if domain_pack is not None else cfg.get("domain_pack")
         )
         # Per-agent backend/model overrides (CLI > env > config > default).
         # Keys are role names ("alpha", "beta"); values are {"backend": [...],
@@ -108,9 +214,10 @@ class SwarmRunner:
     def _resolve_agent_backend(self, role: str) -> Tuple[List[str], Optional[str]]:
         """Resolve (backend_cmd, model) for an agent role.
 
-        Precedence (Stream E): explicit override (set by CLI flags) > env >
-        config > default. Returns (["claude", "-p"], None) when nothing is
-        configured, preserving prior behavior byte-for-byte.
+        Precedence: explicit override (set by CLI flags) > env >
+        config > host-native default. Returns the legacy ["claude", "-p"]
+        only when nothing else selects opencode, preserving prior behavior
+        byte-for-byte on Claude Code hosts.
         """
         override = self.agent_overrides.get(role) or {}
         env_backend = os.environ.get(f"IUMBTEMS_BACKEND_{role.upper()}")
@@ -123,11 +230,23 @@ class SwarmRunner:
             override.get("backend")
             or (env_backend.split() if env_backend else None)
             or role_cfg.get("backend")
-            or ["claude", "-p"]
+            or _default_backend_cmd(self.config.get("backend"))
         )
         model = override.get("model") or env_model or role_cfg.get("model")
         return list(backend), model
 
+    def _resolve_opencode_agent(self, role: str) -> Optional[str]:
+        """Explicitly configured OpenCode agent for this role, else None.
+
+        Default is None: the system prompt is inlined into the message because
+        `--agent <name>` fails hard ("Agent not found") unless the user
+        installed the snippet agent profiles — observed live, so the backend
+        must not depend on them. Set `agents.<role>.opencode_agent` (or the
+        top-level `opencode_agent` config key) to opt in.
+        """
+        role_cfg = (self.config.get("agents") or {}).get(role) or {}
+        return role_cfg.get("opencode_agent") or self.config.get("opencode_agent")
+
     def build_agent_cmd(
         self,
         prompt: str,
@@ -139,8 +258,29 @@ class SwarmRunner:
 
         Exposed separately so tests can assert argv shape (e.g. `--model`
         present when configured, absent in mock/default) without spawning.
+        Claude keeps the legacy shape; opencode builds `opencode run` argv.
         """
         backend, model = self._resolve_agent_backend(role)
+        # S8701 residual: argv-list + shell=False already blocks shell
+        # injection, but a prompt beginning with "-" would be parsed as a
+        # CLI flag by the backend. Agent prompts are generated text and never
+        # legitimately start with a dash.
+        if prompt.startswith("-"):
+            raise ValueError(
+                "Refusing to pass a prompt starting with '-' to the agent "
+                "backend (CLI flag injection)"
+            )
+        if _backend_family(backend) == "opencode":
+            agent = self._resolve_opencode_agent(role)
+            # No --system-prompt flag exists on `opencode run`, and --agent
+            # only works when the user installed the profile. Inline the
+            # system prompt into the message so runs never depend on
+            # host-side agent configuration.
+            if system_prompt_file and system_prompt_file.exists():
+                prompt = (
+                    system_prompt_file.read_text(encoding="utf-8") + "\n\n" + prompt
+                )
+            return _build_opencode_cmd(backend, prompt, model, agent)
         cmd = list(backend) + [prompt, "--tools", tools]
         if model:
             cmd.extend(["--model", str(model)])
@@ -160,6 +300,7 @@ class SwarmRunner:
             return self._mock_claude_response(prompt)
 
         cmd = self.build_agent_cmd(prompt, system_prompt_file, tools, role=role)
+        family = _backend_family(cmd)
 
         try:
             if cmd:
@@ -170,12 +311,21 @@ class SwarmRunner:
                 text=True,
                 check=True,
                 cwd=str(PROJECT_ROOT),
+                # stdin MUST be DEVNULL: `opencode run` reads piped stdin to
+                # EOF before starting, and the MCP server's inherited stdin
+                # pipe is held open by the harness — every agent hung forever
+                # (observed live: 10+ min, 1s CPU, no network I/O).
+                stdin=subprocess.DEVNULL,
                 shell=False,
             )
+            if family == "opencode":
+                return _extract_opencode_text(res.stdout)
             return res.stdout.strip()
         except subprocess.CalledProcessError as e:
-            print(f"[ERROR] Claude process failed: {e.stderr}", file=sys.stderr)
-            raise RuntimeError(f"Claude execution failed: {e.stderr}")
+            print(
+                f"[ERROR] {family} backend process failed: {e.stderr}", file=sys.stderr
+            )
+            raise RuntimeError(f"{family} backend execution failed: {e.stderr}")
         except ValueError as e:
             # Bad backend config: report it as a run failure, not an abort of the
             # whole swarm. Matches the pre-allowlist behavior of surfacing the
@@ -238,19 +388,14 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             orchestrator_prompt, system_prompt_file=system_prompt
         )
 
-        # Parse JSON
-        try:
-            # Handle potential markdown fence blocks
-            clean_json = raw_output
-            if "```json" in clean_json:
-                clean_json = clean_json.split("```json")[1].split("```")[0]
-            elif "```" in clean_json:
-                clean_json = clean_json.split("```")[1].split("```")[0]
-            manifest_data = json.loads(clean_json.strip())
+        # Parse JSON (fence-aware; falls back to a single-scope decomposition)
+        manifest_data = self._parse_json_block(raw_output, require_key="scopes")
+        if manifest_data is not None:
             scopes = manifest_data.get("scopes", [])
-        except Exception as e:
+        else:
             print(
-                f"[WARN] Failed to parse JSON from orchestrator output: {e}. Using fallback decomposition."
+                "[WARN] Failed to parse JSON from orchestrator output. "
+                "Using fallback decomposition."
             )
             scopes = [
                 {
@@ -269,6 +414,67 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         print(f"✅ Generated {len(scopes)} decoupled dialectic scopes.")
         return scopes
 
+    @staticmethod
+    def _parse_json_block(
+        text: str, require_key: str = "scope_id"
+    ) -> Optional[Dict[str, Any]]:
+        """Extract a JSON object from free-form agent stdout (fence-aware)."""
+        if not text or not text.strip():
+            return None
+        candidates = [text]
+        if _JSON_FENCE in text:
+            candidates.append(text.split(_JSON_FENCE, 1)[1].split("```")[0])
+        elif "```" in text:
+            candidates.append(text.split("```", 1)[1].split("```")[0])
+        start = text.find("{")
+        end = text.rfind("}")
+        if start >= 0 and end > start:
+            candidates.append(text[start : end + 1])
+        for candidate in candidates:
+            try:
+                obj = json.loads(candidate.strip())
+            except (ValueError, TypeError):
+                continue
+            if isinstance(obj, dict) and obj.get(require_key):
+                return obj
+        return None
+
+    @staticmethod
+    def _parse_dossier_json(text: str) -> Optional[Dict[str, Any]]:
+        """Extract a dossier dict from free-form agent stdout (fence-aware)."""
+        return SwarmRunner._parse_json_block(text, require_key="scope_id")
+
+    def _load_agent_dossier(
+        self,
+        dossier_path: Path,
+        scope_id: str,
+        role: str,
+        transcript: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Load an agent dossier from disk, falling back to stdout parsing.
+
+        Headless agents sometimes answer in chat instead of writing the
+        dossier file; without this fallback the whole scope dies on
+        FileNotFoundError (observed live: 10+ minute runs, zero dossiers).
+        Parsed stdout dossiers are tagged so the auditor treats them as
+        recovered, not natively filed.
+        """
+        if dossier_path.exists():
+            with open(dossier_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        recovered = self._parse_dossier_json(transcript or "")
+        if recovered is not None:
+            recovered.setdefault("recovered_from_stdout", True)
+            dossier_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(dossier_path, "w", encoding="utf-8") as f:
+                json.dump(recovered, f, indent=2)
+            print(f"  [{role}] ⚠️ Dossier file missing; recovered from stdout.")
+            return recovered
+        raise FileNotFoundError(
+            f"{role} dossier not found at {dossier_path} and no dossier JSON "
+            f"in transcript for scope {scope_id}"
+        )
+
     def run_agent_alpha(self, scope: Dict[str, Any]):
         """Executes Agent Alpha (Thesis / Proponent / Structural Auditor) for a scope."""
         scope_id = scope["scope_id"]
@@ -424,14 +630,15 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                 system_prompt = self.prompts_dir / "agent_darkharvest.md"
             else:
                 system_prompt = self.prompts_dir / "agent_alpha_thesis.md"
-            self.run_claude_process(
+            transcript = self.run_claude_process(
                 prompt, system_prompt_file=system_prompt, role="alpha"
             )
             dossier_path = (
                 self.state_machine.get_scope_dir(scope_id) / "alpha_dossier.json"
             )
-            with open(dossier_path, "r", encoding="utf-8") as f:
-                dossier = json.load(f)
+            dossier = self._load_agent_dossier(
+                dossier_path, scope_id, "alpha", transcript
+            )
 
         self.state_machine.record_agent_completion(scope_id, "alpha", dossier)
         print(f"  [Alpha] ✅ Completed Agent Alpha for [{scope_id}].")
@@ -618,14 +825,15 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                 system_prompt = self.prompts_dir / "agent_darkharvest.md"
             else:
                 system_prompt = self.prompts_dir / "agent_beta_antithesis.md"
-            self.run_claude_process(
+            transcript = self.run_claude_process(
                 prompt, system_prompt_file=system_prompt, role="beta"
             )
             dossier_path = (
                 self.state_machine.get_scope_dir(scope_id) / "beta_dossier.json"
             )
-            with open(dossier_path, "r", encoding="utf-8") as f:
-                dossier = json.load(f)
+            dossier = self._load_agent_dossier(
+                dossier_path, scope_id, "beta", transcript
+            )
 
         self.state_machine.record_agent_completion(scope_id, "beta", dossier)
         print(f"  [Beta] ✅ Completed Agent Beta for [{scope_id}].")
@@ -662,6 +870,64 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         )
         return audit_report
 
+    def _auction_dispatch(self, ready_scopes: List[Dict[str, Any]]) -> None:
+        """Stream F: order the ready batch by expected information gain."""
+        from runner.auctioneer import (
+            estimate_tokens,
+            record_scope_telemetry,
+            score_scopes,
+        )
+
+        scored = score_scopes(ready_scopes, base_dir=self.base_dir)
+        bids = {s.get("scope_id"): b for b, s in scored}
+        for _bid, ordered_scope in scored:
+            audit_report = self.execute_scope_dialectic(ordered_scope)
+            summary = (audit_report or {}).get("summary", {})
+            sid = ordered_scope.get("scope_id", "")
+            record_scope_telemetry(
+                self.base_dir,
+                sid,
+                # tokens_used is a chars/4 ESTIMATE — flagged approximation.
+                tokens_used=estimate_tokens("x" * self._dossier_chars(sid)),
+                verified_claims=summary.get("verified_passed", 0),
+                bid=bids.get(sid),
+            )
+
+    def _dossier_chars(self, scope_id: str) -> int:
+        scope_dir = self.state_machine.get_scope_dir(scope_id)
+        total = 0
+        for name in ("alpha_dossier.json", "beta_dossier.json"):
+            p = scope_dir / name
+            if p.exists():
+                total += p.stat().st_size
+        return total
+
+    def _run_scope_batches(self) -> bool:
+        """Drive scopes by DAG until complete. False on deadlock."""
+        while True:
+            ready_scopes = self.state_machine.get_ready_scopes()
+            if not ready_scopes:
+                manifest = self.state_machine.load_global_manifest()
+                if self._all_scopes_complete(manifest):
+                    return True
+                print("[ERROR] Deadlock in scope dependency graph.", file=sys.stderr)
+                self.state_machine.update_session_status(SessionStatus.FAILED)
+                return False
+            # "auction" reorders each ready batch by expected information
+            # gain; "dag" keeps legacy dependency order.
+            if self.allocation == "auction":
+                self._auction_dispatch(ready_scopes)
+            else:
+                for scope in ready_scopes:
+                    self.execute_scope_dialectic(scope)
+
+    def _all_scopes_complete(self, manifest: Dict[str, Any]) -> bool:
+        return all(
+            self.state_machine.load_scope_manifest(s["scope_id"]).get("status")
+            == ScopeStatus.COMPLETE.value
+            for s in manifest["scopes"]
+        )
+
     def run_swarm(self, objective: str, frontier_file: Optional[Path] = None):
         """Full end-to-end execution loop."""
         start_time = datetime.now(timezone.utc)
@@ -678,59 +944,8 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         self.orchestrate_objective(objective, frontier_file)
 
         # 2. Execute scopes according to DAG
-        while True:
-            ready_scopes = self.state_machine.get_ready_scopes()
-            if not ready_scopes:
-                # Check if all scopes are complete
-                manifest = self.state_machine.load_global_manifest()
-                all_complete = all(
-                    self.state_machine.load_scope_manifest(s["scope_id"]).get("status")
-                    == ScopeStatus.COMPLETE.value
-                    for s in manifest["scopes"]
-                )
-                if all_complete:
-                    break
-                else:
-                    print(
-                        "[ERROR] Deadlock in scope dependency graph.", file=sys.stderr
-                    )
-                    self.state_machine.update_session_status(SessionStatus.FAILED)
-                    return
-
-            # Stream F: "auction" reorders each ready batch by expected
-            # information gain; "dag" keeps legacy dependency order (all ready
-            # scopes dispatched in the batch, unchanged).
-            if self.allocation == "auction":
-                from runner.auctioneer import (
-                    estimate_tokens,
-                    record_scope_telemetry,
-                    score_scopes,
-                )
-
-                scored = score_scopes(ready_scopes, base_dir=self.base_dir)
-                ordered = [s for _b, s in scored]
-                bids = {s.get("scope_id"): b for b, s in scored}
-                for ordered_scope in ordered:
-                    audit_report = self.execute_scope_dialectic(ordered_scope)
-                    summary = (audit_report or {}).get("summary", {})
-                    sid = ordered_scope.get("scope_id", "")
-                    # tokens_used is a chars/4 ESTIMATE — flagged approximation.
-                    dossier_chars = 0
-                    scope_dir = self.state_machine.get_scope_dir(sid)
-                    for name in ("alpha_dossier.json", "beta_dossier.json"):
-                        p = scope_dir / name
-                        if p.exists():
-                            dossier_chars += p.stat().st_size
-                    record_scope_telemetry(
-                        self.base_dir,
-                        sid,
-                        tokens_used=estimate_tokens("x" * dossier_chars),
-                        verified_claims=summary.get("verified_passed", 0),
-                        bid=bids.get(sid),
-                    )
-            else:
-                for scope in ready_scopes:
-                    self.execute_scope_dialectic(scope)
+        if not self._run_scope_batches():
+            return
 
         # 3. Master Synthesis Compilation
         print(
@@ -742,6 +957,36 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         duration = (datetime.now(timezone.utc) - start_time).total_seconds()
         print(f"\n🎉 Swarm run completed in {duration:.1f}s. Report: {report_path}")
 
+    def _collect_scope_totals(
+        self, manifest: Dict[str, Any], synthesis_lines: List[str]
+    ) -> Tuple[int, int, List[float]]:
+        """Fold per-scope audit/synthesis artifacts into running totals."""
+        total_verified = 0
+        total_rejected = 0
+        all_divergences: List[float] = []
+        for scope in manifest["scopes"]:
+            sid = scope["scope_id"]
+            scope_dir = self.state_machine.get_scope_dir(sid)
+            audit_file = scope_dir / "audit_report.json"
+            synth_file = scope_dir / "scope_synthesis.md"
+
+            if audit_file.exists():
+                ar = json.loads(audit_file.read_text(encoding="utf-8"))
+                summary = ar["summary"]
+                total_verified += summary["verified_passed"]
+                total_rejected += summary["unverified_rejected"]
+                all_divergences.append(summary["divergence_score"])
+
+            if synth_file.exists():
+                synthesis_lines.append(synth_file.read_text(encoding="utf-8"))
+                synthesis_lines.append("\n---\n")
+        return total_verified, total_rejected, all_divergences
+
+    def _write_report(self, filename: str, lines: List[str]) -> Path:
+        path = self.base_dir / filename
+        path.write_text("\n".join(lines), encoding="utf-8")
+        return path
+
     def _compile_master_synthesis(self, objective: str) -> Path:
         manifest = self.state_machine.load_global_manifest()
         mode_titles = {
@@ -762,27 +1007,9 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
             "## Scope Findings & Dialectic Balance Sheets\n",
         ]
 
-        total_verified = 0
-        total_rejected = 0
-        all_divergences = []
-
-        for scope in manifest["scopes"]:
-            sid = scope["scope_id"]
-            scope_dir = self.state_machine.get_scope_dir(sid)
-            audit_file = scope_dir / "audit_report.json"
-            synth_file = scope_dir / "scope_synthesis.md"
-
-            if audit_file.exists():
-                with open(audit_file, "r", encoding="utf-8") as f:
-                    ar = json.load(f)
-                    total_verified += ar["summary"]["verified_passed"]
-                    total_rejected += ar["summary"]["unverified_rejected"]
-                    all_divergences.append(ar["summary"]["divergence_score"])
-
-            if synth_file.exists():
-                with open(synth_file, "r", encoding="utf-8") as f:
-                    synthesis_lines.append(f.read())
-                    synthesis_lines.append("\n---\n")
+        total_verified, total_rejected, all_divergences = self._collect_scope_totals(
+            manifest, synthesis_lines
+        )
 
         avg_div = round(sum(all_divergences) / max(1, len(all_divergences)), 2)
         synthesis_lines.append("\n## Swarm Epistemic Audit Totals\n")
@@ -794,32 +1021,17 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
         )
         synthesis_lines.append(f"- **Mean Swarm Divergence Score**: `{avg_div}`")
 
-        final_path = self.base_dir / "final_synthesis.md"
-        with open(final_path, "w", encoding="utf-8") as f:
-            f.write("\n".join(synthesis_lines))
-
-        # Also write specialized report files for audit and scout modes
-        if self.mode == "audit":
-            audit_path = self.base_dir / "code_audit_report.md"
-            with open(audit_path, "w", encoding="utf-8") as f:
-                f.write("\n".join(synthesis_lines))
-            return audit_path
-        elif self.mode == "scout":
-            scout_path = self.base_dir / "oss_scout_report.md"
-            with open(scout_path, "w", encoding="utf-8") as f:
-                f.write("\n".join(synthesis_lines))
-            return scout_path
-        elif self.mode == "brainstorm":
-            brainstorm_path = self.base_dir / "brainstorm_report.md"
-            with open(brainstorm_path, "w", encoding="utf-8") as f:
-                f.write("\n".join(synthesis_lines))
-            return brainstorm_path
-        elif self.mode == "darkharvest":
-            darkharvest_path = self.base_dir / "darkharvest_report.md"
-            with open(darkharvest_path, "w", encoding="utf-8") as f:
-                f.write("\n".join(synthesis_lines))
-            return darkharvest_path
+        final_path = self._write_report("final_synthesis.md", synthesis_lines)
 
+        # Also write specialized report files for audit/scout/brainstorm/darkharvest.
+        specialized = {
+            "audit": "code_audit_report.md",
+            "scout": "oss_scout_report.md",
+            "brainstorm": "brainstorm_report.md",
+            "darkharvest": "darkharvest_report.md",
+        }.get(self.mode)
+        if specialized:
+            return self._write_report(specialized, synthesis_lines)
         return final_path
 
 
@@ -917,11 +1129,21 @@ def main():
         default=None,
         help="Regulated Domain Pack id (config/domain_packs/<id>.json), e.g. biopharma",
     )
+    parser.add_argument(
+        "--backend",
+        choices=["auto", "claude", "opencode"],
+        default=None,
+        help="Agent runtime backend for both roles (default: auto = host-native; explicit beats env/config)",
+    )
 
     args = parser.parse_args()
     frontier_path = Path(args.frontier) if args.frontier else None
 
     agent_overrides: Dict[str, Dict[str, Any]] = {}
+    if args.backend and args.backend != "auto":
+        argv = ["claude", "-p"] if args.backend == "claude" else ["opencode", "run"]
+        agent_overrides.setdefault("alpha", {})["backend"] = argv
+        agent_overrides.setdefault("beta", {})["backend"] = argv
     if args.model_alpha:
         agent_overrides.setdefault("alpha", {})["model"] = args.model_alpha
     if args.model_beta: