@heretek-ai/epistemic-swarm 0.7.19 → 0.7.21

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.19",
+  "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.19",
+  "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.19",
+  "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/config-io.js

@@ -429,6 +429,7 @@ export const FALLBACK_DEFAULTS = {
   },
   opencode_auto: null,
   opencode_agent: null,
+  mcp_servers: {},
 };
 
 /** Effective defaults, derived from the schema `default` keywords. */
@@ -589,6 +590,58 @@ export function isConfigMalformed(baseDir = DEFAULT_RESEARCH_DIR) {
   }
 }
 
+/**
+ * Single-read snapshot of the config file (phase-03 R5): the raw bytes are
+ * read EXACTLY ONCE; `hash` is computed over those bytes and `raw` is parsed
+ * from those bytes, so a config parsed from one era can never pair with a
+ * hash of another. `malformed` is true when bytes exist but are not a JSON
+ * object. Never throws, never writes, never creates directories.
+ */
+export function readConfigSnapshot(baseDir = DEFAULT_RESEARCH_DIR) {
+  try {
+    const bytes = readBytes(getConfigPath(baseDir));
+    if (!bytes) return { hash: null, raw: null, malformed: false };
+    let hash = null;
+    try {
+      hash = createHash('sha256').update(bytes).digest('hex');
+    } catch {
+      hash = null;
+    }
+    const raw = parseJsonObject(bytes);
+    return { hash, raw, malformed: raw === null };
+  } catch {
+    return { hash: null, raw: null, malformed: false };
+  }
+}
+
+/**
+ * Effective config merged over defaults from an already-parsed raw object —
+ * the no-reread half of `loadConfig` (identical merge, migration, and
+ * fallback semantics; the caller owns the bytes). Never throws.
+ */
+export function loadConfigFromRaw(raw) {
+  try {
+    const base = configDefaults();
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return base;
+    const merged = { ...base, ...deepCopy(raw) };
+    merged.agents = mergeAgents(base.agents, raw.agents);
+    if (
+      raw.verify && typeof raw.verify === 'object' && !Array.isArray(raw.verify) &&
+      base.verify && typeof base.verify === 'object' && !Array.isArray(base.verify)
+    ) {
+      merged.verify = { ...base.verify, ...deepCopy(raw.verify) };
+    }
+    migrateLegacyAgentBackends(merged);
+    return merged;
+  } catch {
+    try {
+      return deepCopy(FALLBACK_DEFAULTS);
+    } catch {
+      return {};
+    }
+  }
+}
+
 /**
  * Load config merged over defaults. Pure — never writes. Applies the
  * legacy-pin migration in memory; unknown keys are preserved verbatim.
@@ -596,7 +649,6 @@ export function isConfigMalformed(baseDir = DEFAULT_RESEARCH_DIR) {
  */
 export function loadConfig(baseDir = DEFAULT_RESEARCH_DIR) {
   try {
-    const base = configDefaults();
     const raw = readRawConfig(baseDir);
     if (!raw) {
       if (isConfigMalformed(baseDir)) {
@@ -609,18 +661,9 @@ export function loadConfig(baseDir = DEFAULT_RESEARCH_DIR) {
           /* logging must never throw */
         }
       }
-      return base;
+      return configDefaults();
     }
-    const merged = { ...base, ...deepCopy(raw) };
-    merged.agents = mergeAgents(base.agents, raw.agents);
-    if (
-      raw.verify && typeof raw.verify === 'object' && !Array.isArray(raw.verify) &&
-      base.verify && typeof base.verify === 'object' && !Array.isArray(base.verify)
-    ) {
-      merged.verify = { ...base.verify, ...deepCopy(raw.verify) };
-    }
-    migrateLegacyAgentBackends(merged);
-    return merged;
+    return loadConfigFromRaw(raw);
   } catch {
     try {
       return deepCopy(FALLBACK_DEFAULTS);