wazionapps/nexo

Summary

Before this release every nexo update that bumped version.json wrote mcp-restart-required.json and forced every connected MCP client (Claude Code, Codex, Claude Desktop) to drop its session and reconnect — even when the release was byte-identical to the running code at the Python level (cf. v7.10.1, a README-only release that still triggered a forced restart for everyone).

v7.11.0 introduces a runtime fingerprint: a sha256 digest over every .py file under src/ that the live MCP server can import (excluding scripts/, tests/, migrations/, crons/, __pycache__/, node_modules/, .git/). nexo update only writes the restart marker when that fingerprint actually changes between the pre-update and post-update trees.

• README-only / blog-only / changelog-only releases now skip the marker entirely. nexo update reports MCP source unchanged (no .py byte changed) — no restart needed.
• Real code changes still write the marker. Same restart UX as before.
• Conservative fallback honored (learning #186): when either fingerprint can't be computed, behave like the legacy version-string check.
• Explicit opt-in escape hatch: "force_restart": true in version.json for releases whose behavior change can't be detected from .py bytes (e.g. wire format of a config file read via json.load).

The running server caches its own fingerprint at startup (prime_process_fingerprint() next to the existing prime_process_version()), so the in-process check (resolve_restart_required) is content-aware too. mcp-restart-required.json schema bumped to v2 with optional from_fingerprint / to_fingerprint; v1 reader stays backwards-compatible. nexo mcp-status --json now exposes installed_fingerprint, process_fingerprint, fingerprint_match.

Full design + behavior matrix in docs/runtime-fingerprint.md.

What changed

• src/runtime_versioning.py — new helpers compute_mcp_runtime_fingerprint, installed_runtime_fingerprint, prime_process_fingerprint, installed_force_restart_flag. Module-level PROCESS_FINGERPRINT cache. Refactored resolve_restart_required, clear_restart_required_marker, build_mcp_status, RestartRequiredMiddleware._ack_current_client_if_restarted to prefer fingerprint and fall back to version when fingerprint is unavailable.
• src/server.py — calls prime_process_fingerprint() next to prime_process_version().
• src/plugins/update.py — both git and packaged update paths capture pre/post fingerprints and only write the restart marker when version_changed and (mcp_code_changed or force_restart).
• Tests: tests/test_runtime_fingerprint.py (14 tests), 4 new tests in tests/test_packaged_update_runtime.py. Existing marker stubs widened to accept new kwargs.
• Docs: docs/runtime-fingerprint.md, CHANGELOG.md v7.11.0 entry, gh-pages surfaces (README.md, llms.txt, index.html, blog/index.html + blog/nexo-7-11-0/, changelog/index.html, sitemap.xml), version bumps via scripts/sync_release_artifacts.py.

Test plan

• [x] pytest tests/test_runtime_fingerprint.py tests/test_packaged_update_runtime.py tests/test_runtime_update_contract.py tests/test_continuity_runtime.py → 47 passed locally.
• [x] scripts/sync_release_artifacts.py synced .claude-plugin/plugin.json, clawhub-skill/SKILL.md, openclaw-plugin/src/mcp-bridge.ts, openclaw-plugin/package.json to 7.11.0.
• [x] scripts/verify_release_readiness.py --ci — changelog OK, public surfaces OK, duplicate hygiene OK.
• [ ] CI must pass on Linux runners. Two pre-existing test failures (tests/parity/test_python_driver.py::test_parity_python[R13-pre-edit-no-guard] and tests/test_doctor.py::TestRuntimeChecks::test_launchagent_integrity_fix_normalizes_special_launchagent_env) reproduce on a clean main checkout with no changes — they're local-environment TCC/permission issues, not introduced by this PR. Verified by stashing this PR's diff and running each test against main directly.
• [ ] After merge: tag v7.11.0, npm publish from nexo-brain root and openclaw-plugin/, push gh-pages.
• [ ] Post-publish smoke: nexo update on a sandbox install — expect "MCP source unchanged" line on the next doc-only release, restart required on the next code-changing release.

🤖 Generated with Claude Code

What's Changed

• Release 7.11.0: runtime fingerprint gates restart-required marker by @wazionapps in https://github.com/wazionapps/nexo/pull/307

Full Changelog: https://github.com/wazionapps/nexo/compare/v7.10.1...v7.11.0