nexo-brain 7.23.11 → 7.23.13

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.23.11",
+  "version": "7.23.13",
   "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,11 +18,13 @@
 
 [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.23.11` is the current packaged-runtime line. Patch over v7.23.10 - older installed runtimes can update safely even when `cognitive_paths.py` has not been synced yet.
+Version `7.23.13` is the current packaged-runtime line. Patch over v7.23.12 - release guardrails now audit publish workflows for masked failures and add minimal-delta coverage for punctual UI edits.
 
-Previously in `7.23.6`: patch over v7.23.5 - `nexo update` clears safe legacy `cognitive.db` shadows and keeps superseded archives under runtime backup retention.
+Previously in `7.23.12`: patch over v7.23.11 - protected database recovery now repairs degraded Brain tables from backup without rolling back newer rows.
+
+Previously in `7.23.11`: patch over v7.23.10 - older installed runtimes can update safely even when `cognitive_paths.py` has not been synced yet.
 
-Previously in `7.23.5`: patch over v7.23.4 - `nexo update` keeps external CLI maintenance summary copy in English.
+Previously in `7.23.6`: patch over v7.23.5 - `nexo update` clears safe legacy `cognitive.db` shadows and keeps superseded archives under runtime backup retention.
 
 Previously in `7.23.3`: patch over v7.23.2 - Followup runner skips DONE terminal statuses so already-finished followups do not re-enter executable batches.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.23.11",
+  "version": "7.23.13",
   "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/db_guard.py

@@ -29,7 +29,7 @@ auto_update.py):
     diff_row_counts(current, reference, tables) -> WipeReport
     safe_sqlite_backup(source, dest) -> tuple[bool, str | None]
     validate_backup_matches_source(source, dest, tables) -> tuple[bool, str | None]
-    restore_tables_from_backup(source, target, tables) -> dict
+    restore_tables_from_backup(source, target, tables, mode) -> dict
     kill_nexo_mcp_servers(dry_run) -> dict
     quiesce_nexo_db_writers(dry_run) -> dict
     resume_nexo_launchagents(labels, dry_run) -> dict
@@ -501,23 +501,42 @@ def _quote_identifier(identifier: str) -> str:
     return '"' + identifier.replace('"', '""') + '"'
 
 
+def _quote_sql_name(identifier: str) -> str:
+    return '"' + identifier.replace('"', '""') + '"'
+
+
+def _table_columns(conn: sqlite3.Connection, schema: str, table: str) -> list[str]:
+    if schema not in {"main", "backup_db"}:
+        raise ValueError(f"refusing unsafe schema identifier: {schema!r}")
+    quoted = _quote_identifier(table)
+    rows = conn.execute(f"PRAGMA {schema}.table_info({quoted})").fetchall()
+    return [str(row[1]) for row in rows]
+
+
 def restore_tables_from_backup(
     source: str | Path,
     target: str | Path,
     tables: tuple[str, ...] = LOCAL_CONTEXT_TABLES,
+    *,
+    mode: str = "replace",
 ) -> dict:
-    """Replace selected tables in ``target`` with the copy from ``source``.
+    """Restore selected tables in ``target`` from ``source``.
 
-    This is intentionally table-scoped. It lets Doctor/repair recover days of
-    local indexing from a backup without rolling back newer conversations,
-    credentials, followups, or other Brain state created after that backup.
+    ``mode="replace"`` keeps the historical behavior: target rows are deleted
+    and replaced by the backup table. ``mode="merge_missing"`` preserves target
+    rows and inserts missing rows from the backup with ``INSERT OR IGNORE``.
+    This is intentionally table-scoped so repair can recover data without
+    rolling back unrelated Brain state created after the backup.
     """
+    if mode not in {"replace", "merge_missing"}:
+        raise ValueError(f"unsupported restore mode: {mode!r}")
     src = Path(source)
     dst = Path(target)
     result: dict = {
         "ok": False,
         "source": str(src),
         "target": str(dst),
+        "mode": mode,
         "tables": {},
         "errors": [],
     }
@@ -553,13 +572,29 @@ def restore_tables_from_backup(
                     continue
                 conn.execute(create_sql)
             before = _table_count(conn, table) or 0
-            conn.execute(f"DELETE FROM main.{quoted}")
-            conn.execute(f"INSERT INTO main.{quoted} SELECT * FROM backup_db.{quoted}")
+            if mode == "replace":
+                conn.execute(f"DELETE FROM main.{quoted}")
+                conn.execute(f"INSERT INTO main.{quoted} SELECT * FROM backup_db.{quoted}")
+                status = "restored"
+            else:
+                target_columns = _table_columns(conn, "main", table)
+                source_columns = set(_table_columns(conn, "backup_db", table))
+                common_columns = [column for column in target_columns if column in source_columns]
+                if not common_columns:
+                    result["tables"][table] = {"status": "no_common_columns", "before": int(before)}
+                    continue
+                column_sql = ", ".join(_quote_sql_name(column) for column in common_columns)
+                conn.execute(
+                    f"INSERT OR IGNORE INTO main.{quoted} ({column_sql}) "
+                    f"SELECT {column_sql} FROM backup_db.{quoted}"
+                )
+                status = "merged"
             after = _table_count(conn, table) or 0
             result["tables"][table] = {
-                "status": "restored",
+                "status": status,
                 "before": int(before),
                 "after": int(after),
+                "restored": max(int(after) - int(before), 0),
             }
         conn.commit()
         result["ok"] = not result["errors"]

package/src/doctor/providers/boot.py

@@ -202,21 +202,26 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
         evidence.extend(["Local memory regression:", *local_regression.summary_lines()])
 
     if fix and recoverable_regression:
-        report = restore_tables_from_backup(reference, db_path)
+        report = restore_tables_from_backup(
+            reference,
+            db_path,
+            tables=PROTECTED_TABLES,
+            mode="merge_missing",
+        )
         if report.get("ok"):
             restored = {
                 table: payload
                 for table, payload in (report.get("tables") or {}).items()
-                if isinstance(payload, dict) and payload.get("status") == "restored"
+                if isinstance(payload, dict) and payload.get("status") in {"restored", "merged"}
             }
-            restored_rows = sum(int(payload.get("after") or 0) for payload in restored.values())
+            restored_rows = sum(int(payload.get("restored") or 0) for payload in restored.values())
             return DoctorCheck(
                 id="boot.db_integrity",
                 tier="boot",
                 status="healthy",
                 severity="info",
-                summary=f"Local memory restored from backup ({restored_rows} protected rows)",
-                evidence=evidence + [f"Restored local-memory tables: {len(restored)}"],
+                summary=f"Database protected tables restored from backup ({restored_rows} rows recovered)",
+                evidence=evidence + [f"Restored protected tables: {len(restored)}"],
                 fixed=True,
             )
         return DoctorCheck(
@@ -224,7 +229,7 @@ def check_db_integrity(fix: bool = False) -> DoctorCheck:
             tier="boot",
             status="critical",
             severity="error",
-            summary="Local memory repair failed",
+            summary="Database protected-table repair failed",
             evidence=evidence + [f"Restore errors: {report.get('errors') or []}"],
             repair_plan=["Close NEXO Desktop and run nexo doctor --tier boot --plane database_real --fix"],
         )

package/src/guardrails/minimal_delta.py

@@ -0,0 +1,267 @@
+"""Minimal-delta pre-mutation guardrail (NF-DS-C3E64B2B).
+
+Purpose
+-------
+Block scope creep when the operator describes a *punctual* UI change
+("add this text", "change the size", "adjust the color") but the agent
+proposes a diff that touches many unrelated lines.
+
+How it plugs in
+---------------
+Wire ``check`` from ``hook_guardrails.process_pre_tool_event`` BEFORE the
+``Edit`` / ``Write`` call reaches the model. The hook should:
+
+  1. Call ``classify_request(prompt_text)`` to detect punctual UI verbs.
+  2. If punctual, capture the *target file* + *proposed new_string* from the
+     pending tool payload.
+  3. Read ``read_file_history(path)`` to keep the prior context available
+     (it returns the last 5 commits + current text so the agent can reason
+     in bullet-by-bullet form when replying).
+  4. Call ``check_diff(prompt_text, old_text, new_text)`` and act on the
+     returned ``GuardDecision``:
+
+       * ``decision == "allow"``  → let the tool through, no annotation.
+       * ``decision == "warn"``   → let it through but tell the agent in the
+         response payload how many extra lines it touched.
+       * ``decision == "block"``  → deny the tool with the included reason.
+         The agent must reply with a bullet-by-bullet diff against the prior
+         state and request explicit confirmation before retrying.
+
+Why headless-friendly
+---------------------
+This module is *pure*. No filesystem, no subprocess, no MCP call. The hook
+layer wires it in. That keeps the gate testable in isolation and means a
+wrong tuning here cannot brick the pre-tool pipeline.
+
+Origin: Deep Sleep followup NF-DS-C3E64B2B (scope creep in punctual visual
+changes).
+"""
+from __future__ import annotations
+
+import difflib
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+# Verbs that signal a *punctual* UI change. Matched case-insensitive against
+# the full request text. Spanish terms are intentionally included because the
+# operator often reports UI issues in Spanish; output remains English.
+PUNCTUAL_VERBS: tuple[str, ...] = (
+    "añade",
+    "anade",
+    "agrega",
+    "añadir",
+    "agrega el texto",
+    "cambia el texto",
+    "cambia el color",
+    "cambia el tamaño",
+    "cambia el tamano",
+    "ajusta el tamaño",
+    "ajusta el tamano",
+    "ajusta el padding",
+    "ajusta el margen",
+    "ajusta el color",
+    "renombra",
+    "rename",
+    "tweak",
+    "change the text",
+    "change the color",
+    "adjust the size",
+    "fix the label",
+    "fix the wording",
+    "add the text",
+    "swap the icon",
+)
+
+# File extensions considered UI surfaces. Anything else short-circuits to
+# "not a UI mutation" so we never block server code on accident.
+UI_EXTENSIONS: frozenset[str] = frozenset({
+    ".tsx", ".jsx", ".ts", ".js", ".vue", ".svelte", ".astro",
+    ".html", ".css", ".scss", ".sass", ".less",
+    ".liquid", ".njk", ".hbs",
+})
+
+# Default threshold for "unrelated lines". Tuned conservatively — a real UI
+# tweak usually changes 1-3 contiguous lines. Anything > THRESHOLD blocks.
+DEFAULT_THRESHOLD = 8
+
+
+@dataclass(frozen=True)
+class GuardDecision:
+    decision: str           # "allow" | "warn" | "block"
+    matched_verb: str | None
+    changed_lines: int
+    threshold: int
+    reason: str
+
+    def to_payload(self) -> dict:
+        return {
+            "guard": "minimal-delta",
+            "decision": self.decision,
+            "matched_verb": self.matched_verb,
+            "changed_lines": self.changed_lines,
+            "threshold": self.threshold,
+            "reason": self.reason,
+        }
+
+
+def classify_request(prompt_text: str) -> str | None:
+    """Return the matched punctual verb (lowercase) or ``None``."""
+    if not prompt_text:
+        return None
+    haystack = prompt_text.lower()
+    for verb in PUNCTUAL_VERBS:
+        if verb in haystack:
+            return verb
+    return None
+
+
+def is_ui_path(path: str | Path) -> bool:
+    if not path:
+        return False
+    suffix = Path(str(path)).suffix.lower()
+    return suffix in UI_EXTENSIONS
+
+
+def count_changed_lines(old_text: str, new_text: str) -> int:
+    """Count *non-context* diff lines (+/− only)."""
+    if old_text == new_text:
+        return 0
+    old_lines = old_text.splitlines()
+    new_lines = new_text.splitlines()
+    diff = difflib.unified_diff(old_lines, new_lines, n=0, lineterm="")
+    count = 0
+    for line in diff:
+        if line.startswith(("+++", "---", "@@")):
+            continue
+        if line.startswith(("+", "-")):
+            count += 1
+    return count
+
+
+def check_diff(
+    prompt_text: str,
+    old_text: str,
+    new_text: str,
+    target_path: str | Path = "",
+    *,
+    threshold: int = DEFAULT_THRESHOLD,
+) -> GuardDecision:
+    verb = classify_request(prompt_text)
+    if verb is None:
+        return GuardDecision("allow", None, 0, threshold, "Not a punctual request — guard not applied.")
+    if target_path and not is_ui_path(target_path):
+        return GuardDecision(
+            "allow", verb, 0, threshold,
+            f"Target {target_path} is not a UI surface — guard not applied.",
+        )
+    changed = count_changed_lines(old_text, new_text)
+    if changed <= 2:
+        return GuardDecision(
+            "allow", verb, changed, threshold,
+            "Diff stays within 2 lines — within the punctual envelope.",
+        )
+    if changed <= threshold:
+        return GuardDecision(
+            "warn", verb, changed, threshold,
+            (
+                f"Punctual request ('{verb}') is changing {changed} lines. "
+                "Inside the soft envelope but please justify each line in the reply."
+            ),
+        )
+    return GuardDecision(
+        "block", verb, changed, threshold,
+        (
+            f"Punctual request ('{verb}') is changing {changed} lines (>{threshold}). "
+            "Read git log/blame for the file, present the prior state, list each proposed "
+            "change as a bullet, and ask the operator before applying. Override only with "
+            "explicit confirmation."
+        ),
+    )
+
+
+def read_file_history(path: str | Path, *, max_commits: int = 5) -> dict:
+    """Return ``{"current": str, "log": [str], "blame": [str] | None}``.
+
+    Best-effort: missing git, missing file, or non-zero exit codes are
+    swallowed so the guardrail itself never errors out. The dictionary is
+    purely informational — the agent must surface it in its reply when the
+    guard fires.
+    """
+    path_obj = Path(path)
+    try:
+        current = path_obj.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        current = ""
+
+    log_lines: list[str] = []
+    try:
+        completed = subprocess.run(
+            ["git", "log", f"-{max_commits}", "--pretty=format:%h %ad %s", "--date=short", "--", str(path_obj)],
+            cwd=path_obj.parent if path_obj.parent.exists() else Path.cwd(),
+            capture_output=True,
+            text=True,
+            timeout=4,
+            check=False,
+        )
+        if completed.returncode == 0 and completed.stdout.strip():
+            log_lines = completed.stdout.splitlines()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        log_lines = []
+
+    blame_lines: list[str] | None = None
+    if current:
+        try:
+            completed = subprocess.run(
+                ["git", "blame", "--line-porcelain", "-L", "1,40", str(path_obj)],
+                cwd=path_obj.parent if path_obj.parent.exists() else Path.cwd(),
+                capture_output=True,
+                text=True,
+                timeout=4,
+                check=False,
+            )
+            if completed.returncode == 0:
+                blame_lines = completed.stdout.splitlines()
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            blame_lines = None
+
+    return {"current": current, "log": log_lines, "blame": blame_lines}
+
+
+def evaluate(
+    prompt_text: str,
+    target_path: str | Path,
+    old_text: str,
+    new_text: str,
+    *,
+    threshold: int = DEFAULT_THRESHOLD,
+) -> dict:
+    """Convenience wrapper used by hook_guardrails.
+
+    Returns a payload safe to JSON-serialize and embed in the deny reason
+    or the pass-through note.
+    """
+    decision = check_diff(prompt_text, old_text, new_text, target_path, threshold=threshold)
+    payload = decision.to_payload()
+    payload["target_path"] = str(target_path)
+    if decision.decision == "block":
+        history = read_file_history(target_path)
+        payload["history_log"] = history["log"]
+        payload["current_excerpt"] = (history["current"][:400] + "…") if history["current"] else ""
+    return payload
+
+
+__all__ = [
+    "DEFAULT_THRESHOLD",
+    "GuardDecision",
+    "PUNCTUAL_VERBS",
+    "UI_EXTENSIONS",
+    "check_diff",
+    "classify_request",
+    "count_changed_lines",
+    "evaluate",
+    "is_ui_path",
+    "read_file_history",
+]