nexo-brain 7.10.1 → 7.11.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.10.1",
+  "version": "7.11.1",
   "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,7 @@
 
 [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.10.1` is the current packaged-runtime line. Patch release — removes a residual "Custom LLM endpoint (advanced)" section in this README that still documented the `llm_endpoint.json` / `auth_provider.json` override path as a current feature, including the `Idempotency-Key` proxy semantics and a pointer to the now-deleted `docs/api/override-files.md`. The 7.10.0 code revert was complete; the README cleanup landed in 7.10.1.
+Version `7.11.1` is the current packaged-runtime line. Patch release — caches the runtime fingerprint by `(file_count, size_total, max_mtime)` signature so MCP startup and the per-tool-call `resolve_restart_required` skip the 263-file rehash when nothing on disk changed. ~11× speedup warm path (~40ms → ~3.7ms locally), ~10-20s/day saved across Claude Code / Codex / headless / deep-sleep / cron startups. Cache miss is always safe (falls through to full hash and self-repairs). Default `use_cache=False` keeps `plugins/update.py` on the ground-truth path around `git pull` / `npm update`. Builds on the v7.11.0 runtime fingerprint that gates `mcp-restart-required.json`. Full write-up in [`docs/runtime-fingerprint.md`](docs/runtime-fingerprint.md).
 
 Previously in `7.10.0`: minor release — **removes the LLM proxy override path that 7.9.28 → 7.9.34 introduced**. Background: 7.9.28 added two opt-in files at `~/.nexo/config/llm_endpoint.json` and `~/.nexo/config/auth_provider.json` that let a third-party orchestrator (NEXO Desktop) redirect every Anthropic SDK call from Brain to a custom proxy and resolve the bearer via a local helper, with concrete model names translated to wire aliases (`nexo-max`, `nexo-high`, `nexo-medium`, `nexo-low`, `nexo-mini`) and an `Idempotency-Key` per request. NEXO Desktop's commercial model has changed: Desktop is now a wrapper over the user's own Claude Code subscription (Max / Pro), with a separate Desktop licence. Brain calls go directly to `api.anthropic.com` using the user's existing OAuth (the one stored under `~/.claude/` and consumed by Claude Code spawns) or a plain `ANTHROPIC_API_KEY`. There is no NEXO bearer, no NEXO proxy, no NEXO credit accounting in this codebase. Every proxy symbol is gone from `call_model_raw.py` and `agent_runner.py`; the proxy-specific tests and `docs/api/override-files.md` are removed; any pre-existing override files on disk are simply ignored from this release forward.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.10.1",
+  "version": "7.11.1",
   "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/plugins/update.py

@@ -12,7 +12,12 @@ import time
 from pathlib import Path
 
 from runtime_home import export_resolved_nexo_home
-from runtime_versioning import activate_versioned_runtime_snapshot, write_restart_required_marker
+from runtime_versioning import (
+    activate_versioned_runtime_snapshot,
+    compute_mcp_runtime_fingerprint,
+    installed_force_restart_flag,
+    write_restart_required_marker,
+)
 
 try:
     from tree_hygiene import is_duplicate_artifact_name
@@ -1066,6 +1071,11 @@ def _reload_launch_agents_after_bump() -> dict:
 def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> str:
     """Update a packaged (npm) install — no git repo available."""
     old_version = _read_version()
+    # Capture pre-update fingerprint of the installed runtime so we can decide
+    # whether the npm payload actually changed any MCP-loaded source byte.
+    # Empty string = "fingerprint unavailable", which the marker logic below
+    # treats as "assume changed" (safe fallback).
+    old_fingerprint = compute_mcp_runtime_fingerprint(_runtime_code_root())
 
     # 0. Pre-flight wipe guard (v5.5.5+)
     _emit_progress(progress_fn, "Checking DB integrity before update...")
@@ -1222,6 +1232,9 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
 
     versioned_runtime_summary = None
     restart_marker_summary = None
+    mcp_code_changed = False
+    force_restart = False
+    new_fingerprint = ""
     if old_version != new_version:
         try:
             _emit_progress(progress_fn, "Activating versioned runtime snapshot...")
@@ -1231,13 +1244,35 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
             )
         except Exception as e:
             errors.append(f"versioned runtime activation: {e}")
+        # Decide whether the new release actually altered any MCP-loaded
+        # source file. Doc-only / blog-only / changelog-only releases keep
+        # the same fingerprint and skip the restart marker entirely.
         try:
-            restart_marker_summary = write_restart_required_marker(
-                from_version=old_version,
-                to_version=new_version,
-            )
-        except Exception as e:
-            errors.append(f"restart marker: {e}")
+            new_fingerprint = compute_mcp_runtime_fingerprint(_runtime_code_root())
+        except Exception:
+            new_fingerprint = ""
+        try:
+            force_restart = installed_force_restart_flag()
+        except Exception:
+            force_restart = False
+        # Conservative default: if either fingerprint is missing, behave as
+        # before and force a restart (#186 — never leave a stale process
+        # silently running new bytes).
+        if not old_fingerprint or not new_fingerprint:
+            mcp_code_changed = True
+        else:
+            mcp_code_changed = old_fingerprint != new_fingerprint
+        if mcp_code_changed or force_restart:
+            try:
+                restart_marker_summary = write_restart_required_marker(
+                    from_version=old_version,
+                    to_version=new_version,
+                    reason="brain_update_force" if (force_restart and not mcp_code_changed) else "brain_update",
+                    from_fingerprint=old_fingerprint,
+                    to_fingerprint=new_fingerprint,
+                )
+            except Exception as e:
+                errors.append(f"restart marker: {e}")
 
     if errors:
         # 5. Full rollback: restore code tree + DBs + pip deps + rollback npm package
@@ -1305,7 +1340,15 @@ def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> s
     if restart_marker_summary:
         lines.append(f"  Restart marker: {restart_marker_summary.get('path')}")
     lines.append("")
-    lines.append("MCP server restart needed to load new code.")
+    if old_version != new_version and not mcp_code_changed and not force_restart:
+        # Doc-only / blog-only / changelog-only release. The bytes the running
+        # MCP imports are byte-identical to what's now on disk, so existing
+        # MCP clients keep working without a forced restart.
+        lines.append(
+            "MCP source unchanged (no `.py` byte changed) — no restart needed."
+        )
+    else:
+        lines.append("MCP server restart needed to load new code.")
     return "\n".join(lines)
 
 
@@ -1361,6 +1404,9 @@ def handle_update(
         # Record current state
         old_version = _read_version()
         old_req_hash = _requirements_hash()
+        # Capture pre-pull fingerprint so we can detect doc-only releases that
+        # bump version.json but never touch a single MCP-loaded `.py` byte.
+        old_fingerprint = compute_mcp_runtime_fingerprint(SRC_DIR)
         rc, old_commit, _ = _git("rev-parse", "HEAD")
         if rc != 0:
             return "ABORTED: Not a git repository or git not available."
@@ -1516,6 +1562,9 @@ def handle_update(
 
         versioned_runtime_summary = None
         restart_marker_summary = None
+        mcp_code_changed = False
+        force_restart = False
+        new_fingerprint = ""
         if version_changed:
             try:
                 _emit_progress(progress_fn, "Activating versioned runtime snapshot...")
@@ -1526,14 +1575,35 @@ def handle_update(
                 steps_done.append("versioned-runtime")
             except Exception as e:
                 raise RuntimeError(f"Versioned runtime activation failed: {e}")
+            # Decide whether the new release actually altered any MCP-loaded
+            # source file. Doc-only / blog-only / changelog-only releases keep
+            # the same fingerprint and skip the restart marker entirely.
             try:
-                restart_marker_summary = write_restart_required_marker(
-                    from_version=old_version,
-                    to_version=new_version,
-                )
-                steps_done.append("restart-marker")
-            except Exception as e:
-                raise RuntimeError(f"Restart marker write failed: {e}")
+                new_fingerprint = compute_mcp_runtime_fingerprint(SRC_DIR)
+            except Exception:
+                new_fingerprint = ""
+            try:
+                force_restart = installed_force_restart_flag()
+            except Exception:
+                force_restart = False
+            # Conservative default: if either fingerprint is missing, treat as
+            # changed and force restart (#186).
+            if not old_fingerprint or not new_fingerprint:
+                mcp_code_changed = True
+            else:
+                mcp_code_changed = old_fingerprint != new_fingerprint
+            if mcp_code_changed or force_restart:
+                try:
+                    restart_marker_summary = write_restart_required_marker(
+                        from_version=old_version,
+                        to_version=new_version,
+                        reason="brain_update_force" if (force_restart and not mcp_code_changed) else "brain_update",
+                        from_fingerprint=old_fingerprint,
+                        to_fingerprint=new_fingerprint,
+                    )
+                    steps_done.append("restart-marker")
+                except Exception as e:
+                    raise RuntimeError(f"Restart marker write failed: {e}")
 
         # Build result
         dep_summary_lines = _format_dep_results(dep_results)
@@ -1570,7 +1640,15 @@ def handle_update(
         if restart_marker_summary:
             lines.append(f"  Restart marker: {restart_marker_summary.get('path')}")
         lines.append("")
-        lines.append("MCP server restart needed to load new code.")
+        if version_changed and not mcp_code_changed and not force_restart:
+            # Doc-only / blog-only / changelog-only release. The bytes the
+            # running MCP imports are byte-identical to what's now on disk, so
+            # existing MCP clients keep working without a forced restart.
+            lines.append(
+                "MCP source unchanged (no `.py` byte changed) — no restart needed."
+            )
+        else:
+            lines.append("MCP server restart needed to load new code.")
         return "\n".join(lines)
 
     except Exception as e:

package/src/runtime_versioning.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import shutil
@@ -14,8 +15,25 @@ import paths
 
 
 CONTINUITY_API_LEVEL = 1
-MCP_STATUS_SCHEMA_VERSION = 1
+MCP_STATUS_SCHEMA_VERSION = 2
 PROCESS_VERSION = ""
+PROCESS_FINGERPRINT = ""
+
+# Subtrees under the runtime source root that are NOT loaded by the running
+# MCP server process (subprocess scripts, test fixtures, migrations executed
+# out-of-process, cron entry points spawned separately). Any change limited
+# to these directories should NOT force a restart of running MCP clients.
+# Anything else under the runtime root (server.py, cli.py, plugins/*, helpers)
+# is included in the fingerprint by default.
+_FINGERPRINT_EXCLUDE_DIRS = frozenset({
+    "scripts",
+    "tests",
+    "migrations",
+    "crons",
+    "__pycache__",
+    "node_modules",
+    ".git",
+})
 RESTART_CLIENT_ACTIONS = {
     "claude_desktop": "restart_client_required",
     "claude_code": "restart_session_required",
@@ -142,6 +160,98 @@ def restart_required_marker_path() -> Path:
     return paths.operations_dir() / "mcp-restart-required.json"
 
 
+def fingerprint_cache_path() -> Path:
+    """Where the runtime fingerprint cache lives.
+
+    The cache lets `prime_process_fingerprint()` and `installed_runtime_fingerprint()`
+    skip hashing 200+ source files on every MCP startup / tool call when the
+    runtime tree on disk hasn't changed (same file count, same total size, same
+    max mtime). Invalidates automatically when any source byte changes.
+    """
+    return paths.operations_dir() / "fingerprint-cache.json"
+
+
+def _runtime_tree_signature(src_dir: Path) -> tuple[int, int, float] | None:
+    """Cheap stat-only walk over the fingerprint-tracked tree.
+
+    Returns ``(file_count, size_total, max_mtime)`` or ``None`` when the source
+    tree cannot be traversed. This is the cache key — if it matches, the bytes
+    haven't changed in any way the fingerprint would care about.
+    """
+    try:
+        files = _iter_runtime_source_files(src_dir)
+    except Exception:
+        return None
+    if not files:
+        return None
+    count = 0
+    size_total = 0
+    max_mtime = 0.0
+    for path in files:
+        try:
+            st = path.stat()
+        except Exception:
+            return None
+        count += 1
+        size_total += int(st.st_size)
+        if st.st_mtime > max_mtime:
+            max_mtime = float(st.st_mtime)
+    return (count, size_total, max_mtime)
+
+
+def _read_fingerprint_cache(src_dir: Path) -> str:
+    """Return cached fingerprint when the on-disk signature still matches.
+
+    Empty string means cache miss (corrupt, missing, or signature drifted).
+    Cache miss is always safe — caller falls through to a full hash.
+    """
+    cache_path = fingerprint_cache_path()
+    if not cache_path.is_file():
+        return ""
+    try:
+        payload = json.loads(cache_path.read_text(encoding="utf-8"))
+    except Exception:
+        return ""
+    if not isinstance(payload, dict):
+        return ""
+    if str(payload.get("src_dir") or "") != str(src_dir):
+        return ""
+    sig = _runtime_tree_signature(src_dir)
+    if sig is None:
+        return ""
+    try:
+        cached_count = int(payload.get("file_count"))
+        cached_size = int(payload.get("size_total"))
+        cached_mtime = float(payload.get("max_mtime"))
+    except (TypeError, ValueError):
+        return ""
+    if cached_count != sig[0] or cached_size != sig[1] or cached_mtime != sig[2]:
+        return ""
+    fingerprint = str(payload.get("fingerprint") or "").strip()
+    return fingerprint
+
+
+def _write_fingerprint_cache(src_dir: Path, fingerprint: str) -> None:
+    """Persist the fingerprint+signature pair. Best-effort; failures don't propagate."""
+    if not fingerprint:
+        return
+    sig = _runtime_tree_signature(src_dir)
+    if sig is None:
+        return
+    payload = {
+        "fingerprint": fingerprint,
+        "src_dir": str(src_dir),
+        "file_count": sig[0],
+        "size_total": sig[1],
+        "max_mtime": sig[2],
+        "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    try:
+        _write_json_atomic(fingerprint_cache_path(), payload)
+    except Exception:
+        pass
+
+
 def _candidate_version_files(base: Path) -> list[Path]:
     return [
         base / "version.json",
@@ -170,6 +280,155 @@ def installed_runtime_version() -> str:
     return ""
 
 
+def installed_force_restart_flag() -> bool:
+    """Read explicit `force_restart` opt-in from version.json/package.json.
+
+    A release that touches behavior in subtle ways (config schema, runtime
+    contract) but happens not to change any tracked MCP source byte can still
+    force a restart by setting `force_restart: true` in version.json. Default
+    is False — fingerprint is the source of truth.
+    """
+    for candidate in [active_runtime_root(), paths.home()]:
+        for vfile in _candidate_version_files(candidate):
+            try:
+                if vfile.is_file():
+                    payload = json.loads(vfile.read_text(encoding="utf-8"))
+                    if isinstance(payload, dict) and bool(payload.get("force_restart")):
+                        return True
+            except Exception:
+                continue
+    return False
+
+
+def _iter_runtime_source_files(src_dir: Path) -> list[Path]:
+    """Return MCP-loaded `.py` files under `src_dir`, sorted by relative path."""
+    out: list[Path] = []
+    if not src_dir or not src_dir.is_dir():
+        return out
+    for path in src_dir.rglob("*.py"):
+        try:
+            rel = path.relative_to(src_dir)
+        except ValueError:
+            continue
+        if any(seg in _FINGERPRINT_EXCLUDE_DIRS for seg in rel.parts):
+            continue
+        out.append(path)
+    out.sort(key=lambda p: p.relative_to(src_dir).as_posix())
+    return out
+
+
+def compute_mcp_runtime_fingerprint(
+    src_dir: Path | None = None, *, use_cache: bool = False
+) -> str:
+    """Hash of every Python source file the running MCP can import.
+
+    Returns a sha256 hex digest, or "" when the source tree cannot be located
+    or read (caller treats empty as "fingerprint unavailable" and falls back
+    to the version-string mismatch check).
+
+    Includes:
+      * every `.py` under the runtime root
+    Excludes:
+      * subtrees in `_FINGERPRINT_EXCLUDE_DIRS` (scripts/, tests/, migrations/,
+        crons/, __pycache__/, node_modules/, .git/)
+      * non-`.py` assets (docs, blogs, READMEs, JSON/YAML configs, templates,
+        CHANGELOG, marketing files) — these never affect what the live MCP
+        process executes
+
+    When ``use_cache=True`` (hot paths: server startup, every tool call) the
+    function consults ``fingerprint-cache.json``: if the on-disk tree
+    signature (file count + total size + max mtime) still matches the cached
+    one, the cached digest is returned without re-reading any byte. Cache miss
+    falls through to the normal full-hash path and writes a fresh entry. The
+    update flow keeps ``use_cache=False`` (default) so it always sees ground
+    truth around the pull/npm step.
+    """
+    if src_dir is None:
+        candidates: list[Path] = []
+        try:
+            here = Path(__file__).resolve().parent
+            candidates.append(here)
+        except Exception:
+            pass
+        try:
+            root = active_runtime_root()
+            if root and root not in candidates:
+                candidates.append(root)
+        except Exception:
+            pass
+        try:
+            home = paths.home()
+            if home and home not in candidates:
+                candidates.append(home)
+        except Exception:
+            pass
+        for cand in candidates:
+            if (cand / "server.py").is_file() or (cand / "cli.py").is_file():
+                src_dir = cand
+                break
+        if src_dir is None:
+            return ""
+
+    if use_cache:
+        cached = _read_fingerprint_cache(src_dir)
+        if cached:
+            return cached
+
+    files = _iter_runtime_source_files(src_dir)
+    if not files:
+        return ""
+    h = hashlib.sha256()
+    for path in files:
+        try:
+            rel = path.relative_to(src_dir).as_posix()
+        except ValueError:
+            continue
+        h.update(rel.encode("utf-8"))
+        h.update(b"\x00")
+        try:
+            h.update(path.read_bytes())
+        except Exception:
+            return ""
+        h.update(b"\n")
+    digest = h.hexdigest()
+    if use_cache and digest:
+        _write_fingerprint_cache(src_dir, digest)
+    return digest
+
+
+def installed_runtime_fingerprint() -> str:
+    """Fingerprint of whatever runtime source tree is on disk right now.
+
+    Hot path — runs on every MCP tool call via ``resolve_restart_required``.
+    Uses the disk-signature cache so a repeated call without any source
+    change is a few stat() syscalls instead of 200+ file reads.
+    """
+    candidates: list[Path] = []
+    try:
+        root = active_runtime_root()
+        if root:
+            candidates.append(root)
+    except Exception:
+        pass
+    try:
+        home = paths.home()
+        if home and home not in candidates:
+            candidates.append(home)
+    except Exception:
+        pass
+    try:
+        here = Path(__file__).resolve().parent
+        if here not in candidates:
+            candidates.append(here)
+    except Exception:
+        pass
+    for cand in candidates:
+        fp = compute_mcp_runtime_fingerprint(cand, use_cache=True)
+        if fp:
+            return fp
+    return ""
+
+
 def read_restart_required_marker() -> dict:
     path = restart_required_marker_path()
     if not path.exists():
@@ -198,6 +457,8 @@ def write_restart_required_marker(
     to_version: str,
     reason: str = "brain_update",
     client: str = "",
+    from_fingerprint: str = "",
+    to_fingerprint: str = "",
 ) -> dict:
     path = restart_required_marker_path()
     payload = {
@@ -205,6 +466,8 @@ def write_restart_required_marker(
         "required": True,
         "from_version": str(from_version or "").strip(),
         "to_version": str(to_version or "").strip(),
+        "from_fingerprint": str(from_fingerprint or "").strip(),
+        "to_fingerprint": str(to_fingerprint or "").strip(),
         "reason": str(reason or "brain_update"),
         "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
         "clients": _restart_clients_for_marker(client=client),
@@ -264,7 +527,14 @@ def activate_versioned_runtime_snapshot(*, source_root: Path | None = None, vers
     }
 
 
-def clear_restart_required_marker(*, client: str = "", installed_version: str = "", process_version: str = "") -> dict:
+def clear_restart_required_marker(
+    *,
+    client: str = "",
+    installed_version: str = "",
+    process_version: str = "",
+    installed_fingerprint: str = "",
+    process_fingerprint: str = "",
+) -> dict:
     client = _normalize_restart_client(client)
     path = restart_required_marker_path()
     marker = read_restart_required_marker()
@@ -285,10 +555,31 @@ def clear_restart_required_marker(*, client: str = "", installed_version: str =
     pending_clients = {k: v for k, v in clients.items() if v != "ok"}
     effective_installed = str(installed_version or payload.get("to_version") or "").strip()
     effective_process = str(process_version or "").strip()
+    effective_installed_fp = str(
+        installed_fingerprint or payload.get("to_fingerprint") or ""
+    ).strip()
+    effective_process_fp = str(
+        process_fingerprint or PROCESS_FINGERPRINT or ""
+    ).strip()
     if pending_clients:
         _write_json_atomic(path, payload)
         return {"ok": True, "cleared": False, "path": str(path), "pending_clients": pending_clients}
-    if effective_installed and effective_process and effective_installed != effective_process:
+    # Prefer fingerprint match when both sides have it; fall back to version
+    # comparison only when one side is missing or unknown.
+    if (
+        effective_installed_fp
+        and effective_process_fp
+        and effective_process_fp != "unknown"
+    ):
+        if effective_installed_fp != effective_process_fp:
+            _write_json_atomic(path, payload)
+            return {
+                "ok": True,
+                "cleared": False,
+                "path": str(path),
+                "pending_reason": "process_fingerprint_mismatch",
+            }
+    elif effective_installed and effective_process and effective_installed != effective_process:
         _write_json_atomic(path, payload)
         return {
             "ok": True,
@@ -303,15 +594,25 @@ def clear_restart_required_marker(*, client: str = "", installed_version: str =
     return {"ok": True, "cleared": True, "path": str(path)}
 
 
-def resolve_restart_required(*, client: str = "", installed_version: str = "", process_version: str = "") -> dict:
+def resolve_restart_required(
+    *,
+    client: str = "",
+    installed_version: str = "",
+    process_version: str = "",
+    installed_fingerprint: str = "",
+    process_fingerprint: str = "",
+) -> dict:
     client = _normalize_restart_client(client)
     marker = read_restart_required_marker()
     installed = str(installed_version or installed_runtime_version() or "").strip()
     process = str(process_version or PROCESS_VERSION or installed).strip()
+    installed_fp = str(installed_fingerprint or installed_runtime_fingerprint() or "").strip()
+    process_fp = str(process_fingerprint or PROCESS_FINGERPRINT or "").strip()
     restart_required = False
     reason = ""
     client_action = ""
     marker_clients = dict(marker.get("clients") or {})
+    fingerprint_usable = bool(installed_fp) and bool(process_fp) and process_fp != "unknown"
 
     if marker.get("required"):
         restart_required = True
@@ -320,7 +621,16 @@ def resolve_restart_required(*, client: str = "", installed_version: str = "", p
     if marker.get("corrupt"):
         restart_required = True
         reason = "marker_corrupt"
-    elif installed and process and installed != process:
+    elif fingerprint_usable and installed_fp != process_fp:
+        # Primary signal: the bytes the running process loaded differ from the
+        # bytes currently on disk. Doc-only / blog-only releases produce no
+        # fingerprint change and therefore never reach this branch.
+        restart_required = True
+        reason = reason or "fingerprint_mismatch"
+    elif not fingerprint_usable and installed and process and installed != process:
+        # Fallback: when fingerprint can't be computed (missing source tree,
+        # unreadable files, fresh install), fall back to the legacy version
+        # mismatch check so we never leave a stale process running unnoticed.
         restart_required = True
         reason = reason or "version_mismatch"
     elif client and client_action == "ok":
@@ -334,6 +644,8 @@ def resolve_restart_required(*, client: str = "", installed_version: str = "", p
         "marker": marker,
         "installed_version": installed,
         "process_version": process,
+        "installed_fingerprint": installed_fp,
+        "process_fingerprint": process_fp,
     }
 
 
@@ -341,12 +653,22 @@ def build_mcp_status(*, client: str = "") -> dict:
     client = _normalize_restart_client(client)
     state = resolve_restart_required(client=client)
     marker = state["marker"]
+    installed_fp = state.get("installed_fingerprint", "")
+    process_fp = state.get("process_fingerprint", "")
     return {
         "ok": True,
         "schema_version": MCP_STATUS_SCHEMA_VERSION,
         "client": str(client or "").strip(),
         "installed_version": state["installed_version"],
         "process_version": state["process_version"],
+        "installed_fingerprint": installed_fp,
+        "process_fingerprint": process_fp,
+        "fingerprint_match": (
+            bool(installed_fp)
+            and bool(process_fp)
+            and process_fp != "unknown"
+            and installed_fp == process_fp
+        ),
         "active_runtime_root": str(active_runtime_root()),
         "active_runtime_version": read_version_for_path(active_runtime_root()),
         "restart_required": bool(state["restart_required"]),
@@ -377,6 +699,46 @@ def prime_process_version() -> str:
     return PROCESS_VERSION
 
 
+def prime_process_fingerprint() -> str:
+    """Cache the fingerprint of the source tree this process was loaded from.
+
+    Idempotent. Called once at MCP server startup. After that, the cached
+    value reflects what the live process has actually imported, regardless of
+    what is later written to disk by `nexo update`.
+
+    Returns the cached digest (sha256 hex) or the literal string `"unknown"`
+    when the source tree cannot be located/read at startup time.
+    """
+    global PROCESS_FINGERPRINT
+    if PROCESS_FINGERPRINT:
+        return PROCESS_FINGERPRINT
+    candidates: list[Path] = []
+    try:
+        here = Path(__file__).resolve().parent
+        candidates.append(here)
+    except Exception:
+        pass
+    try:
+        root = active_runtime_root()
+        if root and root not in candidates:
+            candidates.append(root)
+    except Exception:
+        pass
+    try:
+        home = paths.home()
+        if home and home not in candidates:
+            candidates.append(home)
+    except Exception:
+        pass
+    for cand in candidates:
+        fp = compute_mcp_runtime_fingerprint(cand, use_cache=True)
+        if fp:
+            PROCESS_FINGERPRINT = fp
+            return PROCESS_FINGERPRINT
+    PROCESS_FINGERPRINT = "unknown"
+    return PROCESS_FINGERPRINT
+
+
 @dataclass
 class RestartRequiredMiddleware(Middleware):
     client: str = ""
@@ -389,18 +751,31 @@ class RestartRequiredMiddleware(Middleware):
             return state
         installed = str(state.get("installed_version") or "").strip()
         process = str(state.get("process_version") or "").strip()
-        if not installed or not process or installed != process:
-            return state
+        installed_fp = str(state.get("installed_fingerprint") or "").strip()
+        process_fp = str(state.get("process_fingerprint") or "").strip()
+        fingerprint_usable = (
+            bool(installed_fp) and bool(process_fp) and process_fp != "unknown"
+        )
+        if fingerprint_usable:
+            if installed_fp != process_fp:
+                return state
+        else:
+            if not installed or not process or installed != process:
+                return state
 
         clear_restart_required_marker(
             client=self.client,
             installed_version=installed,
             process_version=process,
+            installed_fingerprint=installed_fp,
+            process_fingerprint=process_fp,
         )
         return resolve_restart_required(
             client=self.client,
             installed_version=installed,
             process_version=process,
+            installed_fingerprint=installed_fp,
+            process_fingerprint=process_fp,
         )
 
     async def _tool_result_for_restart_required(self, context, payload: dict) -> ToolResult:

package/src/server.py

@@ -94,6 +94,7 @@ from tools_guardian import handle_guardian_rule_override
 from runtime_versioning import (
     RestartRequiredMiddleware,
     build_mcp_status,
+    prime_process_fingerprint,
     prime_process_version,
 )
 
@@ -276,6 +277,7 @@ mcp = FastMCP(
     ),
 )
 prime_process_version()
+prime_process_fingerprint()
 mcp.add_middleware(
     RestartRequiredMiddleware(client=str(os.environ.get("NEXO_MCP_CLIENT", "") or "").strip())
 )