nexo-brain 7.20.20 → 7.20.22

package/package.json

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

@@ -89,6 +89,7 @@ LOCAL_CONTEXT_BACKUP_TABLES = (
     "local_index_checkpoints",
     "local_index_state",
     "local_index_errors",
+    "local_index_logs",
     "local_assets",
     "local_asset_versions",
     "local_chunks",
@@ -98,7 +99,17 @@ LOCAL_CONTEXT_BACKUP_TABLES = (
     "local_context_queries",
     "local_index_dirs",
 )
-PROTECTED_BACKUP_TABLES = CRITICAL_BACKUP_TABLES + LOCAL_CONTEXT_BACKUP_TABLES
+PROTECTED_BACKUP_TABLES = CRITICAL_BACKUP_TABLES
+
+
+def _backup_validation_tables(db_file: Path) -> tuple[str, ...]:
+    if db_file.name == "nexo.db":
+        return PROTECTED_BACKUP_TABLES
+    if db_file.name == "local-context.db":
+        return LOCAL_CONTEXT_BACKUP_TABLES
+    return ()
+
+
 CLASSIFIER_INSTALL_TIMEOUT_SECONDS = 1800
 CLASSIFIER_INSTALL_JOIN_SECONDS = 1500
 CLASSIFIER_INSTALL_LOG = paths.logs_dir() / "classifier-install.log"
@@ -338,7 +349,7 @@ def _validate_db_backup(source_db: Path, backup_db: Path) -> dict:
         report["errors"].append(f"backup db missing: {backup_db}")
         return report
 
-    for table in PROTECTED_BACKUP_TABLES:
+    for table in _backup_validation_tables(source_db):
         source_count = _critical_table_count(source_db, table)
         backup_count = _critical_table_count(backup_db, table)
         report["source_counts"][table] = source_count
@@ -373,18 +384,29 @@ def _create_validated_db_backup() -> tuple[str | None, dict | None]:
     if not backup_dir:
         return None, None
 
-    source_db = _find_primary_db_path()
-    if source_db is None:
+    source_dbs: list[Path] = []
+    primary_db = _find_primary_db_path()
+    if primary_db is not None:
+        source_dbs.append(primary_db)
+    local_context_db = paths.memory_dir() / "local-context.db"
+    if local_context_db.is_file():
+        source_dbs.append(local_context_db)
+    if not source_dbs:
         return backup_dir, None
 
-    report = _validate_db_backup(source_db, Path(backup_dir) / source_db.name)
-    if not report["ok"]:
-        details = ", ".join(
-            f"{item['table']} {item['source']}->{item['backup']}"
-            for item in report["regressions"]
-        ) or "; ".join(report["errors"])
-        _log(f"DB backup validation failed: {details}")
-    return backup_dir, report
+    reports = []
+    ok = True
+    for source_db in source_dbs:
+        report = _validate_db_backup(source_db, Path(backup_dir) / source_db.name)
+        reports.append(report)
+        if not report["ok"]:
+            ok = False
+            details = ", ".join(
+                f"{item['table']} {item['source']}->{item['backup']}"
+                for item in report["regressions"]
+            ) or "; ".join(report["errors"])
+            _log(f"DB backup validation failed ({source_db.name}): {details}")
+    return backup_dir, {"ok": ok, "reports": reports}
 
 
 def _read_last_check() -> dict:
@@ -2047,6 +2069,9 @@ def _backup_dbs() -> str | None:
     backup_dir = paths.backups_dir() / f"pre-autoupdate-{timestamp}"
 
     db_files = list(DATA_DIR.glob("*.db")) if DATA_DIR.is_dir() else []
+    local_context_db = paths.memory_dir() / "local-context.db"
+    if local_context_db.is_file():
+        db_files.append(local_context_db)
     db_files += [f for f in NEXO_HOME.glob("*.db") if f.is_file()]
     src_db = SRC_DIR / "nexo.db"
     if src_db.is_file() and src_db not in db_files:
@@ -2090,11 +2115,16 @@ def _restore_dbs(backup_dir: str):
     if not bdir.is_dir():
         return
     for db_backup in bdir.glob("*.db"):
-        for candidate in [DATA_DIR / db_backup.name, NEXO_HOME / db_backup.name, SRC_DIR / db_backup.name]:
-            if candidate.is_file():
+        if db_backup.name == "local-context.db":
+            candidates = [paths.memory_dir() / db_backup.name]
+        else:
+            candidates = [DATA_DIR / db_backup.name, NEXO_HOME / db_backup.name, SRC_DIR / db_backup.name]
+        for candidate in candidates:
+            if candidate.is_file() or db_backup.name == "local-context.db":
                 src_conn = None
                 dst_conn = None
                 try:
+                    candidate.parent.mkdir(parents=True, exist_ok=True)
                     src_conn = sqlite3.connect(str(db_backup))
                     dst_conn = sqlite3.connect(str(candidate))
                     src_conn.backup(dst_conn)

package/src/cli.py

@@ -52,6 +52,7 @@ from pathlib import Path
 
 from runtime_home import export_resolved_nexo_home
 from runtime_versioning import build_mcp_status, clear_restart_required_marker
+from mcp_required_tools import BOOTSTRAP_REQUIRED_MCP_TOOLS, missing_required_tools
 
 NEXO_HOME = export_resolved_nexo_home()
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
@@ -200,8 +201,11 @@ def _mcp_probe(args) -> int:
     server_path = NEXO_CODE / "server.py"
     env = os.environ.copy()
     env["NEXO_MCP_PROBE"] = "1"
-    env.setdefault("NEXO_MCP_PLUGIN_MODE", getattr(args, "plugin_mode", None) or "none")
-    env.setdefault("NEXO_MCP_RUN_STARTUP_PREFLIGHT", "0")
+    # Probe must be deterministic: inherited env from an older Desktop/runtime
+    # must not force plugin loading or startup preflight and turn this into a
+    # slow/false-negative health check.
+    env["NEXO_MCP_PLUGIN_MODE"] = getattr(args, "plugin_mode", None) or "none"
+    env["NEXO_MCP_RUN_STARTUP_PREFLIGHT"] = "0"
     client = str(getattr(args, "client", "") or "").strip()
     if client:
         env["NEXO_MCP_CLIENT"] = client
@@ -256,8 +260,8 @@ def _mcp_probe(args) -> int:
             for tool in tools
             if isinstance(tool, dict) and tool.get("name")
         ]
-        required = ["nexo_startup", "nexo_heartbeat", "nexo_task_open", "nexo_guard_check"]
-        missing = [name for name in required if name not in tool_names]
+        required = list(BOOTSTRAP_REQUIRED_MCP_TOOLS)
+        missing = missing_required_tools(tool_names)
         ok = not missing and len(tool_names) > 0
         payload = {
             "ok": ok,
@@ -265,6 +269,8 @@ def _mcp_probe(args) -> int:
             "probe_ok": ok,
             "tools_available": len(tool_names) > 0,
             "tool_count": len(tool_names),
+            "required_tools": required,
+            "required_tool_count": len(required),
             "required_tools_present": not missing,
             "missing_required_tools": missing,
             "client": client,

package/src/db_guard.py

@@ -75,6 +75,7 @@ LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
     "local_index_checkpoints",
     "local_index_state",
     "local_index_errors",
+    "local_index_logs",
     "local_assets",
     "local_asset_versions",
     "local_chunks",
@@ -85,10 +86,11 @@ LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
     "local_index_dirs",
 )
 
-# Everything an updater/recovery path must preserve. Keep CRITICAL_TABLES as a
-# public legacy name for older callers, but new guards should use
-# PROTECTED_TABLES so local indexing cannot regress unnoticed.
-PROTECTED_TABLES: tuple[str, ...] = CRITICAL_TABLES + LOCAL_CONTEXT_TABLES
+# Tables protected inside the operational Brain DB. Local memory now lives in
+# runtime/memory/local-context.db and is validated with LOCAL_CONTEXT_TABLES
+# separately; mixing both here makes old local-index backups look like the
+# source of truth for nexo.db and can block every update.
+PROTECTED_TABLES: tuple[str, ...] = CRITICAL_TABLES
 
 # A reference backup must contain at least this many rows (summed across
 # CRITICAL_TABLES) before we will treat it as "proof the user has real data".
@@ -478,7 +480,7 @@ def _backup_drift_is_safe(source_count: int, backup_count: int) -> bool:
 
 
 def _quote_identifier(identifier: str) -> str:
-    if identifier not in PROTECTED_TABLES:
+    if identifier not in PROTECTED_TABLES and identifier not in LOCAL_CONTEXT_TABLES:
         raise ValueError(f"refusing unsafe table identifier: {identifier!r}")
     return '"' + identifier.replace('"', '""') + '"'
 

package/src/interactive_db.py

@@ -0,0 +1,59 @@
+"""Helpers for interactive MCP tools that must not block on SQLite locks."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from contextlib import contextmanager
+
+from db import get_db
+
+
+def interactive_db_timeout_ms() -> int:
+    """Return the max SQLite busy wait for user-facing MCP calls."""
+    try:
+        return max(50, min(int(os.environ.get("NEXO_MCP_DB_BUSY_TIMEOUT_MS", "250")), 10000))
+    except Exception:
+        return 250
+
+
+def set_interactive_db_timeout() -> None:
+    """Make the shared connection fail fast when a background writer owns the DB."""
+    try:
+        get_db().execute(f"PRAGMA busy_timeout={interactive_db_timeout_ms()}")
+    except Exception:
+        pass
+
+
+@contextmanager
+def interactive_db_timeout():
+    """Temporarily reduce SQLite busy wait for a user-facing MCP call."""
+    conn = None
+    previous = None
+    try:
+        conn = get_db()
+        row = conn.execute("PRAGMA busy_timeout").fetchone()
+        previous = int(row[0]) if row and row[0] is not None else None
+        conn.execute(f"PRAGMA busy_timeout={interactive_db_timeout_ms()}")
+    except Exception:
+        conn = None
+    try:
+        yield
+    finally:
+        if conn is not None and previous is not None:
+            try:
+                conn.execute(f"PRAGMA busy_timeout={previous}")
+            except Exception:
+                pass
+
+
+def is_db_busy(exc: BaseException) -> bool:
+    msg = str(exc).lower()
+    return (
+        isinstance(exc, sqlite3.OperationalError)
+        and (
+            "database is locked" in msg
+            or "database is busy" in msg
+            or "database table is locked" in msg
+        )
+    ) or "database is locked" in msg or "database is busy" in msg

package/src/local_context/api.py

@@ -11,10 +11,8 @@ import sys
 from pathlib import Path
 from typing import Any
 
-from db import get_db, init_db
-from db._schema import run_migrations
-
 from . import embeddings
+from .db import ensure_local_context_db, get_local_context_db
 from .extractors import chunk_text, contains_secret, entities, extract_text, summarize
 from .logging import log_event, tail
 from .privacy import classify_path, is_local_email_tree, is_queryable_path, should_extract, should_skip_file, should_skip_tree
@@ -88,13 +86,12 @@ PERFORMANCE_PROFILES: dict[str, dict[str, Any]] = {
 
 
 def ensure_ready() -> None:
-    init_db()
-    run_migrations()
+    ensure_local_context_db()
 
 
 def _conn():
     ensure_ready()
-    return get_db()
+    return get_local_context_db()
 
 
 def add_root(path: str, *, mode: str = "normal", depth: int | None = None) -> dict:

package/src/local_context/db.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Iterable
+
+import paths
+from db._schema import _m63_local_context_layer, _m64_local_context_live_dirs
+
+LOCAL_CONTEXT_DB_NAME = "local-context.db"
+MIGRATION_STATE_KEY = "local_context_db_migrated_from_main"
+MIGRATION_SKIPPED_KEY = "local_context_db_migration_skipped"
+MAIN_CLEANUP_STATE_KEY = "local_context_main_tables_drained"
+
+LOCAL_CONTEXT_TABLES: tuple[str, ...] = (
+    "local_index_roots",
+    "local_index_exclusions",
+    "local_index_jobs",
+    "local_index_checkpoints",
+    "local_index_state",
+    "local_index_errors",
+    "local_index_logs",
+    "local_assets",
+    "local_asset_versions",
+    "local_chunks",
+    "local_entities",
+    "local_relations",
+    "local_embeddings",
+    "local_context_queries",
+    "local_index_dirs",
+)
+
+_CONN: sqlite3.Connection | None = None
+_CONN_PATH: Path | None = None
+_READY = False
+_LAST_MIGRATION_ATTEMPT = 0.0
+_MIGRATION_RETRY_INTERVAL_SECONDS = 300.0
+
+
+def local_context_db_path() -> Path:
+    override = os.environ.get("NEXO_LOCAL_CONTEXT_DB", "").strip()
+    if override:
+        return Path(override).expanduser()
+    test_db = os.environ.get("NEXO_TEST_DB", "").strip()
+    if test_db:
+        return Path(test_db).expanduser().with_name("test_local_context.db")
+    return paths.memory_dir() / LOCAL_CONTEXT_DB_NAME
+
+
+def _main_db_path_for_migration() -> Path:
+    override = os.environ.get("NEXO_LOCAL_CONTEXT_MAIN_DB", "").strip()
+    if override:
+        return Path(override).expanduser()
+    test_db = os.environ.get("NEXO_TEST_DB", "").strip()
+    if test_db:
+        return Path(test_db).expanduser()
+    return paths.db_path()
+
+
+def _busy_timeout_ms() -> int:
+    raw = os.environ.get("NEXO_LOCAL_CONTEXT_DB_BUSY_TIMEOUT_MS", "15000")
+    try:
+        value = int(raw)
+    except Exception:
+        value = 15000
+    return max(1000, min(value, 60000))
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path), timeout=max(_busy_timeout_ms() / 1000.0, 1.0), check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute(f"PRAGMA busy_timeout={_busy_timeout_ms()}")
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA temp_store=MEMORY")
+    return conn
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    _m63_local_context_layer(conn)
+    _m64_local_context_live_dirs(conn)
+    conn.execute("PRAGMA user_version=64")
+    conn.commit()
+
+
+def _table_exists(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> bool:
+    row = conn.execute(
+        f"SELECT 1 FROM {schema}.sqlite_master WHERE type='table' AND name=? LIMIT 1",
+        (table,),
+    ).fetchone()
+    return bool(row)
+
+
+def _table_count(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> int:
+    if not _table_exists(conn, table, schema=schema):
+        return 0
+    row = conn.execute(f"SELECT COUNT(*) AS total FROM {schema}.{_quoted(table)}").fetchone()
+    return int(row["total"] or 0)
+
+
+def _state(conn: sqlite3.Connection, key: str) -> str:
+    row = conn.execute("SELECT value FROM local_index_state WHERE key=?", (key,)).fetchone()
+    return str(row["value"] or "") if row else ""
+
+
+def _set_state(conn: sqlite3.Connection, key: str, value: str) -> None:
+    conn.execute(
+        """
+        INSERT INTO local_index_state(key, value, updated_at)
+        VALUES (?, ?, strftime('%s','now'))
+        ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at
+        """,
+        (key, value),
+    )
+
+
+def _quoted(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _table_columns(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> list[str]:
+    try:
+        rows = conn.execute(f"PRAGMA {schema}.table_info({_quoted(table)})").fetchall()
+    except sqlite3.OperationalError:
+        return []
+    return [str(row["name"]) for row in rows if row["name"]]
+
+
+def _primary_key_columns(conn: sqlite3.Connection, table: str, *, schema: str = "main") -> list[str]:
+    try:
+        rows = conn.execute(f"PRAGMA {schema}.table_info({_quoted(table)})").fetchall()
+    except sqlite3.OperationalError:
+        return []
+    ordered = sorted(
+        (
+            (int(row["pk"] or 0), str(row["name"]))
+            for row in rows
+            if int(row["pk"] or 0) > 0 and row["name"]
+        ),
+        key=lambda item: item[0],
+    )
+    return [name for _order, name in ordered]
+
+
+def _source_rows_missing_in_target(conn: sqlite3.Connection, table: str) -> int:
+    target_pk = _primary_key_columns(conn, table)
+    source_columns = set(_table_columns(conn, table, schema="source"))
+    pk_columns = [column for column in target_pk if column in source_columns]
+    if not pk_columns:
+        raise RuntimeError(f"cannot verify local context migration for {table}: missing primary key")
+    join_sql = " AND ".join(f"s.{_quoted(column)} = t.{_quoted(column)}" for column in pk_columns)
+    null_check = f"t.{_quoted(pk_columns[0])} IS NULL"
+    row = conn.execute(
+        f"SELECT COUNT(*) AS total "
+        f"FROM source.{_quoted(table)} s "
+        f"LEFT JOIN {_quoted(table)} t ON {join_sql} "
+        f"WHERE {null_check}"
+    ).fetchone()
+    return int(row["total"] or 0)
+
+
+def _copy_local_tables(conn: sqlite3.Connection, tables: Iterable[str]) -> dict[str, int]:
+    copied: dict[str, int] = {}
+    for table in tables:
+        if not _table_exists(conn, table, schema="source"):
+            continue
+        target_columns = _table_columns(conn, table)
+        source_columns = set(_table_columns(conn, table, schema="source"))
+        columns = [column for column in target_columns if column in source_columns]
+        if not columns:
+            continue
+        before = _table_count(conn, table)
+        column_sql = ", ".join(_quoted(column) for column in columns)
+        conn.execute(
+            f"INSERT OR IGNORE INTO {_quoted(table)} ({column_sql}) "
+            f"SELECT {column_sql} FROM source.{_quoted(table)}"
+        )
+        after = _table_count(conn, table)
+        copied[table] = max(0, after - before)
+    return copied
+
+
+def _source_table_counts(conn: sqlite3.Connection, tables: Iterable[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for table in tables:
+        if _table_exists(conn, table, schema="source"):
+            counts[table] = _table_count(conn, table, schema="source")
+    return counts
+
+
+def _drain_source_local_tables_if_verified(
+    conn: sqlite3.Connection,
+    source_counts: dict[str, int],
+) -> dict[str, int]:
+    """Clear old local-memory rows from main DB after verifying the copy.
+
+    We keep the table schema in ``nexo.db`` for backward compatibility with
+    older binaries, but empty the rows after the new DB has at least the same
+    number of records per table. This prevents two sources of truth and stops
+    the main DB from carrying the huge local-memory payload.
+    """
+    drained: dict[str, int] = {}
+    if not source_counts:
+        return drained
+
+    for table, source_count in source_counts.items():
+        local_count = _table_count(conn, table)
+        missing = _source_rows_missing_in_target(conn, table)
+        if local_count < source_count or missing:
+            raise RuntimeError(
+                f"local context migration verification failed for {table}: "
+                f"local={local_count} source={source_count} missing={missing}"
+            )
+
+    for table, source_count in source_counts.items():
+        if source_count <= 0:
+            continue
+        conn.execute(f"DELETE FROM source.{_quoted(table)}")
+        drained[table] = source_count
+
+    if drained:
+        _set_state(conn, MAIN_CLEANUP_STATE_KEY, ",".join(sorted(drained)))
+    return drained
+
+
+def migrate_from_main_if_needed(conn: sqlite3.Connection) -> dict:
+    if os.environ.get("NEXO_LOCAL_CONTEXT_DISABLE_MAIN_MIGRATION", "").strip().lower() in {"1", "true", "yes"}:
+        return {"ok": True, "skipped": "disabled"}
+
+    main_db = _main_db_path_for_migration()
+    if not main_db.is_file():
+        _set_state(conn, MIGRATION_SKIPPED_KEY, "main_db_missing")
+        conn.commit()
+        return {"ok": True, "skipped": "main_db_missing"}
+
+    source = str(main_db).replace("'", "''")
+    try:
+        conn.execute("PRAGMA busy_timeout=1000")
+        conn.execute(f"ATTACH DATABASE '{source}' AS source")
+        if not _table_exists(conn, "local_assets", schema="source") and not _table_exists(conn, "local_index_roots", schema="source"):
+            _set_state(conn, MIGRATION_SKIPPED_KEY, "main_local_tables_missing")
+            if _table_count(conn, "local_assets") > 0 or _table_count(conn, "local_index_jobs") > 0:
+                _set_state(conn, MIGRATION_STATE_KEY, "already_has_local_data")
+            conn.commit()
+            return {"ok": True, "skipped": "main_local_tables_missing"}
+        source_counts = _source_table_counts(conn, LOCAL_CONTEXT_TABLES)
+        if not any(source_counts.values()):
+            _set_state(conn, MIGRATION_STATE_KEY, "main_local_tables_empty")
+            _set_state(conn, MAIN_CLEANUP_STATE_KEY, "empty")
+            conn.commit()
+            return {"ok": True, "skipped": "main_local_tables_empty"}
+        copied = _copy_local_tables(conn, LOCAL_CONTEXT_TABLES)
+        drained = _drain_source_local_tables_if_verified(conn, source_counts)
+        _set_state(conn, MIGRATION_STATE_KEY, str(main_db))
+        _set_state(conn, "local_context_db_migrated_rows", str(sum(copied.values())))
+        if drained:
+            _set_state(conn, "local_context_main_tables_drained_rows", str(sum(drained.values())))
+        conn.commit()
+        return {"ok": True, "migrated_from": str(main_db), "copied": copied, "drained": drained}
+    except sqlite3.OperationalError as exc:
+        message = str(exc)
+        _set_state(conn, MIGRATION_SKIPPED_KEY, message[:240])
+        _set_state(conn, "local_context_db_drain_pending", "main_db_busy_or_unavailable")
+        conn.commit()
+        return {"ok": True, "skipped": "main_db_busy_or_unavailable", "error": message, "retry_pending": True}
+    finally:
+        try:
+            conn.execute("DETACH DATABASE source")
+        except Exception:
+            pass
+        conn.execute(f"PRAGMA busy_timeout={_busy_timeout_ms()}")
+
+
+def ensure_local_context_db() -> None:
+    global _CONN, _CONN_PATH, _READY, _LAST_MIGRATION_ATTEMPT
+    db_path = local_context_db_path()
+    if _CONN is not None and _CONN_PATH != db_path:
+        close_local_context_db()
+    if _CONN is None:
+        _CONN = _connect(db_path)
+        _CONN_PATH = db_path
+    now = time.monotonic()
+    if _READY:
+        if now - _LAST_MIGRATION_ATTEMPT >= _MIGRATION_RETRY_INTERVAL_SECONDS:
+            _LAST_MIGRATION_ATTEMPT = now
+            try:
+                migrate_from_main_if_needed(_CONN)
+            except Exception:
+                # Sidecar data is still usable; cleanup from the old main DB is
+                # best-effort and will retry on later service cycles.
+                pass
+        return
+    _ensure_schema(_CONN)
+    _LAST_MIGRATION_ATTEMPT = now
+    migration = migrate_from_main_if_needed(_CONN)
+    _READY = True
+
+
+def get_local_context_db() -> sqlite3.Connection:
+    ensure_local_context_db()
+    assert _CONN is not None
+    return _CONN
+
+
+def close_local_context_db() -> None:
+    global _CONN, _CONN_PATH, _READY, _LAST_MIGRATION_ATTEMPT
+    if _CONN is not None:
+        try:
+            _CONN.close()
+        except Exception:
+            pass
+    _CONN = None
+    _CONN_PATH = None
+    _READY = False
+    _LAST_MIGRATION_ATTEMPT = 0.0

package/src/local_context/logging.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-from db import get_db
-
+from .db import get_local_context_db
 from .util import json_dumps, now
 
 
 def log_event(level: str, event: str, message: str, **metadata) -> None:
-    conn = get_db()
+    conn = get_local_context_db()
     conn.execute(
         """
         INSERT INTO local_index_logs(created_at, level, event, message, metadata_json)
@@ -18,7 +17,7 @@ def log_event(level: str, event: str, message: str, **metadata) -> None:
 
 
 def tail(limit: int = 100) -> list[dict]:
-    conn = get_db()
+    conn = get_local_context_db()
     rows = conn.execute(
         """
         SELECT created_at, level, event, message, metadata_json

package/src/mcp_required_tools.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+"""Required MCP tool contract shared by Brain and Desktop probes.
+
+These tools are the minimum bootstrap surface NEXO Desktop needs before a
+conversation can be considered healthy. Dynamic plugin loading may still add
+more tools, but these names must always be present.
+"""
+
+BOOTSTRAP_REQUIRED_MCP_TOOLS: tuple[str, ...] = (
+    "nexo_startup",
+    "nexo_heartbeat",
+    "nexo_session_diary_read",
+    "nexo_reminders",
+    "nexo_smart_startup",
+    "nexo_task_open",
+    "nexo_task_close",
+    "nexo_task_acknowledge_guard",
+    "nexo_guard_check",
+    "nexo_learning_add",
+    "nexo_confidence_check",
+    "nexo_followup_create",
+    "nexo_protocol_debt_resolve",
+    "nexo_card_match",
+    "nexo_skill_match",
+)
+
+
+def missing_required_tools(tool_names: list[str] | tuple[str, ...] | set[str]) -> list[str]:
+    available = {str(name) for name in tool_names}
+    return [name for name in BOOTSTRAP_REQUIRED_MCP_TOOLS if name not in available]