@heretek-ai/epistemic-swarm 0.7.19 → 0.7.21

package/runner/tests/test_config_schema.py

@@ -86,6 +86,7 @@ VALID_UPDATES = {
     },
     "opencode_auto": False,
     "opencode_agent": "darkharvester",
+    "mcp_servers": {"searxng": False, "firecrawl": True},
 }
 
 # One clearly invalid value per canonical key.
@@ -107,6 +108,7 @@ INVALID_UPDATES = {
     "agents": "claude -p",
     "opencode_auto": "yes",
     "opencode_agent": 5,
+    "mcp_servers": "enabled",
 }
 
 
@@ -319,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:
@@ -439,6 +506,45 @@ class TestMcpConfigSurface(unittest.TestCase):
             self.assertEqual(healed["max_iterations"], 2)
             self.assertIsNone(healed["agents"]["alpha"]["backend"])
 
+    def test_updated_payload_is_single_read_coherent(self):
+        """R10: `updated` config + hash come from ONE read of the written bytes.
+
+        Regression against the pre-R10 shape (`load_config()` then
+        `config_hash()` as two independent reads): a write landing between the
+        two would pair an era-A config with an era-B hash. We inject exactly
+        that write into `config_hash`; a single-read implementation never calls
+        it, so the returned config/hash stay coherent with the bytes on disk.
+        """
+        import hashlib
+
+        from skills.swarm_config import configure
+
+        with tempfile.TemporaryDirectory() as tmp:
+            original = configure.config_hash
+
+            def torn(base):
+                # Simulate a concurrent writer landing era-B between the old
+                # shape's two reads, immediately before the hash read.
+                cfg = Path(base) / "config.json"
+                data = json.loads(cfg.read_text(encoding="utf-8"))
+                data["mode"] = "audit"
+                cfg.write_text(json.dumps(data), encoding="utf-8")
+                return original(base)
+
+            configure.config_hash = torn
+            try:
+                payload = self._call({"mode": "scout", "base_dir": tmp})
+            finally:
+                configure.config_hash = original
+
+            self.assertEqual(payload["status"], "updated")
+            written = (Path(tmp) / "config.json").read_bytes()
+            # The hash covers the bytes the config was derived from ...
+            self.assertEqual(payload["hash"], hashlib.sha256(written).hexdigest())
+            # ... and the config is that same era (never scout + audit-hash).
+            self.assertEqual(payload["config"]["mode"], json.loads(written)["mode"])
+            self.assertEqual(payload["config"], load_config(tmp))
+
     def test_output_dir_deprecation_is_inert(self):
         with tempfile.TemporaryDirectory() as tmp:
             base = Path(tmp)

package/runner/tests/test_opencode_ux.py

@@ -911,8 +911,8 @@ class TestOpenCodeV2Transforms(unittest.TestCase):
             res = run_node(
                 f"""
                 import plugin from "./plugins/opencode/index.js";
-                let hookName = null;
-                let handler = null;
+                const hookNames = [];
+                let compactionHandler = null;
                 const host = {{
                   options: {{}},
                   location: {{directory: {str(root)!r}}},
@@ -920,16 +920,16 @@ class TestOpenCodeV2Transforms(unittest.TestCase):
                   tool: {{transform: async () => ({{dispose: async () => {{}}}}), reload: async () => {{}}}},
                   session: {{
                     prompt: async () => ({{}}),
-                    hook: async (name, fn) => {{ hookName = name; handler = fn; return {{dispose: async () => {{}}}}; }}
+                    hook: async (name, fn) => {{ hookNames.push(name); if (name === "compaction") compactionHandler = fn; return {{dispose: async () => {{}}}}; }}
                   }}
                 }};
                 await plugin.setup(host);
                 const event = {{system: [], directory: {str(root)!r}}};
-                if (handler) await handler(event);
+                if (compactionHandler) await compactionHandler(event);
                 const emptyEvent = {{system: [], directory: "/tmp/oc-v2-compaction-empty-nonexistent"}};
-                if (handler) await handler(emptyEvent);
+                if (compactionHandler) await compactionHandler(emptyEvent);
                 console.log(JSON.stringify({{
-                  hookName,
+                  hookNames,
                   parts: event.system.map((p) => ({{type: p.type, text: p.text || ""}})),
                   emptySkipped: emptyEvent.system.length
                 }}));
@@ -939,7 +939,7 @@ class TestOpenCodeV2Transforms(unittest.TestCase):
                 res.returncode, 0, f"compaction hook test failed: {res.stderr}"
             )
             data = last_json_object(res.stdout)
-            self.assertEqual(data["hookName"], "compaction")
+            self.assertIn("compaction", data["hookNames"])
             self.assertEqual(
                 data["emptySkipped"], 0, "empty workspace must not push state"
             )
@@ -1747,5 +1747,460 @@ REPLAY_SINGLE = """
 """
 
 
+# ---------------------------------------------------------------------------
+# Phase 03 (opencode-settings-menu): TUI prefers the `iumbtems.settings` RPC
+# (degraded direct-fs fallback with toast), `changed` subscription with the
+# 5s poll as floor, and UI-only prefs that never affect run-affecting values.
+# ---------------------------------------------------------------------------
+
+RPC_TUI_HARNESS = """
+import {
+  openSettingsWizard, openSettingsPanel,
+  subscribeSettingsChanged, getSettingsRpcClient,
+  readUiPrefs, writeUiPrefs,
+  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";
+
+// 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 () => snapshot(),
+    set: async (input) => {
+      state.setCalls.push(input);
+      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) stale();
+      state.raw = { ...state.raw, ...(input?.updates || {}) };
+      state.config = loadConfigFromRaw(state.raw);
+      state.hash = `hash${state.setCalls.length}`;
+      return snapshot();
+    },
+    events: {
+      on: (name, fn) => { state.subs.push({ name, fn }); return () => { state.unsubbed = true; }; },
+    },
+  };
+}
+function tuiStore() {
+  const map = new Map();
+  return {
+    map,
+    storage: {
+      store: (key, { initial }) => {
+        const cur = map.has(key) ? map.get(key) : initial;
+        return [
+          { ...((cur || {})) },
+          async (mut) => {
+            const d = { ...(((map.has(key) ? map.get(key) : initial)) || {}) };
+            mut(d);
+            map.set(key, d);
+          },
+        ];
+      },
+    },
+  };
+}
+function dialogHost(queues) {
+  const toasts = [];
+  const pop = (arr) => ((!arr || arr.length === 0) ? null : arr.shift());
+  return {
+    toasts,
+    ui: {
+      toast: { show: (t) => toasts.push(t) },
+      dialog: {
+        select: async (a) => pop(queues.select),
+        prompt: async (a) => pop(queues.prompt),
+        confirm: async (a) => pop(queues.confirm),
+      },
+      panel: async (p) => { dialogHost._panel = p; return {}; },
+    },
+  };
+}
+"""
+
+
+class TestRpcPreferredPath(unittest.TestCase):
+    def test_wizard_prefers_rpc_and_writes_nothing_to_disk(self):
+        # C2 (preferred leg): with `client.rpc` the wizard round-trips through
+        # the RPC subclient; the workspace is never touched on disk.
+        with tempfile.TemporaryDirectory() as tmp:
+            res = run_node(
+                RPC_TUI_HARNESS
+                + f"""
+                const root = {tmp!r};
+                const state = rpcState({{ search_engine: "duckduckgo" }}, "h0");
+                const store = tuiStore();
+                const h = dialogHost({{ select: ["search_engine", "brave", "__iumbtems_save__"], confirm: [true] }});
+                const host = {{
+                  directory: root, client: {{ rpc: (def) => rpcClient(state) }},
+                  storage: store.storage, ui: h.ui,
+                }};
+                const r = await openSettingsWizard(host, root, {{ env: {{}} }});
+                const toasts = h.toasts.map((t) => JSON.stringify(t)).join("\\n");
+                console.log(JSON.stringify({{
+                  ok: r.ok, written: r.written, hash: r.hash,
+                  setCalls: state.setCalls,
+                  files: (function walk(d) {{
+                    try {{ return fs.readdirSync(d); }} catch {{ return []; }}
+                  }})(root),
+                  degraded: toasts.includes("degraded"),
+                  viaRpc: toasts.includes("server RPC"),
+                  prefs: store.map.get(UI_PREFS_KEY) || null,
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"rpc wizard failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["ok"])
+            self.assertTrue(data["written"])
+            self.assertEqual(len(data["setCalls"]), 1)
+            self.assertEqual(data["setCalls"][0]["updates"]["search_engine"], "brave")
+            self.assertEqual(data["setCalls"][0]["expectedHash"], "h0")
+            self.assertEqual(data["hash"], "hash1")
+            # Nothing written to disk: the RPC is the write path.
+            self.assertEqual(data["files"], [])
+            self.assertFalse(data["degraded"])
+            self.assertTrue(data["viaRpc"])
+            # UI prefs recorded the save; nothing else.
+            self.assertIn("lastSavedAt", data["prefs"])
+
+    def test_wizard_falls_back_without_client_with_toast(self):
+        # C2 (fallback leg): no `client.rpc` -> direct-fs write + toast, same
+        # validation and hash guard as before.
+        with tempfile.TemporaryDirectory() as tmp:
+            res = run_node(
+                RPC_TUI_HARNESS
+                + f"""
+                const root = {tmp!r};
+                const h = dialogHost({{ select: ["search_engine", "brave", "__iumbtems_save__"], confirm: [true] }});
+                const host = {{ directory: root, ui: h.ui }};
+                const r = await openSettingsWizard(host, root, {{ env: {{}} }});
+                const saved = JSON.parse(fs.readFileSync(path.join(root, ".research", "config.json"), "utf-8"));
+                const toasts = h.toasts.map((t) => JSON.stringify(t)).join("\\n");
+                console.log(JSON.stringify({{
+                  ok: r.ok, written: r.written,
+                  engine: saved.search_engine,
+                  degraded: toasts.includes("degraded path"),
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"fallback failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["ok"])
+            self.assertTrue(data["written"])
+            self.assertEqual(data["engine"], "brave")
+            self.assertTrue(data["degraded"])
+
+    def test_wizard_rpc_stale_maps_to_stale_result(self):
+        # C3 at the TUI: a stale RPC write surfaces the stale outcome and
+        # writes nothing anywhere.
+        with tempfile.TemporaryDirectory() as tmp:
+            res = run_node(
+                RPC_TUI_HARNESS
+                + f"""
+                const root = {tmp!r};
+                const state = rpcState({{ search_engine: "duckduckgo" }}, "h0");
+                state.staleAlways = true;
+                const h = dialogHost({{ select: ["search_engine", "brave", "__iumbtems_save__"], confirm: [true] }});
+                const host = {{
+                  directory: root, client: {{ rpc: (def) => rpcClient(state) }}, ui: h.ui,
+                }};
+                const r = await openSettingsWizard(host, root, {{ env: {{}} }});
+                const toasts = h.toasts.map((t) => JSON.stringify(t)).join("\\n");
+                let files = [];
+                try {{ files = fs.readdirSync(root); }} catch {{ files = []; }}
+                console.log(JSON.stringify({{
+                  ok: r.ok, reason: r.reason, written: r.written,
+                  staleToast: toasts.includes("refusing the stale write"),
+                  files,
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"stale wizard failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertFalse(data["ok"])
+            self.assertEqual(data["reason"], "stale")
+            self.assertFalse(data["written"])
+            self.assertTrue(data["staleToast"])
+            self.assertEqual(data["files"], [])
+
+    def test_panel_prefers_rpc_snapshot_without_writing(self):
+        # The panel never writes: seed a real file (the single-read snapshot
+        # serves it) and prove the bytes are untouched.
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            seed = json.dumps({"mode": "audit", "search_engine": "brave"})
+            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", search_engine: "brave" }}, "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 after = fs.readFileSync(path.join(root, ".research", "config.json"), "utf-8");
+                console.log(JSON.stringify({{
+                  ok: r.ok, degraded: r.degraded, body: shown[0].body,
+                  intact: after === {seed!r},
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"rpc panel failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["ok"])
+            self.assertFalse(data["degraded"])
+            self.assertIn("audit", data["body"])
+            self.assertIn("Operating Mode", data["body"])
+            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.
+        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 h = dialogHost({{ select: ["__iumbtems_cancel__"] }});
+                const host = {{
+                  directory: root, client: {{ rpc: (def) => rpcClient(state) }}, ui: h.ui,
+                }};
+                const r = await openSettingsWizard(host, root, {{ env: {{}} }});
+                const toasts = h.toasts.map((t) => JSON.stringify(t)).join("\\n");
+                console.log(JSON.stringify({{
+                  cancelled: r.cancelled, written: r.written,
+                  warns: toasts.includes("Could not parse"),
+                  intact: fs.readFileSync(path.join(root, ".research", "config.json"), "utf-8") === {garbage!r},
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"malformed rpc failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["cancelled"])
+            self.assertFalse(data["written"])
+            self.assertTrue(data["warns"])
+            self.assertTrue(data["intact"])
+
+
+class TestChangedSubscription(unittest.TestCase):
+    def test_changed_event_reaches_subscriber_and_poll_floor_held(self):
+        res = run_node(
+            RPC_TUI_HARNESS
+            + """
+            const state = rpcState({}, "h0");
+            const withRpc = { client: { rpc: (def) => rpcClient(state) } };
+            const seen = [];
+            const unsub = subscribeSettingsChanged(withRpc, (e) => seen.push(e));
+            state.subs[0].fn({ hash: "hash9", keys: ["mode"] });
+            if (typeof unsub === "function") unsub();
+            const withoutRpc = subscribeSettingsChanged({ ui: {} }, () => {});
+            console.log(JSON.stringify({
+              subscribed: state.subs.map((s) => s.name),
+              seen,
+              unsubbed: state.unsubbed,
+              bare: withoutRpc,
+              pollMs: SETTINGS_POLL_MS,
+              rpcId: SettingsRpc.id,
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        data = last_json_object(res.stdout)
+        # Subscribed with the local event name; the received payload arrives.
+        self.assertEqual(data["subscribed"], ["changed"])
+        self.assertEqual(data["seen"], [{"hash": "hash9", "keys": ["mode"]}])
+        self.assertTrue(data["unsubbed"])
+        # No RPC -> null (the 5s mtime poll remains the floor).
+        self.assertIsNone(data["bare"])
+        self.assertEqual(data["pollMs"], 5000)
+        self.assertEqual(data["rpcId"], "iumbtems.settings")
+
+
+class TestUiPrefsBoundary(unittest.TestCase):
+    """C4 (TUI half): `storage.store` prefs never affect run-affecting values."""
+
+    def test_prefs_round_trip_without_touching_config(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            research.joinpath("config.json").write_text(
+                json.dumps({"mode": "research"}), encoding="utf-8"
+            )
+            res = run_node(
+                RPC_TUI_HARNESS
+                + f"""
+                const root = {tmp!r};
+                const store = tuiStore();
+                const host = {{
+                  directory: root, storage: store.storage,
+                  ui: {{ panel: async (p) => {{ host._panel = p; }} }},
+                }};
+                // Prefs deliberately named like run-affecting keys.
+                const wrote = await writeUiPrefs(host, {{ mode: "audit", search_engine: "evil", lastSavedAt: "x" }});
+                const prefs = readUiPrefs(host);
+                const r = await openSettingsPanel(host, root, {{ env: {{}} }});
+                const onDisk = JSON.parse(fs.readFileSync(path.join(root, ".research", "config.json"), "utf-8"));
+                console.log(JSON.stringify({{
+                  wrote, prefs, body: host._panel.body, onDisk,
+                  bare: readUiPrefs({{ ui: {{}} }}),
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"prefs failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["wrote"])
+            self.assertEqual(data["prefs"]["mode"], "audit")
+            # Effective values still come from the file, never the prefs.
+            self.assertIn("research", data["body"])
+            self.assertNotIn("evil", data["body"])
+            self.assertEqual(data["onDisk"], {"mode": "research"})
+            # No TUI storage -> {} (never throws).
+            self.assertEqual(data["bare"], {})
+
+
 if __name__ == "__main__":
     unittest.main()