nexo-brain 7.30.31 → 7.30.32

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.30.31",
+  "version": "7.30.32",
   "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

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.30.31` is the current packaged-runtime line. Patch release over v7.30.30 - Core Rules now reach agents both through a compact managed bootstrap summary and task-specific `cortex/task_open` injection from the protected `core_rules` registry.
+Version `7.30.32` is the current packaged-runtime line. Patch release over v7.30.31 - packaged update/doctor now repair npm/npx wrapper drift, archive stale personal script backups, validate observable automation health contracts, and block legacy Claude/Codex project memory writes.
+
+Previously in `7.30.31`: patch release over v7.30.30 - Core Rules now reach agents both through a compact managed bootstrap summary and task-specific `cortex/task_open` injection from the protected `core_rules` registry.
 
 Previously in `7.30.30`: product-managed Core Rules now sync from `src/rules/core-rules.json` into protected DB rows for bootstrap and product behavior, with provenance, hashes, severity, and install/update synchronization.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.30.31",
+  "version": "7.30.32",
   "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/doctor/providers/runtime.py

@@ -2016,9 +2016,14 @@ def check_personal_script_registry(fix: bool = False) -> DoctorCheck:
     """Check the DB-backed personal script registry against filesystem/plists."""
     try:
         from db import init_db, get_personal_script_health_report
-        from script_registry import repair_orphan_personal_schedule_metadata, sync_personal_scripts
+        from script_registry import (
+            archive_ignored_personal_script_artifacts,
+            repair_orphan_personal_schedule_metadata,
+            sync_personal_scripts,
+        )
 
         init_db()
+        backup_cleanup = archive_ignored_personal_script_artifacts(dry_run=not fix)
         if fix:
             repair_orphan_personal_schedule_metadata(dry_run=False)
         sync_personal_scripts(prune_missing=True)
@@ -2032,7 +2037,17 @@ def check_personal_script_registry(fix: bool = False) -> DoctorCheck:
             summary=f"Personal scripts registry check failed: {e}",
         )
 
-    issues = report.get("issues", [])
+    issues = list(report.get("issues", []))
+    backup_candidates = backup_cleanup.get("candidates", []) if isinstance(backup_cleanup, dict) else []
+    backup_archived = backup_cleanup.get("archived", []) if isinstance(backup_cleanup, dict) else []
+    if backup_candidates and not fix:
+        issues.append({
+            "severity": "warn",
+            "message": (
+                f"{len(backup_candidates)} ignored personal script backup artifact(s) still carry NEXO metadata; "
+                "doctor --fix will archive them outside personal/scripts"
+            ),
+        })
     if not issues:
         audit = report.get("schedule_audit", {}).get("summary", {})
         summary = (
@@ -2047,6 +2062,8 @@ def check_personal_script_registry(fix: bool = False) -> DoctorCheck:
             )
         if fix:
             summary += " (fixed)"
+        if backup_archived:
+            summary += f", archived {len(backup_archived)} stale backup artifact(s)"
         return DoctorCheck(
             id="runtime.personal_scripts",
             tier="runtime",
@@ -2079,6 +2096,103 @@ def check_personal_script_registry(fix: bool = False) -> DoctorCheck:
     )
 
 
+def _truthy_metadata(value) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _metadata_int(value, fallback: int = 0) -> int:
+    try:
+        return int(str(value or "").strip())
+    except Exception:
+        return fallback
+
+
+def _resolve_personal_health_path(raw: str) -> Path:
+    path = Path(str(raw or "").strip()).expanduser()
+    if path.is_absolute():
+        return path
+    return NEXO_HOME / path
+
+
+def check_personal_automation_health_contracts() -> DoctorCheck:
+    """Check observable success contracts for scheduled personal automations."""
+    try:
+        from script_registry import list_scripts
+        scripts = list_scripts(include_core=False)
+    except Exception as exc:
+        return DoctorCheck(
+            id="runtime.personal_automation_health",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary=f"Personal automation health check failed: {exc}",
+        )
+
+    issues: list[str] = []
+    checked = 0
+    scheduled = 0
+    now = time.time()
+    for script in scripts:
+        metadata = script.get("metadata") if isinstance(script.get("metadata"), dict) else {}
+        declared = script.get("declared_schedule") if isinstance(script.get("declared_schedule"), dict) else {}
+        if not declared.get("required"):
+            continue
+        scheduled += 1
+        name = str(script.get("name") or metadata.get("name") or Path(str(script.get("path") or "")).name)
+        health_file_raw = str(metadata.get("health_file") or "").strip()
+        if not health_file_raw:
+            issues.append(f"{name}: scheduled automation has no health_file contract")
+            continue
+        checked += 1
+        health_file = _resolve_personal_health_path(health_file_raw)
+        if not health_file.is_file():
+            issues.append(f"{name}: health_file missing ({health_file})")
+            continue
+        try:
+            stat = health_file.stat()
+            content = health_file.read_text(errors="ignore")
+        except Exception as exc:
+            issues.append(f"{name}: health_file unreadable ({exc})")
+            continue
+        max_age = _metadata_int(metadata.get("health_max_age_seconds"), 0)
+        if max_age > 0 and now - stat.st_mtime > max_age:
+            issues.append(f"{name}: health_file stale ({int(now - stat.st_mtime)}s > {max_age}s)")
+        if _truthy_metadata(metadata.get("health_nonempty")) and not content.strip():
+            issues.append(f"{name}: health_file is empty")
+        must_contain = str(metadata.get("health_must_contain") or "").strip()
+        if must_contain and must_contain not in content:
+            issues.append(f"{name}: health_file does not contain required marker `{must_contain}`")
+
+    if not issues:
+        return DoctorCheck(
+            id="runtime.personal_automation_health",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary=f"Scheduled personal automation health contracts OK ({checked}/{scheduled} checked)",
+        )
+
+    return DoctorCheck(
+        id="runtime.personal_automation_health",
+        tier="runtime",
+        status="degraded",
+        severity="warn",
+        summary=f"Personal automation health contract issues detected in {len(issues)} item(s)",
+        evidence=issues[:12],
+        repair_plan=[
+            "Add `# nexo: health_file=...` to scheduled personal automations that must prove useful output",
+            "Use `health_max_age_seconds`, `health_nonempty=true`, or `health_must_contain=...` for semantic success checks",
+            "Run `nexo doctor --tier runtime` after updates to catch stale or missing automation outputs",
+        ],
+        escalation_prompt=(
+            "Scheduled personal automations need observable success contracts; a cron exit code alone is not enough "
+            "to know that useful work happened."
+        ),
+    )
+
+
 def check_client_backend_preferences(fix: bool = False) -> DoctorCheck:
     schedule = {}
     try:
@@ -2212,6 +2326,60 @@ def check_client_backend_preferences(fix: bool = False) -> DoctorCheck:
     )
 
 
+def check_packaged_update_npm_toolchain(fix: bool = False) -> DoctorCheck:
+    """Verify the npm runtime used by packaged Brain updates can actually run."""
+    try:
+        from plugins.update import packaged_npm_toolchain_status
+        status = packaged_npm_toolchain_status(repair=fix)
+    except Exception as exc:
+        return DoctorCheck(
+            id="runtime.packaged_update_npm",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary=f"Packaged update npm check failed: {exc}",
+        )
+
+    attempts = status.get("attempts") if isinstance(status, dict) else []
+    evidence: list[str] = []
+    for item in (attempts[:6] if isinstance(attempts, list) else []):
+        cmd = " ".join(str(part) for part in (item.get("cmd") or []))
+        if item.get("ok"):
+            evidence.append(f"ok: {cmd}")
+        else:
+            evidence.append(f"failed: {cmd}: {item.get('error') or 'unknown error'}")
+
+    repaired = status.get("repaired") if isinstance(status, dict) else []
+    if status.get("ok"):
+        summary = "Packaged update npm runtime is healthy"
+        if repaired:
+            summary += f" (repaired wrappers: {', '.join(str(item) for item in repaired)})"
+        return DoctorCheck(
+            id="runtime.packaged_update_npm",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary=summary,
+            evidence=evidence,
+            fixed=bool(fix and repaired),
+        )
+
+    return DoctorCheck(
+        id="runtime.packaged_update_npm",
+        tier="runtime",
+        status="critical",
+        severity="error",
+        summary="Packaged update cannot find a healthy npm runtime",
+        evidence=evidence,
+        repair_plan=[
+            "Run `nexo doctor --tier runtime --fix` to repair NEXO npm/npx wrappers when a healthy Node/npm exists",
+            "Install Node.js or restore an nvm Node version if no healthy npm candidate exists",
+            "Retry `nexo update` after the npm runtime check is healthy",
+        ],
+        escalation_prompt="Packaged Brain update cannot run npm safely; repair the local Node/npm runtime before updating.",
+    )
+
+
 def check_client_bootstrap_parity(fix: bool = False) -> DoctorCheck:
     """Check managed Claude/Codex bootstrap documents and CORE/USER markers."""
     try:
@@ -4137,6 +4305,7 @@ def run_runtime_checks(fix: bool = False, plane: str = "") -> list[DoctorCheck]:
         safe_check(check_stale_sessions),
         safe_check(check_cron_freshness),
         safe_check(check_client_backend_preferences, fix=fix),
+        safe_check(check_packaged_update_npm_toolchain, fix=fix),
         safe_check(check_client_bootstrap_parity, fix=fix),
         safe_check(check_codex_session_parity),
         safe_check(check_bootstrap_reached_startup),
@@ -4156,6 +4325,7 @@ def run_runtime_checks(fix: bool = False, plane: str = "") -> list[DoctorCheck]:
         safe_check(check_launchagent_inventory),
         safe_check(check_launchagent_integrity, fix=fix),
         safe_check(check_personal_script_registry, fix=fix),
+        safe_check(check_personal_automation_health_contracts),
         safe_check(check_skill_health, fix=fix),
     ]
     return _filter_runtime_checks_for_plane(checks, plane=plane)

package/src/hook_guardrails.py

@@ -575,6 +575,14 @@ def _is_legacy_client_memory_path(path_value: str) -> bool:
         return True
     if len(parts) >= 2 and parts[0] in {".claude", ".codex"} and parts[1] == "memories":
         return True
+    if (
+        len(parts) >= 5
+        and parts[0] in {".claude", ".codex"}
+        and parts[1] == "projects"
+        and parts[-2] == "memory"
+        and parts[-1] == "MEMORY.md"
+    ):
+        return True
     return False
 
 

package/src/plugins/update.py

@@ -410,6 +410,142 @@ def _apply_desktop_npm_prefix(env: dict[str, str]) -> None:
     env["PATH"] = os.pathsep.join([prefix_bin, *[entry for entry in entries if entry != prefix_bin]])
 
 
+def _prepend_path(env: dict[str, str], directory: Path | str) -> None:
+    directory = Path(directory)
+    if not str(directory):
+        return
+    current_path = str(env.get("PATH", ""))
+    entries = [entry for entry in current_path.split(os.pathsep) if entry]
+    directory_text = str(directory)
+    env["PATH"] = os.pathsep.join([directory_text, *[entry for entry in entries if entry != directory_text]])
+
+
+def _candidate_npm_paths() -> list[Path]:
+    candidates: list[Path] = []
+    seen: set[str] = set()
+
+    def add(candidate: str | Path | None) -> None:
+        if not candidate:
+            return
+        path = Path(str(candidate)).expanduser()
+        key = str(path)
+        if key in seen:
+            return
+        seen.add(key)
+        candidates.append(path)
+
+    add(shutil.which("npm"))
+    for base in (
+        Path("/opt/homebrew/bin/npm"),
+        Path("/usr/local/bin/npm"),
+        Path.home() / ".nexo" / "bin" / "npm",
+    ):
+        add(base)
+    nvm_root = Path.home() / ".nvm" / "versions" / "node"
+    if nvm_root.is_dir():
+        for npm_path in sorted(nvm_root.glob("*/bin/npm"), reverse=True):
+            add(npm_path)
+    return candidates
+
+
+def _npm_probe(cmd: list[str], env: dict[str, str]) -> dict:
+    evidence: list[str] = []
+    try:
+        version = subprocess.run([*cmd, "--version"], env=env, capture_output=True, text=True, timeout=10)
+    except FileNotFoundError as exc:
+        return {"ok": False, "error": f"not found: {exc}", "evidence": evidence}
+    except Exception as exc:
+        return {"ok": False, "error": str(exc), "evidence": evidence}
+    evidence.append(f"npm --version rc={version.returncode} out={str(version.stdout or version.stderr).strip()[:160]}")
+    if version.returncode != 0:
+        return {"ok": False, "error": str(version.stderr or version.stdout).strip()[:300], "evidence": evidence}
+    try:
+        root = subprocess.run([*cmd, "root", "-g"], env=env, capture_output=True, text=True, timeout=10)
+    except Exception as exc:
+        return {"ok": False, "error": f"npm root -g failed: {exc}", "evidence": evidence}
+    evidence.append(f"npm root -g rc={root.returncode} out={str(root.stdout or root.stderr).strip()[:160]}")
+    if root.returncode != 0:
+        return {"ok": False, "error": str(root.stderr or root.stdout).strip()[:300], "evidence": evidence}
+    return {"ok": True, "error": "", "evidence": evidence}
+
+
+def _write_nexo_bin_wrapper(wrapper: Path, target: Path) -> bool:
+    if not target.exists():
+        return False
+    content = f'#!/bin/sh\nexec "{target}" "$@"\n'
+    try:
+        if wrapper.exists() and wrapper.read_text(errors="ignore") == content:
+            return False
+    except Exception:
+        pass
+    wrapper.parent.mkdir(parents=True, exist_ok=True)
+    if wrapper.exists():
+        backup_dir = NEXO_HOME / "runtime" / "backups" / "npm-shim-repair"
+        backup_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(wrapper, backup_dir / f"{int(time.time())}-{wrapper.name}")
+    wrapper.write_text(content)
+    wrapper.chmod(0o755)
+    return True
+
+
+def _repair_nexo_npm_wrappers(selected_npm: Path | None) -> list[str]:
+    if not selected_npm:
+        return []
+    selected_bin = selected_npm.parent
+    repaired: list[str] = []
+    wrapper_dir = NEXO_HOME / "bin"
+    for name in ("npm", "npx"):
+        target = selected_bin / name
+        if _write_nexo_bin_wrapper(wrapper_dir / name, target):
+            repaired.append(name)
+    return repaired
+
+
+def packaged_npm_toolchain_status(*, repair: bool = False) -> dict:
+    """Resolve a healthy npm invocation for packaged update/doctor paths."""
+    default_cmd, default_env = _npm_command_parts()
+    attempts: list[dict] = []
+    default_probe = _npm_probe(default_cmd, default_env)
+    attempts.append({"cmd": default_cmd, **default_probe})
+    if default_probe.get("ok"):
+        return {"ok": True, "cmd": default_cmd, "env": default_env, "attempts": attempts, "repaired": []}
+
+    for npm_path in _candidate_npm_paths():
+        if not npm_path.exists():
+            continue
+        env = dict(os.environ)
+        _prepend_path(env, npm_path.parent)
+        probe = _npm_probe([str(npm_path)], env)
+        attempts.append({"cmd": [str(npm_path)], **probe})
+        if not probe.get("ok"):
+            continue
+        repaired = _repair_nexo_npm_wrappers(npm_path) if repair else []
+        if repaired:
+            # Re-probe through the normal path after repair so updates use the
+            # same command a fresh shell will resolve.
+            refreshed_cmd, refreshed_env = _npm_command_parts()
+            refreshed_probe = _npm_probe(refreshed_cmd, refreshed_env)
+            attempts.append({"cmd": refreshed_cmd, **refreshed_probe, "after_repair": True})
+            if refreshed_probe.get("ok"):
+                return {
+                    "ok": True,
+                    "cmd": refreshed_cmd,
+                    "env": refreshed_env,
+                    "attempts": attempts,
+                    "repaired": repaired,
+                }
+        return {"ok": True, "cmd": [str(npm_path)], "env": env, "attempts": attempts, "repaired": repaired}
+
+    return {
+        "ok": False,
+        "cmd": default_cmd,
+        "env": default_env,
+        "attempts": attempts,
+        "repaired": [],
+        "error": "No healthy npm runtime found.",
+    }
+
+
 def _run_npm(args: list[str], **kwargs):
     cmd, env = _npm_command_parts()
     extra_env = kwargs.pop("env", None)
@@ -1377,6 +1513,18 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
     if wipe_err:
         return f"ABORTED (wipe guard): {wipe_err}"
 
+    _emit_progress(progress_fn, "Checking npm runtime for packaged update...")
+    npm_status = packaged_npm_toolchain_status(repair=True)
+    if not npm_status.get("ok"):
+        attempts = "; ".join(
+            f"{' '.join(item.get('cmd') or [])}: {item.get('error') or 'failed'}"
+            for item in npm_status.get("attempts", [])[:6]
+            if isinstance(item, dict)
+        )
+        return f"ABORTED: npm runtime unavailable. {attempts or npm_status.get('error') or 'No npm candidate worked.'}"
+    npm_cmd = list(npm_status.get("cmd") or ["npm"])
+    npm_env = dict(npm_status.get("env") or os.environ)
+
     # 1. Backup databases BEFORE any changes
     _emit_progress(progress_fn, "Backing up runtime databases...")
     backup_dir, backup_err = _backup_databases()
@@ -1395,10 +1543,11 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
     # 3. Run npm update (postinstall.js will migrate NEXO_HOME in-place)
     try:
         _emit_progress(progress_fn, "Downloading and applying the latest npm package...")
-        result = _run_npm(
-            ["install", "-g", "nexo-brain@latest"],
+        install_env = {**npm_env, "NEXO_HOME": str(NEXO_HOME)}
+        result = subprocess.run(
+            [*npm_cmd, "install", "-g", "nexo-brain@latest"],
             capture_output=True, text=True, timeout=120,
-            env={**os.environ, "NEXO_HOME": str(NEXO_HOME)},
+            env=install_env,
         )
         if result.returncode != 0:
             # npm failed (including postinstall failures) — full rollback

package/src/script_registry.py

@@ -102,6 +102,10 @@ METADATA_KEYS = {
     "agent_archived",
     "agent_enabled_before_archive",
     "agent_icon",
+    "health_file",
+    "health_max_age_seconds",
+    "health_nonempty",
+    "health_must_contain",
 }
 AGENT_METADATA_KEYS = {
     "agent",
@@ -125,6 +129,10 @@ METADATA_WRITE_ORDER = [
     "agent_archived",
     "agent_enabled_before_archive",
     "agent_icon",
+    "health_file",
+    "health_max_age_seconds",
+    "health_nonempty",
+    "health_must_contain",
     "cron_id",
     "schedule_required",
     "schedule",
@@ -179,6 +187,10 @@ PRODUCT_AUTOMATION_NAMES = (
     "followup-runner",
     "morning-agent",
 )
+_BACKUP_ARTIFACT_RE = re.compile(
+    r"(?:\.bak(?:[-.][\w.-]+)?|\.backup(?:[-.][\w.-]+)?|\.old(?:[-.][\w.-]+)?)$",
+    re.IGNORECASE,
+)
 
 
 def get_nexo_home() -> Path:
@@ -531,7 +543,7 @@ def _is_ignored(path: Path) -> bool:
     """Check if file should be ignored entirely."""
     if path.name in _IGNORED_FILES:
         return True
-    if re.search(r"\.bak(?:-[\w.-]+)?$", path.name, re.IGNORECASE):
+    if _BACKUP_ARTIFACT_RE.search(path.name):
         return True
     if path.name.endswith("~"):
         return True
@@ -547,6 +559,38 @@ def _is_ignored(path: Path) -> bool:
     return False
 
 
+def archive_ignored_personal_script_artifacts(*, dry_run: bool = True) -> dict:
+    """Move ignored backup artifacts with NEXO metadata out of personal/scripts."""
+    scripts_dir = get_scripts_dir()
+    result = {"ok": True, "candidates": [], "archived": [], "errors": []}
+    if not scripts_dir.is_dir():
+        return result
+    backup_root = paths.backups_dir() / "personal-script-backups"
+    for path in sorted(scripts_dir.iterdir()):
+        if not path.is_file() or not _BACKUP_ARTIFACT_RE.search(path.name):
+            continue
+        meta = parse_inline_metadata(path)
+        if not meta:
+            continue
+        item = {"path": str(path), "name": str(meta.get("name") or path.name)}
+        result["candidates"].append(item)
+        if dry_run:
+            continue
+        try:
+            backup_root.mkdir(parents=True, exist_ok=True)
+            target = backup_root / f"{int(time.time())}-{path.name}"
+            counter = 1
+            while target.exists():
+                target = backup_root / f"{int(time.time())}-{counter}-{path.name}"
+                counter += 1
+            shutil.move(str(path), str(target))
+            result["archived"].append({**item, "backup_path": str(target)})
+        except Exception as exc:
+            result["ok"] = False
+            result["errors"].append({"path": str(path), "error": str(exc)})
+    return result
+
+
 def _is_script_candidate(path: Path, metadata: dict | None = None) -> bool:
     metadata = metadata or {}
     runtime = classify_runtime(path, metadata)