@heretek-ai/epistemic-swarm 0.7.7 → 0.7.9

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/runner/mcp_server.py

@@ -84,12 +84,16 @@ def _handle_config(args: Dict[str, Any]) -> str:
     """Inspect or modify swarm parameters in .research/config.json."""
     from skills.swarm_config.configure import (
         display_config,
+        heal_config,
         load_config,
         save_config,
     )
 
     base_dir = str(_resolve_base_dir(args))
     cfg = load_config(base_dir)
+    # Persist a legacy ["claude", "-p"] agent pin migration so an OpenCode host
+    # stops silently spawning Claude on every run.
+    healed = heal_config(base_dir)
 
     updates = {}
     for key in (
@@ -99,6 +103,8 @@ def _handle_config(args: Dict[str, Any]) -> str:
         "depth",
         "mode",
         "divergence_threshold",
+        "backend",
+        "agents",
     ):
         if key in args and args[key] is not None:
             canon = {
@@ -119,7 +125,7 @@ def _handle_config(args: Dict[str, Any]) -> str:
             }
         )
 
-    return _tool_text({"status": "current", "config": cfg})
+    return _tool_text({"status": "current", "config": cfg, "migrated": healed})
 
 
 def _run_swarm_mode(mode: Optional[str], args: Dict[str, Any]) -> str:

package/runner/research_swarm.py

@@ -66,6 +66,23 @@ def _backend_family(backend: List[str]) -> str:
     return Path(backend[0]).name if backend else "claude"
 
 
+def _agent_cwd(project_root: Path) -> str:
+    """Working directory for spawned agent processes.
+
+    The canonical agent prompts name evidence paths RELATIVELY (`.research/...`)
+    and the runner reads dossiers from `<base_dir>/scratchpads/...`. Spawning in
+    the package root made those writes land inside node_modules (denied). Spawn
+    in the project root instead so `.research/` means the operator's evidence
+    tree. Override with IUMBTEMS_AGENT_CWD=package|project|<absolute path>.
+    """
+    override = os.environ.get("IUMBTEMS_AGENT_CWD", "").strip()
+    if override == "package":
+        return str(PROJECT_ROOT)
+    if override and override != "project":
+        return override
+    return str(project_root)
+
+
 def _build_opencode_cmd(
     backend: List[str],
     prompt: str,
@@ -190,6 +207,13 @@ class SwarmRunner:
         domain_pack: Optional[str] = None,
     ):
         self.base_dir = base_dir or Path(".research")
+        # Project root = the directory containing the evidence dir. Agents are
+        # spawned here so the relative `.research/...` paths named by the
+        # canonical prompts resolve to the RUNNER's evidence tree. Spawning in
+        # PROJECT_ROOT (the installed package) sent those writes into
+        # node_modules, where they were denied and no agent-authored dossier
+        # ever landed — runs survived only on the stdout-recovery fallback.
+        self.project_root = Path(os.path.realpath(str(self.base_dir))).parent
         self.mock_mode = mock_mode
         self.config = load_config(str(self.base_dir))
         cfg = self.config
@@ -233,8 +257,46 @@ class SwarmRunner:
             or _default_backend_cmd(self.config.get("backend"))
         )
         model = override.get("model") or env_model or role_cfg.get("model")
+        self._warn_backend_host_mismatch(role, backend)
         return list(backend), model
 
+    @staticmethod
+    def _warn_backend_host_mismatch(role: str, backend: List[str]) -> None:
+        """Surface a config pin that silently defeats the host-native default.
+
+        Observed live: a pre-0.7.6 config pin of ["claude", "-p"] beat
+        IUMBTEMS_HOST=opencode, so an OpenCode host spawned Claude with no
+        signal. Warn loudly instead of failing silently.
+        """
+        host = os.environ.get("IUMBTEMS_HOST", "").strip().lower()
+        if host not in ("claude", "opencode"):
+            return
+        family = _backend_family(backend)
+        if family == host:
+            return
+        sys.stderr.write(
+            f"[swarm] WARNING: role={role} resolved backend={family!r} from an "
+            f"explicit pin/override, but IUMBTEMS_HOST={host!r}. The explicit pin "
+            f"wins. Set backend: {host!r}, agents.{role}.backend: null, or "
+            f"IUMBTEMS_BACKEND_{role.upper()}={host} to follow the host.\n"
+        )
+
+    def _scope_prompt(self, role: str, scope: Dict[str, Any], scope_id: str) -> str:
+        """Prompt for a dialectic agent, naming the absolute scratchpad dir.
+
+        The canonical prompts describe evidence paths RELATIVELY, so a bare
+        scope id left the agent guessing which `.research` tree to write to.
+        Naming the absolute directory removes the ambiguity even when the
+        spawn cwd is overridden.
+        """
+        return (
+            f"Run Agent {role} ({self.mode} mode) for scope: {json.dumps(scope)}. "
+            f"Engine: {self.engine}. Depth: {self.depth}. "
+            f"Save findings to the scratchpad directory "
+            f"{self.state_machine.get_scope_dir(scope_id)} (scope {scope_id}); "
+            f"write the dossier files there and nowhere else."
+        )
+
     def _resolve_opencode_agent(self, role: str) -> Optional[str]:
         """Explicitly configured OpenCode agent for this role, else None.
 
@@ -305,12 +367,19 @@ class SwarmRunner:
         try:
             if cmd:
                 _validate_backend([cmd[0]])
+            agent_cwd = _agent_cwd(self.project_root)
             res = subprocess.run(
                 cmd,
                 capture_output=True,
                 text=True,
                 check=True,
-                cwd=str(PROJECT_ROOT),
+                cwd=agent_cwd,
+                # `opencode run` resolves its project root from $PWD, not the OS
+                # cwd — and subprocess.run(cwd=...) does NOT update PWD. Without
+                # this the worker operated on the launcher's PWD (observed live:
+                # runner evidence dir 5da7ec/sunny-otter, worker cwd
+                # /home/john/Projects/STC). Keep PWD consistent with cwd.
+                env={**os.environ, "PWD": agent_cwd},
                 # 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
@@ -619,7 +688,7 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                     "negative_knowledge": [],
                 }
         else:
-            prompt = f"Run Agent Alpha ({self.mode} mode) for scope: {json.dumps(scope)}. Engine: {self.engine}. Depth: {self.depth}. Save findings to {scope_id} scratchpad."
+            prompt = self._scope_prompt("Alpha", scope, scope_id)
             if self.mode == "audit":
                 system_prompt = self.prompts_dir / "agent_code_auditor.md"
             elif self.mode == "scout":
@@ -814,7 +883,7 @@ Output ONLY valid JSON representing the scope decomposition conforming to prompt
                     ],
                 }
         else:
-            prompt = f"Run Agent Beta ({self.mode} mode) for scope: {json.dumps(scope)}. Engine: {self.engine}. Depth: {self.depth}. Save findings to {scope_id} scratchpad."
+            prompt = self._scope_prompt("Beta", scope, scope_id)
             if self.mode == "audit":
                 system_prompt = self.prompts_dir / "agent_code_auditor.md"
             elif self.mode == "scout":

package/runner/tests/test_swarm_config.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Config-merge and agent-spawn regressions.
+
+Covers two live failures observed on an OpenCode host running the installed
+package against an operator project:
+
+1. A pre-0.7.6 config persisted `agents.<role>.backend = ["claude", "-p"]`.
+   The shallow merge in `load_config` preserved it and it out-ranked the
+   host-native default, so an OpenCode host silently spawned Claude.
+2. Agents were spawned with `cwd=PROJECT_ROOT` (the installed package) while
+   evidence lives in the project's `.research/`, so prompt-mandated relative
+   writes landed inside node_modules and were denied.
+"""
+
+import io
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+from unittest import mock
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from runner.research_swarm import (  # noqa: E402
+    PROJECT_ROOT as PACKAGE_ROOT,
+    SwarmRunner,
+    _agent_cwd,
+)
+from skills.swarm_config.configure import (  # noqa: E402
+    DEFAULT_CONFIG,
+    heal_config,
+    load_config,
+    migrate_legacy_agent_backends,
+    save_config,
+)
+
+
+def _write_config(base_dir: Path, payload: dict) -> Path:
+    base_dir.mkdir(parents=True, exist_ok=True)
+    cfg_file = base_dir / "config.json"
+    cfg_file.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return cfg_file
+
+
+class TestLegacyAgentPinMigration(unittest.TestCase):
+    def test_legacy_pin_is_dropped_when_backend_is_auto(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(
+                base,
+                {
+                    "backend": "auto",
+                    "agents": {
+                        "alpha": {"backend": ["claude", "-p"], "model": None},
+                        "beta": {"backend": ["claude", "-p"], "model": None},
+                    },
+                },
+            )
+            cfg = load_config(str(base))
+            self.assertIsNone(cfg["agents"]["alpha"]["backend"])
+            self.assertIsNone(cfg["agents"]["beta"]["backend"])
+
+    def test_legacy_pin_no_longer_forces_claude_on_opencode_host(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(
+                base,
+                {
+                    "backend": "auto",
+                    "agents": {
+                        "alpha": {"backend": ["claude", "-p"], "model": None},
+                        "beta": {"backend": ["claude", "-p"], "model": None},
+                    },
+                },
+            )
+            with mock.patch.dict(os.environ, {"IUMBTEMS_HOST": "opencode"}):
+                runner = SwarmRunner(base_dir=base, mock_mode=True, mode="darkharvest")
+                cmd = runner.build_agent_cmd("objective", role="alpha")
+            self.assertEqual(cmd[:2], ["opencode", "run"])
+
+    def test_explicit_claude_choice_is_preserved(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(
+                base,
+                {
+                    "backend": "claude",
+                    "agents": {
+                        "alpha": {"backend": ["claude", "-p"], "model": None},
+                        "beta": {"backend": ["claude", "-p"], "model": None},
+                    },
+                },
+            )
+            with mock.patch.dict(os.environ, {"IUMBTEMS_HOST": "opencode"}):
+                runner = SwarmRunner(base_dir=base, mock_mode=True, mode="research")
+                with redirect_stderr(io.StringIO()):
+                    cmd = runner.build_agent_cmd("objective", role="alpha")
+            self.assertEqual(cmd[:2], ["claude", "-p"])
+
+    def test_backend_opencode_top_level_drops_legacy_pin(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(
+                base,
+                {
+                    "backend": "opencode",
+                    "agents": {
+                        "alpha": {"backend": ["claude", "-p"], "model": None},
+                    },
+                },
+            )
+            cfg = load_config(str(base))
+            self.assertIsNone(cfg["agents"]["alpha"]["backend"])
+
+    def test_migration_helper_reports_change(self):
+        cfg = {
+            "backend": "auto",
+            "agents": {"alpha": {"backend": ["claude", "-p"]}},
+        }
+        self.assertTrue(migrate_legacy_agent_backends(cfg))
+        self.assertFalse(migrate_legacy_agent_backends(cfg))
+
+    def test_heal_config_persists_and_is_idempotent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            cfg_file = _write_config(
+                base,
+                {
+                    "backend": "auto",
+                    "agents": {"alpha": {"backend": ["claude", "-p"], "model": None}},
+                },
+            )
+            self.assertTrue(heal_config(str(base)))
+            on_disk = json.loads(cfg_file.read_text(encoding="utf-8"))
+            self.assertIsNone(on_disk["agents"]["alpha"]["backend"])
+            # Second pass has nothing left to migrate.
+            self.assertFalse(heal_config(str(base)))
+
+
+class TestConfigMergeSemantics(unittest.TestCase):
+    def test_partial_agents_block_does_not_clobber_defaults(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(base, {"agents": {"alpha": {"model": "some-model"}}})
+            cfg = load_config(str(base))
+            self.assertEqual(cfg["agents"]["alpha"]["model"], "some-model")
+            self.assertIsNone(cfg["agents"]["alpha"]["backend"])
+            # Beta was absent from the file and keeps its defaults.
+            self.assertIsNone(cfg["agents"]["beta"]["backend"])
+
+    def test_loaded_config_does_not_alias_default_config(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            cfg = load_config(str(base))
+            cfg["agents"]["alpha"]["backend"] = "MUTATED"
+            cfg["license_whitelist"].append("MUTATED")
+            self.assertIsNone(DEFAULT_CONFIG["agents"]["alpha"]["backend"])
+            self.assertNotIn("MUTATED", DEFAULT_CONFIG["license_whitelist"])
+
+    def test_malformed_agents_block_is_tolerated(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(base, {"agents": None})
+            cfg = load_config(str(base))
+            self.assertIsNone(cfg["agents"]["alpha"]["backend"])
+
+            _write_config(base, {"agents": {"alpha": None}})
+            cfg = load_config(str(base))
+            self.assertIsNone(cfg["agents"]["alpha"])
+            self.assertIsNone(cfg["agents"]["beta"]["backend"])
+
+    def test_non_object_config_falls_back_to_defaults(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            base.mkdir(parents=True, exist_ok=True)
+            (base / "config.json").write_text("[1, 2, 3]", encoding="utf-8")
+            with redirect_stderr(io.StringIO()):
+                cfg = load_config(str(base))
+            self.assertEqual(cfg["search_engine"], "duckduckgo")
+
+    def test_save_load_roundtrip_is_idempotent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            save_config(load_config(str(base)), str(base))
+            first = load_config(str(base))
+            save_config(first, str(base))
+            self.assertEqual(first, load_config(str(base)))
+
+
+class TestAgentSpawnWorkingDirectory(unittest.TestCase):
+    def test_project_root_is_evidence_dir_parent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=True, mode="research")
+            self.assertEqual(
+                runner.project_root, Path(os.path.realpath(str(base))).parent
+            )
+
+    def test_agent_cwd_defaults_to_project_root(self):
+        project = Path("/tmp/some-project")
+        with mock.patch.dict(os.environ, {}, clear=True):
+            self.assertEqual(_agent_cwd(project), str(project))
+
+    def test_agent_cwd_package_override(self):
+        with mock.patch.dict(os.environ, {"IUMBTEMS_AGENT_CWD": "package"}):
+            self.assertEqual(_agent_cwd(Path("/tmp/x")), str(PACKAGE_ROOT))
+
+    def test_agent_cwd_absolute_override(self):
+        with mock.patch.dict(os.environ, {"IUMBTEMS_AGENT_CWD": "/custom/dir"}):
+            self.assertEqual(_agent_cwd(Path("/tmp/x")), "/custom/dir")
+
+    def test_scope_prompt_names_absolute_scratchpad(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=True, mode="darkharvest")
+            prompt = runner._scope_prompt("Alpha", {"scope_id": "s1"}, "s1")
+            expected = str(runner.state_machine.get_scope_dir("s1"))
+            self.assertIn(expected, prompt)
+            self.assertTrue(Path(expected).is_absolute())
+
+    def test_spawn_uses_project_root_not_package_root(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            runner = SwarmRunner(base_dir=base, mock_mode=False, mode="research")
+            fake = mock.Mock()
+            fake.stdout = "ok"
+            with mock.patch.dict(os.environ, {}, clear=True):
+                with mock.patch("subprocess.run", return_value=fake) as run_mock:
+                    runner.run_claude_process("objective text")
+            kwargs = run_mock.call_args.kwargs
+            self.assertEqual(kwargs["cwd"], str(runner.project_root))
+            self.assertNotEqual(kwargs["cwd"], str(PACKAGE_ROOT))
+            self.assertEqual(kwargs["stdin"], subprocess.DEVNULL)
+            # `opencode run` follows $PWD, which subprocess.run(cwd=...) does not
+            # update — keep them identical.
+            self.assertEqual(kwargs["env"]["PWD"], kwargs["cwd"])
+
+
+class TestBackendHostMismatchWarning(unittest.TestCase):
+    def test_warns_when_pin_contradicts_host(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            _write_config(
+                base,
+                {
+                    "backend": "claude",
+                    "agents": {"alpha": {"backend": ["claude", "-p"]}},
+                },
+            )
+            with mock.patch.dict(os.environ, {"IUMBTEMS_HOST": "opencode"}):
+                runner = SwarmRunner(base_dir=base, mock_mode=True, mode="research")
+                buf = io.StringIO()
+                with redirect_stderr(buf):
+                    runner.build_agent_cmd("objective", role="alpha")
+            self.assertIn("IUMBTEMS_HOST", buf.getvalue())
+            self.assertIn("alpha", buf.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/swarm_config/__init__.py

@@ -1,4 +1,17 @@
 """Epistemic Swarm configuration package."""
-from .configure import load_config, save_config, DEFAULT_CONFIG
 
-__all__ = ["load_config", "save_config", "DEFAULT_CONFIG"]
+from .configure import (
+    DEFAULT_CONFIG,
+    heal_config,
+    load_config,
+    migrate_legacy_agent_backends,
+    save_config,
+)
+
+__all__ = [
+    "load_config",
+    "save_config",
+    "heal_config",
+    "migrate_legacy_agent_backends",
+    "DEFAULT_CONFIG",
+]

package/skills/swarm_config/configure.py

@@ -4,11 +4,12 @@ Interactive Configuration Manager for IUMBTEMS Epistemic Swarm.
 Reads, modifies, and persists research parameters in .research/config.json.
 """
 
+import copy
 import sys
 import os
 import json
 from pathlib import Path
-from typing import Dict, Any
+from typing import Any, Dict
 
 DEFAULT_RESEARCH_DIR = ".research"
 
@@ -42,25 +43,117 @@ DEFAULT_CONFIG: Dict[str, Any] = {
 }
 
 
+# Historical pre-0.7.6 default that was persisted verbatim into user configs.
+# A per-role pin equal to this value, while the top-level `backend` is not an
+# explicit "claude", is a stale default rather than a deliberate choice: it must
+# not override the host-native backend (opencode on OpenCode). Explicit intent
+# lives in `backend: "claude"` or `IUMBTEMS_BACKEND_<ROLE>`.
+LEGACY_AGENT_BACKEND_PINS = (["claude", "-p"],)
+
+AGENT_ROLES = ("alpha", "beta")
+
+
 def get_config_path(base_dir: str = DEFAULT_RESEARCH_DIR) -> Path:
     return Path(base_dir) / "config.json"
 
 
+def _merge_agents(default_agents: Any, file_agents: Any) -> Dict[str, Any]:
+    """Deep-merge the per-role `agents` block, one role/key at a time.
+
+    A shallow `merged.update(data)` let a single on-disk role key clobber the
+    whole default block, which silently re-pinned every agent to whatever the
+    user's file happened to contain (the host-native default was never reached).
+    """
+    merged = copy.deepcopy(default_agents) if isinstance(default_agents, dict) else {}
+    if not isinstance(file_agents, dict):
+        return merged
+    for role, role_cfg in file_agents.items():
+        if not isinstance(role_cfg, dict):
+            # Preserve unexpected shapes verbatim rather than crashing; the
+            # backend resolver tolerates non-dict role configs.
+            merged[role] = copy.deepcopy(role_cfg)
+            continue
+        base = merged.get(role)
+        if isinstance(base, dict):
+            base.update(copy.deepcopy(role_cfg))
+        else:
+            merged[role] = copy.deepcopy(role_cfg)
+    return merged
+
+
+def migrate_legacy_agent_backends(cfg: Dict[str, Any]) -> bool:
+    """Drop stale pre-0.7.6 `["claude", "-p"]` pins in place; True if changed.
+
+    Only fires when the top-level backend is not an explicit "claude", so a user
+    who deliberately selected Claude is never silently switched to something
+    else. To keep Claude on an OpenCode host, set `backend: "claude"`.
+    """
+    if str(cfg.get("backend") or "auto").strip().lower() == "claude":
+        return False
+    agents = cfg.get("agents")
+    if not isinstance(agents, dict):
+        return False
+    changed = False
+    for role in AGENT_ROLES:
+        role_cfg = agents.get(role)
+        if (
+            isinstance(role_cfg, dict)
+            and role_cfg.get("backend") in LEGACY_AGENT_BACKEND_PINS
+        ):
+            role_cfg["backend"] = None
+            changed = True
+    return changed
+
+
 def load_config(base_dir: str = DEFAULT_RESEARCH_DIR) -> Dict[str, Any]:
+    """Load config merged over defaults. Pure — never writes to disk.
+
+    Applies the legacy-pin migration in memory so a stale config stops forcing
+    Claude immediately; `heal_config` persists that migration on next touch.
+    """
+    base = copy.deepcopy(DEFAULT_CONFIG)
     cfg_file = get_config_path(base_dir)
     if not cfg_file.exists():
-        return dict(DEFAULT_CONFIG)
+        return base
     try:
         with open(cfg_file, "r", encoding="utf-8") as f:
             data = json.load(f)
-            merged = dict(DEFAULT_CONFIG)
-            merged.update(data)
-            return merged
     except Exception as e:
         sys.stderr.write(
             f"[swarm-config] Warning: Failed to parse {cfg_file}: {e}. Using defaults.\n"
         )
-        return dict(DEFAULT_CONFIG)
+        return base
+    if not isinstance(data, dict):
+        sys.stderr.write(
+            f"[swarm-config] Warning: {cfg_file} is not a JSON object. Using defaults.\n"
+        )
+        return base
+    merged: Dict[str, Any] = {**base, **data}
+    merged["agents"] = _merge_agents(base.get("agents", {}), data.get("agents"))
+    migrate_legacy_agent_backends(merged)
+    return merged
+
+
+def heal_config(base_dir: str = DEFAULT_RESEARCH_DIR) -> bool:
+    """Persist a legacy agent-backend migration to disk; True if rewritten.
+
+    `load_config` stays side-effect free; the CLI and MCP surfaces call this so
+    an affected install self-heals instead of re-pinning Claude on every save.
+    """
+    cfg_file = get_config_path(base_dir)
+    if not cfg_file.exists():
+        return False
+    try:
+        with open(cfg_file, "r", encoding="utf-8") as f:
+            raw = json.load(f)
+    except Exception:
+        return False
+    if not isinstance(raw, dict):
+        return False
+    if not migrate_legacy_agent_backends(raw):
+        return False
+    save_config(load_config(base_dir), base_dir)
+    return True
 
 
 def save_config(cfg: Dict[str, Any], base_dir: str = DEFAULT_RESEARCH_DIR) -> Path:
@@ -218,6 +311,10 @@ def _parse_cli_updates(args: list, cfg: Dict[str, Any]) -> bool:
 
 def main():
     cfg = load_config()
+    if heal_config():
+        print(
+            "ℹ️  Migrated legacy ['claude', '-p'] agent backend pin → host-native default."
+        )
     args = sys.argv[1:]
 
     if not args or "--show" in args: