nexo-brain 7.16.0 → 7.17.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.16.0",
+  "version": "7.17.0",
   "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,11 @@
 
 [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.16.0` is the current packaged-runtime line. Minor release over v7.15.2 - Brain adds Memory Observations v2: evidence-backed event capture, derived observations, update-safe backfill, MCP retrieval, dashboard visibility, and safer refusal when memory lacks evidence.
+Version `7.17.0` is the current packaged-runtime line. Minor release over v7.16.3 - the headless runner pre-emptive guard becomes advisory: it surfaces learnings/schemas to the agent and logs to `guard_checks`, but never returns `blocked=True`. The PreToolUse hook is the authoritative gate at write time. This closes the family of bugs where heuristic path matches in the prompt aborted email-monitor sessions, followup-runner cycles, Deep Sleep synth, and postmortem-consolidation. Also rolls in the directory-path hardening planned for 7.16.4.
+
+Previously in `7.16.3`: patch release over v7.16.2 - the headless runner guard opts out of the runtime-core blocking rule because actual writes on those paths are already blocked at the PreToolUse layer.
+
+Previously in `7.16.0`: minor release over v7.15.2 - Brain adds Memory Observations v2: evidence-backed event capture, derived observations, update-safe backfill, MCP retrieval, dashboard visibility, and safer refusal when memory lacks evidence.
 
 Previously in `7.15.2`: patch release over v7.15.1 - Brain treats normal Codex startup context reads of calibration and project atlas files as healthy bootstrap activity instead of conditioned-file drift.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.16.0",
+  "version": "7.17.0",
   "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/agent_runner.py

@@ -405,15 +405,53 @@ def _runner_mutating_tools_allowed(allowed_tools: str) -> bool:
     return bool(parts & _MUTATING_TOOL_NAMES)
 
 
+_RUNNER_GUARD_EXEC_INVOCATION_PATTERN = re.compile(
+    r"\b(?:python3?|python|node|nodejs|bash|sh|zsh|ruby|deno|perl|pwsh|powershell|"
+    r"npx|pnpm|yarn|uv|pipx|env)\b\s+"
+    r"(/[^\s'\"`<>]+|[A-Za-z]:\\[^\s'\"`<>]+)"
+)
+
+
 def _extract_runner_guard_paths(prompt: str, cwd: Path) -> list[str]:
+    """Return paths that the prompt seems to instruct the agent to *edit*.
+
+    Paths that appear immediately after a known interpreter
+    (``python3 /path/to/tool.py ...``) are stripped out: those are
+    subprocess executions, not edits, and the runner guard must not treat
+    them as protected-file writes. Without this exclusion the email-monitor
+    prompt — which explicitly instructs the agent to invoke
+    ``~/.nexo/core/scripts/nexo-send-reply.py`` to deliver the reply —
+    triggers the ``runtime-core`` blocking rule on every email and the
+    session aborts with exit 2 before any reply is generated.
+    """
     found: set[str] = set()
     text = str(prompt or "")
+
+    exec_only_paths: set[str] = set()
+    for match in _RUNNER_GUARD_EXEC_INVOCATION_PATTERN.finditer(text):
+        candidate = match.group(1).rstrip(".,);:]")
+        if candidate:
+            exec_only_paths.add(candidate)
+            try:
+                exec_only_paths.add(str(Path(candidate).expanduser().resolve(strict=False)))
+            except Exception:
+                pass
+
     for match in re.findall(r"(?<![A-Za-z0-9_])(?:/[^\s'\"`<>]+|[A-Za-z]:\\[^\s'\"`<>]+)", text):
         cleaned = match.rstrip(".,);:]")
-        if cleaned:
-            found.add(cleaned)
+        # Drop trailing slashes — `/tmp/` and friends are directories, not
+        # edit targets. Without this the followup-runner prompt's mention
+        # of `/tmp/` reached `handle_guard_check`, which tried to `open()`
+        # the directory and crashed the whole pre-emptive guard.
+        cleaned = cleaned.rstrip("/")
+        if not cleaned or cleaned in exec_only_paths:
+            continue
+        found.add(cleaned)
     for match in re.findall(r"(?<![A-Za-z0-9_])(?:src|scripts|tests|docs|lib|renderer|app)/[A-Za-z0-9_./-]+\.[A-Za-z0-9]+", text):
-        found.add(str((cwd / match.rstrip(".,);:]")).resolve()))
+        resolved = str((cwd / match.rstrip(".,);:]")).resolve())
+        if resolved in exec_only_paths:
+            continue
+        found.add(resolved)
     try:
         resolved_cwd = cwd.resolve()
     except Exception:
@@ -428,34 +466,64 @@ def _extract_runner_guard_paths(prompt: str, cwd: Path) -> list[str]:
 
 
 def _run_headless_runner_guard(*, caller: str, cwd: Path, prompt: str, allowed_tools: str) -> dict:
+    """Pre-emptive runner guard — observational, never blocking.
+
+    The pre-emptive guard scans the *prompt text* for paths the agent might
+    edit. That is heuristic: it cannot tell whether a path will actually be
+    written, read, executed, or just mentioned in passing. Treating the
+    learnings/blocking-rules surfaced by that heuristic as hard blockers
+    has caused a year's worth of operational pain — every time a learning's
+    ``applies_to`` happens to match a path the prompt mentions for any
+    reason, every cron, every email-monitor session, every Deep Sleep
+    synth aborts with exit 2.
+
+    The authoritative gate is the PreToolUse hook
+    (``hook_guardrails._collect_runtime_core_write_blocks`` and the
+    learning-aware blocks alongside it). That layer fires only when the
+    agent *actually attempts* a Write/Edit, with severity ``error``, and
+    prevents the protected mutation. The pre-emptive guard's job is to
+    surface relevant learnings/schemas to the agent up front so it can
+    reason about them, plus log to ``guard_checks`` for observability —
+    not to abort the run on a regex match.
+
+    Therefore this function always returns ``blocked=False``. Errors from
+    ``handle_guard_check`` are also non-blocking; we let the run start so
+    the PreToolUse layer can do its job, and we log the unavailability for
+    diagnostics.
+    """
     if not _runner_mutating_tools_allowed(allowed_tools):
         return {"blocked": False, "skipped": "read_only_tools"}
     guard_paths = _extract_runner_guard_paths(prompt, cwd)
     if not guard_paths:
         return {"blocked": False, "skipped": "no_explicit_paths"}
+    summary = ""
     try:
         runtime_root = str(NEXO_HOME)
         if runtime_root and runtime_root not in sys.path:
             sys.path.insert(0, runtime_root)
         from plugins.guard import handle_guard_check  # type: ignore
 
+        # We still pass ``enforce_runtime_core_block="false"`` because that
+        # opt-out predates the advisory-only switch and other callers may
+        # still rely on it. With the advisory contract in place this flag
+        # is effectively redundant, but kept for back-compat.
         output = handle_guard_check(
             files=",".join(guard_paths),
             area=f"runner:{caller or 'headless'}",
             project_hint=f"headless runner caller={caller or 'unknown'} cwd={cwd}",
             include_schemas="true",
+            enforce_runtime_core_block="false",
         )
+        summary = str(output or "")
     except Exception as exc:
-        return {
-            "blocked": True,
-            "summary": f"Runner guard unavailable: {exc}",
-            "paths": guard_paths,
-        }
-    blocked = "BLOCKING RULES" in str(output or "")
+        # Guard unavailable is observational, not blocking. The PreToolUse
+        # hook will catch any actual protected write at execute time.
+        summary = f"Runner guard unavailable: {exc}"
     return {
-        "blocked": blocked,
-        "summary": str(output or ""),
+        "blocked": False,
+        "summary": summary,
         "paths": guard_paths,
+        "advisory": True,
     }
 
 

package/src/plugins/guard.py

@@ -309,6 +309,7 @@ def handle_guard_check(
     area: str = "",
     project_hint: str = "",
     include_schemas: str = "true",
+    enforce_runtime_core_block: str = "true",
 ) -> str:
     """Check learnings relevant to files/area before editing. Call BEFORE any code change.
 
@@ -316,11 +317,21 @@ def handle_guard_check(
         files: Comma-separated file paths about to be edited
         area: System area (webapp, shopify, infrastructure, nexo-ops, etc.)
         include_schemas: Include DB table schemas if files touch database code (true/false)
+        enforce_runtime_core_block: When ``true`` (default) any path under
+            ``~/.nexo/core/`` adds a ``runtime-core`` blocking rule. When
+            ``false`` the caller is opting out because another guard layer
+            already protects those writes (the PreToolUse hook in
+            ``hook_guardrails._collect_runtime_core_write_blocks`` blocks any
+            actual Write/Edit on core paths with severity ``error``).
+            ``_run_headless_runner_guard`` passes ``false`` so that paths
+            mentioned in a prompt — e.g. invocations of helper scripts —
+            no longer abort the session pre-emptively.
     """
     conn = get_db()
     include_schemas_bool = include_schemas.lower() in ("true", "1", "yes")
     file_list = [f.strip() for f in files.split(",") if f.strip()] if files else []
     project_hint_active = bool(_project_hint_tokens(project_hint))
+    enforce_runtime_core_bool = str(enforce_runtime_core_block or "").lower() in ("true", "1", "yes")
 
     result = {
         "learnings": [],
@@ -335,18 +346,19 @@ def handle_guard_check(
     conditioned_blocking_seen = set()
     conditioned_by_file = _load_conditioned_learnings(conn, file_list) if file_list else {}
 
-    runtime_core_hits = [filepath for filepath in file_list if _is_runtime_core_path(filepath)]
-    for filepath in runtime_core_hits:
-        result["blocking_rules"].append({
-            "id": "runtime-core",
-            "rule": (
-                "Installed runtime core files are protected. Edit the source repo, validate there, "
-                "then ship the change through release/update instead of mutating ~/.nexo/core directly."
-            ),
-            "repetitions": 0,
-            "reason": "runtime_core_protected",
-            "file": filepath,
-        })
+    if enforce_runtime_core_bool:
+        runtime_core_hits = [filepath for filepath in file_list if _is_runtime_core_path(filepath)]
+        for filepath in runtime_core_hits:
+            result["blocking_rules"].append({
+                "id": "runtime-core",
+                "rule": (
+                    "Installed runtime core files are protected. Edit the source repo, validate there, "
+                    "then ship the change through release/update instead of mutating ~/.nexo/core directly."
+                ),
+                "repetitions": 0,
+                "reason": "runtime_core_protected",
+                "file": filepath,
+            })
 
     # 1. File-conditioned learnings — explicit applies_to guardrails for target files
     hit_ids = []
@@ -482,12 +494,24 @@ def handle_guard_check(
         all_tables = set()
         for filepath in file_list:
             try:
+                # Skip directories silently — the path extractor that calls
+                # us is permissive and can hand back paths that end in `/`
+                # (e.g. `/tmp/`) or that resolve to real directories. Opening
+                # one of those raises IsADirectoryError, which is an OSError
+                # subclass; the prior except only caught FileNotFoundError /
+                # PermissionError, so the exception propagated and the whole
+                # runner pre-emptive guard returned `blocked=True` with
+                # "Runner guard unavailable: [Errno 21] Is a directory".
+                # That is exactly what was killing the followup-runner every
+                # hour after 7.16.0.
+                if Path(filepath).is_dir():
+                    continue
                 with open(filepath, 'r', errors='ignore') as f:
                     content = f.read()
                 sql_keywords = ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE TABLE']
                 if any(kw in content.upper() for kw in sql_keywords):
                     all_tables.update(_extract_table_names(content))
-            except (FileNotFoundError, PermissionError):
+            except (FileNotFoundError, PermissionError, IsADirectoryError, OSError):
                 continue
 
         cache = _load_schema_cache()

package/src/scripts/nexo-email-monitor.py

@@ -30,7 +30,7 @@ import sqlite3
 import signal
 import time
 import uuid
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from email.utils import parseaddr
 from pathlib import Path
 from logging.handlers import RotatingFileHandler
@@ -1269,6 +1269,8 @@ def _ensure_emails_table(conn):
         conn.execute("ALTER TABLE emails ADD COLUMN attempts INTEGER DEFAULT 0")
     if "error" not in cols:
         conn.execute("ALTER TABLE emails ADD COLUMN error TEXT")
+    if "escalation_notified_at" not in cols:
+        conn.execute("ALTER TABLE emails ADD COLUMN escalation_notified_at TEXT")
 
 
 def _email_table_columns(conn):
@@ -2356,9 +2358,61 @@ def _mark_needs_interactive(email_ids):
         log.warning(f"Failed to mark needs_interactive: {e}")
 
 
+def _filter_already_notified(message_ids):
+    """Return the subset of message_ids that have NOT been escalated yet
+    (i.e. emails.escalation_notified_at IS NULL). Idempotent: if the column
+    is missing for any reason, no row is filtered out."""
+    if not message_ids:
+        return []
+    try:
+        conn = sqlite3.connect(str(EMAIL_DB_PATH))
+        try:
+            _ensure_emails_table(conn)
+            placeholders = ",".join("?" for _ in message_ids)
+            rows = conn.execute(
+                f"""
+                SELECT message_id FROM emails
+                WHERE message_id IN ({placeholders})
+                  AND escalation_notified_at IS NULL
+                """,
+                tuple(message_ids),
+            ).fetchall()
+            return [r[0] for r in rows]
+        finally:
+            conn.close()
+    except Exception as e:
+        log.warning(f"escalation_notified_at filter failed, falling through: {e}")
+        return list(message_ids)
+
+
+def _mark_escalation_notified(message_ids):
+    """Stamp emails.escalation_notified_at = now() so we never re-notify
+    the operator about the same exhausted email."""
+    if not message_ids:
+        return
+    try:
+        conn = sqlite3.connect(str(EMAIL_DB_PATH))
+        try:
+            _ensure_emails_table(conn)
+            now_iso = datetime.now(timezone.utc).isoformat()
+            for mid in message_ids:
+                conn.execute(
+                    "UPDATE emails SET escalation_notified_at = ? WHERE message_id = ?",
+                    (now_iso, mid),
+                )
+            conn.commit()
+        finally:
+            conn.close()
+    except Exception as e:
+        log.warning(f"Failed to stamp escalation_notified_at: {e}")
+
+
 def _escalate_exhausted_emails(config, batch):
     """After all retries exhausted, directly escalate emails with attempts >= MAX
-    by marking them needs_interactive and sending email to operator via nexo-send-reply.py."""
+    by marking them needs_interactive and sending email to operator via nexo-send-reply.py.
+
+    Deduplicated by emails.escalation_notified_at: if an email is already in
+    needs_interactive state from a previous run, we do not re-notify the operator."""
     exhausted = [e for e in batch if (e.get("attempts", 0) + 1) >= MAX_EMAIL_ATTEMPTS]
     if not exhausted:
         return
@@ -2366,6 +2420,19 @@ def _escalate_exhausted_emails(config, batch):
     _mark_needs_interactive(ids)
     log.info(f"Marked {len(ids)} email(s) as needs_interactive after exhausting retries")
 
+    pending_notify_ids = set(_filter_already_notified(ids))
+    if not pending_notify_ids:
+        log.info(
+            f"All {len(ids)} exhausted email(s) already escalated to operator earlier — skipping duplicate notification."
+        )
+        return
+    skipped = len(ids) - len(pending_notify_ids)
+    if skipped:
+        log.info(
+            f"Escalation dedup: {skipped} email(s) already notified, will only escalate {len(pending_notify_ids)} new one(s)."
+        )
+    exhausted = [e for e in exhausted if e["message_id"] in pending_notify_ids]
+
     operator_name, assistant_name, operator_language = _get_operator_info()
     operator_email = config.get("operator_email", "")
     if not operator_email:
@@ -2387,8 +2454,9 @@ def _escalate_exhausted_emails(config, batch):
     body_file.write_text(body, encoding="utf-8")
 
     send_script = get_send_reply_script_path(local_script_dir=_script_dir)
+    send_ok = False
     try:
-        subprocess.run(
+        result = subprocess.run(
             [
                 sys.executable, str(send_script),
                 "--to", f"{operator_name} <{operator_email}>",
@@ -2398,12 +2466,22 @@ def _escalate_exhausted_emails(config, batch):
             timeout=30,
             capture_output=True,
         )
-        log.info(f"Escalation email sent to {operator_email}")
+        send_ok = (result.returncode == 0)
+        if send_ok:
+            log.info(f"Escalation email sent to {operator_email}")
+        else:
+            log.warning(
+                f"Escalation send returned exit={result.returncode}; "
+                f"stderr={(result.stderr or b'').decode('utf-8', 'replace')[:200]}"
+            )
     except Exception as e:
         log.warning(f"Failed to send escalation email: {e}")
     finally:
         body_file.unlink(missing_ok=True)
 
+    if send_ok:
+        _mark_escalation_notified(list(pending_notify_ids))
+
 
 def main():
     log.info("=== Monitor check ===")