nexo-brain 7.10.0 → 7.11.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.10.0",
+  "version": "7.11.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,9 @@
 
 [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.0` is the current packaged-runtime line. 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.
+Version `7.11.0` is the current packaged-runtime line. Minor release — introduces a runtime fingerprint that gates `mcp-restart-required.json`. `nexo update` now only forces connected MCP clients (Claude Code, Codex, Claude Desktop) to restart when at least one `.py` file the running server actually imports has changed. README-only, blog-only, changelog-only releases skip the restart entirely. Conservative fallback (#186): if the fingerprint can't be computed, the gate behaves like the legacy version-string check and writes the marker. Explicit opt-in escape hatch via `"force_restart": true` in `version.json`. Marker schema bumped to v2 with optional `from_fingerprint` / `to_fingerprint`. 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.
 
 Previously in `7.9.34`: two fixes — the email monitor's header parser was dropping any email whose RFC822 headers came back as `email.header.Header` instances (Q-encoded utf-8 / quoted-printable). Every `msg.get(...)` now goes through `_decode_header`, and the failure log is lifted from DEBUG to WARNING. The PreToolUse Guardian gate hardens hard blocks with stderr + exit 2 enforcement so terminal Claude cannot ignore the deny channel mid-tool-loop.
 
@@ -1093,19 +1095,6 @@ Use a personal plugin only when you need a new MCP tool in the runtime surface.
 - **Auto-update is resilient.** NEXO checks for updates on startup. If an update fails, it continues with the current version and notifies you. Local migrations (database schema, configuration) always run. Network updates (git pull) can be disabled by setting `auto_update: false` in `NEXO_HOME/config/schedule.json`.
 - **Secret redaction.** API keys and tokens are stripped before they ever reach memory storage.
 
-## Custom LLM endpoint (advanced)
-
-NEXO Brain reads two optional override files at `~/.nexo/config/`:
-
-- `llm_endpoint.json` — set a custom Anthropic-compatible base URL.
-- `auth_provider.json` — delegate bearer token resolution to a local command (analogous to git's `credential.helper`).
-
-This lets third-party orchestrators — for example an Anthropic-compatible proxy that adds rate limiting, cost accounting, multi-provider failover, or per-team auth — route Brain's LLM calls without modifying its source.
-
-**If neither file exists, Brain operates exactly as before:** direct call to `https://api.anthropic.com` using `ANTHROPIC_API_KEY` from environment or filesystem. The override path is opt-in.
-
-When override mode is active, Brain attaches an opaque `Idempotency-Key` to every request so the proxy can dedup transparent retries (24h window) without double-billing. The same redirection applies to every CLI child Brain spawns (deep-sleep, evolution, followup-runner, morning-agent, email-monitor, `nexo chat`): `agent_runner.py` injects `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` into the spawned environment when override mode is on, so headless crons hit the proxy too — LaunchAgent crons do not inherit env from a UI process. See `docs/api/override-files.md` for the full schema, fallback rules, and an end-to-end example.
-
 ## The Psychology Behind NEXO Brain
 
 NEXO Brain isn't just engineering — it's applied cognitive psychology:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.10.0",
+  "version": "7.11.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/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",
@@ -170,6 +188,132 @@ 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) -> 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
+    """
+    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 ""
+
+    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")
+    return h.hexdigest()
+
+
+def installed_runtime_fingerprint() -> str:
+    """Fingerprint of whatever runtime source tree is on disk right now."""
+    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)
+        if fp:
+            return fp
+    return ""
+
+
 def read_restart_required_marker() -> dict:
     path = restart_required_marker_path()
     if not path.exists():
@@ -198,6 +342,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 +351,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 +412,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 +440,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 +479,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 +506,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 +529,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 +538,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 +584,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)
+        if fp:
+            PROCESS_FINGERPRINT = fp
+            return PROCESS_FINGERPRINT
+    PROCESS_FINGERPRINT = "unknown"
+    return PROCESS_FINGERPRINT
+
+
 @dataclass
 class RestartRequiredMiddleware(Middleware):
     client: str = ""
@@ -389,18 +636,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())
 )