@heretek-ai/epistemic-swarm 0.7.20 → 0.7.21

package/.claude-plugin/plugin.json

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

package/README.md

@@ -157,7 +157,7 @@ Related environment variables:
 
 Spawned agents inherit `PWD` set to their working directory, so harnesses that resolve their project root from `$PWD` (OpenCode) land in the same tree the runner reads from.
 
-> **Legacy config migration:** configs written before 0.7.6 could pin `agents.<role>.backend = ["claude", "-p"]`, which silently overrode the host-native default. That pin is now migrated to `null` on load (only when the top-level `backend` is not an explicit `"claude"`), and the migration is persisted by `iumbtems config`. To deliberately keep Claude on an OpenCode host, set `"backend": "claude"`.
+> **Legacy config migration:** configs written before 0.7.6 could pin `agents.<role>.backend = ["claude", "-p"]`, which silently overrode the host-native default. That pin is now migrated to `null` on load (only when the top-level `backend` is not an explicit `"claude"`), and the migration is persisted on the next config **write** (a read / `--show` never heals). To deliberately keep Claude on an OpenCode host, set `"backend": "claude"`.
 
 ---
 
@@ -265,6 +265,27 @@ Nine canonical skills live in `skills/*/SKILL.md`. Each maps to a slash command
 
 ---
 
+## ⚙️ Settings Surface (`/swarm-config`)
+
+The settings surface is the recommended way to tune the harness from inside OpenCode V2. It has two parts:
+
+- **`/swarm-config` wizard** — a native dialog wizard (`ui.dialog.select/prompt/confirm`) showing every canonical key with a provenance badge (`default` / `file` / `env-override`), one editable row at a time, validated and written atomically on save.
+- **Status panel** — a read-only panel opened from the command palette / keymap (`iumbtems.swarm-settings`) rendering the effective rows with a **next-run** badge. It never writes.
+
+The canonical config it edits is **`.research/config.json`** — the TUI resolves `.research` from the OpenCode host root; `IUMBTEMS_PROJECT_DIR` / `--dir` / `base_dir` select the workspace for the CLI, MCP, and runner surfaces. Configurable values include the search engine, depth (`max_iterations`), operating `mode`, `backend`, per-role (`agents.*`) backend/model, `license_whitelist`, the cache / TTL / search-timeout knobs, `searxng_url`, `verify.min_fuzzy_confidence`, the persistence `mcp_servers` toggle map, `allocation`, `domain_pack`, and the deprecated display-only `output_dir`. (`divergence_threshold` is advisory: recorded, never gating a verdict.)
+
+**Honest boundaries**
+
+- **Values apply to the NEXT swarm run.** The Python runner reads `.research/config.json` once at run start, so a save never hot-swaps a running swarm — the wizard and panel both say "applies to the next swarm run".
+- **Per-role temperature does not govern spawned agents.** The OpenCode session `context` hook honors `IUMBTEMS_TEMPERATURE[_<ROLE>]` for sessions running inside OpenCode, but there is **no verified path** that sets per-role temperature for spawned swarm agents — that leg is recorded `[NEGATIVE_KNOWLEDGE]` (S3, dated 2026-09-29; waiver W3). The UI deliberately makes no temperature claim.
+- **No secrets in config.** API keys stay in the environment (`FIRECRAWL_API_KEY`, …). The surface only reports whether an env override is set for the keys it models; it never renders an env value, and it does not probe engine availability.
+
+Writes prefer the plugin's `iumbtems.settings` RPC (server-side validation + an `expectedHash` lost-update guard; the RPC surfaces a `conflict` error type, and Python's code is `CONFLICTING_EXPECTED_HASH`) and degrade to a direct-fs write with a visible toast when `client.rpc` is absent; `.research/config.json` stays the single source of truth. See [docs/SYSTEM_ARCHITECTURE.md](docs/SYSTEM_ARCHITECTURE.md) §6.7 for the full data flow, the atomic-write + lock protocol, and the `ctx.storage` mirror.
+
+*Reviewed settings-surface patterns from Gemini CLI, Codex, Goose, Aider, Cline, OpenCode, and Crush (docs-only) informed this design; no code was copied.*
+
+---
+
 ## 🗂️ Workspace & Evidence Model
 
 All state lives in a local `.research/` directory (resolved from `IUMBTEMS_PROJECT_DIR` when set, else the process cwd):
@@ -366,7 +387,7 @@ The package is distributed on npm as `@heretek-ai/epistemic-swarm` using [npm Tr
 
 **Release flow** (see [AGENTS.md](AGENTS.md#releases)):
 
-1. Bump `package.json` **and** `.claude-plugin/plugin.json` **and** the lockfile in lockstep.
+1. Bump the **four enforced manifests** in lockstep: `package.json`, `package-lock.json`, `.claude-plugin/plugin.json`, and `plugins/antigravity/plugin.json` (`python3 scripts/build_adapters.py --check` guards the AntiGravity one).
 2. Commit and push to `main`.
 3. `gh release create vX.Y.Z` — the `Publish to npm` workflow
    (`.github/workflows/publish.yml`) runs on `release: published`, executes the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.20",
+  "version": "0.7.21",
   "description": "IUMBTEMS (Epistemic Swarm) \u2014 High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi (pi.dev), OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/plugins/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.7.20",
+  "version": "0.7.21",
   "description": "IUMBTEMS (Epistemic Swarm) \u2014 High-Integrity Dialectic Research, Architecture Auditing, Competitor Teardowns, and Socratic Planning for Antigravity.",
   "author": {
     "name": "Heretek AI",

package/plugins/antigravity/rules/AGENTS.md

@@ -109,9 +109,11 @@ or `[NEGATIVE_KNOWLEDGE: <query>]`. Never present parametric recall as verified.
   effect only after release + reinstall.
 
 ## Releases
-- Bump `package.json` (+ lockfile sync) **and `.claude-plugin/plugin.json`**
-  (0.7.5 shipped with a stale plugin manifest — keep all three in lockstep),
-  commit, push to `main`, then
+- Bump the **four enforced manifests** in lockstep — `package.json`,
+  `package-lock.json`, `.claude-plugin/plugin.json`, and
+  `plugins/antigravity/plugin.json` (0.7.5 shipped a stale plugin manifest and
+  v0.7.18 missed the AntiGravity manifest, failing `Validate All Harnesses` +
+  `Publish to npm` twice). Then commit, push to `main`, then
   `gh release create vX.Y.Z`. The `Publish to npm` workflow (OIDC trusted
   publishing) runs on release-published. Verify with
   `curl https://registry.npmjs.org/@heretek-ai%2Fepistemic-swarm`

package/plugins/opencode/index.js

@@ -2097,6 +2097,7 @@ export const SettingsRpc = {
         type: 'object',
         properties: {
           config: { type: 'object' },
+          raw: { type: ['object', 'null'] },
           hash: { type: ['string', 'null'] },
           migrated: { type: 'boolean' },
         },
@@ -2308,11 +2309,12 @@ export function createSettingsHandlers(opts = {}) {
         throw sanitized;
       }
       // Single-read (phase-03 R5): the raw bytes are read EXACTLY ONCE below;
-      // the returned config is merged from those bytes and the hash is
-      // computed over those bytes, so an era-A config with an era-B hash is
+      // the returned effective `config` is merged from those bytes, the `raw`
+      // on-disk subset is parsed from those bytes, and the hash is computed
+      // over those bytes — so an era-A config with an era-B hash (or raw) is
       // impossible. The Python surface still supplies the `migrated` flag
-      // (and keeps its heal-on-read side effect); the returned triple is one
-      // snapshot regardless of what either side read on its own clock.
+      // (computed in memory; the show leg never writes); the returned payload
+      // is one snapshot regardless of what either side read on its own clock.
       const snap = readConfigSnapshot(researchDir);
       const config = loadConfigFromRaw(snap.raw);
       // Refresh-on-read (phase-03 R1): a direct-fs fallback-leg write bypasses
@@ -2330,7 +2332,10 @@ export function createSettingsHandlers(opts = {}) {
       } catch {
         /* the storage mirror is best-effort */
       }
-      return { config, hash: snap.hash, migrated: Boolean(payload.migrated) };
+      // `raw` (phase-04 R1) is the parsed ON-DISK file config (null when
+      // absent/malformed) so the TUI can compute provenance: a key present in
+      // `raw` is `file`, otherwise `default` (env-override still wins).
+      return { config, raw: snap.raw, hash: snap.hash, migrated: Boolean(payload.migrated) };
     },
     validate: async (input = {}) => {
       const updates = input?.updates;

package/plugins/opencode/tui.js

@@ -165,19 +165,33 @@ function formatSettingRows(rows) {
  * otherwise. Never throws.
  */
 async function effectiveSettingsBody(host, baseDir, env) {
+  let body = null;
   const rpc = getSettingsRpcClient(host);
   if (rpc) {
     try {
       const snap = await rpc.get();
       if (snap && snap.config && typeof snap.config === 'object') {
-        const rows = buildSettingRows({ ...snap.config }, snap.config, env);
-        if (rows.length > 0) return formatSettingRows(rows);
+        // Provenance comes from the ON-DISK `raw`, not the merged effective
+        // `config` (every key is present there, which made every row `file`).
+        const rows = buildSettingRows({ ...snap.config }, snap.raw, env);
+        if (rows.length > 0) body = formatSettingRows(rows);
       }
     } catch {
       /* fall through to the direct-fs read */
     }
   }
-  return formatSettingsText(baseDir, env);
+  if (body === null) body = formatSettingsText(baseDir, env);
+  // R10: a malformed file must not render as silent defaults. Advisory local-fs
+  // check (the same rule the wizard warns on); surfaced in the panel body —
+  // never throws, never writes.
+  try {
+    if (isConfigMalformed(baseDir)) {
+      body = `⚠️ Could not parse ${baseDir}/config.json — showing defaults.\n\n${body}`;
+    }
+  } catch {
+    /* advisory only — a failed check must not break the panel */
+  }
+  return body;
 }
 
 /** Palette command opening the read-only settings status panel. */
@@ -1009,7 +1023,9 @@ export async function openSettingsWizard(host, root, opts = {}) {
       try {
         const snap = await rpc.get();
         if (!snap || typeof snap.config !== 'object') throw new Error('empty snapshot');
-        raw = snap.config;
+        // R1: provenance uses the RPC's on-disk `raw` (null/absent -> {}),
+        // never the merged effective `config`.
+        raw = snap.raw && typeof snap.raw === 'object' ? snap.raw : {};
         draft = JSON.parse(JSON.stringify(snap.config));
         startHash = typeof snap.hash === 'string' ? snap.hash : null;
       } catch {

package/runner/mcp_server.py

@@ -145,6 +145,35 @@ def _allows_null(schema: Dict[str, Any]) -> bool:
     return types == "null"
 
 
+def _legacy_pin_migration_pending(base_dir: str) -> bool:
+    """Would the legacy-pin migration apply on the next write? (read-only)
+
+    Phase-04 R11: the `show` leg reports this WITHOUT persisting, so a read API
+    stays side-effect free. Mirrors `heal_config`'s decision — the on-disk file
+    carries a legacy ``["claude", "-p"]`` pin AND the would-be-persisted config
+    passes canonical validation (an invalid file is never healed, R1) — but
+    never writes.
+    """
+    try:
+        from skills.swarm_config.configure import (
+            load_config,
+            migrate_legacy_agent_backends,
+            validate_config,
+        )
+
+        cfg_file = Path(base_dir) / "config.json"
+        if not cfg_file.is_file():
+            return False
+        raw = json.loads(cfg_file.read_bytes().decode("utf-8"))
+        if not isinstance(raw, dict):
+            return False
+        if not migrate_legacy_agent_backends(raw):
+            return False
+        return not validate_config(load_config(base_dir))
+    except Exception:
+        return False
+
+
 def _handle_config(args: Dict[str, Any]) -> str:
     """Inspect or modify swarm parameters in .research/config.json.
 
@@ -159,7 +188,6 @@ def _handle_config(args: Dict[str, Any]) -> str:
     from skills.swarm_config.configure import (
         DEFAULT_CONFIG,
         ConfigError,
-        heal_config,
         load_config,
         merge_config,
         save_config,
@@ -169,10 +197,6 @@ def _handle_config(args: Dict[str, Any]) -> str:
 
     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. `heal_config` refuses to
-    # persist a schema-rejected file (R1).
-    healed = heal_config(base_dir)
 
     # R4: both spellings must agree; never silently prefer one.
     snake = args.get("expected_hash")
@@ -242,7 +266,16 @@ def _handle_config(args: Dict[str, Any]) -> str:
         )
 
     if not updates:
-        return _tool_text({"status": "current", "config": cfg, "migrated": healed})
+        # R11: the show leg is strictly read-only — a settings panel reads
+        # through it, so it must never persist the legacy-pin migration. Report
+        # whether a migration is pending; only the write leg below heals.
+        return _tool_text(
+            {
+                "status": "current",
+                "config": cfg,
+                "migrated": _legacy_pin_migration_pending(base_dir),
+            }
+        )
 
     candidate = merge_config(cfg, updates)
     problems = validate_config(candidate)
@@ -257,6 +290,11 @@ def _handle_config(args: Dict[str, Any]) -> str:
             }
         )
 
+    # R12 (F1): do NOT heal before saving. The candidate is already migrated in
+    # memory (`load_config`) and `save_config` merges it over the on-disk bytes,
+    # so the legacy-pin migration persists as a side effect — while the caller's
+    # `expected_hash` guard still matches the bytes they read. A heal-before-save
+    # rewrote the file and turned a valid guarded write into a false `stale`.
     try:
         save_config(
             candidate,

package/runner/tests/test_config_schema.py

@@ -321,6 +321,71 @@ class TestMcpConfigSurface(unittest.TestCase):
             self.assertFalse((Path(tmp) / "config.json").exists())
             shown = self._call({"base_dir": tmp, "show": True})
             self.assertEqual(shown["status"], "current")
+            # R11: the legacy-pin case must NOT write (the old test was vacuous
+            # here). Seed a pin, snapshot the bytes, and prove the show leg
+            # leaves them byte-identical while still reporting the migration.
+            cfg_file = _write_config(
+                Path(tmp), {"agents": {"alpha": {"backend": ["claude", "-p"]}}}
+            )
+            before = cfg_file.read_bytes()
+            pinned = self._call({"base_dir": tmp})
+            self.assertEqual(pinned["status"], "current")
+            self.assertTrue(pinned["migrated"])
+            self.assertEqual(cfg_file.read_bytes(), before)
+
+    def test_write_leg_heals_legacy_pin_and_persists(self):
+        # R11 preserves phase-01 A6: a write still migrates the legacy pin on disk.
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp)
+            cfg_file = _write_config(
+                base, {"agents": {"alpha": {"backend": ["claude", "-p"]}}}
+            )
+            payload = self._call({"max_iterations": 2, "base_dir": tmp})
+            self.assertEqual(payload["status"], "updated", payload)
+            healed = json.loads(cfg_file.read_text(encoding="utf-8"))
+            self.assertIsNone(healed["agents"]["alpha"]["backend"])
+            self.assertEqual(healed["max_iterations"], 2)
+
+    def test_guarded_write_on_legacy_pin_succeeds_and_heals(self):
+        # F1/R12: the wizard always sends `expected_hash`. With no heal-before-
+        # save, the guard still matches so the write is `updated` (never a false
+        # `stale`) and the pin is migrated on disk.
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp)
+            cfg_file = _write_config(
+                base, {"agents": {"alpha": {"backend": ["claude", "-p"]}}}
+            )
+            start_hash = config_hash(tmp)
+            payload = self._call(
+                {"max_iterations": 3, "expected_hash": start_hash, "base_dir": tmp}
+            )
+            self.assertEqual(payload["status"], "updated", payload)
+            healed = json.loads(cfg_file.read_text(encoding="utf-8"))
+            self.assertIsNone(healed["agents"]["alpha"]["backend"])
+            self.assertEqual(healed["max_iterations"], 3)
+
+    def test_invalid_pin_file_show_reports_no_migration_and_write_blocked(self):
+        # R12/R11: an invalid file is never healed, and a write that would leave
+        # it invalid is rejected without touching the bytes.
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp)
+            cfg_file = _write_config(
+                base,
+                {
+                    "max_iterations": 99,
+                    "agents": {"alpha": {"backend": ["claude", "-p"]}},
+                },
+            )
+            before = cfg_file.read_bytes()
+            shown = self._call({"base_dir": tmp})
+            self.assertEqual(shown["status"], "current")
+            self.assertFalse(shown["migrated"])
+            self.assertEqual(cfg_file.read_bytes(), before)
+            blocked = self._call({"mode": "audit", "base_dir": tmp})
+            self.assertEqual(blocked["status"], "error")
+            self.assertEqual(blocked["code"], "CONFIG_VALIDATION_FAILED")
+            self.assertFalse(blocked["written"])
+            self.assertEqual(cfg_file.read_bytes(), before)
 
     def test_null_clears_a_nullable_key(self):
         with tempfile.TemporaryDirectory() as tmp:

package/runner/tests/test_opencode_ux.py

@@ -1761,33 +1761,41 @@ import {
   SETTINGS_POLL_MS, UI_PREFS_KEY,
 } from "./plugins/opencode/tui.js";
 import { SettingsRpc } from "./plugins/opencode/index.js";
+import { loadConfigFromRaw } from "./plugins/opencode/config-io.js";
 import fs from "node:fs";
 import path from "node:path";
 
-function rpcState(config, hash) {
-  return { config: { ...config }, hash, setCalls: [], subs: [], unsubbed: false, staleAlways: false };
+// Realistic RPC snapshot (phase-04 R1): `raw` is the parsed ON-DISK file config;
+// `config` is the defaults-merged EFFECTIVE config (the production `get` builds
+// it with `loadConfigFromRaw`). A partial-config mock here is exactly what let
+// the RPC-path provenance defect ship.
+function rpcState(raw, hash) {
+  const onDisk = raw && typeof raw === "object" ? raw : {};
+  return {
+    raw: { ...onDisk },
+    config: loadConfigFromRaw(onDisk),
+    hash, setCalls: [], subs: [], unsubbed: false, staleAlways: false,
+  };
 }
 function rpcClient(state) {
+  const snapshot = () => ({ config: { ...state.config }, raw: { ...state.raw }, hash: state.hash });
   return {
-    get: async () => ({ config: { ...state.config }, hash: state.hash }),
+    get: async () => snapshot(),
     set: async (input) => {
       state.setCalls.push(input);
-      if (state.staleAlways) {
+      const stale = () => {
         const e = new Error("stale");
         e.type = "stale";
         e.data = { current_hash: state.hash, config: { ...state.config } };
         throw e;
-      }
+      };
+      if (state.staleAlways) stale();
       const exp = input?.expected_hash !== undefined ? input.expected_hash : input?.expectedHash;
-      if (exp !== undefined && exp !== null && exp !== state.hash) {
-        const e = new Error("stale");
-        e.type = "stale";
-        e.data = { current_hash: state.hash, config: { ...state.config } };
-        throw e;
-      }
-      state.config = { ...state.config, ...(input?.updates || {}) };
+      if (exp !== undefined && exp !== null && exp !== state.hash) stale();
+      state.raw = { ...state.raw, ...(input?.updates || {}) };
+      state.config = loadConfigFromRaw(state.raw);
       state.hash = `hash${state.setCalls.length}`;
-      return { config: { ...state.config }, hash: state.hash };
+      return snapshot();
     },
     events: {
       on: (name, fn) => { state.subs.push({ name, fn }); return () => { state.unsubbed = true; }; },
@@ -1972,6 +1980,118 @@ class TestRpcPreferredPath(unittest.TestCase):
             self.assertIn("applies to next swarm run", data["body"])
             self.assertTrue(data["intact"])
 
+    def test_panel_rpc_path_provenance_distinguishes_sources(self):
+        # R1 (the shipped defect): on the PREFERRED RPC path, provenance must be
+        # default | file | env-override, derived from the RPC `raw` (on-disk)
+        # rather than the merged effective `config`. Pre-fix, every row was
+        # `[file]` and `[default]` was unreachable ({file: 18}).
+        res = run_node(
+            RPC_TUI_HARNESS
+            + """
+            const state = rpcState({ search_engine: "brave" }, "h0");
+            const shown = [];
+            const host = {
+              directory: "/tmp/oc-rpc-prov",
+              client: { rpc: (def) => rpcClient(state) },
+              ui: { panel: async (p) => shown.push(p) },
+            };
+            const r = await openSettingsPanel(host, "/tmp/oc-rpc-prov", {
+              env: { IUMBTEMS_SEARCH_TIMEOUT_S: "9" },
+            });
+            const body = shown[0].body;
+            const rowOf = (key) => body.split("\\n").find((l) => l.includes("(" + key + ")"));
+            console.log(JSON.stringify({
+              ok: r.ok,
+              searchEngine: rowOf("search_engine"),
+              mode: rowOf("mode"),
+              timeout: rowOf("search_timeout_s"),
+              fileCount: (body.match(/\\[file\\]/g) || []).length,
+              defaultCount: (body.match(/\\[default\\]/g) || []).length,
+              envCount: (body.match(/\\[env-override\\]/g) || []).length,
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"rpc provenance failed: {res.stderr}")
+        d = last_json_object(res.stdout)
+        self.assertTrue(d["ok"])
+        # The on-disk file sets only `search_engine` -> `file`, and exactly one row.
+        self.assertIn("[file]", d["searchEngine"])
+        self.assertEqual(d["fileCount"], 1)
+        # `default` is REACHABLE for keys the on-disk file does not set.
+        self.assertIn("[default]", d["mode"])
+        self.assertGreater(d["defaultCount"], 0)
+        # env-override wins for the mapped key.
+        self.assertIn("[env-override]", d["timeout"])
+        self.assertEqual(d["envCount"], 1)
+
+    def test_panel_rpc_path_warns_on_malformed_config(self):
+        # R10: the read-only panel must warn on a malformed config (the wizard
+        # already does), never render silent defaults, never throw, never write.
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            garbage = "{oops not json"
+            research.joinpath("config.json").write_text(garbage, encoding="utf-8")
+            res = run_node(
+                RPC_TUI_HARNESS
+                + f"""
+                const root = {tmp!r};
+                const state = rpcState({{}}, null);
+                const shown = [];
+                const host = {{
+                  directory: root, client: {{ rpc: (def) => rpcClient(state) }},
+                  ui: {{ panel: async (p) => shown.push(p) }},
+                }};
+                const r = await openSettingsPanel(host, root, {{ env: {{}} }});
+                const body = (shown[0] && shown[0].body) || "";
+                const after = fs.readFileSync(path.join(root, ".research", "config.json"), "utf-8");
+                console.log(JSON.stringify({{
+                  ok: r.ok,
+                  warns: body.includes("Could not parse"),
+                  hasRows: body.includes("effective values"),
+                  intact: after === {garbage!r},
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"panel malformed failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["ok"])
+            self.assertTrue(data["warns"])
+            self.assertTrue(data["hasRows"])
+            self.assertTrue(data["intact"])
+
+    def test_panel_rpc_path_no_notice_for_valid_config(self):
+        # R10 companion: a valid config renders NO malformed notice.
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            seed = json.dumps({"mode": "audit"})
+            research.joinpath("config.json").write_text(seed, encoding="utf-8")
+            res = run_node(
+                RPC_TUI_HARNESS
+                + f"""
+                const root = {tmp!r};
+                const state = rpcState({{ mode: "audit" }}, "h0");
+                const shown = [];
+                const host = {{
+                  directory: root, client: {{ rpc: (def) => rpcClient(state) }},
+                  ui: {{ panel: async (p) => shown.push(p) }},
+                }};
+                const r = await openSettingsPanel(host, root, {{ env: {{}} }});
+                const body = (shown[0] && shown[0].body) || "";
+                console.log(JSON.stringify({{
+                  ok: r.ok,
+                  warns: body.includes("Could not parse"),
+                  hasMode: body.includes("audit"),
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"panel valid failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["ok"])
+            self.assertFalse(data["warns"])
+            self.assertTrue(data["hasMode"])
+
     def test_wizard_rpc_path_warns_on_malformed_config(self):
         # Phase-03 R6 (phase-02 B2 on the primary path): corrupt config with
         # an RPC-preferred host warns instead of rendering silent defaults.

package/runner/tests/test_opencode_v2_registrars.py

@@ -693,6 +693,7 @@ class TestSettingsRpcDomain(unittest.TestCase):
               rpcId: SETTINGS_RPC_ID,
               methods,
               getIn: SettingsRpc.methods.get.input,
+              getOut: SettingsRpc.methods.get.output,
               setOutRequired: SettingsRpc.methods.set.output.required,
               events: Object.keys(SettingsRpc.events),
               changedRequired: SettingsRpc.events.changed.schema.required,
@@ -708,6 +709,10 @@ class TestSettingsRpcDomain(unittest.TestCase):
         self.assertEqual(d["methods"], ["get", "set", "validate"])
         # JSON-Schema I/O per the v2 RPC pattern; event data is an object.
         self.assertEqual(d["getIn"]["type"], "object")
+        # R1: `get` carries the on-disk `raw` alongside the effective `config`.
+        self.assertEqual(d["getOut"]["type"], "object")
+        self.assertIn("raw", d["getOut"]["properties"])
+        self.assertIn("config", d["getOut"]["required"])
         self.assertIn("config", d["setOutRequired"])
         self.assertIn("hash", d["setOutRequired"])
         self.assertEqual(d["events"], ["changed"])
@@ -1436,6 +1441,52 @@ class TestSingleReadSnapshot(unittest.TestCase):
             self.assertEqual(d["mirrorMode"], d["gotMode"])
             self.assertEqual(d["mirrorHash"], d["gotHash"])
 
+    def test_get_payload_carries_raw_and_effective_from_one_read(self):
+        """R1: `get` carries the on-disk `raw` alongside the merged effective
+        `config`, and the hash covers the same bytes (single-read preserved)."""
+        import hashlib
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            cfg = research / "config.json"
+            on_disk = {"mode": "scout"}
+            cfg.write_text(json.dumps(on_disk), encoding="utf-8")
+            res = run_node(
+                PHASE3_HOST
+                + f"""
+                const box = makePhase3Host({tmp!r});
+                const stub = async () => ({{
+                  content: JSON.stringify({{ status: "current", config: {{}}, migrated: false }}),
+                  status: "success",
+                }});
+                const handlers = createSettingsHandlers({{
+                  root: {tmp!r},
+                  callMcpImpl: stub,
+                  storage: box.host.storage,
+                }});
+                const got = await handlers.get({{}}, rpcCtx());
+                console.log(JSON.stringify({{
+                  raw: got.raw,
+                  effectiveMode: got.config.mode,
+                  effectiveHasDefaults: ("search_engine" in got.config) && ("max_iterations" in got.config),
+                  rawHasSearchEngine: Boolean(got.raw && ("search_engine" in got.raw)),
+                  hash: got.hash,
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, res.stderr)
+            d = last_json_object(res.stdout)
+            # `raw` is exactly the on-disk file config (not the merged result).
+            self.assertEqual(d["raw"], on_disk)
+            self.assertFalse(d["rawHasSearchEngine"])
+            # `config` is the merged effective config.
+            self.assertEqual(d["effectiveMode"], "scout")
+            self.assertTrue(d["effectiveHasDefaults"])
+            # Single-read: the hash is of the same bytes `raw` was parsed from.
+            self.assertEqual(d["hash"], hashlib.sha256(cfg.read_bytes()).hexdigest())
+
 
 class TestRpcGetSanitizedError(unittest.TestCase):
     """Phase-03 R4b: `get` spawn failures are structured, fail-closed errors."""

package/skills/swarm_config/SKILL.md

@@ -124,6 +124,32 @@ prefix of **at least 8 hex characters**; conflicting spellings are rejected with
 canonical validation (the legacy-pin migration stays in memory until the
 invalid values are fixed).
 
+## 4. TUI Settings Surface (OpenCode V2)
+
+On OpenCode V2 hosts the plugin ships a native settings surface — the recommended
+path when you are already inside OpenCode:
+
+- **`/swarm-config` wizard** — `ui.dialog.select/prompt/confirm`, one row per
+  canonical key with a provenance badge (`default` / `file` / `env-override`);
+  edits validate on save.
+- **`iumbtems.swarm-settings` status panel** — a read-only panel opened from the
+  command palette / keymap showing the effective rows with a **next-run** badge;
+  it never writes.
+
+Both read and write the same canonical `.research/config.json`, preferring the
+server `iumbtems.settings` RPC (server-side validation + `expectedHash` guard) and
+degrading to a direct-fs write (`plugins/opencode/config-io.js`) with a visible
+toast when `client.rpc` is absent. Live refresh subscribes to the RPC `changed`
+event; the 5s poll remains the floor.
+
+The honest boundaries are unchanged from the CLI/MCP paths: values apply to the
+**next** swarm run (the runner reads config at run start); per-role temperature
+does **not** govern spawned agents (dated `[NEGATIVE_KNOWLEDGE]`, waiver W3);
+out-of-range `IUMBTEMS_TEMPERATURE[_<ROLE>]` values are DISCARDED (fail-closed),
+not clamped; secrets stay in the environment. See `docs/SYSTEM_ARCHITECTURE.md`
+§6.7 for the full data flow, the `.research/.config.lock` protocol, the
+`expectedHash` guard, and the `ctx.storage` mirror.
+
 ## 5. Known limitations (recorded by phase 01)
 
 - **Crash-safety scope (F9):** the atomic-write regression patches `os.replace`

package/skills/swarm_config/configure.py

@@ -694,15 +694,38 @@ def _save_or_report(cfg: Dict[str, Any]) -> Optional[Path]:
         return None
 
 
+def _legacy_pin_pending(base_dir: str = DEFAULT_RESEARCH_DIR) -> bool:
+    """Would the legacy-pin migration apply on the next save? (read-only)
+
+    R12/F2: the CLI read paths (`--show` / bare) must never write, so this
+    reports a pending migration without persisting it. Mirrors `heal_config`'s
+    decision — a legacy ``["claude", "-p"]`` pin is present AND the
+    would-be-persisted config passes canonical validation — but never writes.
+    """
+    try:
+        raw = _read_raw_config(get_config_path(base_dir))
+        if not isinstance(raw, dict):
+            return False
+        if not migrate_legacy_agent_backends(raw):
+            return False
+        return not validate_config(load_config(base_dir))
+    except Exception:
+        return False
+
+
 def main():
     cfg = load_config()
-    if heal_config():
-        print(
-            "ℹ️  Migrated legacy ['claude', '-p'] agent backend pin → host-native default."
-        )
     args = sys.argv[1:]
+    # R12/F2: compute the pending migration READ-ONLY. Heal only when an update
+    # is actually saved; a read (`--show` / bare) must never write.
+    pending_migration = _legacy_pin_pending()
 
     if not args or "--show" in args:
+        if pending_migration:
+            print(
+                "ℹ️  A legacy ['claude', '-p'] agent backend pin is present; it "
+                "will migrate to the host-native default on the next save."
+            )
         display_config(cfg)
         if not args:
             print("To edit settings, run:")
@@ -717,6 +740,10 @@ def main():
         cfg_path = _save_or_report(cfg)
         if cfg_path is None:
             raise SystemExit(1)
+        if pending_migration:
+            print(
+                "ℹ️  Migrated legacy ['claude', '-p'] agent backend pin → host-native default."
+            )
         print(f"✅ Configuration saved to {cfg_path}")
         display_config(cfg)
         return
@@ -726,6 +753,10 @@ def main():
         cfg_path = _save_or_report(cfg)
         if cfg_path is None:
             raise SystemExit(1)
+        if pending_migration:
+            print(
+                "ℹ️  Migrated legacy ['claude', '-p'] agent backend pin → host-native default."
+            )
         print(f"✅ Configuration updated and saved to {cfg_path}")
     display_config(cfg)