nexo-brain 5.3.1 → 5.3.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.1",
+  "version": "5.3.2",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -87,6 +87,8 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
+Version `5.3.2` hardens the packaged runtime boundary: NEXO now persists which runtime scripts/hooks are core product artifacts, `nexo scripts` no longer mixes those into the personal bucket, and `nexo update` migrates the legacy Claude Code heartbeat wrappers into managed core hooks.
+
 Version `5.3.1` normalizes packaged npm installs so they behave like packaged npm installs: `nexo update` now keeps the runtime anchored to `~/.nexo`, refreshes packaged bootstrap/client artifacts after upgrade, avoids repo-only release-artifact drift in installed runtimes, and keeps personal scripts on the canonical packaged path.
 
 Version `5.3.0` adds `nexo uninstall` — a CLI command that cleanly separates runtime from user data. It stops all crons, removes the MCP server config, and preserves databases, learnings, and personal scripts for safe reinstall.

package/bin/nexo-brain.js

@@ -93,6 +93,33 @@ function syncWatchdogHashRegistry(nexoHome) {
   }
 }
 
+function writeRuntimeCoreArtifactsManifest(nexoHome, srcDir) {
+  try {
+    const listTopLevelFiles = (dirPath) => {
+      if (!fs.existsSync(dirPath)) return [];
+      return fs.readdirSync(dirPath)
+        .filter((name) => {
+          const full = path.join(dirPath, name);
+          return fs.existsSync(full) && fs.statSync(full).isFile();
+        })
+        .sort();
+    };
+    const configDir = path.join(nexoHome, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    const payload = {
+      generated_at: new Date().toISOString(),
+      script_names: listTopLevelFiles(path.join(srcDir, "scripts")),
+      hook_names: listTopLevelFiles(path.join(srcDir, "hooks")),
+    };
+    fs.writeFileSync(
+      path.join(configDir, "runtime-core-artifacts.json"),
+      `${JSON.stringify(payload, null, 2)}\n`
+    );
+  } catch (err) {
+    log(`WARN: could not write runtime core-artifacts manifest: ${err.message}`);
+  }
+}
+
 function getCoreRuntimeFlatFiles() {
   return [
     "server.py",
@@ -1538,6 +1565,7 @@ async function main() {
             fs.chmodSync(path.join(scriptsDest, f), "755");
           });
         }
+        writeRuntimeCoreArtifactsManifest(NEXO_HOME, srcDir);
         log("  Scripts updated.");
 
         // Register ALL 8 core hooks in settings.json (additive — don't remove user's custom hooks)
@@ -2359,6 +2387,7 @@ async function main() {
     });
     log("  Hooks installed.");
   }
+  writeRuntimeCoreArtifactsManifest(NEXO_HOME, srcDir);
 
   // Generate personality
   const personality = `# ${operatorName} — Personality

package/hooks/hooks.json

@@ -50,6 +50,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/heartbeat-user-msg.sh\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",
@@ -73,6 +85,11 @@
             "type": "command",
             "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/protocol-guardrail.sh\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/heartbeat-posttool.sh\"",
+            "timeout": 3
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.1",
+  "version": "5.3.2",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/auto_update.py

@@ -359,6 +359,10 @@ def _cleanup_retired_runtime_files():
     """Remove retired core files that should not survive updates."""
     retired = [
         NEXO_HOME / "scripts" / "nexo-day-orchestrator.sh",
+        NEXO_HOME / "scripts" / "heartbeat-enforcement.py",
+        NEXO_HOME / "scripts" / "heartbeat-posttool.sh",
+        NEXO_HOME / "scripts" / "heartbeat-user-msg.sh",
+        NEXO_HOME / "hooks" / "heartbeat-guard.sh",
     ]
     for target in retired:
         try:

package/src/client_sync.py

@@ -349,6 +349,12 @@ CORE_HOOK_SPECS = [
         "timeout": 5,
         "script": "protocol-pretool-guardrail.sh",
     },
+    {
+        "event": "UserPromptSubmit",
+        "identity": "heartbeat-user-msg.sh",
+        "timeout": 3,
+        "script": "heartbeat-user-msg.sh",
+    },
     {
         "event": "PostToolUse",
         "identity": "capture-tool-logs.sh",
@@ -373,6 +379,12 @@ CORE_HOOK_SPECS = [
         "timeout": 5,
         "script": "protocol-guardrail.sh",
     },
+    {
+        "event": "PostToolUse",
+        "identity": "heartbeat-posttool.sh",
+        "timeout": 3,
+        "script": "heartbeat-posttool.sh",
+    },
     {
         "event": "PreCompact",
         "identity": "pre-compact.sh",

package/src/hooks/heartbeat-enforcement.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Heartbeat enforcement for NEXO sessions.
+
+Tracks user messages vs heartbeat calls. Emits a warning when more than two
+user messages pass without a heartbeat call.
+
+Modes:
+- HEARTBEAT_MODE=user_msg: increment counter on UserPromptSubmit
+- HEARTBEAT_MODE=post_tool: inspect PostToolUse payload, reset on heartbeat,
+  warn when other tools keep running without one
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+STATE_FILE = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo")) / "operations" / ".heartbeat-state.json"
+THRESHOLD = 2
+HEARTBEAT_TOOL = "nexo_heartbeat"
+SKIP_TOOLS = {"nexo_startup", "nexo_stop", "nexo_smart_startup"}
+
+
+def _read_state() -> dict:
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except Exception:
+        return {"user_msgs": 0, "last_heartbeat_ts": 0.0, "last_user_msg_ts": 0.0}
+
+
+def _write_state(state: dict) -> None:
+    try:
+        STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        STATE_FILE.write_text(json.dumps(state))
+    except Exception:
+        pass
+
+
+def handle_user_message() -> int:
+    state = _read_state()
+    state["user_msgs"] = state.get("user_msgs", 0) + 1
+    state["last_user_msg_ts"] = time.time()
+    _write_state(state)
+    return 0
+
+
+def handle_post_tool(payload: dict) -> int:
+    tool_name = str(payload.get("tool_name", "")).strip()
+    short_name = tool_name.rsplit("__", 1)[-1] if "__" in tool_name else tool_name
+    state = _read_state()
+
+    if short_name == HEARTBEAT_TOOL:
+        state["user_msgs"] = 0
+        state["last_heartbeat_ts"] = time.time()
+        _write_state(state)
+        return 0
+
+    if short_name in SKIP_TOOLS:
+        return 0
+
+    user_msgs = state.get("user_msgs", 0)
+    if user_msgs > THRESHOLD:
+        print(
+            f"\nWARNING: HEARTBEAT OVERDUE ({user_msgs} user messages without nexo_heartbeat). "
+            "Call nexo_heartbeat(sid=SID, task='...') before continuing."
+        )
+    return 0
+
+
+def main() -> int:
+    mode = os.environ.get("HEARTBEAT_MODE", "").strip()
+    if mode == "user_msg":
+        return handle_user_message()
+    if mode == "post_tool":
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return 0
+        try:
+            payload = json.loads(raw)
+        except Exception:
+            return 0
+        return handle_post_tool(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/hooks/heartbeat-posttool.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# NEXO PostToolUse hook — heartbeat enforcement checker
+set -uo pipefail
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+HELPER=""
+if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="${NEXO_CODE%/}/hooks/heartbeat-enforcement.py"
+elif [ -f "$NEXO_HOME/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="$NEXO_HOME/hooks/heartbeat-enforcement.py"
+fi
+
+[ -z "$HELPER" ] && exit 0
+HEARTBEAT_MODE=post_tool python3 "$HELPER" <<< "$INPUT" 2>/dev/null || true
+exit 0

package/src/hooks/heartbeat-user-msg.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# NEXO UserPromptSubmit hook — track user messages for heartbeat enforcement
+set -uo pipefail
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+HELPER=""
+if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="${NEXO_CODE%/}/hooks/heartbeat-enforcement.py"
+elif [ -f "$NEXO_HOME/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="$NEXO_HOME/hooks/heartbeat-enforcement.py"
+fi
+
+[ -z "$HELPER" ] && exit 0
+HEARTBEAT_MODE=user_msg python3 "$HELPER" 2>/dev/null || true
+exit 0

package/src/plugins/update.py

@@ -81,7 +81,7 @@ def _is_git_repo() -> bool:
 
 
 def _refresh_installed_manifest():
-    """Copy source crons/ to NEXO_HOME/crons/ so catchup & watchdog stay current."""
+    """Refresh packaged crons and persist the runtime core-artifacts manifest."""
     try:
         src_crons = SRC_DIR / "crons"
         dst_crons = NEXO_HOME / "crons"
@@ -90,10 +90,45 @@ def _refresh_installed_manifest():
             for f in src_crons.iterdir():
                 if f.is_file():
                     shutil.copy2(str(f), str(dst_crons / f.name))
+        config_dir = NEXO_HOME / "config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "script_names": sorted(
+                f.name for f in (SRC_DIR / "scripts").iterdir()
+                if f.is_file()
+            ) if (SRC_DIR / "scripts").is_dir() else [],
+            "hook_names": sorted(
+                f.name for f in (SRC_DIR / "hooks").iterdir()
+                if f.is_file()
+            ) if (SRC_DIR / "hooks").is_dir() else [],
+        }
+        (config_dir / "runtime-core-artifacts.json").write_text(
+            json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+        )
     except Exception:
         pass
 
 
+def _cleanup_retired_runtime_files() -> list[str]:
+    removed: list[str] = []
+    retired_paths = [
+        NEXO_HOME / "scripts" / "heartbeat-enforcement.py",
+        NEXO_HOME / "scripts" / "heartbeat-posttool.sh",
+        NEXO_HOME / "scripts" / "heartbeat-user-msg.sh",
+        NEXO_HOME / "hooks" / "heartbeat-guard.sh",
+    ]
+    for path in retired_paths:
+        if not path.exists():
+            continue
+        try:
+            path.unlink()
+            removed.append(str(path))
+        except Exception:
+            continue
+    return removed
+
+
 def _read_version() -> str:
     """Read the installed/runtime version."""
     if _PACKAGED_INSTALL:
@@ -546,10 +581,12 @@ def _handle_packaged_update(progress_fn=None) -> str:
         errors.append(f"verification: {verify_err}")
 
     hook_sync_warning = None
+    retired_runtime_files: list[str] = []
     try:
         _emit_progress(progress_fn, "Refreshing installed hooks and manifests...")
         _refresh_installed_manifest()
         _sync_hooks_to_home()
+        retired_runtime_files = _cleanup_retired_runtime_files()
     except Exception as e:
         hook_sync_warning = f"{e}"
 
@@ -599,6 +636,8 @@ def _handle_packaged_update(progress_fn=None) -> str:
         lines.append("  Hooks: synced to NEXO_HOME")
     else:
         lines.append(f"  WARNING: hook sync: {hook_sync_warning}")
+    if retired_runtime_files:
+        lines.append(f"  Cleanup: removed {len(retired_runtime_files)} retired runtime file(s)")
     if not client_sync_warning:
         lines.append("  Clients: configured client targets synced")
     else:
@@ -714,9 +753,11 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
             cron_sync_result = f"Cron sync warning: {e}"
 
         # Step 9: Sync hooks to NEXO_HOME
+        retired_runtime_files: list[str] = []
         try:
             _emit_progress(progress_fn, "Syncing core Claude hooks...")
             _sync_hooks_to_home()
+            retired_runtime_files = _cleanup_retired_runtime_files()
             steps_done.append("hook-sync")
         except Exception as e:
             pass  # Non-critical, log in function
@@ -768,6 +809,8 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
             lines.append("  Crons: synced with manifest")
         if "hook-sync" in steps_done:
             lines.append("  Hooks: synced to NEXO_HOME")
+        if retired_runtime_files:
+            lines.append(f"  Cleanup: removed {len(retired_runtime_files)} retired runtime file(s)")
         if "client-sync" in steps_done:
             lines.append("  Clients: configured client targets synced")
         lines.append("")

package/src/script_registry.py

@@ -44,6 +44,14 @@ _LEGACY_WAKE_RECOVERY_METADATA = [
     "# nexo: run_on_boot=true",
 ]
 
+_LEGACY_CORE_RUNTIME_FILES = {
+    "capture-tool-logs.sh",
+    "daily-briefing-check.sh",
+    "heartbeat-enforcement.py",
+    "heartbeat-posttool.sh",
+    "heartbeat-user-msg.sh",
+}
+
 # Forbidden patterns — direct DB access from personal scripts
 _FORBIDDEN_PATTERNS = [
     re.compile(r"\bsqlite3\b"),
@@ -119,7 +127,7 @@ def _apply_legacy_personal_script_backfills() -> None:
 
 
 def load_core_script_names() -> set[str]:
-    """Load script names from crons/manifest.json (these are core, not personal)."""
+    """Load runtime-managed script names (core, not personal)."""
     names: set[str] = set()
     for manifest_path in [NEXO_CODE / "crons" / "manifest.json", NEXO_HOME / "crons" / "manifest.json"]:
         if manifest_path.exists():
@@ -132,6 +140,26 @@ def load_core_script_names() -> set[str]:
                 break
             except Exception:
                 continue
+    runtime_manifest = NEXO_HOME / "config" / "runtime-core-artifacts.json"
+    if runtime_manifest.exists():
+        try:
+            data = json.loads(runtime_manifest.read_text())
+            for key in ("script_names", "hook_names"):
+                for name in data.get(key, []):
+                    clean = Path(str(name)).name
+                    if clean:
+                        names.add(clean)
+        except Exception:
+            pass
+    hooks_dir = NEXO_HOME / "hooks"
+    if hooks_dir.is_dir():
+        try:
+            for item in hooks_dir.iterdir():
+                if item.is_file():
+                    names.add(item.name)
+        except Exception:
+            pass
+    names.update(_LEGACY_CORE_RUNTIME_FILES)
     return names
 
 

package/templates/launchagents/README.md

@@ -112,7 +112,6 @@ These agents power NEXO's learning and memory systems. Strongly recommended.
 | File | Schedule | What it does |
 |------|----------|-------------|
 | `com.nexo.dashboard.plist` | Persistent (KeepAlive) | Runs the NEXO web dashboard on `http://localhost:6174`. Provides a browser-based view of sessions, reminders, followups, and system health. Only needed if you want the dashboard UI. |
-| `com.nexo.github-monitor.plist` | Daily 08:00 | Checks the NEXO public GitHub repository for open issues, pull requests, and pending releases. Writes results to `~/.nexo/github-status.json` for NEXO to read at startup. Only relevant if you maintain the public NEXO repository. |
 
 ---
 

package/templates/launchagents/com.nexo.github-monitor.plist

@@ -1,45 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- com.nexo.github-monitor
-     Runs nexo-github-monitor.py every day at 08:00 to check the NEXO
-     public GitHub repository for new issues, pull requests, and pending
-     releases. Writes results to ~/.nexo/github-status.json. At the next
-     session startup, NEXO reads this file and responds to open issues,
-     reviews PRs, and proposes a release if enough commits have
-     accumulated since the last tag.
--->
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.nexo.github-monitor</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/usr/bin/python3</string>
-        <string>{{NEXO_HOME}}/scripts/nexo-github-monitor.py</string>
-    </array>
-    <key>StartCalendarInterval</key>
-    <dict>
-        <key>Hour</key>
-        <integer>8</integer>
-        <key>Minute</key>
-        <integer>0</integer>
-    </dict>
-    <key>StandardOutPath</key>
-    <string>{{NEXO_HOME}}/logs/github-monitor-stdout.log</string>
-    <key>StandardErrorPath</key>
-    <string>{{NEXO_HOME}}/logs/github-monitor-stderr.log</string>
-    <key>EnvironmentVariables</key>
-    <dict>
-        <key>HOME</key>
-        <string>{{HOME}}</string>
-        <key>NEXO_HOME</key>
-        <string>{{NEXO_HOME}}</string>
-        <key>NEXO_CODE</key>
-        <string>{{NEXO_CODE}}</string>
-        <key>PATH</key>
-        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
-    </dict>
-    <key>RunAtLoad</key>
-    <false/>
-</dict>
-</plist>