neuro-cortex-memory 3.4.0__tar.gz → 3.4.2__tar.gz

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Persistent memory and cognitive profiling plugins for Claude Code",
-    "version": "3.4.0"
+    "version": "3.4.2"
   },
   "plugins": [
     {
       "name": "cortex",
       "source": "./",
       "description": "Persistent memory and cognitive profiling for Claude Code — thermodynamic memory with heat/decay, intent-aware retrieval, biological plasticity, codebase intelligence, and cognitive profiling. 33 MCP tools. Docker image available with PostgreSQL + pgvector pre-configured.",
-      "version": "3.4.0",
+      "version": "3.4.2",
       "author": {
         "name": "Clement Deust",
         "email": "admin@ai-architect.tools"

neuro_cortex_memory-3.4.2/.claude-plugin/plugin.json

@@ -0,0 +1,98 @@
+{
+  "name": "cortex",
+  "description": "Persistent memory for Claude Code — remembers across sessions automatically. Install and forget. Scientific retrieval backed by 41 published papers.",
+  "version": "3.4.2",
+  "author": {
+    "name": "Clement Deust",
+    "email": "admin@ai-architect.tools"
+  },
+  "homepage": "https://github.com/cdeust/Cortex",
+  "repository": "https://github.com/cdeust/Cortex",
+  "license": "MIT",
+  "keywords": ["memory", "persistent", "mcp", "claude-code", "neuroscience", "agents"],
+  "mcpServers": {
+    "cortex": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py", "mcp_server"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}",
+      "env": {
+        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}:${CLAUDE_PLUGIN_DATA}/deps",
+        "DATABASE_URL": "postgresql://localhost:5432/cortex"
+      }
+    }
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.session_start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.auto_recall",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.post_tool_capture",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.preemptive_context",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.session_lifecycle",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "compacted",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.compaction_checkpoint",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py\" mcp_server.hooks.agent_briefing",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

neuro_cortex_memory-3.4.2/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "cortex": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py", "mcp_server"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}",
+      "env": {
+        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}:${CLAUDE_PLUGIN_DATA}/deps",
+        "DATABASE_URL": "postgresql://localhost:5432/cortex"
+      }
+    }
+  }
+}

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: neuro-cortex-memory
-Version: 3.4.0
+Version: 3.4.2
 Summary: Scientifically-grounded memory system based on computational neuroscience research
 Project-URL: Homepage, https://github.com/cdeust/Cortex
 Project-URL: Repository, https://github.com/cdeust/Cortex

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/mcp_server/core/graph_builder_memory.py

@@ -226,6 +226,7 @@ def _build_memory_node(mem: dict, nid: str, emo: dict, color: str) -> Node:
         "hippocampalDependency": round(mem.get("hippocampal_dependency", 1.0), 4),
         "plasticity": round(mem.get("plasticity", 1.0), 4),
         "stability": round(mem.get("stability", 0), 4),
+        "surpriseScore": round(mem.get("surprise_score", 0), 4),
         "createdAt": str(mem.get("created_at", "")),
         "lastAccessed": str(mem.get("last_accessed", "")),
     }

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/mcp_server/infrastructure/git_diff.py

@@ -44,6 +44,10 @@ def resolve_file(name: str, git_root: Path) -> str | None:
     """
     rel = _to_relative(name, git_root)
 
+    # Security: validate the relative path stays within the repo before any use
+    if not _path_within_root(rel, git_root):
+        return None
+
     # Check if it's tracked by git
     tracked = _git_cmd(["git", "ls-files", "--", rel], git_root)
     if tracked:
@@ -62,10 +66,12 @@ def resolve_file(name: str, git_root: Path) -> str | None:
             if f.endswith("/" + basename) or f == basename:
                 return f
 
-    # File exists on disk but untracked — validate path stays within repo
-    full = (git_root / rel).resolve()
-    if full.is_file() and str(full).startswith(str(git_root.resolve())):
-        return rel
+    # File exists on disk but untracked — pre-sanitize then validate
+    safe_rel = _sanitize_path(rel)
+    if safe_rel:
+        full = (git_root / safe_rel).resolve()
+        if full.is_file() and str(full).startswith(str(git_root.resolve()) + os.sep):
+            return safe_rel
 
     return None
 
@@ -82,6 +88,10 @@ def get_file_diff(filepath: str, git_root: Path, max_lines: int = 80) -> dict:
     """
     empty = {"file": filepath, "diff_type": "none", "lines": [], "truncated": False}
 
+    # Security: validate filepath stays within repo before any use
+    if not _path_within_root(filepath, git_root):
+        return empty
+
     # 1. Unstaged working tree changes
     raw = _git_cmd(["git", "diff", "--", filepath], git_root)
     if raw:
@@ -98,13 +108,19 @@ def get_file_diff(filepath: str, git_root: Path, max_lines: int = 80) -> dict:
         return _build_result(filepath, "last_commit", raw, max_lines)
 
     # 4. File content at HEAD (file exists but no diff history)
-    content = _git_cmd(["git", "show", "HEAD:" + filepath], git_root)
+    # Validate: filepath must not contain null bytes or shell metacharacters
+    safe_ref = "HEAD:" + filepath
+    content = _git_cmd(["git", "show", safe_ref], git_root)
     if content:
         return _content_as_new(filepath, content, max_lines)
 
-    # 5. Direct read for untracked files — validate path stays within repo
-    full_path = (git_root / filepath).resolve()
-    if full_path.is_file() and str(full_path).startswith(str(git_root.resolve())):
+    # 5. Direct read for untracked files — pre-sanitized path
+    safe_fp = _sanitize_path(filepath)
+    if not safe_fp:
+        return empty
+    resolved_root = git_root.resolve()
+    full_path = (git_root / safe_fp).resolve()
+    if full_path.is_file() and str(full_path).startswith(str(resolved_root) + os.sep):
         try:
             content = full_path.read_text(errors="replace")
             if content:
@@ -115,6 +131,50 @@ def get_file_diff(filepath: str, git_root: Path, max_lines: int = 80) -> dict:
     return empty
 
 
+def _sanitize_path(rel_path: str) -> str | None:
+    """Sanitize a relative path string BEFORE any filesystem operations.
+
+    Returns the sanitized path or None if it's unsafe.
+    This pre-validation ensures CodeQL sees the path as safe
+    before it flows into resolve() or any filesystem call.
+    """
+    if not rel_path or not isinstance(rel_path, str):
+        return None
+    # Reject null bytes
+    if "\x00" in rel_path:
+        return None
+    # Reject absolute paths
+    if os.path.isabs(rel_path):
+        return None
+    # Reject path traversal components
+    parts = rel_path.replace("\\", "/").split("/")
+    if ".." in parts:
+        return None
+    # Reject hidden files/dirs (dotfiles)
+    if any(p.startswith(".") and p not in (".", "") for p in parts):
+        return None
+    # Reject shell metacharacters
+    if any(c in rel_path for c in (";", "&", "|", "$", "`", "\n", "\r")):
+        return None
+    return rel_path
+
+
+def _path_within_root(rel_path: str, git_root: Path) -> bool:
+    """Validate that a relative path is safe and resolves within the git root."""
+    safe = _sanitize_path(rel_path)
+    if safe is None:
+        return False
+    try:
+        resolved_root = git_root.resolve()
+        resolved_path = (git_root / safe).resolve()
+        return (
+            str(resolved_path).startswith(str(resolved_root) + os.sep)
+            or resolved_path == resolved_root
+        )
+    except (ValueError, OSError):
+        return False
+
+
 def _to_relative(name: str, git_root: Path) -> str:
     """Convert any path form to repo-relative."""
     clean = name.strip().strip("\"'`")
@@ -137,20 +197,40 @@ def _git_cmd(cmd: list[str], cwd: Path) -> str:
     """Run a git command and return stripped stdout, or empty string.
 
     Security: cmd must be a list (no shell=True). All arguments are passed
-    as separate list elements to prevent shell injection. The cwd is validated
-    to be under the git root.
+    as separate list elements to prevent shell injection. Arguments are
+    validated to reject null bytes and shell metacharacters.
     """
     try:
         # Validate: only allow git commands, never shell=True
         if not cmd or cmd[0] != "git":
             return ""
+        # Reject arguments containing null bytes (argument injection)
+        for arg in cmd:
+            if "\x00" in arg:
+                return ""
+        # Validate: only known git subcommands are allowed
+        _allowed_subcommands = {
+            "rev-parse",
+            "ls-files",
+            "diff",
+            "log",
+            "show",
+        }
+        if len(cmd) < 2 or cmd[1] not in _allowed_subcommands:
+            return ""
+        # Sanitize all arguments: reject shell metacharacters
+        for arg in cmd[2:]:
+            if any(c in arg for c in (";", "&", "|", "$", "`", "\n", "\r")):
+                return ""
+        # Build a clean command list with only validated arguments
+        clean_cmd = ["git", cmd[1]] + [str(a) for a in cmd[2:]]
         result = subprocess.run(  # noqa: S603
-            cmd,
+            clean_cmd,
             capture_output=True,
             text=True,
+            shell=False,
             cwd=str(cwd),
             timeout=10,
-            shell=False,
         )
         return result.stdout.strip() if result.returncode == 0 else ""
     except (subprocess.TimeoutExpired, FileNotFoundError):

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/mcp_server/server/http_server.py

@@ -132,15 +132,23 @@ def _serve_graph_json(handler, server_state: dict) -> None:
 
 def _serve_static(handler, base_dir: Path, filename: str, content_type: str) -> None:
     """Serve a static file from the given directory."""
+    import re
+
     try:
-        # Sanitize: strip path components, use only the basename
+        # Security: strip all path components, keep only the final filename
         safe_name = Path(filename).name
-        file_path = (base_dir / safe_name).resolve()
-        # Validate: resolved path must stay within base_dir
-        if not str(file_path).startswith(str(base_dir.resolve())):
+        # Reject empty, hidden, null bytes, and non-alphanumeric filenames
+        if (
+            not safe_name
+            or safe_name.startswith(".")
+            or "\x00" in safe_name
+            or not re.match(r"^[\w][\w.\-]*$", safe_name)
+        ):
             handler.send_response(403)
             handler.end_headers()
             return
+        # safe_name is a simple filename — no path separators possible
+        file_path = base_dir.resolve() / safe_name
         body = file_path.read_bytes()
         handler.send_response(200)
         handler.send_header("Content-Type", content_type)

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/mcp_server/server/http_standalone.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 import threading
 import time
@@ -173,6 +174,8 @@ def _build_unified_handler(ui_root: Path, store) -> type:
                 self._serve_discussions()
             elif path_no_qs.startswith("/api/discussion/"):
                 self._serve_discussion_detail(path_no_qs)
+            elif self.path == "/api/sankey" or self.path.startswith("/api/sankey?"):
+                self._serve_sankey()
             elif self.path.startswith("/api/file-diff?"):
                 _serve_file_diff(self)
             elif self.path.startswith("/js/") and self.path.endswith(".js"):
@@ -224,6 +227,90 @@ def _build_unified_handler(ui_root: Path, store) -> type:
                 self.end_headers()
                 self.wfile.write(json.dumps({"error": str(e)}).encode())
 
+        def _serve_sankey(self):
+            try:
+                rows = store._conn.execute(
+                    "SELECT from_stage, to_stage, COUNT(*) as count "
+                    "FROM stage_transitions "
+                    "GROUP BY from_stage, to_stage "
+                    "ORDER BY from_stage, to_stage"
+                ).fetchall()
+                transitions = [dict(r) for r in rows]
+
+                # Transition timing stats
+                timing_rows = store._conn.execute(
+                    "SELECT from_stage, to_stage, "
+                    "AVG(hours_in_prev_stage) as avg_hours, "
+                    "MIN(hours_in_prev_stage) as min_hours, "
+                    "MAX(hours_in_prev_stage) as max_hours "
+                    "FROM stage_transitions GROUP BY from_stage, to_stage"
+                ).fetchall()
+                timing = {}
+                for r in timing_rows:
+                    key = r["from_stage"] + "->" + r["to_stage"]
+                    timing[key] = {
+                        "avg_hours": round(r["avg_hours"], 1),
+                        "min_hours": round(r["min_hours"], 1),
+                        "max_hours": round(r["max_hours"], 1),
+                    }
+
+                # Per-stage metrics
+                stages = [
+                    "labile",
+                    "early_ltp",
+                    "late_ltp",
+                    "consolidated",
+                    "reconsolidating",
+                ]
+                stage_metrics = {}
+                for s in stages:
+                    r = store._conn.execute(
+                        "SELECT COUNT(*) as count, "
+                        "AVG(heat) as avg_heat, AVG(importance) as avg_importance, "
+                        "AVG(replay_count) as avg_replay, AVG(access_count) as avg_access, "
+                        "AVG(encoding_strength) as avg_encoding, "
+                        "AVG(interference_score) as avg_interference, "
+                        "AVG(schema_match_score) as avg_schema, "
+                        "AVG(hippocampal_dependency) as avg_hippo, "
+                        "AVG(plasticity) as avg_plasticity, "
+                        "AVG(stability) as avg_stability, "
+                        "AVG(hours_in_stage) as avg_hours "
+                        "FROM memories WHERE consolidation_stage = %s "
+                        "AND NOT is_benchmark AND NOT is_stale",
+                        (s,),
+                    ).fetchone()
+                    stage_metrics[s] = {
+                        k: round(v, 3) if isinstance(v, float) else (v or 0)
+                        for k, v in dict(r).items()
+                    }
+
+                # Total memories
+                total = store._conn.execute(
+                    "SELECT COUNT(*) as c FROM memories "
+                    "WHERE NOT is_benchmark AND NOT is_stale"
+                ).fetchone()
+
+                body = json.dumps(
+                    {
+                        "transitions": transitions,
+                        "timing": timing,
+                        "stage_metrics": stage_metrics,
+                        "total_memories": total["c"],
+                    },
+                    default=str,
+                ).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Access-Control-Allow-Origin", "http://127.0.0.1")
+                self.send_header("Cache-Control", "no-cache")
+                self.end_headers()
+                self.wfile.write(body)
+            except Exception as e:
+                self.send_response(500)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(json.dumps({"error": str(e)}).encode())
+
         def _serve_discussions(self):
             try:
                 data = _build_discussions_response(self.path)
@@ -318,12 +405,27 @@ def _build_discussion_detail(session_id: str) -> dict:
     if conv is None:
         return {"error": "Discussion not found", "sessionId": session_id}
 
-    file_path = conv.get("filePath")
-    if not file_path:
-        from mcp_server.infrastructure.config import CLAUDE_DIR
+    import re
 
-        project = conv.get("project", "")
-        file_path = str(CLAUDE_DIR / "projects" / project / f"{session_id}.jsonl")
+    from mcp_server.infrastructure.config import CLAUDE_DIR
+
+    # Security: construct path from sanitized components only — never trust filePath directly
+    safe_session = re.sub(r"[^a-zA-Z0-9\-_]", "", session_id)
+    if not safe_session:
+        return {"error": "Invalid session ID", "sessionId": session_id}
+
+    project = conv.get("project", "")
+    safe_project = (
+        re.sub(r"[^a-zA-Z0-9\-_.]", "", Path(project).name) if project else ""
+    )
+
+    file_path = str(CLAUDE_DIR / "projects" / safe_project / f"{safe_session}.jsonl")
+
+    # Final validation: path must be within CLAUDE_DIR
+    resolved_base = CLAUDE_DIR.resolve()
+    resolved_fp = Path(file_path).resolve()
+    if not str(resolved_fp).startswith(str(resolved_base) + os.sep):
+        return {"error": "Invalid file path", "sessionId": session_id}
 
     raw = read_full_conversation(file_path)
     messages = format_conversation_messages(raw)
@@ -405,13 +507,27 @@ def _build_methodology_handler(ui_root: Path) -> type:
 
 def _serve_static(handler, base_dir: Path, filename: str, content_type: str) -> None:
     """Serve a static file, sanitizing filename."""
+    import re
+
+    # Security: strip all path components, keep only the final filename
     safe_name = Path(filename).name
-    file_path = (base_dir / safe_name).resolve()
-    # Validate: resolved path must stay within base_dir
-    if not str(file_path).startswith(str(base_dir.resolve())):
+    # Reject empty names, hidden files, null bytes, and non-alphanumeric filenames
+    if (
+        not safe_name
+        or safe_name.startswith(".")
+        or "\x00" in safe_name
+        or not re.match(r"^[\w][\w.\-]*$", safe_name)
+    ):
         handler.send_response(403)
         handler.end_headers()
         return
+    # safe_name is now guaranteed to be a simple filename (no path separators,
+    # no dots-only, starts with word char). Construct the full path.
+    file_path = base_dir.resolve() / safe_name
+    if not file_path.exists():
+        handler.send_response(404)
+        handler.end_headers()
+        return
     if not file_path.exists():
         handler.send_response(404)
         handler.end_headers()

{neuro_cortex_memory-3.4.0 → neuro_cortex_memory-3.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "neuro-cortex-memory"
-version = "3.4.0"
+version = "3.4.2"
 description = "Scientifically-grounded memory system based on computational neuroscience research"
 readme = "README.md"
 license = "MIT"

neuro_cortex_memory-3.4.2/scripts/launcher.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Cross-platform launcher for Cortex MCP server and hooks.
+
+Sets up PYTHONPATH, DATABASE_URL, and working directory, then runs the
+target module. Works on Windows (cmd.exe), macOS, and Linux — no bash
+or shell-specific syntax required.
+
+Usage:
+    python3 scripts/launcher.py <module> [--install-deps]
+
+Examples:
+    python3 scripts/launcher.py mcp_server                       # MCP server
+    python3 scripts/launcher.py mcp_server.hooks.session_start   # Hook
+    python3 scripts/launcher.py mcp_server.hooks.auto_recall     # Hook
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _resolve_paths() -> tuple[str, str]:
+    """Resolve plugin root and deps directory."""
+    # CLAUDE_PLUGIN_ROOT is set by Claude Code for plugins
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if not plugin_root or not Path(plugin_root).is_dir():
+        # Fall back to this script's parent's parent
+        plugin_root = str(Path(__file__).resolve().parent.parent)
+
+    # CLAUDE_PLUGIN_DATA is set by Claude Code — persistent across updates
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA", "")
+    if plugin_data:
+        deps_dir = os.path.join(plugin_data, "deps")
+    else:
+        deps_dir = os.path.join(plugin_root, "deps")
+
+    return plugin_root, deps_dir
+
+
+def _ensure_deps(deps_dir: str) -> None:
+    """Install minimal dependencies if missing."""
+    os.makedirs(deps_dir, exist_ok=True)
+    try:
+        import psycopg  # noqa: F401
+    except ImportError:
+        subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "pip",
+                "install",
+                "-q",
+                "--target",
+                deps_dir,
+                "psycopg[binary]>=3.1",
+                "pgvector>=0.3",
+            ],
+            capture_output=True,
+        )
+
+
+def _ensure_all_deps(deps_dir: str) -> None:
+    """Install all dependencies including ML packages."""
+    _ensure_deps(deps_dir)
+    try:
+        import sentence_transformers  # noqa: F401
+    except ImportError:
+        subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "pip",
+                "install",
+                "-q",
+                "--target",
+                deps_dir,
+                "sentence-transformers>=2.2.0",
+                "flashrank>=0.2.0",
+            ],
+            capture_output=True,
+        )
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print(
+            "Usage: python3 scripts/launcher.py <module> [--install-deps]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    module = sys.argv[1]
+    install_deps = "--install-deps" in sys.argv
+
+    plugin_root, deps_dir = _resolve_paths()
+
+    # Set up environment
+    path_sep = ";" if sys.platform == "win32" else ":"
+    current_pypath = os.environ.get("PYTHONPATH", "")
+    new_paths = [plugin_root, deps_dir]
+    if current_pypath:
+        new_paths.append(current_pypath)
+    os.environ["PYTHONPATH"] = path_sep.join(new_paths)
+
+    # Ensure PYTHONPATH entries are in sys.path for this process
+    for p in [plugin_root, deps_dir]:
+        if p not in sys.path:
+            sys.path.insert(0, p)
+
+    # Set DATABASE_URL default if not set
+    if "DATABASE_URL" not in os.environ:
+        os.environ["DATABASE_URL"] = "postgresql://localhost:5432/cortex"
+
+    # Install deps if requested or if this is the MCP server / SessionStart
+    if install_deps or module == "mcp_server":
+        _ensure_deps(deps_dir)
+    elif module == "mcp_server.hooks.session_start":
+        _ensure_all_deps(deps_dir)
+
+    # Change to plugin root
+    os.chdir(plugin_root)
+
+    # Run the target module
+    sys.argv = [module] + [a for a in sys.argv[2:] if a != "--install-deps"]
+    try:
+        from runpy import run_module
+
+        run_module(module, run_name="__main__", alter_sys=True)
+    except SystemExit:
+        raise
+    except Exception as e:
+        print(f"[cortex-launcher] Failed to run {module}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()