nexo-brain 5.3.0 → 5.3.2

package/src/script_registry.py

@@ -16,7 +16,9 @@ import stat
 import subprocess
 from pathlib import Path
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+from runtime_home import export_resolved_nexo_home
+
+NEXO_HOME = export_resolved_nexo_home()
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
 
 # Internal artifacts to always ignore
@@ -42,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"),
@@ -73,6 +83,7 @@ METADATA_KEYS = {
     "run_on_wake",
     "idempotent",
     "max_catchup_age",
+    "doctor_allow_db",
 }
 SUPPORTED_RUNTIMES = {"python", "shell", "node", "php", "unknown"}
 PERSONAL_SCHEDULE_MANAGED_ENV = "NEXO_MANAGED_PERSONAL_CRON"
@@ -116,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():
@@ -129,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
 
 
@@ -213,7 +244,11 @@ def _is_ignored(path: Path) -> bool:
         return True
     if path.name.startswith("."):
         return True
-    for parent in path.relative_to(get_scripts_dir()).parents:
+    try:
+        relative_path = path.resolve().relative_to(get_scripts_dir().resolve())
+    except Exception:
+        return False
+    for parent in relative_path.parents:
         if parent.name in _IGNORED_DIRS:
             return True
     return False
@@ -1425,14 +1460,19 @@ def doctor_script(path_or_name: str) -> dict:
             elif cmd:
                 items.append({"level": "pass", "msg": f"Required command found: {cmd}"})
 
+    allow_db_access = str(meta.get("doctor_allow_db", "")).strip().lower() in {"1", "true", "yes", "on"}
+    if allow_db_access:
+        items.append({"level": "pass", "msg": "Doctor DB access explicitly allowed"})
+
     # Forbidden patterns (only for personal scripts)
     if not is_core:
         try:
             content = p.read_text(errors="ignore")
-            for pat in _FORBIDDEN_PATTERNS:
-                match = pat.search(content)
-                if match:
-                    items.append({"level": "fail", "msg": f"Forbidden DB pattern found: {match.group()}"})
+            if not allow_db_access:
+                for pat in _FORBIDDEN_PATTERNS:
+                    match = pat.search(content)
+                    if match:
+                        items.append({"level": "fail", "msg": f"Forbidden DB pattern found: {match.group()}"})
         except Exception:
             pass
 

package/src/scripts/nexo-cognitive-decay.py

@@ -63,7 +63,7 @@ def _open_correction_fatigue_followup(fatigued: list) -> str:
         lines.append(f"... and {len(fatigued) - 10} more")
     description = "\n".join(lines)
     verification = (
-        "sqlite3 ~/claude/data/cognitive.db \"SELECT id, content, strength, tags "
+        "sqlite3 ~/.nexo/data/cognitive.db \"SELECT id, content, strength, tags "
         "FROM ltm_memories WHERE tags LIKE '%under_review%' ORDER BY strength ASC LIMIT 50\""
     )
     now_epoch = datetime.now().timestamp()

package/src/scripts/nexo-cortex-cycle.py

@@ -12,7 +12,7 @@ recommendation pattern could persist indefinitely between user reports.
 What this script does (idempotent and best-effort):
 
 1. Loads cortex_evaluation_summary for the last 7 days and last 1 day.
-2. Persists the snapshot to ~/claude/operations/cortex-quality-latest.json
+2. Persists the snapshot to ~/.nexo/operations/cortex-quality-latest.json
    so dashboards / morning briefings can read fresh metrics without
    re-running the SQL.
 3. Detects degradation signals on the 7-day window. The criteria are
@@ -25,7 +25,7 @@ What this script does (idempotent and best-effort):
    metrics when degradation is detected. Idempotent: if a non-PENDING /
    resolved followup of the same id already exists, it is updated in
    place rather than duplicated.
-5. Logs every run to ~/claude/logs/cortex-cycle.log.
+5. Logs every run to ~/.nexo/logs/cortex-cycle.log.
 
 Catchup-friendly: a stale plist firing twice in quick succession is fine.
 The quality file is rewritten in place, the followup is upserted, no

package/src/scripts/nexo-hook-record.py

@@ -3,7 +3,7 @@
 
 Closes Fase 3 item 7 of NEXO-AUDIT-2026-04-11. Bash hooks can call:
 
-    python3 ~/Documents/_PhpstormProjects/nexo/src/scripts/nexo-hook-record.py \
+    NEXO_HOME=~/.nexo python3 ~/.nexo/scripts/nexo-hook-record.py \
         --hook session-start --duration-ms 142 --exit $? --session $SID
 
 This script is intentionally minimal so it adds <50ms of latency to the

package/src/scripts/nexo-migrate.py

@@ -7,7 +7,7 @@ Usage:
     python3 nexo-migrate.py --from 1.6.0 # override detected current version
 
 Reads current version from $NEXO_HOME/version.json.
-Reads target version from the repo's package.json.
+Reads target version from the installed runtime package.json.
 Backs up NEXO_HOME/db/ before any migration.
 Runs DB schema migrations via the existing _schema.py system.
 """
@@ -16,13 +16,43 @@ import argparse
 import json
 import os
 import shutil
-import sqlite3
 import sys
 from datetime import datetime
 from pathlib import Path
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo"))
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent  # nexo/src/scripts -> nexo/
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))).expanduser()
+SCRIPT_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _resolve_runtime_root() -> Path:
+    candidates: list[Path] = []
+
+    raw_code = os.environ.get("NEXO_CODE", "").strip()
+    if raw_code:
+        env_code = Path(raw_code).expanduser()
+        candidates.append(env_code)
+        if env_code.name == "src":
+            candidates.append(env_code.parent)
+
+    candidates.extend([SCRIPT_ROOT, NEXO_HOME])
+
+    seen: set[str] = set()
+    for candidate in candidates:
+        candidate = candidate if candidate.is_dir() else candidate.parent
+        key = str(candidate)
+        if key in seen:
+            continue
+        seen.add(key)
+        if (candidate / "package.json").is_file():
+            return candidate
+        if (candidate / "src" / "server.py").is_file() and (candidate / "package.json").is_file():
+            return candidate
+
+    return SCRIPT_ROOT
+
+
+RUNTIME_ROOT = _resolve_runtime_root()
+SOURCE_ROOT = RUNTIME_ROOT / "src" if (RUNTIME_ROOT / "src" / "db").is_dir() else RUNTIME_ROOT
 
 
 # ── Version helpers ──────────────────────────────────────────────
@@ -56,8 +86,8 @@ def get_current_version() -> str:
 
 
 def get_target_version() -> str:
-    """Read target version from repo package.json."""
-    pkg = REPO_ROOT / "package.json"
+    """Read target version from installed runtime package.json."""
+    pkg = RUNTIME_ROOT / "package.json"
     if not pkg.exists():
         print(f"ERROR: package.json not found at {pkg}", file=sys.stderr)
         sys.exit(1)
@@ -107,10 +137,8 @@ def ensure_nexo_home_dirs():
 
 def run_db_schema_migrations():
     """Run the formal DB schema migration system from _schema.py."""
-    # Add src/ to path so we can import the db module
-    src_dir = REPO_ROOT / "src"
-    if str(src_dir) not in sys.path:
-        sys.path.insert(0, str(src_dir))
+    if str(SOURCE_ROOT) not in sys.path:
+        sys.path.insert(0, str(SOURCE_ROOT))
 
     # Set NEXO_HOME env for the db module
     os.environ["NEXO_HOME"] = str(NEXO_HOME)

package/src/state_watchers_runtime.py

@@ -374,7 +374,7 @@ def _open_watcher_followup(result: dict) -> dict:
     )
     description = "\n".join(description_lines)
     verification = (
-        f"sqlite3 ~/claude/data/nexo.db \"SELECT last_health, last_result "
+        f"sqlite3 ~/.nexo/data/nexo.db \"SELECT last_health, last_result "
         f"FROM state_watchers WHERE watcher_id = '{watcher_id}'\""
     )
 

package/templates/CLAUDE.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-claude-md-version: 2.1.3 -->
+<!-- nexo-claude-md-version: 2.1.4 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — Cognitive Co-Operator
@@ -35,6 +35,12 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 - For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
 - After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first user-visible answer unless the user explicitly asked for it.
 
+## Communication Guardrail
+- In the first answer to Francisco on any thread, lead with the direct recommendation, decision, or status.
+- Keep each decision point to 2-3 short sentences maximum. Hold extra detail unless he explicitly asks for it.
+- Do not use internal NEXO jargon in the first answer (`protocol debt`, `cortex evaluation`, `runtime check`, `guard_check`, `heartbeat`, etc.). Translate it into plain operational language.
+- Prefer conclusion plus next action over option dumps, raw diagnostics, or internal process narration. Apply this equally to chat replies, emails, briefings, and headless reports intended for Francisco.
+
 <!-- nexo:start:profile -->
 ## User Profile
 - **Calibration:** `{{NEXO_HOME}}/brain/calibration.json` (personality settings + language + user name)

package/templates/CODEX.AGENTS.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-codex-agents-version: 1.2.3 -->
+<!-- nexo-codex-agents-version: 1.2.4 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — NEXO Shared Brain for Codex
@@ -32,6 +32,12 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 - For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
 - After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first visible answer unless the user explicitly asked for it.
 
+## Communication Guardrail
+- In the first answer to Francisco on any thread, lead with the direct recommendation, decision, or status.
+- Keep each decision point to 2-3 short sentences maximum. Hold extra detail unless he explicitly asks for it.
+- Do not use internal NEXO jargon in the first answer (`protocol debt`, `cortex evaluation`, `runtime check`, `guard_check`, `heartbeat`, etc.). Translate it into plain operational language.
+- Prefer conclusion plus next action over option dumps, raw diagnostics, or internal process narration. Apply this equally to chat replies, emails, briefings, and headless reports intended for Francisco.
+
 ## Codex Runtime Notes
 - Codex does not provide Claude Code hooks, so protocol discipline must be explicit.
 - If a stable session token is useful, pass `session_token='codex-<task>-<date>'` and `session_client='codex'` to `nexo_startup`; otherwise leave them blank.

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/nexo_helper.py

@@ -30,11 +30,15 @@ def _detect_nexo_home() -> Path:
     ):
         return inferred_home
 
+    default_home = Path.home() / ".nexo"
+    if default_home.is_dir():
+        return default_home
+
     claude_home = Path.home() / "claude"
     if claude_home.is_dir():
         return claude_home
 
-    return Path.home() / ".nexo"
+    return default_home
 
 
 NEXO_HOME = _detect_nexo_home()

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>