@heretek-ai/epistemic-swarm 0.7.19 → 0.7.21

package/runner/tests/test_opencode_v2_registrars.py

@@ -388,9 +388,11 @@ class TestConfigToolCatalogSurface(unittest.TestCase):
         self.assertEqual(problems, [])
         advertised_keys = set(advertised["properties"]) - self.CONTROL_ARGS
         self.assertEqual(advertised_keys, set(artifact["properties"]))
-        # Phase 03 owns mcp_servers: it must stay out of the schema AND the ad.
-        self.assertNotIn("mcp_servers", advertised["properties"])
-        self.assertNotIn("mcp_servers", artifact["properties"])
+        # Phase 03 owns mcp_servers: the persisted toggle map is in the schema
+        # AND the ad (applied via ctx.mcp.transform; catalog file untouched).
+        self.assertIn("mcp_servers", advertised["properties"])
+        self.assertIn("mcp_servers", artifact["properties"])
+        self.assertEqual(advertised["properties"]["mcp_servers"]["type"], "object")
         # R4: both expected-hash spellings are advertised and documented.
         self.assertIn("expected_hash", advertised["properties"])
         self.assertIn("expectedHash", advertised["properties"])
@@ -512,5 +514,1112 @@ class TestWizardSlashRegistration(unittest.TestCase):
         self.assertEqual(data["withPanel"]["panels"], 1)
 
 
+# ---------------------------------------------------------------------------
+# Phase 03 (opencode-settings-menu): `iumbtems.settings` RPC domain, storage
+# mirror, MCP toggles, temperature hook + the bounded S3 spike harness.
+#
+# The mock host below models the v2 API shapes verified against
+# @opencode/plugin@2.0.18 + https://opencode.ai/v2/docs/build/plugins/rpc:
+# `ctx.rpc.register(Def, handlers)` returning `{dispose, events.emit}`,
+# `ctx.storage` get/set/remove/scan, `ctx.mcp.transform` with an
+# editor over `[name, config]` tuples, and `session.hook(name, fn)`.
+# ---------------------------------------------------------------------------
+
+PHASE3_HOST = """
+import plugin, {
+  SettingsRpc, SETTINGS_RPC_ID, SETTINGS_STORAGE_KEY,
+  createSettingsHandlers, registerSettingsRpc,
+  resolveMcpToggles, readPersistedMcpToggles, loadControllableMcpServers,
+  registerMcpToggles,
+  temperatureForRole, applyTemperatureToContext, registerTemperatureHook,
+} from "./plugins/opencode/index.js";
+
+function makePhase3Host(root, opts = {}) {
+  const emits = [];
+  const handlers = {};
+  let def = null;
+  const storageMap = new Map();
+  const mcpServers = new Map(Object.entries(opts.mcpSeed || {
+    iumbtems: {}, searxng: {}, "brave-search": {}, firecrawl: {}, "custom-evil": {},
+  }));
+  const hookCalls = [];
+  const host = {
+    options: {},
+    location: { directory: root },
+    rpc: {
+      register: async (d, h) => {
+        def = d;
+        Object.assign(handlers, h);
+        return {
+          dispose: async () => {},
+          events: { emit: async (name, data) => { emits.push({ name, data }); } },
+        };
+      },
+    },
+    storage: {
+      get: async (k) => storageMap.get(k),
+      set: async (k, v) => { storageMap.set(k, v); },
+      remove: async (k) => { storageMap.delete(k); },
+      scan: async ({ prefix }) => ({
+        entries: [...storageMap.entries()]
+          .filter(([k]) => String(k).startsWith(prefix))
+          .map(([key, value]) => ({ key, value })),
+      }),
+    },
+    mcp: {
+      transform: async (fn) => {
+        const editor = {
+          list: () => [...mcpServers.entries()],
+          get: (n) => mcpServers.get(n),
+          set: (n, c) => { mcpServers.set(n, c); },
+          update: (n, fn2) => { const c = mcpServers.get(n); if (c) fn2(c); },
+          remove: (n) => { mcpServers.delete(n); },
+        };
+        fn(editor);
+        return { dispose: async () => {} };
+      },
+      reload: async () => { host._reloads = (host._reloads || 0) + 1; },
+    },
+    session: {
+      prompt: async () => ({}),
+      hook: async (name, fn) => { hookCalls.push({ name, fn }); return { dispose: async () => {} }; },
+    },
+    command: {
+      list: async () => ({ data: [] }),
+      transform: async () => ({ dispose: () => {} }),
+      reload: async () => {},
+    },
+    tool: { transform: async () => ({ dispose: () => {} }), reload: async () => {} },
+    agent: {
+      list: async () => ({ data: [] }),
+      transform: async () => ({ dispose: () => {} }),
+      reload: async () => {},
+    },
+    skill: {
+      list: async () => ({ data: [] }),
+      transform: async () => ({ dispose: () => {} }),
+      reload: async () => {},
+    },
+  };
+  return { host, emits, handlers, storageMap, mcpServers, hookCalls, getDef: () => def };
+}
+
+// In-memory stub of the canonical Python surface (`callMcp`) with the
+// phase-01/02 hash-guard semantics: full/prefix match proceeds, mismatch is
+// `stale` with a fresh snapshot, conflicting spellings are an error.
+function makeStubMcp(state) {
+  const calls = [];
+  const impl = async (tool, args = {}) => {
+    calls.push({ tool, args });
+    if (tool !== "iumbtems_config") {
+      return { content: JSON.stringify({ status: "error" }), status: "error" };
+    }
+    const keys = Object.keys(args || {});
+    const readOnly = keys.every((k) =>
+      ["base_dir", "show", "expected_hash", "expectedHash"].includes(k));
+    if (readOnly) {
+      return {
+        content: JSON.stringify({
+          status: "current", config: { ...state.config }, migrated: false,
+        }),
+        status: "success",
+      };
+    }
+    const snake = args.expected_hash;
+    const camel = args.expectedHash;
+    if (snake !== undefined && camel !== undefined && String(snake) !== String(camel)) {
+      return {
+        content: JSON.stringify({
+          status: "error", code: "CONFLICTING_EXPECTED_HASH", written: false,
+        }),
+        status: "success",
+      };
+    }
+    const expected = snake !== undefined ? snake : camel;
+    if (expected !== undefined && expected !== null &&
+        !(state.hash || "").startsWith(String(expected))) {
+      return {
+        content: JSON.stringify({
+          status: "stale", written: false,
+          expected_hash: String(expected),
+          current_hash: state.hash,
+          config: { ...state.config },
+        }),
+        status: "success",
+      };
+    }
+    const updates = { ...(args || {}) };
+    for (const k of ["base_dir", "show", "expected_hash", "expectedHash"]) delete updates[k];
+    Object.assign(state.config, updates);
+    state.writes = (state.writes || 0) + 1;
+    state.hash = `hash${state.writes}`;
+    return {
+      content: JSON.stringify({
+        status: "updated", config: { ...state.config }, hash: state.hash,
+      }),
+      status: "success",
+    };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+// Real-host `context.error(type, message, data)` shape: throw a typed error.
+function rpcCtx() {
+  return {
+    signal: null,
+    error: (type, message, data) => {
+      const e = new Error(message);
+      e.type = type;
+      e.data = data;
+      throw e;
+    },
+  };
+}
+"""
+
+
+class TestSettingsRpcDomain(unittest.TestCase):
+    """C1: the `iumbtems.settings` domain registers; get/set/validate run."""
+
+    def test_definition_shape_matches_v2_rpc_pattern(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const methods = Object.keys(SettingsRpc.methods).sort();
+            const errorNames = Object.keys(SettingsRpc.methods.set.errors || {});
+            console.log(JSON.stringify({
+              id: SettingsRpc.id,
+              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,
+              changedType: SettingsRpc.events.changed.schema.type,
+              errorNames,
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["id"], "iumbtems.settings")
+        self.assertEqual(d["rpcId"], "iumbtems.settings")
+        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"])
+        self.assertIn("hash", d["changedRequired"])
+        self.assertEqual(d["changedType"], "object")
+        # `rpc.*` error names are reserved by OpenCode and must not be used.
+        self.assertFalse([n for n in d["errorNames"] if n.startswith("rpc.")])
+        self.assertIn("stale", d["errorNames"])
+
+    def test_setup_registers_rpc_domain(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-rpc-setup");
+            await plugin.setup(box.host);
+            const def = box.getDef();
+            console.log(JSON.stringify({
+              defId: def && def.id,
+              handlerNames: Object.keys(box.handlers).sort(),
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["defId"], "iumbtems.settings")
+        self.assertEqual(d["handlerNames"], ["get", "set", "validate"])
+
+    def test_setup_without_rpc_domain_still_works(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-rpc-bare");
+            delete box.host.rpc;
+            delete box.host.storage;
+            delete box.host.mcp;
+            delete box.host.session.hook;
+            const cleanup = await plugin.setup(box.host);
+            console.log(JSON.stringify({ cleanupFn: typeof cleanup }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        self.assertEqual(last_json_object(res.stdout)["cleanupFn"], "function")
+
+    def test_get_set_validate_round_trip(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-rpc-roundtrip");
+            const state = { config: { mode: "research", max_iterations: 2 }, hash: "abc123def4567890", writes: 0 };
+            const callMcp = makeStubMcp(state);
+            const emitted = [];
+            const handlers = createSettingsHandlers({
+              root: "/tmp/oc-rpc-roundtrip",
+              callMcpImpl: callMcp,
+              storage: box.host.storage,
+              emitChanged: async (data) => { emitted.push(data); },
+              reloadMcp: async () => { await box.host.mcp.reload(); },
+            });
+            const ctx = rpcCtx();
+            const got = await handlers.get({}, ctx);
+            const validated = await handlers.validate({ updates: { max_iterations: 9 } });
+            const validatedOk = await handlers.validate({ updates: { mode: "audit" } });
+            const written = await handlers.set({ updates: { mode: "audit" } }, ctx);
+            const mirror = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+            console.log(JSON.stringify({
+              gotMode: got.config.mode,
+              gotHash: got.hash,
+              invalid: validated.valid,
+              invalidProblems: validated.problems.length,
+              validOk: validatedOk.valid,
+              writtenMode: written.config.mode,
+              writtenHash: written.hash,
+              emits: emitted,
+              reloads: box.host._reloads || 0,
+              mirrorMode: mirror && mirror.config && mirror.config.mode,
+              mirrorHash: mirror && mirror.hash,
+              mirrorHasUpdated: Boolean(mirror && mirror.updated),
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["gotMode"], "research")
+        # No config file on disk in the stubbed workspace: hash is null.
+        self.assertIsNone(d["gotHash"])
+        self.assertFalse(d["invalid"])
+        self.assertGreater(d["invalidProblems"], 0)
+        self.assertTrue(d["validOk"])
+        self.assertEqual(d["writtenMode"], "audit")
+        # `changed` emitted exactly once per successful write.
+        self.assertEqual(len(d["emits"]), 1)
+        self.assertEqual(d["emits"][0]["hash"], d["writtenHash"])
+        self.assertIn("mode", d["emits"][0]["keys"])
+        self.assertEqual(d["reloads"], 1)
+        # Storage mirror holds the last effective config + hash.
+        self.assertEqual(d["mirrorMode"], "audit")
+        self.assertEqual(d["mirrorHash"], d["writtenHash"])
+        self.assertTrue(d["mirrorHasUpdated"])
+
+    def test_rpc_writes_through_canonical_python_surface(self):
+        # No stub: the default callMcp spawns runner/mcp_server.py for real,
+        # proving the single-writer discipline holds end to end.
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            res = run_node(
+                PHASE3_HOST
+                + f"""
+                const handlers = createSettingsHandlers({{ root: {tmp!r} }});
+                const ctx = rpcCtx();
+                const before = await handlers.get(ctx);
+                const written = await handlers.set({{ updates: {{ mode: "audit" }} }}, ctx);
+                const after = await handlers.get(ctx);
+                console.log(JSON.stringify({{
+                  beforeMode: before.config.mode,
+                  writtenMode: written.config.mode,
+                  hashLen: String(written.hash || "").length,
+                  afterMode: after.config.mode,
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, res.stderr)
+            d = last_json_object(res.stdout)
+            self.assertEqual(d["beforeMode"], "research")
+            self.assertEqual(d["writtenMode"], "audit")
+            self.assertEqual(d["hashLen"], 64)
+            self.assertEqual(d["afterMode"], "audit")
+
+
+class TestSettingsRpcGuards(unittest.TestCase):
+    """C3: stale/conflicting/malformed guards reject with no write."""
+
+    def test_stale_expected_hash_returns_structured_error(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-rpc-stale");
+            const state = { config: { mode: "audit" }, hash: "abcdef1234567890", writes: 0 };
+            const callMcp = makeStubMcp(state);
+            const emitted = [];
+            const handlers = createSettingsHandlers({
+              root: "/tmp/oc-rpc-stale",
+              callMcpImpl: callMcp,
+              storage: box.host.storage,
+              emitChanged: async (data) => { emitted.push(data); },
+            });
+            const ctx = rpcCtx();
+            let failure = null;
+            try {
+              await handlers.set({ updates: { mode: "research" }, expected_hash: "deadbeef00" }, ctx);
+            } catch (e) { failure = { type: e.type, data: e.data }; }
+            const mirror = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+            console.log(JSON.stringify({
+              failureType: failure && failure.type,
+              currentHash: failure && failure.data && failure.data.current_hash,
+              freshMode: failure && failure.data && failure.data.config && failure.data.config.mode,
+              writtenFlag: failure && failure.data && failure.data.written,
+              writes: state.writes,
+              emits: emitted.length,
+              mirror: mirror === undefined ? null : mirror,
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["failureType"], "stale")
+        self.assertEqual(d["currentHash"], "abcdef1234567890")
+        self.assertEqual(d["freshMode"], "audit")
+        self.assertFalse(d["writtenFlag"])
+        self.assertEqual(d["writes"], 0)
+        self.assertEqual(d["emits"], 0)
+        self.assertIsNone(d["mirror"])
+
+    def test_conflicting_spellings_rejected_without_call(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-rpc-conflict");
+            const state = { config: { mode: "audit" }, hash: "abcdef1234567890", writes: 0 };
+            const callMcp = makeStubMcp(state);
+            const handlers = createSettingsHandlers({
+              root: "/tmp/oc-rpc-conflict", callMcpImpl: callMcp,
+            });
+            const ctx = rpcCtx();
+            let failure = null;
+            try {
+              await handlers.set(
+                { updates: { mode: "research" }, expected_hash: "abcdef1234567890", expectedHash: "00000000" },
+                ctx
+              );
+            } catch (e) { failure = { type: e.type, message: e.message }; }
+            console.log(JSON.stringify({
+              failureType: failure && failure.type,
+              calls: callMcp.calls.length,
+              writes: state.writes,
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["failureType"], "conflict")
+        self.assertEqual(d["calls"], 0)
+        self.assertEqual(d["writes"], 0)
+
+    def test_malformed_guard_rejected_without_call(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-rpc-malformed");
+            const state = { config: {}, hash: "abcdef1234567890", writes: 0 };
+            const callMcp = makeStubMcp(state);
+            const handlers = createSettingsHandlers({
+              root: "/tmp/oc-rpc-malformed", callMcpImpl: callMcp,
+            });
+            const ctx = rpcCtx();
+            const types = [];
+            for (const guard of ["abcd", "xyz-not-hex", "12"]) {
+              try {
+                await handlers.set({ updates: { mode: "research" }, expectedHash: guard }, ctx);
+                types.push("accepted:" + guard);
+              } catch (e) { types.push(e.type); }
+            }
+            // Equal spellings carrying the live hash proceed.
+            const ok = await handlers.set(
+              { updates: { mode: "research" }, expected_hash: "abcdef1234567890", expectedHash: "abcdef1234567890" },
+              ctx
+            );
+            console.log(JSON.stringify({ types, okMode: ok.config.mode, calls: callMcp.calls.length }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["types"], ["invalid", "invalid", "invalid"])
+        self.assertEqual(d["okMode"], "research")
+        # Only the accepted write reached the canonical surface.
+        self.assertEqual(d["calls"], 1)
+
+
+class TestMcpToggleReconcile(unittest.TestCase):
+    """C5: `ctx.mcp.transform` applies `disabled`; the catalog is untouched."""
+
+    def test_controllable_set_matches_catalog(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            import fs from "node:fs";
+            import path from "node:path";
+            const catalog = JSON.parse(
+              fs.readFileSync("config/mcp-research-servers.json", "utf-8")
+            );
+            console.log(JSON.stringify({
+              controllable: loadControllableMcpServers().sort(),
+              catalogKeys: Object.keys(catalog.mcpServers || {}).sort(),
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["controllable"], d["catalogKeys"])
+        self.assertIn("iumbtems", d["controllable"])
+
+    def test_resolve_toggles_triple_gate(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const toggles = resolveMcpToggles(
+              { searxng: false, iumbtems: true, "custom-evil": false, nope: false, bad: "x" },
+              ["iumbtems", "searxng", "custom-evil"],
+              ["iumbtems", "searxng", "brave-search", "firecrawl"]
+            );
+            console.log(JSON.stringify({ toggles }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        toggles = last_json_object(res.stdout)["toggles"]
+        # searxng disables; iumbtems:true reconciles to disabled:false;
+        # custom-evil is not controllable, nope is not in the registry,
+        # bad is not a boolean.
+        self.assertEqual(
+            toggles,
+            [
+                {"name": "searxng", "disabled": True},
+                {"name": "iumbtems", "disabled": False},
+            ],
+        )
+
+    def test_transform_applies_disabled_from_persisted_map(self):
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            research.joinpath("config.json").write_text(
+                json.dumps({"mcp_servers": {"searxng": False}}),
+                encoding="utf-8",
+            )
+            res = run_node(
+                PHASE3_HOST
+                + f"""
+                const box = makePhase3Host({tmp!r});
+                const reg = await registerMcpToggles(box.host, {{ root: {tmp!r} }});
+                const servers = Object.fromEntries(box.mcpServers);
+                console.log(JSON.stringify({{
+                  registered: Boolean(reg),
+                  searxngDisabled: servers.searxng && servers.searxng.disabled,
+                  iumbtemsKeys: Object.keys(servers.iumbtems || {{}}),
+                  evilKeys: Object.keys(servers["custom-evil"] || {{}}),
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, res.stderr)
+            d = last_json_object(res.stdout)
+            self.assertTrue(d["registered"])
+            self.assertTrue(d["searxngDisabled"])
+            self.assertEqual(d["iumbtemsKeys"], [])
+            self.assertEqual(d["evilKeys"], [])
+
+    def test_catalog_file_byte_identical(self):
+        catalog = PROJECT_ROOT / "config" / "mcp-research-servers.json"
+        before = catalog.read_bytes()
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-mcp-catalog");
+            await plugin.setup(box.host);
+            console.log(JSON.stringify({ ok: true }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        self.assertEqual(catalog.read_bytes(), before)
+
+    def test_mcp_domain_absent_is_graceful(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-mcp-bare");
+            delete box.host.mcp;
+            const reg = await registerMcpToggles(box.host, { root: "/tmp/oc-mcp-bare" });
+            console.log(JSON.stringify({ reg }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        self.assertIsNone(last_json_object(res.stdout)["reg"])
+
+
+class TestTemperatureHook(unittest.TestCase):
+    """C6 (wired half): the context hook keys off `event.agent`."""
+
+    HOOK_FIRE = """
+            const box = makePhase3Host("/tmp/oc-temp");
+            const reg = await registerTemperatureHook(box.host, { env: {
+              IUMBTEMS_TEMPERATURE_ALPHA: "0.2",
+              IUMBTEMS_TEMPERATURE_BETA: "not-a-number",
+            }});
+            const hook = box.hookCalls.find((h) => h.name === "context");
+    """
+
+    def test_hook_registered_and_keyed_off_event_agent(self):
+        res = run_node(
+            PHASE3_HOST
+            + self.HOOK_FIRE
+            + """
+            // The role comes from `event.agent` (type-guaranteed SessionContext),
+            // never from the IUMBTEMS_AGENT_ROLE env var: a hostile env naming
+            // beta must not move an alpha request.
+            process.env.IUMBTEMS_AGENT_ROLE = "beta";
+            const alpha = { agent: "alpha", options: {} };
+            const beta = { agent: "beta", options: {} };
+            const noAgent = { options: {} };
+            hook.fn(alpha);
+            hook.fn(beta);
+            hook.fn(noAgent);
+            console.log(JSON.stringify({
+              registered: Boolean(reg),
+              hookName: hook && hook.name,
+              alphaTemp: alpha.options.temperature,
+              betaHasTemp: Object.prototype.hasOwnProperty.call(beta.options, "temperature"),
+              noAgentHasTemp: Object.prototype.hasOwnProperty.call(noAgent.options, "temperature"),
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertTrue(d["registered"])
+        self.assertEqual(d["hookName"], "context")
+        self.assertEqual(d["alphaTemp"], 0.2)
+        self.assertFalse(d["betaHasTemp"])
+        self.assertFalse(d["noAgentHasTemp"])
+
+    def test_temperature_bounds(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const env = {
+              IUMBTEMS_TEMPERATURE_ALPHA: "0.2",
+              IUMBTEMS_TEMPERATURE_BETA: "high",
+              IUMBTEMS_TEMPERATURE_GAMMA: "5",
+              IUMBTEMS_TEMPERATURE_DELTA: "",
+            };
+            const generic = { IUMBTEMS_TEMPERATURE: "0.7" };
+            console.log(JSON.stringify({
+              alpha: temperatureForRole("alpha", env) ?? null,
+              beta: temperatureForRole("beta", env) ?? null,
+              gamma: temperatureForRole("gamma", env) ?? null,
+              delta: temperatureForRole("delta", env) ?? null,
+              missing: temperatureForRole("zeta", env) ?? null,
+              empty: temperatureForRole("", env) ?? null,
+              genericAlpha: temperatureForRole("alpha", generic) ?? null,
+              applied: applyTemperatureToContext({ agent: "alpha", options: {} }, env),
+              skipped: applyTemperatureToContext({ options: {} }, env),
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        self.assertEqual(d["alpha"], 0.2)
+        self.assertIsNone(d["beta"])
+        self.assertIsNone(d["gamma"])
+        self.assertIsNone(d["delta"])
+        self.assertIsNone(d["missing"])
+        self.assertIsNone(d["empty"])
+        self.assertEqual(d["genericAlpha"], 0.7)
+        self.assertTrue(d["applied"])
+        self.assertFalse(d["skipped"])
+
+    def test_hook_domain_absent_is_graceful(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const reg = await registerTemperatureHook({}, {});
+            console.log(JSON.stringify({ reg }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        self.assertIsNone(last_json_object(res.stdout)["reg"])
+
+
+class TestS3SpikeHarness(unittest.TestCase):
+    """C6 (spike): `IUMBTEMS_AGENT_ROLE` reaches the spawned child env.
+
+    Bounded by the phase brief: local stub harness only — no model spend, no
+    network. The dated outcome is recorded in the phase receipt: the runner
+    env leg and the in-host hook leg are verified below; whether a live
+    `opencode run` child loads the project plugin and honors the hook is
+    NEGATIVE_KNOWLEDGE (unobservable without spending a model call).
+    """
+
+    def test_role_exported_to_child_env(self):
+        import os
+        from unittest import mock
+
+        from runner.research_swarm import _config_child_env
+
+        with mock.patch.dict(os.environ, {}, clear=True):
+            env = _config_child_env(
+                Path("/tmp/proj/.research"), "/tmp/proj", {}, role="alpha"
+            )
+            self.assertEqual(env["IUMBTEMS_AGENT_ROLE"], "alpha")
+            beta = _config_child_env(
+                Path("/tmp/proj/.research"), "/tmp/proj", {}, role="beta"
+            )
+            self.assertEqual(beta["IUMBTEMS_AGENT_ROLE"], "beta")
+            # Absent/empty role exports nothing (byte-identical default path).
+            for blank in (None, ""):
+                plain = _config_child_env(
+                    Path("/tmp/proj/.research"), "/tmp/proj", {}, role=blank
+                )
+                self.assertNotIn("IUMBTEMS_AGENT_ROLE", plain)
+            # The pre-existing channels are unchanged by the new parameter.
+            self.assertEqual(env["PWD"], "/tmp/proj")
+            self.assertEqual(env["IUMBTEMS_RESEARCH_DIR"], "/tmp/proj/.research")
+
+    def test_spawn_wiring_carries_role(self):
+        import json as _json
+        import os
+        import tempfile
+        from unittest import mock
+
+        from runner.research_swarm import SwarmRunner
+
+        with tempfile.TemporaryDirectory() as tmp:
+            base = Path(tmp) / ".research"
+            base.mkdir(parents=True, exist_ok=True)
+            (base / "config.json").write_text(
+                _json.dumps({"searxng_url": "http://searx.local:8888"}),
+                encoding="utf-8",
+            )
+            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", role="beta")
+            kwargs = run_mock.call_args.kwargs
+            self.assertEqual(kwargs["env"]["IUMBTEMS_AGENT_ROLE"], "beta")
+            # Default callers (no role) keep the historical shape.
+            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["env"]["IUMBTEMS_AGENT_ROLE"], "alpha")
+
+    def test_stub_child_observes_role_in_its_env(self):
+        # OS-level leg: a stub child spawned with the produced env observes
+        # IUMBTEMS_AGENT_ROLE. No model, no network — pure env plumbing.
+        import os
+        import subprocess
+        import sys
+        import tempfile
+        from unittest import mock
+
+        from runner.research_swarm import _config_child_env
+
+        with tempfile.TemporaryDirectory() as tmp:
+            probe = Path(tmp) / "role_probe.py"
+            probe.write_text(
+                "import os, sys; sys.stdout.write(os.environ.get("
+                "'IUMBTEMS_AGENT_ROLE', '<absent>'))",
+                encoding="utf-8",
+            )
+            with mock.patch.dict(os.environ, {}, clear=True):
+                env = _config_child_env(Path(tmp) / ".research", tmp, {}, role="beta")
+                out = subprocess.run(
+                    [sys.executable, str(probe)],
+                    capture_output=True,
+                    text=True,
+                    env=env,
+                )
+            self.assertEqual(out.returncode, 0, out.stderr)
+            self.assertEqual(out.stdout, "beta")
+
+
+class TestFallbackMirrorConvergence(unittest.TestCase):
+    """Phase-03 R1: fallback-write -> RPC-get-fresh + mirror-converged.
+
+    The degraded path honestly stays degraded, but the mirror must not lie
+    permanently: every server-mediated read refreshes it to disk truth
+    (refresh-on-read; no new protocol). The stub below is file-backed so the
+    single-read snapshot (phase-03 R5) exercises real disk bytes end to end.
+    """
+
+    FILE_BACKED = """
+    const __fs = await import("node:fs");
+    const __crypto = await import("node:crypto");
+    const __path = await import("node:path");
+    const fs = __fs.default || __fs;
+    const fspath = __path.default || __path;
+    const shaFile = (f) => __crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+    // File-backed stub of the canonical surface: show reads the real file,
+    // set guards + writes the real file. The handler's single-read snapshot
+    // therefore sees the same bytes a production fallback write leaves.
+    function makeFileBackedMcp(cfgFile) {
+      const calls = [];
+      const impl = async (tool, args = {}) => {
+        calls.push(args);
+        const read = () => JSON.parse(fs.readFileSync(cfgFile, "utf-8"));
+        const keys = Object.keys(args || {});
+        const readOnly = keys.every((k) =>
+          ["base_dir", "show", "expected_hash", "expectedHash"].includes(k));
+        if (readOnly) {
+          return {
+            content: JSON.stringify({ status: "current", config: read(), migrated: false }),
+            status: "success",
+          };
+        }
+        const exp = args.expected_hash !== undefined ? args.expected_hash : args.expectedHash;
+        const cur = shaFile(cfgFile);
+        if (exp !== undefined && exp !== null && !cur.startsWith(String(exp))) {
+          return {
+            content: JSON.stringify({
+              status: "stale", written: false,
+              expected_hash: String(exp), current_hash: cur, config: read(),
+            }),
+            status: "success",
+          };
+        }
+        const updates = { ...(args || {}) };
+        for (const k of ["base_dir", "show", "expected_hash", "expectedHash"]) delete updates[k];
+        const next = { ...read(), ...updates };
+        fs.writeFileSync(cfgFile, JSON.stringify(next, null, 2));
+        return {
+          content: JSON.stringify({ status: "updated", config: next, hash: shaFile(cfgFile) }),
+          status: "success",
+        };
+      };
+      impl.calls = calls;
+      return impl;
+    }
+    """
+
+    def test_fallback_write_then_get_refreshes_mirror(self):
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            cfg = research / "config.json"
+            cfg.write_text(json.dumps({"mode": "research"}), encoding="utf-8")
+            res = run_node(
+                PHASE3_HOST
+                + self.FILE_BACKED
+                + f"""
+                const cfgFile = {str(cfg)!r};
+                const box = makePhase3Host({tmp!r});
+                const callMcp = makeFileBackedMcp(cfgFile);
+                const emitted = [];
+                const handlers = createSettingsHandlers({{
+                  root: {tmp!r},
+                  callMcpImpl: callMcp,
+                  storage: box.host.storage,
+                  emitChanged: async (data) => {{ emitted.push(data); }},
+                }});
+                const ctx = rpcCtx();
+                // 1. RPC-leg write: mirror holds the written snapshot.
+                await handlers.set({{ updates: {{ mode: "audit" }} }}, ctx);
+                const afterSet = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+                // 2. Fallback-leg write: direct-fs, bypassing RPC and the mirror
+                // (exactly what the degraded TUI path does via config-io.js).
+                fs.writeFileSync(cfgFile, JSON.stringify({{ mode: "scout" }}, null, 2));
+                const staleMirror = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+                // 3. Next server-mediated read: disk truth + converged mirror.
+                const got = await handlers.get({{}}, ctx);
+                const converged = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+                console.log(JSON.stringify({{
+                  mirrorAfterSet: afterSet && afterSet.config.mode,
+                  mirrorWasStale: staleMirror && staleMirror.config.mode,
+                  gotMode: got.config.mode,
+                  gotHash: got.hash,
+                  diskHash: shaFile(cfgFile),
+                  mirrorMode: converged && converged.config.mode,
+                  mirrorHash: converged && converged.hash,
+                  extraEmits: emitted.length,
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, res.stderr)
+            d = last_json_object(res.stdout)
+            self.assertEqual(d["mirrorAfterSet"], "audit")
+            # The test is not vacuous: the mirror genuinely lagged disk.
+            self.assertEqual(d["mirrorWasStale"], "audit")
+            # The read returns disk truth and the mirror converges to it.
+            self.assertEqual(d["gotMode"], "scout")
+            self.assertEqual(d["gotHash"], d["diskHash"])
+            self.assertEqual(d["mirrorMode"], "scout")
+            self.assertEqual(d["mirrorHash"], d["diskHash"])
+            # Convergence emits nothing: `changed` fires on writes, not reads.
+            self.assertEqual(d["extraEmits"], 1)
+
+
+class TestSingleReadSnapshot(unittest.TestCase):
+    """Phase-03 R5: no era mixing — config, hash, and mirror are one snapshot.
+
+    Torn-race repro (qa-b section E shape): the Python payload is built from
+    era-A bytes while the disk is mutated to era-B mid-call. The handler must
+    return a coherent pair from a single disk read — an era-A config with an
+    era-B hash must be impossible.
+    """
+
+    def test_torn_race_cannot_mix_eras(self):
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            research = Path(tmp) / ".research"
+            research.mkdir()
+            cfg = research / "config.json"
+            era_a = {"mode": "scout"}
+            era_b = {"mode": "audit"}
+            cfg.write_text(json.dumps(era_a), encoding="utf-8")
+            res = run_node(
+                PHASE3_HOST
+                + f"""
+                import {{ createHash }} from "node:crypto";
+                import fs from "node:fs";
+                const cfgFile = {str(cfg)!r};
+                const shaBytes = (b) => createHash("sha256").update(b).digest("hex");
+                const bytesA = fs.readFileSync(cfgFile);
+                const box = makePhase3Host({tmp!r});
+                // Payload built from era-A bytes; disk mutated to era-B while
+                // the "Python surface" is in flight.
+                const callMcp = async () => {{
+                  await new Promise((r) => setTimeout(r, 15));
+                  fs.writeFileSync(cfgFile, JSON.stringify({json.dumps(era_b)}, null, 2));
+                  return {{
+                    content: JSON.stringify({{
+                      status: "current",
+                      config: JSON.parse(String(bytesA)),
+                      migrated: false,
+                    }}),
+                    status: "success",
+                  }};
+                }};
+                const handlers = createSettingsHandlers({{
+                  root: {tmp!r},
+                  callMcpImpl: callMcp,
+                  storage: box.host.storage,
+                }});
+                const got = await handlers.get({{}}, rpcCtx());
+                const mirror = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+                const bytesB = fs.readFileSync(cfgFile);
+                console.log(JSON.stringify({{
+                  gotMode: got.config.mode,
+                  gotHash: got.hash,
+                  shaA: shaBytes(bytesA),
+                  shaB: shaBytes(bytesB),
+                  mirrorMode: mirror && mirror.config.mode,
+                  mirrorHash: mirror && mirror.hash,
+                }}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, res.stderr)
+            d = last_json_object(res.stdout)
+            # Coherence: the pair matches exactly one era — never scout+shaB.
+            coherent = (d["gotMode"], d["gotHash"]) in (
+                ("scout", d["shaA"]),
+                ("audit", d["shaB"]),
+            )
+            self.assertTrue(
+                coherent,
+                f"era mixing: mode={d['gotMode']} hash matches neither era",
+            )
+            self.assertFalse(
+                d["gotMode"] == "scout" and d["gotHash"] == d["shaB"],
+                "era-A config with era-B hash",
+            )
+            # The mirror converges to the same coherent pair.
+            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."""
+
+    def test_spawn_enoent_never_leaks_internals(self):
+        res = run_node(
+            PHASE3_HOST
+            + """
+            const box = makePhase3Host("/tmp/oc-r4b-enoent");
+            const throwing = async () => {
+              const err = new Error("spawn python3 ENOENT");
+              err.code = "ENOENT";
+              throw err;
+            };
+            const garbage = async () => ({ content: "garbage{{{not json", status: "error" });
+            const results = [];
+            for (const impl of [throwing, garbage]) {
+              const handlers = createSettingsHandlers({
+                root: "/tmp/oc-r4b-enoent",
+                callMcpImpl: impl,
+                storage: box.host.storage,
+              });
+              try {
+                await handlers.get({}, rpcCtx());
+                results.push({ threw: false });
+              } catch (e) {
+                results.push({
+                  threw: true,
+                  code: e.code || null,
+                  leaksEnoent: String(e.message).includes("ENOENT"),
+                  leaksRaw: String(e.message).includes("garbage"),
+                });
+              }
+            }
+            const mirror = await box.host.storage.get(SETTINGS_STORAGE_KEY);
+            console.log(JSON.stringify({
+              results,
+              mirror: mirror === undefined ? null : mirror,
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        for r in d["results"]:
+            self.assertTrue(r["threw"])
+            self.assertEqual(r["code"], "SETTINGS_RPC_UNAVAILABLE")
+            self.assertFalse(r["leaksEnoent"])
+            self.assertFalse(r["leaksRaw"])
+        # Fail-closed: nothing was mirrored on a failed read.
+        self.assertIsNone(d["mirror"])
+
+
+class TestSetLegSanitizedErrors(unittest.TestCase):
+    """Phase-03 R7/R9: `set` failure payloads carry no tracebacks/paths.
+
+    R9 de-circularization: the fixtures and the expected sanitized strings are
+    INDEPENDENT of the sanitizer's implementation — there is no shared regex
+    here. The fixtures are real interpreter stderr (any POSIX root),
+    Windows-drive and UNC paths, a `File "…", line N` frame, and a clean schema
+    message; the mixed list proves PER-ITEM sanitization (the pre-R9
+    all-or-nothing `list.every` would collapse the whole list to one reason).
+    """
+
+    FIXED = (
+        "Config write rejected: canonical config surface returned an "
+        "unreadable failure."
+    )
+    CLEAN = "mode: value 'nope' not in enum ['research', 'audit']"
+
+    def test_set_failure_payload_sweep(self):
+        res = run_node(
+            PHASE3_HOST
+            + r"""
+            const box = makePhase3Host("/tmp/oc-r9-sweep");
+            const fixtures = {
+              posixStderr: "python3: can't open file '/workspace/nope/runner/mcp_server.py': [Errno 2] No such file or directory",
+              windowsDrive: "C:\\Users\\x\\AppData\\Local\\Temp\\iumbtems\\config.json",
+              uncShare: "\\\\fileserver\\share\\iumbtems\\config.json",
+              fileLine: '  File "/srv/app/runner/mcp_server.py", line 42, in _handle_config',
+              cleanEnum: "mode: value 'nope' not in enum ['research', 'audit']",
+            };
+            const call = async (impl) => {
+              const handlers = createSettingsHandlers({
+                root: "/tmp/oc-r9-sweep",
+                callMcpImpl: impl,
+                storage: box.host.storage,
+              });
+              try {
+                await handlers.set({ updates: { mode: "scout" } }, rpcCtx());
+                return { threw: false };
+              } catch (e) {
+                const data = e.data || e.rpcData || {};
+                return { threw: true, type: e.type || e.rpcType || null, written: data.written, errors: data.errors || null };
+              }
+            };
+            const listImpl = (items) => async () => ({
+              content: JSON.stringify({ status: "error", code: "CONFIG_VALIDATION_FAILED", written: false, errors: items }),
+              status: "success",
+            });
+            const rawImpl = (text) => async () => ({ content: text, status: "error" });
+            const out = {};
+            out.posixStderr = await call(listImpl([fixtures.posixStderr]));
+            out.windowsDrive = await call(listImpl([fixtures.windowsDrive]));
+            out.uncShare = await call(listImpl([fixtures.uncShare]));
+            out.fileLine = await call(listImpl([fixtures.fileLine]));
+            out.cleanEnum = await call(listImpl([fixtures.cleanEnum]));
+            out.mixed = await call(listImpl([fixtures.cleanEnum, fixtures.posixStderr]));
+            out.rawStderr = await call(rawImpl(fixtures.posixStderr));
+            console.log(JSON.stringify(out));
+            """
+        )
+        self.assertEqual(res.returncode, 0, res.stderr)
+        d = last_json_object(res.stdout)
+        # Every leaking fixture (JSON error list or raw non-JSON stderr) is
+        # replaced by the fixed reason, and nothing is written.
+        for name in (
+            "posixStderr",
+            "windowsDrive",
+            "uncShare",
+            "fileLine",
+            "rawStderr",
+        ):
+            self.assertTrue(d[name]["threw"], name)
+            self.assertEqual(d[name]["type"], "invalid", name)
+            self.assertFalse(d[name]["written"], name)
+            self.assertEqual(d[name]["errors"], [self.FIXED], name)
+        # A clean schema message passes through untouched (no over-sanitization).
+        self.assertTrue(d["cleanEnum"]["threw"])
+        self.assertEqual(d["cleanEnum"]["errors"], [self.CLEAN])
+        # PER-ITEM: the clean entry survives while only the leaking entry is
+        # replaced (the pre-R9 list.every would have returned just [FIXED]).
+        self.assertEqual(d["mixed"]["errors"], [self.CLEAN, self.FIXED])
+
+
 if __name__ == "__main__":
     unittest.main()