@heretek-ai/epistemic-swarm 0.4.1 → 0.4.2

package/.claude-plugin/plugin.json

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

package/install.sh

@@ -109,10 +109,98 @@ except Exception as e:
 EOF
 fi
 
+# 5. OpenCode V2 integration (plugin tuple, agents, MCP server — merge only)
+OPENCODE_JSON="$HOME/.config/opencode/opencode.json"
+echo "🔧 Merging OpenCode V2 configuration into $OPENCODE_JSON..."
+python3 - <<EOF
+import json
+from pathlib import Path
+
+repo = Path("$REPO_DIR")
+oc_path = Path("$OPENCODE_JSON")
+PKG = "@heretek-ai/epistemic-swarm"
+OPTION_KEYS = {"search_engine", "max_iterations", "mode", "divergence_threshold"}
+
+oc_path.parent.mkdir(parents=True, exist_ok=True)
+cfg = json.loads(oc_path.read_text(encoding="utf-8")) if oc_path.exists() else {}
+
+# --- plugin entry: tuple form [package, options]; repair bare-object form ---
+plugins = cfg.get("plugin", [])
+if not isinstance(plugins, list):
+    print("   ⚠️ 'plugin' is not a list; leaving untouched")
+    plugins = cfg.get("plugin", [])
+else:
+    repaired = []
+    i = 0
+    changed = False
+    while i < len(plugins):
+        item = plugins[i]
+        # Bare options object following our package string (or standalone):
+        # fold into a tuple instead of leaving an invalid entry.
+        if isinstance(item, dict) and set(item) & OPTION_KEYS:
+            prev_is_pkg = repaired and repaired[-1] == PKG
+            prev_is_tuple = (
+                repaired and isinstance(repaired[-1], list)
+                and repaired[-1] and repaired[-1][0] == PKG
+            )
+            if prev_is_pkg:
+                repaired[-1] = [PKG, item]
+                changed = True
+                print("   ~ Repaired bare options object into tuple entry")
+            elif prev_is_tuple:
+                merged = {**(repaired[-1][1] if len(repaired[-1]) > 1 else {}), **item}
+                repaired[-1] = [PKG, merged]
+                changed = True
+                print("   ~ Folded stray options into existing tuple entry")
+            else:
+                repaired.append([PKG, item])
+                changed = True
+                print("   ~ Attached stray options object to new tuple entry")
+        else:
+            repaired.append(item)
+        i += 1
+    if not any((p == PKG or (isinstance(p, list) and p and p[0] == PKG)) for p in repaired):
+        repaired.append([PKG, {"search_engine": "duckduckgo", "max_iterations": 2, "mode": "research"}])
+        changed = True
+        print(f"   + Added plugin entry: {PKG}")
+    else:
+        print(f"   ℹ️ Plugin entry already configured: {PKG}")
+    cfg["plugin"] = repaired
+
+# --- agents: merge snippet definitions, never overwrite user agents ---
+try:
+    snippet = json.loads((repo / "config" / "opencode-snippet.json").read_text(encoding="utf-8"))
+    agents = cfg.setdefault("agent", {})
+    for name, definition in snippet.get("agent", {}).items():
+        if name not in agents:
+            agents[name] = definition
+            print(f"   + Added agent: {name}")
+        else:
+            print(f"   ℹ️ Agent already configured: {name}")
+except Exception as e:
+    print(f"   ⚠️ Non-critical warning merging agents: {e}")
+
+# --- MCP server: absolute runner path (relative paths only work at repo root) ---
+mcp = cfg.setdefault("mcp", {})
+if "iumbtems" not in mcp:
+    mcp["iumbtems"] = {
+        "type": "local",
+        "command": ["python3", str(repo / "runner" / "mcp_server.py")],
+        "enabled": True,
+    }
+    print("   + Added MCP server: iumbtems")
+else:
+    print("   ℹ️ MCP server already configured: iumbtems")
+
+oc_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+print("✅ OpenCode configuration updated.")
+EOF
+
 echo ""
 echo "🎉 Epistemic Swarm installation complete!"
 echo "   - Interactive Grilling: run /grilling inside Claude Code"
 echo "   - Lateral Brainstorming: run /brainstorming inside Claude Code (skills/brainstorming)"
+echo "   - OpenCode V2: /swarm /grill /audit /scout /brainstorming via plugin commands"
 echo "   - Rebuild harness adapters: python3 scripts/build_adapters.py"
 echo "   - Headless Research Swarm: npx @heretek-ai/epistemic-swarm run \"<objective>\""
 echo "========================================================"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {
@@ -11,12 +11,17 @@
     ".": "./bin/cli.js",
     "./opencode": "./plugins/opencode/index.js",
     "./server": "./plugins/opencode/index.js",
+    "./tui": "./plugins/opencode/tui.js",
     "./pi": "./extensions/pi/index.js",
     "./omp": "./extensions/pi/index.js"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "solid-js": "1.9.12",
+    "@opentui/solid": ">=0.4.0 <0.6.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Heretek-AI/IUMBTEMS.git"

package/plugins/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for AntiGravity.",
   "author": "Heretek AI",
   "license": "Apache-2.0",

package/plugins/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for Gemini CLI.",
   "mcpServers": {
     "brave-search": {

package/plugins/opencode/index.js

@@ -234,7 +234,7 @@ const TOOL_CATALOG = [
       properties: {
         base_dir: {
           type: 'string',
-          description: 'Path to .research workspace',
+          description: 'Path to .research workspace (default: current directory)',
         },
       },
     },
@@ -249,7 +249,7 @@ const TOOL_CATALOG = [
         hash: { type: 'string', description: 'Content-addressed SHA-256 of the affected source' },
         event: { type: 'string', enum: ['RETRACTED', 'REVISED'] },
         note: { type: 'string', description: 'Why the source was retracted/revised' },
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
       },
       required: ['hash', 'event'],
     },
@@ -261,7 +261,7 @@ const TOOL_CATALOG = [
     input: {
       type: 'object',
       properties: {
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
         scope_ids: {
           type: 'array',
           items: { type: 'string' },
@@ -278,7 +278,7 @@ const TOOL_CATALOG = [
       type: 'object',
       properties: {
         pack: { type: 'string', description: 'Pack id: biopharma | quant | legal (or a path)' },
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
       },
       required: ['pack'],
     },
@@ -290,11 +290,11 @@ const TOOL_CATALOG = [
     input: {
       type: 'object',
       properties: {
-        base_dir: { type: 'string' },
+        base_dir: { type: 'string', description: 'Path to .research workspace (default: current directory)' },
         out: { type: 'string', description: 'Output path (default <base_dir>/brief.pcrb.json)' },
-        objective: { type: 'string' },
+        objective: { type: 'string', description: 'Research objective the brief must cover' },
         key: { type: 'string', description: 'HMAC key (prefer key_file or env IUMBTEMS_PCRB_KEY)' },
-        key_file: { type: 'string' },
+        key_file: { type: 'string', description: 'Path to file containing the HMAC key' },
       },
     },
   },
@@ -306,8 +306,8 @@ const TOOL_CATALOG = [
       type: 'object',
       properties: {
         brief: { type: 'string', description: 'Path to brief.pcrb.json' },
-        key: { type: 'string' },
-        key_file: { type: 'string' },
+        key: { type: 'string', description: 'HMAC key (prefer key_file or env IUMBTEMS_PCRB_KEY)' },
+        key_file: { type: 'string', description: 'Path to file containing the HMAC key' },
       },
       required: ['brief'],
     },
@@ -337,6 +337,271 @@ function normalizeArgs(tool, args = {}) {
   return a;
 }
 
+/**
+ * OpenCode slash-command catalog (Phase A discoverability).
+ *
+ * Mirrors the Pi/OMP/Gemini command surface. Each entry registers into
+ * `config.command[name] = {description, template}` via the server `config`
+ * hook (same pattern as @prevalentware/opencode-goal-plugin). `$ARGUMENTS`
+ * is the raw text after the slash command. Templates instruct the agent to
+ * call the corresponding canonical `iumbtems_*` tool — commands never
+ * reimplement tool logic.
+ */
+export const OPENCODE_COMMANDS = [
+  {
+    name: 'swarm',
+    description: 'Run IUMBTEMS dialectic research swarm on an objective',
+    template: [
+      'Run an IUMBTEMS dialectic research swarm.',
+      'Objective: $ARGUMENTS',
+      '1. If the objective is ambiguous, frame it first via iumbtems_socratic_frontier.',
+      '2. Execute iumbtems_swarm_research with {"objective": "<objective>"} (pass "mock_mode": true only for dry runs).',
+      '3. Summarize .research/final_synthesis.md, preserving [VERIFIED:<hash>] pointers.',
+    ].join('\n'),
+  },
+  {
+    name: 'grill',
+    description: 'Launch Socratic grilling and decision tree frontier exploration',
+    template: [
+      'Launch Socratic grilling on the decision frontier.',
+      'Objective: $ARGUMENTS (may be empty to inspect the current frontier)',
+      'Call iumbtems_socratic_frontier with {"objective": "<objective>", "file": ".research/frontier.json"}; omit "objective" to inspect.',
+      'Challenge premises, invert assumptions, and report open frontier nodes.',
+    ].join('\n'),
+  },
+  {
+    name: 'swarm-config',
+    description: 'Inspect or update Epistemic Swarm parameters (engine, depth, mode)',
+    template: [
+      'Inspect or update the Epistemic Swarm configuration.',
+      'Arguments: $ARGUMENTS (may be empty to inspect current settings)',
+      'Call iumbtems_config; map --engine/--depth/--mode/--show style flags to search_engine/max_iterations/mode, or pass through no arguments to inspect.',
+    ].join('\n'),
+  },
+  {
+    name: 'audit',
+    description: 'Run dialectic codebase architectural and security audit with line-level proof',
+    template: [
+      'Run an IUMBTEMS dialectic codebase audit (structural architect vs adversarial red-teamer).',
+      'Target: $ARGUMENTS (path, component, or empty for full-repository architecture and vulnerability audit)',
+      '1. Execute iumbtems_code_audit with {"target": "<target>"} (pass "mock_mode": true only for dry runs).',
+      '2. Summarize .research/code_audit_report.md with line-level proof pointers.',
+    ].join('\n'),
+  },
+  {
+    name: 'scout',
+    description: 'Scout open-source libraries, audit copyleft licenses, generate clean-room blueprints',
+    template: [
+      'Scout open-source solutions for the requested capability.',
+      'Feature: $ARGUMENTS',
+      '1. Execute iumbtems_oss_scout with {"feature": "<feature>"} (pass "mock_mode": true only for dry runs).',
+      '2. Report mature candidates, GPL/AGPL copyleft risks, and the clean-room blueprint in .research/oss_scout_report.md.',
+    ].join('\n'),
+  },
+  {
+    name: 'brainstorming',
+    description: 'Lateral brainstorming: novel feature vectors, paradigm inversions, falsifiable spikes',
+    template: [
+      'Run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
+      'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
+      '1. Execute iumbtems_brainstorm with {"objective": "<prompt>"} (pass "mock_mode": true only for dry runs).',
+      '2. Report novel feature vectors, paradigm inversions, and falsifiable spikes from .research/brainstorm_report.md.',
+    ].join('\n'),
+  },
+  {
+    name: 'brainstorm',
+    description: 'Alias for /brainstorming',
+    template: [
+      'Alias for /brainstorming: run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
+      'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
+      'Execute iumbtems_brainstorm with {"objective": "<prompt>"} and report feature vectors, paradigm inversions, and falsifiable spikes.',
+    ].join('\n'),
+  },
+];
+
+/**
+ * Register the command catalog into an OpenCode config object without
+ * overwriting user-defined commands of the same name. Exported for tests.
+ */
+export function registerOpenCodeCommands(cfg = {}) {
+  cfg.command ??= {};
+  for (const cmd of OPENCODE_COMMANDS) {
+    if (cfg.command[cmd.name]) continue;
+    cfg.command[cmd.name] = { description: cmd.description, template: cmd.template };
+  }
+  return cfg;
+}
+
+/** Tool map (object form) for the server hook; array catalog stays canonical. */
+function buildToolMap() {
+  return Object.fromEntries(
+    TOOL_CATALOG.map((tool) => [
+      tool.name,
+      {
+        ...tool,
+        options: { codemode: false },
+        execute: async (args = {}, toolContext) =>
+          callMcp(tool.name, normalizeArgs(tool.name, args), toolContext?.cwd),
+      },
+    ])
+  );
+}
+
+/**
+ * Phase C retention: session lifecycle hooks.
+ *
+ * Reference pattern: @prevalentware/opencode-goal-plugin subscribes via
+ * `context.event.subscribe({signal})`, detects idle as `session.idle` or an
+ * idle `session.status`, continues via `context.session.prompt`, and preserves
+ * state across compaction with the `experimental.session.compacting` hook.
+ * Every hook here is best-effort and never throws into the host.
+ */
+
+/** Idle detection matching the reference implementation. Exported for tests. */
+export function isIdleEvent(event) {
+  if (!event || typeof event.type !== 'string') return false;
+  if (event.type === 'session.idle') return true;
+  const status = event.properties?.status;
+  return (
+    event.type === 'session.status' &&
+    typeof status === 'object' &&
+    status !== null &&
+    status.type === 'idle'
+  );
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Last-write-wins degraded claims + requeue list. Pure fs reads. */
+export function readLedgerDegraded(root) {
+  const out = { stale: [], suspect: [], requeued: [], fingerprint: 'empty' };
+  try {
+    const ledger = readJsonFile(path.join(root, '.research', 'ledger', 'claim_status.json'));
+    if (Array.isArray(ledger)) {
+      const last = new Map();
+      for (const e of ledger) {
+        if (e && typeof e.claim_id === 'string') last.set(e.claim_id, e.to_status);
+      }
+      for (const [id, s] of last) {
+        if (s === 'STALE') out.stale.push(id);
+        else if (s === 'SUSPECT') out.suspect.push(id);
+      }
+      const lastAt = ledger.length > 0 ? ledger[ledger.length - 1]?.at : '';
+      out.fingerprint = `${ledger.length}:${lastAt}`;
+    }
+    const requeue = readJsonFile(path.join(root, '.research', 'requeue.json'));
+    if (Array.isArray(requeue)) {
+      out.requeued = requeue.map((e) => e?.scope_id).filter((s) => typeof s === 'string');
+    }
+  } catch {
+    /* unreadable workspace -> no degraded claims */
+  }
+  return out;
+}
+
+/**
+ * Compaction context preserving .research state. Returns null when there is
+ * no workspace (hook then pushes nothing).
+ */
+export function buildCompactionContext(root) {
+  try {
+    const cfg = readJsonFile(path.join(root, '.research', 'config.json'));
+    if (!cfg || typeof cfg !== 'object') return null;
+    const degraded = readLedgerDegraded(root);
+    const lines = [
+      'IUMBTEMS Epistemic Swarm workspace state (preserved across compaction):',
+      `- mode=${cfg.mode ?? '?'} engine=${cfg.search_engine ?? '?'} depth=${cfg.max_iterations ?? '?'}`,
+      `- degraded claims: ${degraded.stale.length} STALE, ${degraded.suspect.length} SUSPECT`,
+    ];
+    if (degraded.stale.length > 0) {
+      lines.push(`- STALE claim ids: ${degraded.stale.slice(0, 10).join(', ')}`);
+    }
+    if (degraded.requeued.length > 0) {
+      lines.push(`- scopes queued for re-run: ${degraded.requeued.slice(0, 10).join(', ')}`);
+    }
+    lines.push('- Continue with iumbtems_check_staleness when resuming audit work.');
+    return lines.join('\n');
+  } catch {
+    return null;
+  }
+}
+
+const NUDGE_MIN_INTERVAL_MS = 5 * 60 * 1000;
+const activeNudges = new Map();
+
+/**
+ * Handle one subscribed event: nudge once per ledger change when degraded
+ * claims exist. Returns true when a nudge was sent. Exported for tests.
+ */
+export function handleIdleEvent(host, root, state, event) {
+  try {
+    if (!isIdleEvent(event)) return false;
+    const sessionID = event?.properties?.sessionID ?? event?.sessionID;
+    if (typeof sessionID !== 'string' || !sessionID) return false;
+    const now = Date.now();
+    if (now - (state.lastNudgeAt || 0) < NUDGE_MIN_INTERVAL_MS) return false;
+    const degraded = readLedgerDegraded(root);
+    const total = degraded.stale.length + degraded.suspect.length;
+    if (total === 0) return false;
+    if (state.lastFingerprint === degraded.fingerprint) return false;
+    state.lastFingerprint = degraded.fingerprint;
+    state.lastNudgeAt = now;
+    const example = degraded.stale.slice(0, 5).join(', ');
+    Promise.resolve(
+      host.session.prompt({
+        sessionID,
+        text:
+          `IUMBTEMS staleness nudge: ${total} degraded claim(s) ` +
+          `(${degraded.stale.length} STALE, ${degraded.suspect.length} SUSPECT) in .research/ledger/claim_status.json` +
+          (example ? `, e.g. ${example}` : '') +
+          '. Run iumbtems_check_staleness and re-audit affected scopes, or reply that it is already handled.',
+      })
+    ).catch(() => {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Subscribe to session events for idle nudges. One subscription per root. */
+export function startStalenessNudge(host, root) {
+  try {
+    if (!host || typeof host.event?.subscribe !== 'function') return null;
+    if (typeof host.session?.prompt !== 'function') return null;
+    if (activeNudges.has(root)) return activeNudges.get(root).stop;
+    const abort = new AbortController();
+    const state = { lastFingerprint: null, lastNudgeAt: 0 };
+    const stop = () => {
+      try { abort.abort(); } catch { /* noop */ }
+      activeNudges.delete(root);
+    };
+    activeNudges.set(root, { stop });
+    (async () => {
+      try {
+        const sub = host.event.subscribe({ signal: abort.signal });
+        const it = sub[Symbol.asyncIterator]();
+        while (true) {
+          const { value, done } = await it.next();
+          if (done) break;
+          handleIdleEvent(host, root, state, value);
+        }
+      } catch {
+        /* aborted or host closed the stream */
+      }
+      activeNudges.delete(root);
+    })();
+    return stop;
+  } catch {
+    return null;
+  }
+}
+
 export function createOpenCodePlugin(context = {}) {
   return {
     id: 'heretek.iumbtems.epistemic-swarm',
@@ -345,13 +610,24 @@ export function createOpenCodePlugin(context = {}) {
     description:
       'I Use My Brain To Express My Self: High-integrity dialectic research, code audits, and open-source scouting',
 
-    server: (toolContext) =>
-      TOOL_CATALOG.map((tool) => ({
-        ...tool,
-        options: { codemode: false },
-        execute: async (args = {}) =>
-          callMcp(tool.name, normalizeArgs(tool.name, args), toolContext?.cwd),
-      })),
+    server: async () => ({
+      // Config hook: slash-command catalog (mirrors the goal plugin's
+      // registerDesktopCommands pattern; never overwrites user commands).
+      config: (cfg) => registerOpenCodeCommands(cfg),
+      // Tool map (object form, as in the reference implementation).
+      tool: buildToolMap(),
+      // Compaction hook: preserve .research state (best-effort, silent skip
+      // when no workspace is present so compaction never breaks).
+      'experimental.session.compacting': async (input, output) => {
+        try {
+          const root = input?.directory ?? input?.location?.directory ?? process.cwd();
+          const ctx = buildCompactionContext(root);
+          if (ctx && output && Array.isArray(output.context)) output.context.push(ctx);
+        } catch {
+          /* never break compaction */
+        }
+      },
+    }),
 
     setup: async (appContext) => {
       const opts = context.options || appContext?.options;
@@ -367,6 +643,21 @@ export function createOpenCodePlugin(context = {}) {
           callMcp('iumbtems_config', updates, appContext?.cwd);
         }
       }
+      // Phase C: idle staleness nudge (opt out with {staleness_nudge: false}).
+      // Subscribes only when the host exposes event/session; one per root.
+      try {
+        if ((opts?.staleness_nudge ?? true)) {
+          const host = {
+            event: appContext?.event || context.event,
+            session: appContext?.session || context.session,
+          };
+          const root =
+            appContext?.location?.directory || context.location?.directory;
+          if (root) startStalenessNudge(host, root);
+        }
+      } catch {
+        /* lifecycle hooks are best-effort */
+      }
       return { initialized: true, platform: 'opencode-v2' };
     },
   };

package/plugins/opencode/tui.js

@@ -0,0 +1,247 @@
+/**
+ * IUMBTEMS Epistemic Swarm — OpenCode TUI surface (Phase B visibility).
+ *
+ * Sidebar status panel + command-palette entry. Read-only: pure `fs` reads of
+ * the `.research` workspace (config, report inventory, frontier open nodes,
+ * claim-status ledger). Never spawns processes, never writes. Every read is
+ * defensive — an absent workspace renders as "no swarm state", never throws.
+ *
+ * Host API mirrors @prevalentware/opencode-goal-plugin's V2 TUI usage:
+ * `ui.slot({append, render})`, `ui.toast.show`, `ui.router.current`,
+ * `keymap.layer` (inside a component scope), `api.theme`.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'fs';
+import path from 'path';
+import { createElement, insert, setProp } from '@opentui/solid';
+import { createEffect, createSignal, onCleanup } from 'solid-js';
+
+const PLUGIN_ID = 'heretek.iumbtems.epistemic-swarm.tui';
+const REFRESH_MS = 5000;
+
+function element(tag, props = {}, children = []) {
+  const node = createElement(tag);
+  for (const [key, value] of Object.entries(props)) {
+    if (value !== undefined) setProp(node, key, value);
+  }
+  for (const child of children) {
+    if (child !== null && child !== undefined && child !== false) insert(node, child);
+  }
+  return node;
+}
+
+function text(props, children) {
+  return element('text', props, children);
+}
+
+function box(props, children = []) {
+  return element('box', props, children);
+}
+
+function readJson(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Snapshot the workspace status. Pure fs reads; safe on missing workspace.
+ * Exported for tests.
+ */
+export function readSwarmStatus(root) {
+  const research = path.join(root || process.cwd(), '.research');
+  const status = {
+    workspace: false,
+    mode: null,
+    searchEngine: null,
+    maxIterations: null,
+    reports: [],
+    frontierOpen: null,
+    stale: 0,
+    suspect: 0,
+    requeued: 0,
+  };
+  let entries = [];
+  try {
+    entries = readdirSync(research);
+    status.workspace = true;
+  } catch {
+    return status;
+  }
+  const cfg = readJson(path.join(research, 'config.json'));
+  if (cfg && typeof cfg === 'object') {
+    status.mode = cfg.mode ?? null;
+    status.searchEngine = cfg.search_engine ?? null;
+    status.maxIterations = cfg.max_iterations ?? null;
+  }
+  for (const name of [
+    'final_synthesis.md',
+    'brainstorm_report.md',
+    'code_audit_report.md',
+    'oss_scout_report.md',
+  ]) {
+    try {
+      const st = statSync(path.join(research, name));
+      status.reports.push({ name, mtimeMs: st.mtimeMs });
+    } catch {
+      /* absent report */
+    }
+  }
+  const frontier = readJson(path.join(research, 'frontier.json'));
+  if (frontier && typeof frontier === 'object') {
+    const nodes = Array.isArray(frontier.nodes) ? frontier.nodes : Object.values(frontier.nodes || {});
+    const open = nodes.filter((n) => n && n.status !== 'settled' && n.status !== 'closed');
+    status.frontierOpen = open.length;
+  }
+  const ledger = readJson(path.join(research, 'ledger', 'claim_status.json'));
+  if (Array.isArray(ledger)) {
+    const last = new Map();
+    for (const e of ledger) {
+      if (e && typeof e.claim_id === 'string') last.set(e.claim_id, e.to_status);
+    }
+    for (const s of last.values()) {
+      if (s === 'STALE') status.stale += 1;
+      else if (s === 'SUSPECT') status.suspect += 1;
+    }
+  }
+  const requeue = readJson(path.join(research, 'requeue.json'));
+  if (Array.isArray(requeue)) status.requeued = requeue.length;
+  return status;
+}
+
+function themeFg(theme) {
+  try {
+    const t = theme ?? {};
+    const pick = (...paths) => {
+      for (const p of paths) {
+        let cur = t;
+        for (const k of p) {
+          if (cur === null || typeof cur !== 'object') { cur = undefined; break; }
+          cur = cur[k];
+        }
+        if (cur && typeof cur === 'object' && 'default' in cur) cur = cur.default;
+        if (cur !== undefined && cur !== null) return cur;
+      }
+      return undefined;
+    };
+    return {
+      text: pick(['text', 'default'], ['text']),
+      muted: pick(['text', 'subdued'], ['textMuted']),
+      warn: pick(['text', 'feedback', 'warning'], ['warning']),
+    };
+  } catch {
+    return {};
+  }
+}
+
+function summarize(status) {
+  if (!status.workspace) return 'IUMBTEMS: no swarm state';
+  const bits = [];
+  if (status.mode) bits.push(status.mode);
+  bits.push(`${status.reports.length} reports`);
+  if (status.frontierOpen !== null) bits.push(`${status.frontierOpen} open frontier`);
+  if (status.stale > 0 || status.suspect > 0) bits.push(`${status.stale} STALE/${status.suspect} SUSPECT`);
+  if (status.requeued > 0) bits.push(`${status.requeued} requeued`);
+  return `IUMBTEMS: ${bits.join(' · ')}`;
+}
+
+function SwarmSidebar(api, root, sessionID) {
+  const colors = themeFg(api?.theme);
+  const [snapshot, setSnapshot] = createSignal(readSwarmStatus(root));
+  createEffect(() => {
+    const timer = setInterval(() => {
+      try {
+        setSnapshot(readSwarmStatus(root));
+      } catch {
+        /* keep last snapshot */
+      }
+    }, REFRESH_MS);
+    onCleanup(() => clearInterval(timer));
+  });
+  void sessionID;
+  return box({}, [
+    () => {
+      const s = snapshot();
+      const degraded = s.stale > 0 || s.suspect > 0;
+      return text({ fg: degraded ? colors.warn : colors.muted }, [summarize(s)]);
+    },
+  ]);
+}
+
+function SwarmKeymapLayer(api) {
+  api.keymap.layer(() => ({
+    mode: 'global',
+    commands: [
+      {
+        id: 'iumbtems.swarm-status',
+        title: 'Swarm status',
+        description: 'Show IUMBTEMS workspace status (mode, reports, frontier, STALE claims)',
+        group: 'IUMBTEMS',
+        palette: true,
+        run: () => {
+          const root = resolveRoot(api);
+          api.ui.toast.show({
+            title: 'IUMBTEMS',
+            message: summarize(readSwarmStatus(root)),
+            variant: 'info',
+            duration: 4000,
+          });
+        },
+      },
+    ],
+  }));
+  return null;
+}
+
+function resolveRoot(api) {
+  try {
+    return (
+      api?.directory ??
+      api?.project?.directory ??
+      api?.cwd ??
+      process.cwd()
+    );
+  } catch {
+    return process.cwd();
+  }
+}
+
+function registerSlot(api, name, render) {
+  const slot = api?.ui?.slot;
+  if (typeof slot !== 'function') return () => {};
+  try {
+    const dispose =
+      slot.length <= 1 ? slot({ append: name, render }) : slot(name, render);
+    return typeof dispose === 'function' ? dispose : () => {};
+  } catch {
+    return () => {};
+  }
+}
+
+/** TUI setup: sidebar slot + palette command. Never throws. */
+export function setupTui(api) {
+  try {
+    const root = resolveRoot(api);
+    const offSidebar = registerSlot(api, 'sidebar.content', (props) =>
+      SwarmSidebar(api, root, props?.sessionID)
+    );
+    const offApp = registerSlot(api, 'app', () => SwarmKeymapLayer(api));
+    return () => {
+      try { offSidebar(); } catch { /* noop */ }
+      try { offApp(); } catch { /* noop */ }
+    };
+  } catch {
+    return () => {};
+  }
+}
+
+const plugin = {
+  id: PLUGIN_ID,
+  tui: true,
+  setup: setupTui,
+};
+
+export default plugin;

package/runner/tests/test_opencode_ux.py

@@ -0,0 +1,393 @@
+#!/usr/bin/env python3
+"""Tests for the OpenCode v2 end-user UX surface (goal Phase A).
+
+Covers the slash-command catalog, the server object-form contract, and
+install.sh OpenCode handling (idempotency + bare-object repair).
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+EXPECTED_COMMANDS = [
+    "swarm",
+    "grill",
+    "swarm-config",
+    "audit",
+    "scout",
+    "brainstorming",
+    "brainstorm",
+]
+
+
+def run_node(code):
+    return subprocess.run(
+        ["node", "--input-type=module", "-e", code],
+        capture_output=True,
+        text=True,
+        cwd=str(PROJECT_ROOT),
+    )
+
+
+def last_json_object(stdout):
+    lines = [l.strip() for l in stdout.strip().split("\n") if l.strip().startswith("{")]
+    return json.loads(lines[-1])
+
+
+class TestOpenCodeCommandCatalog(unittest.TestCase):
+    def test_catalog_shape_and_registration(self):
+        res = run_node(
+            """
+            import plugin, { OPENCODE_COMMANDS, registerOpenCodeCommands } from "./plugins/opencode/index.js";
+            const shell = await plugin.server();
+            const cfg = {};
+            shell.config(cfg);
+            console.log(JSON.stringify({
+              catalog: OPENCODE_COMMANDS.map(c => ({name: c.name, hasDesc: !!c.description, hasArgs: c.template.includes("$ARGUMENTS")})),
+              registered: Object.keys(cfg.command || {}),
+              templates: Object.fromEntries(Object.entries(cfg.command || {}).map(([k, v]) => [k, !!v.description && !!v.template]))
+            }));
+            """
+        )
+        self.assertEqual(
+            res.returncode, 0, f"command catalog test failed: {res.stderr}"
+        )
+        data = last_json_object(res.stdout)
+        names = [c["name"] for c in data["catalog"]]
+        for c in EXPECTED_COMMANDS:
+            self.assertIn(c, names)
+        for entry in data["catalog"]:
+            self.assertTrue(
+                entry["hasDesc"], f"command lacks description: {entry['name']}"
+            )
+            self.assertTrue(
+                entry["hasArgs"], f"template lacks $ARGUMENTS: {entry['name']}"
+            )
+        for c in EXPECTED_COMMANDS:
+            self.assertIn(c, data["registered"])
+            self.assertTrue(data["templates"][c])
+
+    def test_registration_never_overwrites(self):
+        res = run_node(
+            """
+            import { registerOpenCodeCommands } from "./plugins/opencode/index.js";
+            const cfg = {command: {swarm: {description: "mine", template: "mine"}}};
+            registerOpenCodeCommands(cfg);
+            console.log(JSON.stringify({swarm: cfg.command.swarm, count: Object.keys(cfg.command).length}));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"no-overwrite test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["swarm"], {"description": "mine", "template": "mine"})
+        self.assertEqual(data["count"], len(EXPECTED_COMMANDS))
+
+    def test_tool_map_shape(self):
+        res = run_node(
+            """
+            import plugin, { IUMBTEMS_TOOL_NAMES } from "./plugins/opencode/index.js";
+            const shell = await plugin.server();
+            const entries = Object.entries(shell.tool);
+            console.log(JSON.stringify({
+              keys: entries.map(([k]) => k),
+              canonical: IUMBTEMS_TOOL_NAMES,
+              ok: entries.map(([k, t]) => (!!t.description && !!t.input && typeof t.execute === "function" && t.options && t.options.codemode === false))
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"tool map test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(sorted(data["keys"]), sorted(data["canonical"]))
+        self.assertEqual(len(data["keys"]), 13)
+        self.assertTrue(all(data["ok"]))
+
+
+class TestInstallOpenCode(unittest.TestCase):
+    def _run_install(self, home):
+        env = dict(os.environ, HOME=str(home))
+        return subprocess.run(
+            ["bash", str(PROJECT_ROOT / "install.sh")],
+            capture_output=True,
+            text=True,
+            cwd=str(PROJECT_ROOT),
+            env=env,
+        )
+
+    def _seed_malformed(self, home):
+        oc = home / ".config" / "opencode"
+        oc.mkdir(parents=True, exist_ok=True)
+        # Exact malformation seen in the wild: bare options object after the string.
+        oc.joinpath("opencode.json").write_text(
+            json.dumps(
+                {
+                    "$schema": "https://opencode.ai/config.json",
+                    "plugin": [
+                        "@prevalentware/opencode-goal-plugin",
+                        "@heretek-ai/epistemic-swarm",
+                        {
+                            "search_engine": "duckduckgo",
+                            "max_iterations": 10,
+                            "mode": "research",
+                        },
+                    ],
+                }
+            ),
+            encoding="utf-8",
+        )
+
+    def test_idempotent_and_repairs_bare_object(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            self._seed_malformed(home)
+            first = self._run_install(home)
+            self.assertEqual(first.returncode, 0, f"install failed: {first.stderr}")
+            oc_path = home / ".config" / "opencode" / "opencode.json"
+            cfg = json.loads(oc_path.read_text(encoding="utf-8"))
+            # Bare object repaired into tuple form, preserving user options.
+            tuples = [
+                p
+                for p in cfg["plugin"]
+                if isinstance(p, list) and p and p[0] == "@heretek-ai/epistemic-swarm"
+            ]
+            self.assertEqual(len(tuples), 1)
+            self.assertEqual(
+                tuples[0][1],
+                {
+                    "search_engine": "duckduckgo",
+                    "max_iterations": 10,
+                    "mode": "research",
+                },
+            )
+            self.assertFalse(any(isinstance(p, dict) for p in cfg["plugin"]))
+            # Agents merged from the snippet, MCP server absolute.
+            for agent in [
+                "code-auditor",
+                "oss-scout",
+                "alpha-thesis",
+                "beta-redteam",
+                "epistemic-auditor",
+                "brainstormer",
+            ]:
+                self.assertIn(agent, cfg.get("agent", {}))
+            self.assertIn("iumbtems", cfg.get("mcp", {}))
+            cmd = cfg["mcp"]["iumbtems"]["command"]
+            self.assertTrue(Path(cmd[-1]).is_absolute())
+            self.assertEqual(cmd[-1], str(PROJECT_ROOT / "runner" / "mcp_server.py"))
+            # Second run changes nothing.
+            before = oc_path.read_bytes()
+            second = self._run_install(home)
+            self.assertEqual(second.returncode, 0, f"reinstall failed: {second.stderr}")
+            self.assertEqual(oc_path.read_bytes(), before)
+
+
+class TestOpenCodeTui(unittest.TestCase):
+    def test_module_load_and_setup(self):
+        res = run_node(
+            """
+            import plugin, { readSwarmStatus, setupTui } from "./plugins/opencode/tui.js";
+            const calls = [];
+            const mock = {
+              theme: {}, directory: "/tmp/oc-tui-empty",
+              ui: { slot: (...a) => { calls.push(a.length); return () => {}; }, toast: { show: () => {} }, router: { current: () => ({type: "other"}) } },
+              keymap: { layer: () => {} }
+            };
+            const cleanup = setupTui(mock);
+            const empty = readSwarmStatus("/tmp/oc-tui-empty");
+            console.log(JSON.stringify({id: plugin.id, hasTui: !!plugin.tui, setupFn: typeof plugin.setup, slots: calls, cleanup: typeof cleanup, emptyWorkspace: empty.workspace}));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"tui load test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["id"], "heretek.iumbtems.epistemic-swarm.tui")
+        self.assertTrue(data["hasTui"])
+        self.assertEqual(data["setupFn"], "function")
+        self.assertEqual(data["slots"], [1, 1])
+        self.assertEqual(data["cleanup"], "function")
+        self.assertFalse(data["emptyWorkspace"])
+
+    def test_status_snapshot_counts(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            research = root / ".research"
+            (research / "ledger").mkdir(parents=True)
+            research.joinpath("config.json").write_text(
+                json.dumps(
+                    {
+                        "mode": "research",
+                        "search_engine": "duckduckgo",
+                        "max_iterations": 2,
+                    }
+                ),
+                encoding="utf-8",
+            )
+            research.joinpath("final_synthesis.md").write_text(
+                "# synthesis\n", encoding="utf-8"
+            )
+            research.joinpath("frontier.json").write_text(
+                json.dumps({"nodes": [{"status": "open"}, {"status": "settled"}]}),
+                encoding="utf-8",
+            )
+            research.joinpath("ledger", "claim_status.json").write_text(
+                json.dumps(
+                    [
+                        {
+                            "scope_id": "s",
+                            "claim_id": "a",
+                            "from_status": "UNVERIFIED",
+                            "to_status": "VERIFIED",
+                            "reason": "",
+                            "at": "t1",
+                        },
+                        {
+                            "scope_id": "s",
+                            "claim_id": "a",
+                            "from_status": "VERIFIED",
+                            "to_status": "STALE",
+                            "reason": "retracted",
+                            "at": "t2",
+                        },
+                        {
+                            "scope_id": "s",
+                            "claim_id": "b",
+                            "from_status": "VERIFIED",
+                            "to_status": "SUSPECT",
+                            "reason": "",
+                            "at": "t3",
+                        },
+                    ]
+                ),
+                encoding="utf-8",
+            )
+            research.joinpath("requeue.json").write_text(
+                json.dumps([{"scope_id": "s1"}, {"scope_id": "s2"}]), encoding="utf-8"
+            )
+            res = run_node(
+                f"""
+                import {{ readSwarmStatus }} from "./plugins/opencode/tui.js";
+                console.log(JSON.stringify(readSwarmStatus({str(root)!r})));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"snapshot test failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["workspace"])
+            self.assertEqual(data["mode"], "research")
+            self.assertEqual(data["searchEngine"], "duckduckgo")
+            self.assertEqual(len(data["reports"]), 1)
+            self.assertEqual(data["frontierOpen"], 1)
+            self.assertEqual(data["stale"], 1)
+            self.assertEqual(data["suspect"], 1)
+            self.assertEqual(data["requeued"], 2)
+
+
+class TestOpenCodeLifecycle(unittest.TestCase):
+    @staticmethod
+    def _fixture(tmp):
+        root = Path(tmp)
+        research = root / ".research"
+        (research / "ledger").mkdir(parents=True)
+        research.joinpath("config.json").write_text(
+            json.dumps(
+                {"mode": "audit", "search_engine": "brave", "max_iterations": 3}
+            ),
+            encoding="utf-8",
+        )
+        research.joinpath("ledger", "claim_status.json").write_text(
+            json.dumps(
+                [
+                    {
+                        "scope_id": "s",
+                        "claim_id": "x1",
+                        "from_status": "VERIFIED",
+                        "to_status": "STALE",
+                        "reason": "retracted",
+                        "at": "t1",
+                    },
+                ]
+            ),
+            encoding="utf-8",
+        )
+        research.joinpath("requeue.json").write_text(
+            json.dumps([{"scope_id": "s9"}]), encoding="utf-8"
+        )
+        return str(root)
+
+    def test_idle_detection(self):
+        res = run_node(
+            """
+            import { isIdleEvent } from "./plugins/opencode/index.js";
+            console.log(JSON.stringify({
+              idle: isIdleEvent({type: "session.idle"}),
+              statusIdle: isIdleEvent({type: "session.status", properties: {status: {type: "idle"}}}),
+              busy: isIdleEvent({type: "session.status", properties: {status: {type: "busy"}}}),
+              other: isIdleEvent({type: "message.updated"}),
+              empty: isIdleEvent(null)
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"idle test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertTrue(data["idle"])
+        self.assertTrue(data["statusIdle"])
+        self.assertFalse(data["busy"])
+        self.assertFalse(data["other"])
+        self.assertFalse(data["empty"])
+
+    def test_compaction_hook_pushes_state(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = self._fixture(tmp)
+            res = run_node(
+                f"""
+                import plugin from "./plugins/opencode/index.js";
+                const shell = await plugin.server();
+                const hook = shell["experimental.session.compacting"];
+                const out = {{context: []}};
+                await hook({{directory: {root!r}}}, out);
+                const empty = {{context: []}};
+                await hook({{directory: "/tmp/oc-lifecycle-empty"}}, empty);
+                console.log(JSON.stringify({{hook: typeof hook, pushed: out.context.length, text: out.context[0] || "", skipped: empty.context.length}}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"compaction test failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertEqual(data["hook"], "function")
+            self.assertEqual(data["pushed"], 1)
+            self.assertIn("mode=audit", data["text"])
+            self.assertIn("x1", data["text"])
+            self.assertIn("s9", data["text"])
+            self.assertEqual(data["skipped"], 0)
+
+    def test_nudge_once_per_ledger_state(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = self._fixture(tmp)
+            res = run_node(
+                f"""
+                import {{ handleIdleEvent }} from "./plugins/opencode/index.js";
+                const prompts = [];
+                const host = {{session: {{prompt: async (p) => {{ prompts.push(p); return {{}}; }}}}}};
+                const state = {{}};
+                const evt = {{type: "session.idle", properties: {{sessionID: "ses_1"}}}};
+                const first = handleIdleEvent(host, {root!r}, state, evt);
+                await new Promise(r => setTimeout(r, 20));
+                const second = handleIdleEvent(host, {root!r}, state, evt);
+                const busy = handleIdleEvent(host, {root!r}, state, {{type: "message.updated"}});
+                console.log(JSON.stringify({{first, second, busy, prompts: prompts.length, sid: prompts[0]?.sessionID || null}}));
+                """
+            )
+            self.assertEqual(res.returncode, 0, f"nudge test failed: {res.stderr}")
+            data = last_json_object(res.stdout)
+            self.assertTrue(data["first"])
+            self.assertFalse(data["second"])
+            self.assertFalse(data["busy"])
+            self.assertEqual(data["prompts"], 1)
+            self.assertEqual(data["sid"], "ses_1")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runner/tests/test_swarm.py

@@ -318,15 +318,20 @@ In our experiments, the 70B parameter model was trained on 15.0 trillion tokens.
 
         # 1. Test OpenCode Plugin registration (A2b: thin forwarders + both
         #    name exports — canonical IUMBTEMS_TOOL_NAMES and the deprecated
-        #    IUMBEMS_TOOL_NAMES alias).
+        #    IUMBEMS_TOOL_NAMES alias). Object form: server() resolves to
+        #    {config, tool} with the tool map keyed by name.
         node_code_oc = """
         import plugin, { IUMBTEMS_TOOL_NAMES, IUMBEMS_TOOL_NAMES } from "./plugins/opencode/index.js";
-        const tools = plugin.server();
+        const shell = await plugin.server();
+        const tools = Object.values(shell.tool);
         const names = tools.map(t => t.name);
+        const cfg = {};
+        shell.config(cfg);
         console.log(JSON.stringify({
           names,
           canonical: IUMBTEMS_TOOL_NAMES,
-          alias: IUMBEMS_TOOL_NAMES
+          alias: IUMBEMS_TOOL_NAMES,
+          commands: Object.keys(cfg.command || {})
         }));
         """
         res_oc = subprocess.run(
@@ -365,6 +370,17 @@ In our experiments, the 70B parameter model was trained on 15.0 trillion tokens.
         ]
         for t in expected_tools:
             self.assertIn(t, tools)
+        # Slash-command catalog registered via the server config hook.
+        for c in [
+            "swarm",
+            "grill",
+            "swarm-config",
+            "audit",
+            "scout",
+            "brainstorming",
+            "brainstorm",
+        ]:
+            self.assertIn(c, data_oc["commands"])
 
         # 2. Test Pi Extension registration
         node_code_pi = """