@neuroverseos/nv-sim 0.1.9 → 0.1.11

package/connectors/nv_mirofish_wrapper.py

@@ -0,0 +1,841 @@
+#!/usr/bin/env python3
+"""
+NeuroVerse MiroFish Connector — Runtime Governance Without Hooks
+
+OpenClaw didn't accept our governance hook PR. So we built this.
+
+This wrapper governs MiroFish simulations WITHOUT modifying MiroFish code.
+It monkey-patches the OASIS action execution layer at import time so every
+agent action flows through NeuroVerse governance before reaching the
+simulation environment.
+
+Three operating modes:
+
+  MODE 1: Runtime Patch (recommended)
+    Imports MiroFish/OASIS, patches agent action methods, runs governed.
+    Requires: MiroFish installed in the same Python environment.
+
+  MODE 2: Process Wrapper
+    Spawns MiroFish as a subprocess, parses structured JSON output,
+    evaluates each action/round through the governance API.
+    Requires: MiroFish on PATH or MIROFISH_BIN set.
+
+  MODE 3: Bridge-Only
+    Doesn't run MiroFish at all. Instead, starts a governance bridge
+    that MiroFish can call into via neuroverse_bridge.py.
+    Requires: User drops neuroverse_bridge.py into their MiroFish project.
+
+Usage:
+    # Mode 1: Runtime patch (auto-detected if OASIS is importable)
+    python nv_mirofish_wrapper.py --simulation twitter --world social-media
+
+    # Mode 2: Process wrapper (if OASIS not importable)
+    python nv_mirofish_wrapper.py --simulation twitter --world social-media
+
+    # Mode 3: Bridge only
+    python nv_mirofish_wrapper.py --bridge-only
+
+    # With custom governance server
+    python nv_mirofish_wrapper.py --nv-url http://localhost:4000
+
+Requires:
+    - NeuroVerse governance server running: npx nv-sim serve
+    - pip install requests
+    - For Mode 1: pip install oasis-social (MiroFish/OASIS)
+
+Zero edits to MiroFish required. Zero PRs needed.
+"""
+
+import subprocess
+import sys
+import os
+import json
+import time
+import signal
+import threading
+import importlib
+import functools
+from typing import Any, Callable, Optional
+
+try:
+    import requests
+except ImportError:
+    print("ERROR: 'requests' package required. Install with: pip install requests")
+    sys.exit(1)
+
+# ============================================
+# CONFIGURATION
+# ============================================
+
+NEUROVERSE_URL = os.environ.get("NEUROVERSE_URL", "http://localhost:3456")
+EVALUATE_ENDPOINT = f"{NEUROVERSE_URL}/api/evaluate"
+MIROFISH_BIN = os.environ.get("MIROFISH_BIN", "python")
+MIROFISH_SCRIPT = os.environ.get("MIROFISH_SCRIPT", "run_twitter_simulation.py")
+VERBOSE = os.environ.get("NV_VERBOSE", "0") == "1"
+ENFORCE_STREAMING = os.environ.get("NV_ENFORCE_STREAMING", "1") == "1"
+NV_FAIL_OPEN = os.environ.get("NV_FAIL_OPEN", "true").lower() in ("true", "1", "yes")
+NV_WORLD = os.environ.get("NV_WORLD", "social-media")
+
+# ============================================
+# STATS
+# ============================================
+
+stats = {
+    "evaluated": 0,
+    "allowed": 0,
+    "blocked": 0,
+    "modified": 0,
+    "penalized": 0,
+    "rewarded": 0,
+    "paused": 0,
+    "rounds_seen": 0,
+    "actions_seen": 0,
+    "actions_intercepted": 0,
+    "mode": "unknown",
+}
+
+# ============================================
+# ARGUMENT PARSING
+# ============================================
+
+def parse_args(argv):
+    """Parse wrapper-specific and passthrough arguments."""
+    args = argv[1:]
+    parsed = {
+        "simulation": "twitter",
+        "world": NV_WORLD,
+        "bridge_only": False,
+        "compare": False,
+        "rounds": None,
+        "agents": None,
+        "rules_file": None,
+        "passthrough_args": [],
+    }
+
+    nv_args = set()
+    i = 0
+    while i < len(args):
+        flag = args[i]
+        if flag == "--simulation" and i + 1 < len(args):
+            parsed["simulation"] = args[i + 1]
+            nv_args.update([i, i + 1])
+            i += 2
+        elif flag == "--world" and i + 1 < len(args):
+            parsed["world"] = args[i + 1]
+            nv_args.update([i, i + 1])
+            i += 2
+        elif flag == "--bridge-only":
+            parsed["bridge_only"] = True
+            nv_args.add(i)
+            i += 1
+        elif flag == "--compare":
+            parsed["compare"] = True
+            nv_args.add(i)
+            i += 1
+        elif flag == "--rounds" and i + 1 < len(args):
+            parsed["rounds"] = int(args[i + 1])
+            nv_args.update([i, i + 1])
+            i += 2
+        elif flag == "--agents" and i + 1 < len(args):
+            parsed["agents"] = int(args[i + 1])
+            nv_args.update([i, i + 1])
+            i += 2
+        elif flag == "--rules" and i + 1 < len(args):
+            parsed["rules_file"] = args[i + 1]
+            nv_args.update([i, i + 1])
+            i += 2
+        elif flag == "--nv-url" and i + 1 < len(args):
+            nv_args.update([i, i + 1])
+            global NEUROVERSE_URL, EVALUATE_ENDPOINT
+            NEUROVERSE_URL = args[i + 1]
+            EVALUATE_ENDPOINT = f"{NEUROVERSE_URL}/api/evaluate"
+            i += 2
+        elif flag == "--nv-verbose":
+            nv_args.add(i)
+            global VERBOSE
+            VERBOSE = True
+            i += 1
+        elif flag == "--nv-fail-closed":
+            nv_args.add(i)
+            global NV_FAIL_OPEN
+            NV_FAIL_OPEN = False
+            i += 1
+        elif flag == "--mirofish-bin" and i + 1 < len(args):
+            nv_args.update([i, i + 1])
+            global MIROFISH_BIN
+            MIROFISH_BIN = args[i + 1]
+            i += 2
+        elif flag == "--mirofish-script" and i + 1 < len(args):
+            nv_args.update([i, i + 1])
+            global MIROFISH_SCRIPT
+            MIROFISH_SCRIPT = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    parsed["passthrough_args"] = [
+        a for idx, a in enumerate(args) if idx not in nv_args
+    ]
+
+    return parsed
+
+# ============================================
+# GOVERNANCE EVALUATION
+# ============================================
+
+def evaluate_action(action_type, agent, payload_extra=None):
+    """Call NeuroVerse /api/evaluate and return the verdict."""
+    payload = {
+        "actor": agent,
+        "action": action_type,
+        "payload": {
+            "description": f"Agent {agent} executing {action_type}",
+        },
+        "world": NV_WORLD,
+    }
+
+    if payload_extra:
+        payload["payload"].update(payload_extra)
+
+    try:
+        resp = requests.post(EVALUATE_ENDPOINT, json=payload, timeout=5)
+        resp.raise_for_status()
+        result = resp.json()
+        stats["evaluated"] += 1
+
+        decision = result.get("decision", result.get("status", "ALLOW")).upper()
+        if decision == "ALLOW":
+            stats["allowed"] += 1
+        elif decision == "BLOCK":
+            stats["blocked"] += 1
+        elif decision == "PENALIZE":
+            stats["penalized"] += 1
+        elif decision == "REWARD":
+            stats["rewarded"] += 1
+        elif decision == "MODIFY":
+            stats["modified"] += 1
+        elif decision == "PAUSE":
+            stats["paused"] += 1
+
+        if VERBOSE:
+            reason = result.get("reason", "")
+            print(f"  [NV] {agent}/{action_type} -> {decision}: {reason}")
+
+        return result
+    except requests.ConnectionError:
+        if stats["evaluated"] == 0:
+            print(f"  [NV] WARNING: NeuroVerse server not reachable at {NEUROVERSE_URL}")
+            print(f"  [NV] Start it with: npx nv-sim serve")
+            if NV_FAIL_OPEN:
+                print(f"  [NV] Falling back to ALLOW (ungoverned mode)\n")
+            else:
+                print(f"  [NV] Failing CLOSED — all actions blocked\n")
+        if NV_FAIL_OPEN:
+            return {"decision": "ALLOW", "reason": "Governance server unavailable — fail open"}
+        return {"decision": "BLOCK", "reason": "Governance server unavailable — fail closed"}
+    except Exception as e:
+        if NV_FAIL_OPEN:
+            return {"decision": "ALLOW", "reason": f"Evaluation error: {e}"}
+        return {"decision": "BLOCK", "reason": f"Evaluation error: {e}"}
+
+
+def apply_rules_from_file(rules_file):
+    """Load a rules file and send it to the governance server."""
+    if not rules_file or not os.path.exists(rules_file):
+        return
+
+    with open(rules_file, "r") as f:
+        rules_text = f.read()
+
+    try:
+        resp = requests.post(
+            f"{NEUROVERSE_URL}/api/apply-rules",
+            json={"text": rules_text},
+            timeout=5,
+        )
+        resp.raise_for_status()
+        result = resp.json()
+        rule_count = result.get("ruleCount", 0)
+        enforced = result.get("enforcedCount", 0)
+        health = result.get("healthScore", 0)
+        print(f"  [NV] Rules loaded: {rule_count} rules ({enforced} enforced), health {health}/100")
+    except requests.ConnectionError:
+        print(f"  [NV] WARNING: Could not load rules — server not reachable")
+    except Exception as e:
+        print(f"  [NV] WARNING: Could not load rules: {e}")
+
+
+# ============================================
+# MODE 1: RUNTIME PATCH
+# ============================================
+
+def try_runtime_patch(parsed):
+    """
+    Attempt to import OASIS and monkey-patch agent action execution.
+
+    MiroFish/OASIS architecture:
+      1. Agent generates action via LLM  -> agent.generate_action()
+      2. Action is submitted to env       -> env.step(actions)
+
+    We patch env.step() so every action dict flows through governance
+    BEFORE reaching the simulation environment. Blocked actions are
+    replaced with no-ops. Modified actions have reduced magnitude.
+
+    Returns True if patching succeeded, False if OASIS not available.
+    """
+    try:
+        # Try importing OASIS modules — this tells us if MiroFish is installed
+        oasis_env = importlib.import_module("oasis.social_platform.platform")
+        print(f"  [NV] OASIS detected — using runtime patch mode")
+        stats["mode"] = "runtime_patch"
+    except (ImportError, ModuleNotFoundError):
+        return False
+
+    # Find the Platform class and patch its step method
+    Platform = getattr(oasis_env, "Platform", None)
+    if Platform is None:
+        # Try alternative module paths
+        try:
+            oasis_env = importlib.import_module("oasis.social_agent.agent")
+            print(f"  [NV] OASIS agent module detected")
+        except (ImportError, ModuleNotFoundError):
+            pass
+        return False
+
+    original_step = Platform.step
+
+    @functools.wraps(original_step)
+    def governed_step(self, actions):
+        """
+        Governed version of Platform.step().
+
+        Intercepts agent actions, evaluates each through NeuroVerse governance,
+        and only passes allowed/modified actions to the original step function.
+        """
+        if not isinstance(actions, dict):
+            return original_step(self, actions)
+
+        governed_actions = {}
+        for agent_id, action_data in actions.items():
+            stats["actions_seen"] += 1
+
+            # Extract action metadata for governance
+            action_type = "unknown"
+            description = f"Agent {agent_id} action"
+            magnitude = 0.5
+
+            if isinstance(action_data, dict):
+                action_type = action_data.get("action_type", action_data.get("type", "social_action"))
+                description = action_data.get("content", action_data.get("message", description))
+                # Estimate magnitude from action characteristics
+                magnitude = _estimate_magnitude(action_data)
+            elif isinstance(action_data, (list, tuple)) and len(action_data) >= 2:
+                action_type = str(action_data[1]) if len(action_data) > 1 else "social_action"
+                description = str(action_data[0]) if len(action_data) > 0 else description
+
+            verdict = evaluate_action(
+                action_type=action_type,
+                agent=str(agent_id),
+                payload_extra={
+                    "description": description[:500],
+                    "magnitude": magnitude,
+                    "simulation_type": parsed.get("simulation", "social"),
+                },
+            )
+
+            decision = verdict.get("decision", verdict.get("status", "ALLOW")).upper()
+
+            if decision == "BLOCK" or decision == "PENALIZE":
+                stats["actions_intercepted"] += 1
+                # Replace with no-op action
+                if isinstance(action_data, dict):
+                    governed_actions[agent_id] = {
+                        **action_data,
+                        "action_type": "idle",
+                        "content": "",
+                        "_nv_blocked": True,
+                        "_nv_reason": verdict.get("reason", "governance"),
+                    }
+                else:
+                    governed_actions[agent_id] = action_data  # pass through if we can't modify
+                continue
+
+            elif decision == "MODIFY":
+                stats["actions_intercepted"] += 1
+                modified = verdict.get("modified_action", {})
+                if isinstance(action_data, dict):
+                    governed_actions[agent_id] = {
+                        **action_data,
+                        **modified,
+                        "_nv_modified": True,
+                    }
+                else:
+                    governed_actions[agent_id] = action_data
+                continue
+
+            elif decision == "PAUSE":
+                stats["actions_intercepted"] += 1
+                # Delay execution — reduce urgency
+                if isinstance(action_data, dict):
+                    governed_actions[agent_id] = {
+                        **action_data,
+                        "_nv_paused": True,
+                    }
+                else:
+                    governed_actions[agent_id] = action_data
+                continue
+
+            else:
+                # ALLOW or REWARD — pass through unchanged
+                governed_actions[agent_id] = action_data
+
+        return original_step(self, governed_actions)
+
+    # Apply the monkey-patch
+    Platform.step = governed_step
+    print(f"  [NV] Platform.step() patched — all actions now governed")
+    return True
+
+
+def _estimate_magnitude(action_data):
+    """Estimate action magnitude from OASIS action data."""
+    magnitude = 0.5
+
+    action_type = action_data.get("action_type", action_data.get("type", ""))
+
+    # High-magnitude actions
+    if action_type in ("create_post", "publish", "broadcast"):
+        magnitude = 0.6
+    elif action_type in ("repost", "retweet", "share", "amplify"):
+        magnitude = 0.55
+    elif action_type in ("like", "react", "upvote"):
+        magnitude = 0.2
+    elif action_type in ("follow", "subscribe"):
+        magnitude = 0.15
+    elif action_type in ("block_user", "report", "flag"):
+        magnitude = 0.7
+
+    # Content length increases magnitude
+    content = action_data.get("content", action_data.get("message", ""))
+    if isinstance(content, str) and len(content) > 500:
+        magnitude = min(1.0, magnitude + 0.15)
+
+    # Mentions/hashtags increase reach
+    if isinstance(content, str):
+        mentions = content.count("@")
+        hashtags = content.count("#")
+        if mentions + hashtags > 3:
+            magnitude = min(1.0, magnitude + 0.1)
+
+    return magnitude
+
+
+# ============================================
+# MODE 2: PROCESS WRAPPER
+# ============================================
+
+def run_process_wrapper(parsed):
+    """
+    Wrap MiroFish as a subprocess.
+    Parse stdout for structured JSON, evaluate actions through governance.
+    """
+    stats["mode"] = "process_wrapper"
+
+    simulation = parsed["simulation"]
+    script = MIROFISH_SCRIPT
+
+    # Map simulation names to common MiroFish scripts
+    script_map = {
+        "twitter": "run_twitter_simulation.py",
+        "reddit": "run_reddit_simulation.py",
+        "social": "run_simulation.py",
+    }
+    if simulation in script_map:
+        script = script_map[simulation]
+
+    cmd = [MIROFISH_BIN, script] + parsed["passthrough_args"]
+
+    print(f"  [NV] Running as subprocess: {' '.join(cmd)}")
+    if ENFORCE_STREAMING:
+        print(f"  [NV] Streaming governance active — each round evaluated\n")
+    else:
+        print(f"  [NV] Entry gate only — subprocess runs ungoverned\n")
+
+    print(f"  {'=' * 50}")
+
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+    except FileNotFoundError:
+        print(f"\n  ERROR: Could not execute: {' '.join(cmd)}")
+        print(f"  Set MIROFISH_BIN and MIROFISH_SCRIPT environment variables")
+        print(f"  Or use --mirofish-bin and --mirofish-script flags")
+        sys.exit(127)
+
+    # Read stderr in background
+    stderr_thread = threading.Thread(
+        target=_stream_stderr, args=(proc,), daemon=True
+    )
+    stderr_thread.start()
+
+    # Stream stdout — parse and govern
+    terminated_by_governance = False
+    try:
+        for line in iter(proc.stdout.readline, ""):
+            sys.stdout.write(line)
+            sys.stdout.flush()
+
+            if ENFORCE_STREAMING and proc.poll() is None:
+                _govern_mirofish_output(line, proc)
+                if proc.poll() is not None:
+                    terminated_by_governance = True
+                    break
+    except KeyboardInterrupt:
+        proc.terminate()
+        proc.wait(timeout=5)
+
+    exit_code = proc.wait()
+    return exit_code, terminated_by_governance
+
+
+def _govern_mirofish_output(line, proc):
+    """
+    Parse a line of MiroFish output and evaluate for governance.
+
+    MiroFish/OASIS outputs vary by simulation type:
+      - JSON lines with round/step and agent_actions
+      - Log lines with agent action descriptions
+      - Status lines
+
+    We govern JSON-structured output only (same principle as ScienceClaw).
+    """
+    line = line.strip()
+    if not line or not line.startswith("{"):
+        return
+
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return
+
+    # Look for round/step structure
+    round_num = data.get("round") or data.get("step") or data.get("cycle")
+    actions = (
+        data.get("agent_actions")
+        or data.get("actions")
+        or data.get("reactions")
+        or []
+    )
+
+    if round_num is not None:
+        stats["rounds_seen"] += 1
+
+    if not actions:
+        # Check if this is a single agent action
+        if data.get("agent_id") and (data.get("action") or data.get("action_type")):
+            actions = [data]
+        else:
+            return
+
+    for action in actions:
+        stats["actions_seen"] += 1
+        agent_id = action.get("agent_id") or action.get("id") or "unknown"
+        action_type = action.get("action_type") or action.get("action") or action.get("type") or "social_action"
+        description = action.get("content") or action.get("message") or action.get("description") or f"{action_type}"
+
+        verdict = evaluate_action(
+            action_type=action_type,
+            agent=str(agent_id),
+            payload_extra={
+                "description": str(description)[:500],
+                "round": round_num,
+                "magnitude": _estimate_magnitude(action) if isinstance(action, dict) else 0.5,
+            },
+        )
+
+        decision = verdict.get("decision", verdict.get("status", "ALLOW")).upper()
+
+        if decision in ("BLOCK", "PENALIZE") and ENFORCE_STREAMING:
+            reason = verdict.get("reason", "policy violation")
+            print(f"\n  [NV] GOVERNANCE HALT at round {round_num}")
+            print(f"        Agent:    {agent_id}")
+            print(f"        Action:   {action_type}: {str(description)[:80]}")
+            print(f"        Decision: {decision}")
+            print(f"        Reason:   {reason}")
+
+            if decision == "PENALIZE" and verdict.get("consequence"):
+                c = verdict["consequence"]
+                print(f"        Consequence: {c.get('type', 'unknown')} for {c.get('rounds', 1)} round(s)")
+
+            print(f"        Terminating MiroFish process...\n")
+
+            try:
+                proc.terminate()
+                proc.wait(timeout=5)
+            except Exception:
+                proc.kill()
+            return
+
+
+def _stream_stderr(proc):
+    """Read stderr in a background thread."""
+    for line in iter(proc.stderr.readline, ""):
+        if line.strip():
+            sys.stderr.write(line)
+            sys.stderr.flush()
+
+
+# ============================================
+# MODE 3: BRIDGE ONLY
+# ============================================
+
+def run_bridge_only():
+    """
+    Don't run MiroFish. Just verify the governance server is running
+    and print instructions for using neuroverse_bridge.py.
+    """
+    stats["mode"] = "bridge_only"
+
+    print(f"\n  NeuroVerse MiroFish Bridge Mode")
+    print(f"  {'=' * 60}")
+    print(f"  Governance server: {NEUROVERSE_URL}")
+
+    # Check if server is running
+    try:
+        resp = requests.get(f"{NEUROVERSE_URL}/api/session", timeout=3)
+        resp.raise_for_status()
+        session = resp.json()
+        print(f"  Server status:    RUNNING")
+        print(f"  Evaluations:      {session.get('totalEvaluations', 0)}")
+    except Exception:
+        print(f"  Server status:    NOT RUNNING")
+        print(f"\n  Start the governance server first:")
+        print(f"    npx nv-sim serve")
+        print(f"\n  Then run this again.")
+        sys.exit(1)
+
+    print(f"\n  {'=' * 60}")
+    print(f"""
+  HOW TO USE WITH MIROFISH:
+
+  1. Copy the bridge into your MiroFish project:
+
+     cp bridges/neuroverse_bridge.py /path/to/mirofish/
+
+  2. In your MiroFish agent code (e.g., agent_action.py), add:
+
+     from neuroverse_bridge import evaluate, is_allowed
+
+     # Before executing any action:
+     verdict = evaluate(
+         actor=str(self.agent_id),
+         action=action_type,
+         payload={{"message": message}},
+     )
+     if not is_allowed(verdict):
+         return {{"blocked": True, "reason": verdict["reason"]}}
+
+  3. Or use the zero-code approach — run MiroFish through the wrapper:
+
+     python connectors/nv_mirofish_wrapper.py \\
+       --simulation twitter \\
+       --world social-media
+
+  Environment variables:
+    NV_GOVERNANCE_URL={NEUROVERSE_URL}
+    NV_WORLD={NV_WORLD}
+    NV_FAIL_OPEN=true          # allow actions if server is down
+    NV_ENABLED=true             # disable governance without removing code
+
+  {'=' * 60}
+""")
+
+    # Keep running so user can test with curl
+    print(f"  Bridge is ready. Test with:")
+    print(f"    curl -X POST {NEUROVERSE_URL}/api/evaluate \\")
+    print(f'      -H "Content-Type: application/json" \\')
+    print(f'      -d \'{{"actor":"agent_1","action":"create_post","payload":{{"message":"test"}}}}\'')
+    print()
+    print(f"  Press Ctrl+C to exit.\n")
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print(f"\n  Bridge stopped.")
+
+
+# ============================================
+# PRINT SESSION REPORT
+# ============================================
+
+def print_report(exit_code=0, terminated_by_governance=False):
+    """Print the governance session summary."""
+    print(f"\n  {'=' * 60}")
+    print(f"  NeuroVerse Governance Report")
+    print(f"  {'=' * 60}")
+    print(f"  Mode:           {stats['mode']}")
+
+    if terminated_by_governance:
+        print(f"  Status:         HALTED by governance")
+    elif exit_code == 0:
+        print(f"  Status:         Completed")
+    else:
+        print(f"  Status:         Exited with code {exit_code}")
+
+    print(f"  Evaluations:    {stats['evaluated']}")
+    print(f"  Rounds:         {stats['rounds_seen']}")
+    print(f"  Actions seen:   {stats['actions_seen']}")
+    print(f"  Intercepted:    {stats['actions_intercepted']}")
+    print(f"  {'-' * 40}")
+    print(f"  Allowed:        {stats['allowed']}")
+    print(f"  Blocked:        {stats['blocked']}")
+    print(f"  Modified:       {stats['modified']}")
+    print(f"  Paused:         {stats['paused']}")
+    print(f"  Penalized:      {stats['penalized']}")
+    print(f"  Rewarded:       {stats['rewarded']}")
+
+    # Effectiveness summary
+    total = stats["evaluated"]
+    if total > 0:
+        governance_rate = ((stats["blocked"] + stats["modified"] + stats["penalized"]) / total) * 100
+        pass_rate = (stats["allowed"] / total) * 100
+        print(f"  {'-' * 40}")
+        print(f"  Governance rate: {governance_rate:.0f}% (actions affected by rules)")
+        print(f"  Pass-through:    {pass_rate:.0f}% (actions allowed unchanged)")
+
+    print(f"  {'=' * 60}\n")
+
+    # Report completion to governance server
+    try:
+        requests.post(
+            EVALUATE_ENDPOINT,
+            json={
+                "actor": "nv_mirofish_wrapper",
+                "action": "simulation_complete",
+                "payload": {
+                    "description": f"MiroFish simulation {'halted by governance' if terminated_by_governance else 'completed'}",
+                    "exit_code": exit_code,
+                    "halted_by_governance": terminated_by_governance,
+                    "stats": stats,
+                },
+                "world": NV_WORLD,
+            },
+            timeout=3,
+        )
+    except Exception:
+        pass
+
+
+# ============================================
+# MAIN
+# ============================================
+
+def run():
+    parsed = parse_args(sys.argv)
+    NV_WORLD_LOCAL = parsed["world"]
+    global NV_WORLD
+    NV_WORLD = NV_WORLD_LOCAL
+
+    print(f"\n  NeuroVerse MiroFish Connector")
+    print(f"  {'=' * 60}")
+    print(f"  Simulation: {parsed['simulation']}")
+    print(f"  World:      {NV_WORLD}")
+    print(f"  Server:     {NEUROVERSE_URL}")
+    print(f"  Fail mode:  {'open (ungoverned)' if NV_FAIL_OPEN else 'closed (all blocked)'}")
+    print(f"  {'=' * 60}\n")
+
+    # Load custom rules if provided
+    if parsed["rules_file"]:
+        print(f"  [NV] Loading rules from: {parsed['rules_file']}")
+        apply_rules_from_file(parsed["rules_file"])
+        print()
+
+    # Mode 3: Bridge only
+    if parsed["bridge_only"]:
+        run_bridge_only()
+        return
+
+    # Mode 1: Try runtime patch first
+    print(f"  [1/3] Detecting MiroFish/OASIS installation...")
+    patched = try_runtime_patch(parsed)
+
+    if patched:
+        # Runtime patch succeeded — now run the simulation
+        print(f"  [2/3] Launching governed simulation...\n")
+
+        # Entry gate: evaluate the simulation launch itself
+        verdict = evaluate_action(
+            action_type="launch_simulation",
+            agent="nv_mirofish_wrapper",
+            payload_extra={
+                "simulation_type": parsed["simulation"],
+                "description": f"Launch MiroFish {parsed['simulation']} simulation with governance",
+            },
+        )
+
+        decision = verdict.get("decision", verdict.get("status", "ALLOW")).upper()
+        if decision in ("BLOCK", "PENALIZE"):
+            print(f"  [NV] Simulation launch BLOCKED: {verdict.get('reason', '')}")
+            sys.exit(1)
+
+        # Import and run the actual MiroFish simulation
+        try:
+            if parsed["simulation"] == "twitter":
+                sim_module = importlib.import_module("run_twitter_simulation")
+            elif parsed["simulation"] == "reddit":
+                sim_module = importlib.import_module("run_reddit_simulation")
+            else:
+                sim_module = importlib.import_module(f"run_{parsed['simulation']}_simulation")
+
+            if hasattr(sim_module, "main"):
+                sim_module.main()
+            elif hasattr(sim_module, "run"):
+                sim_module.run()
+            else:
+                print(f"  [NV] WARNING: No main() or run() found in simulation module")
+                print(f"  [NV] The module was imported and patched — if it runs on import, governance was active")
+
+            print_report(exit_code=0, terminated_by_governance=False)
+
+        except SystemExit as e:
+            print_report(exit_code=e.code or 0, terminated_by_governance=False)
+        except Exception as e:
+            print(f"\n  [NV] Simulation error: {e}")
+            print_report(exit_code=1, terminated_by_governance=False)
+        return
+
+    # Mode 2: Fall back to process wrapper
+    print(f"  [NV] OASIS not importable — falling back to process wrapper mode")
+    print(f"  [2/3] Evaluating launch governance...")
+
+    verdict = evaluate_action(
+        action_type="launch_simulation",
+        agent="nv_mirofish_wrapper",
+        payload_extra={
+            "simulation_type": parsed["simulation"],
+            "description": f"Launch MiroFish {parsed['simulation']} simulation via subprocess",
+        },
+    )
+
+    decision = verdict.get("decision", verdict.get("status", "ALLOW")).upper()
+    if decision in ("BLOCK", "PENALIZE"):
+        print(f"  [NV] Simulation launch BLOCKED: {verdict.get('reason', '')}")
+        sys.exit(1)
+    else:
+        print(f"  [NV] Launch: {decision}")
+
+    print(f"  [3/3] Starting MiroFish subprocess...\n")
+
+    exit_code, terminated = run_process_wrapper(parsed)
+    print_report(exit_code=exit_code, terminated_by_governance=terminated)
+    sys.exit(1 if terminated else exit_code)
+
+
+if __name__ == "__main__":
+    run()