nexo-brain 5.3.0 → 5.3.2

package/src/client_sync.py

@@ -18,6 +18,7 @@ except ModuleNotFoundError:  # Python < 3.11
     import tomli as tomllib
 
 from bootstrap_docs import sync_client_bootstrap
+from runtime_home import resolve_nexo_home
 
 try:
     from client_preferences import (
@@ -73,7 +74,7 @@ def _user_home() -> Path:
 
 
 def _default_nexo_home() -> Path:
-    return Path(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo"))).expanduser()
+    return resolve_nexo_home(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo")))
 
 
 def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
@@ -348,6 +349,12 @@ CORE_HOOK_SPECS = [
         "timeout": 5,
         "script": "protocol-pretool-guardrail.sh",
     },
+    {
+        "event": "UserPromptSubmit",
+        "identity": "heartbeat-user-msg.sh",
+        "timeout": 3,
+        "script": "heartbeat-user-msg.sh",
+    },
     {
         "event": "PostToolUse",
         "identity": "capture-tool-logs.sh",
@@ -372,6 +379,12 @@ CORE_HOOK_SPECS = [
         "timeout": 5,
         "script": "protocol-guardrail.sh",
     },
+    {
+        "event": "PostToolUse",
+        "identity": "heartbeat-posttool.sh",
+        "timeout": 3,
+        "script": "heartbeat-posttool.sh",
+    },
     {
         "event": "PreCompact",
         "identity": "pre-compact.sh",

package/src/db/_personal_scripts.py

@@ -12,15 +12,30 @@ import os
 from pathlib import Path
 
 from db._core import get_db
+from runtime_home import resolve_nexo_home
 
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_HOME = resolve_nexo_home()
 
 
 def _now_text() -> str:
     return datetime.datetime.now().isoformat(timespec="seconds")
 
 
+def _canonical_scripts_dir() -> Path:
+    home = resolve_nexo_home(os.environ.get("NEXO_HOME", str(NEXO_HOME)))
+    return home / "scripts"
+
+
+def _normalize_script_path(path: str | Path) -> str:
+    candidate = Path(path).expanduser()
+    try:
+        relative = candidate.resolve(strict=False).relative_to(_canonical_scripts_dir().resolve(strict=False))
+    except Exception:
+        return str(candidate)
+    return str(_canonical_scripts_dir() / relative)
+
+
 def _row_to_dict(row) -> dict:
     return dict(row) if row is not None else {}
 
@@ -61,6 +76,7 @@ def _safe_slug(value: str) -> str:
 
 
 def _ensure_script_id(conn, name: str, path: str) -> str:
+    path = _normalize_script_path(path)
     existing = conn.execute(
         "SELECT id FROM personal_scripts WHERE path = ? LIMIT 1",
         (path,),
@@ -90,6 +106,7 @@ def upsert_personal_script(
     has_inline_metadata: bool = False,
 ) -> dict:
     conn = get_db()
+    path = _normalize_script_path(path)
     script_id = _ensure_script_id(conn, name, path)
     now = _now_text()
     conn.execute(
@@ -132,11 +149,12 @@ def upsert_personal_script(
 
 def delete_missing_personal_scripts(active_paths: list[str]) -> int:
     conn = get_db()
-    if active_paths:
-        placeholders = ",".join("?" for _ in active_paths)
+    normalized_paths = [_normalize_script_path(path) for path in active_paths]
+    if normalized_paths:
+        placeholders = ",".join("?" for _ in normalized_paths)
         rows = conn.execute(
             f"SELECT id FROM personal_scripts WHERE path NOT IN ({placeholders})",
-            tuple(active_paths),
+            tuple(normalized_paths),
         ).fetchall()
     else:
         rows = conn.execute("SELECT id FROM personal_scripts").fetchall()
@@ -160,6 +178,7 @@ def register_personal_script_schedule(
     enabled: bool = True,
 ) -> dict | None:
     conn = get_db()
+    script_path = _normalize_script_path(script_path)
     script = conn.execute(
         "SELECT id FROM personal_scripts WHERE path = ?",
         (script_path,),
@@ -342,6 +361,7 @@ def list_personal_scripts(include_disabled: bool = True) -> list[dict]:
 
 def get_personal_script(name_or_path: str) -> dict | None:
     conn = get_db()
+    normalized_path = _normalize_script_path(name_or_path)
     row = conn.execute(
         """
         SELECT * FROM personal_scripts
@@ -349,7 +369,7 @@ def get_personal_script(name_or_path: str) -> dict | None:
         ORDER BY path = ? DESC
         LIMIT 1
         """,
-        (name_or_path, name_or_path, name_or_path),
+        (normalized_path, name_or_path, normalized_path),
     ).fetchone()
     if not row:
         return None
@@ -361,9 +381,10 @@ def get_personal_script(name_or_path: str) -> dict | None:
 
 def delete_personal_script(name_or_path: str) -> int:
     conn = get_db()
+    normalized_path = _normalize_script_path(name_or_path)
     result = conn.execute(
         "DELETE FROM personal_scripts WHERE path = ? OR name = ? OR id = ?",
-        (name_or_path, name_or_path, name_or_path),
+        (normalized_path, name_or_path, name_or_path),
     )
     return int(result.rowcount or 0)
 
@@ -371,13 +392,14 @@ def delete_personal_script(name_or_path: str) -> int:
 def record_personal_script_run(name_or_path: str, exit_code: int, run_at: str | None = None) -> None:
     conn = get_db()
     run_at = run_at or _now_text()
+    normalized_path = _normalize_script_path(name_or_path)
     conn.execute(
         """
         UPDATE personal_scripts
         SET last_run_at = ?, last_exit_code = ?, updated_at = ?
         WHERE path = ? OR name = ?
         """,
-        (run_at, exit_code, _now_text(), name_or_path, name_or_path),
+        (run_at, exit_code, _now_text(), normalized_path, name_or_path),
     )
 
 
@@ -393,7 +415,7 @@ def sync_personal_scripts_registry(
     scheduled = 0
 
     for record in script_records:
-        path = str(record["path"])
+        path = _normalize_script_path(record["path"])
         active_paths.append(path)
         upsert_personal_script(
             name=record.get("name") or Path(path).stem,

package/src/doctor/providers/runtime.py

@@ -84,6 +84,28 @@ def _release_root() -> Path:
     return Path(NEXO_CODE)
 
 
+def _has_release_publish_context(release_root: Path) -> bool:
+    git_dir = release_root / ".git"
+    if git_dir.exists() or git_dir.is_file():
+        return True
+    if _recorded_source_root() is not None:
+        return True
+    try:
+        release_root_resolved = release_root.resolve()
+        nexo_home_resolved = NEXO_HOME.resolve()
+    except Exception:
+        release_root_resolved = release_root
+        nexo_home_resolved = NEXO_HOME
+    if release_root_resolved == nexo_home_resolved:
+        return False
+    has_release_files = (
+        (release_root / "package.json").is_file()
+        and (release_root / "CHANGELOG.md").is_file()
+        and (release_root / "scripts" / "sync_release_artifacts.py").is_file()
+    )
+    return has_release_files
+
+
 def _package_json_path() -> Path:
     if PACKAGE_JSON.is_file():
         return PACKAGE_JSON
@@ -2660,13 +2682,27 @@ def check_release_artifact_sync() -> DoctorCheck:
     if changelog_version:
         evidence.append(f"top changelog version: {changelog_version}")
 
+    release_root = _release_root()
+    if not _has_release_publish_context(release_root):
+        if version:
+            evidence.append(f"package version: {version}")
+        evidence.append(f"release root: {release_root}")
+        evidence.append("packaged runtime without source repo; release artifact audit skipped")
+        return DoctorCheck(
+            id="runtime.release_artifacts",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary="Release artifact audit skipped for packaged runtime",
+            evidence=evidence,
+        )
+
     if version and changelog_version and version != changelog_version:
         status = "critical"
         severity = "error"
         evidence.append("package/changelog release version mismatch")
         repair_plan.append("Bump or align CHANGELOG.md before publishing")
 
-    release_root = _release_root()
     sync_script = release_root / "scripts" / "sync_release_artifacts.py"
     if not sync_script.is_file():
         status = "critical"

package/src/hooks/heartbeat-enforcement.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Heartbeat enforcement for NEXO sessions.
+
+Tracks user messages vs heartbeat calls. Emits a warning when more than two
+user messages pass without a heartbeat call.
+
+Modes:
+- HEARTBEAT_MODE=user_msg: increment counter on UserPromptSubmit
+- HEARTBEAT_MODE=post_tool: inspect PostToolUse payload, reset on heartbeat,
+  warn when other tools keep running without one
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+STATE_FILE = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo")) / "operations" / ".heartbeat-state.json"
+THRESHOLD = 2
+HEARTBEAT_TOOL = "nexo_heartbeat"
+SKIP_TOOLS = {"nexo_startup", "nexo_stop", "nexo_smart_startup"}
+
+
+def _read_state() -> dict:
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except Exception:
+        return {"user_msgs": 0, "last_heartbeat_ts": 0.0, "last_user_msg_ts": 0.0}
+
+
+def _write_state(state: dict) -> None:
+    try:
+        STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        STATE_FILE.write_text(json.dumps(state))
+    except Exception:
+        pass
+
+
+def handle_user_message() -> int:
+    state = _read_state()
+    state["user_msgs"] = state.get("user_msgs", 0) + 1
+    state["last_user_msg_ts"] = time.time()
+    _write_state(state)
+    return 0
+
+
+def handle_post_tool(payload: dict) -> int:
+    tool_name = str(payload.get("tool_name", "")).strip()
+    short_name = tool_name.rsplit("__", 1)[-1] if "__" in tool_name else tool_name
+    state = _read_state()
+
+    if short_name == HEARTBEAT_TOOL:
+        state["user_msgs"] = 0
+        state["last_heartbeat_ts"] = time.time()
+        _write_state(state)
+        return 0
+
+    if short_name in SKIP_TOOLS:
+        return 0
+
+    user_msgs = state.get("user_msgs", 0)
+    if user_msgs > THRESHOLD:
+        print(
+            f"\nWARNING: HEARTBEAT OVERDUE ({user_msgs} user messages without nexo_heartbeat). "
+            "Call nexo_heartbeat(sid=SID, task='...') before continuing."
+        )
+    return 0
+
+
+def main() -> int:
+    mode = os.environ.get("HEARTBEAT_MODE", "").strip()
+    if mode == "user_msg":
+        return handle_user_message()
+    if mode == "post_tool":
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return 0
+        try:
+            payload = json.loads(raw)
+        except Exception:
+            return 0
+        return handle_post_tool(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/hooks/heartbeat-posttool.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# NEXO PostToolUse hook — heartbeat enforcement checker
+set -uo pipefail
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+HELPER=""
+if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="${NEXO_CODE%/}/hooks/heartbeat-enforcement.py"
+elif [ -f "$NEXO_HOME/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="$NEXO_HOME/hooks/heartbeat-enforcement.py"
+fi
+
+[ -z "$HELPER" ] && exit 0
+HEARTBEAT_MODE=post_tool python3 "$HELPER" <<< "$INPUT" 2>/dev/null || true
+exit 0

package/src/hooks/heartbeat-user-msg.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# NEXO UserPromptSubmit hook — track user messages for heartbeat enforcement
+set -uo pipefail
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+HELPER=""
+if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="${NEXO_CODE%/}/hooks/heartbeat-enforcement.py"
+elif [ -f "$NEXO_HOME/hooks/heartbeat-enforcement.py" ]; then
+    HELPER="$NEXO_HOME/hooks/heartbeat-enforcement.py"
+fi
+
+[ -z "$HELPER" ] && exit 0
+HEARTBEAT_MODE=user_msg python3 "$HELPER" 2>/dev/null || true
+exit 0

package/src/hooks/session-start.sh

@@ -4,6 +4,8 @@
 # Caches output for 1 hour to avoid regenerating on rapid successive sessions.
 set -uo pipefail
 
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+
 # Fase 3 item 7: hook lifecycle observability — record duration + exit code
 # in hook_runs on EXIT. Best-effort: a failure here must not break the hook.
 NEXO_HOOK_START_MS=$(python3 -c "import time; print(int(time.time()*1000))" 2>/dev/null || echo 0)
@@ -18,8 +20,12 @@ _nexo_record_hook_run() {
             duration_ms=$((now_ms - NEXO_HOOK_START_MS))
         fi
     fi
-    local recorder
-    recorder="${NEXO_CODE:-/Users/franciscoc/Documents/_PhpstormProjects/nexo/src}/scripts/nexo-hook-record.py"
+    local recorder=""
+    if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/scripts/nexo-hook-record.py" ]; then
+        recorder="${NEXO_CODE%/}/scripts/nexo-hook-record.py"
+    elif [ -f "$NEXO_HOME/scripts/nexo-hook-record.py" ]; then
+        recorder="$NEXO_HOME/scripts/nexo-hook-record.py"
+    fi
     if [ -f "$recorder" ]; then
         python3 "$recorder" record \
             --hook "$NEXO_HOOK_NAME" \
@@ -30,8 +36,6 @@ _nexo_record_hook_run() {
     fi
 }
 trap _nexo_record_hook_run EXIT
-
-NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
 BRIEFING_FILE="$NEXO_HOME/coordination/session-briefing.txt"
 MAX_AGE_SECONDS=3600  # 1 hour cache
 

package/src/plugins/update.py

@@ -9,6 +9,8 @@ import sys
 import time
 from pathlib import Path
 
+from runtime_home import export_resolved_nexo_home
+
 # Code root is the parent of plugins/:
 # - source checkout: <repo>/src
 # - packaged runtime: <NEXO_HOME>
@@ -16,7 +18,7 @@ _THIS_DIR = Path(__file__).resolve().parent
 CODE_ROOT = _THIS_DIR.parent
 _REPO_CANDIDATE = CODE_ROOT.parent
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_HOME = export_resolved_nexo_home()
 DATA_DIR = NEXO_HOME / "data"
 BACKUP_BASE = NEXO_HOME / "backups"
 
@@ -79,7 +81,7 @@ def _is_git_repo() -> bool:
 
 
 def _refresh_installed_manifest():
-    """Copy source crons/ to NEXO_HOME/crons/ so catchup & watchdog stay current."""
+    """Refresh packaged crons and persist the runtime core-artifacts manifest."""
     try:
         src_crons = SRC_DIR / "crons"
         dst_crons = NEXO_HOME / "crons"
@@ -88,10 +90,45 @@ def _refresh_installed_manifest():
             for f in src_crons.iterdir():
                 if f.is_file():
                     shutil.copy2(str(f), str(dst_crons / f.name))
+        config_dir = NEXO_HOME / "config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "script_names": sorted(
+                f.name for f in (SRC_DIR / "scripts").iterdir()
+                if f.is_file()
+            ) if (SRC_DIR / "scripts").is_dir() else [],
+            "hook_names": sorted(
+                f.name for f in (SRC_DIR / "hooks").iterdir()
+                if f.is_file()
+            ) if (SRC_DIR / "hooks").is_dir() else [],
+        }
+        (config_dir / "runtime-core-artifacts.json").write_text(
+            json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+        )
     except Exception:
         pass
 
 
+def _cleanup_retired_runtime_files() -> list[str]:
+    removed: list[str] = []
+    retired_paths = [
+        NEXO_HOME / "scripts" / "heartbeat-enforcement.py",
+        NEXO_HOME / "scripts" / "heartbeat-posttool.sh",
+        NEXO_HOME / "scripts" / "heartbeat-user-msg.sh",
+        NEXO_HOME / "hooks" / "heartbeat-guard.sh",
+    ]
+    for path in retired_paths:
+        if not path.exists():
+            continue
+        try:
+            path.unlink()
+            removed.append(str(path))
+        except Exception:
+            continue
+    return removed
+
+
 def _read_version() -> str:
     """Read the installed/runtime version."""
     if _PACKAGED_INSTALL:
@@ -330,8 +367,23 @@ def _backup_code_tree() -> tuple[str | None, str | None]:
     timestamp = time.strftime("%Y-%m-%d-%H%M%S")
     backup_dir = BACKUP_BASE / f"code-tree-{timestamp}"
     # Directories and flat files that postinstall copies into NEXO_HOME
-    code_dirs = ["hooks", "plugins", "db", "cognitive", "dashboard", "rules", "crons", "scripts"]
-    code_files_glob = ["*.py", "requirements.txt"]
+    code_dirs = [
+        "bin",
+        "hooks",
+        "plugins",
+        "db",
+        "cognitive",
+        "dashboard",
+        "rules",
+        "crons",
+        "scripts",
+        "doctor",
+        "skills",
+        "skills-core",
+        "skills-runtime",
+        "templates",
+    ]
+    code_files_glob = ["*.py", "requirements.txt", "package.json"]
     try:
         backup_dir.mkdir(parents=True, exist_ok=True)
         # Backup directories
@@ -372,6 +424,54 @@ def _restore_code_tree(backup_dir: str) -> str | None:
     return None
 
 
+def _normalize_preferences_for_client_sync() -> dict:
+    from client_preferences import normalize_client_preferences
+
+    schedule_path = NEXO_HOME / "config" / "schedule.json"
+    schedule_payload = json.loads(schedule_path.read_text()) if schedule_path.exists() else {}
+    normalized_preferences = normalize_client_preferences(schedule_payload)
+    if normalized_preferences != {
+        key: schedule_payload.get(key)
+        for key in normalized_preferences
+    }:
+        merged_schedule = dict(schedule_payload)
+        merged_schedule.update(normalized_preferences)
+        schedule_path.parent.mkdir(parents=True, exist_ok=True)
+        schedule_path.write_text(json.dumps(merged_schedule, indent=2, ensure_ascii=False) + "\n")
+    return normalized_preferences
+
+
+def _sync_packaged_clients() -> tuple[bool, str | None]:
+    try:
+        from client_sync import sync_all_clients
+    except Exception as e:
+        return False, f"client sync import failed: {e}"
+
+    try:
+        preferences = _normalize_preferences_for_client_sync()
+        result = sync_all_clients(
+            nexo_home=NEXO_HOME,
+            runtime_root=NEXO_HOME,
+            operator_name=os.environ.get("NEXO_NAME", ""),
+            preferences=preferences,
+        )
+    except Exception as e:
+        return False, f"client sync failed: {e}"
+
+    if result.get("ok"):
+        return True, None
+
+    clients = result.get("clients", {})
+    failures = []
+    for key, payload in clients.items():
+        if payload.get("ok") or payload.get("skipped"):
+            continue
+        failures.append(f"{key}: {payload.get('error', 'unknown error')}")
+    if not failures:
+        failures.append("unknown client sync failure")
+    return False, "; ".join(failures)
+
+
 def _rollback_npm_package(target_version: str) -> str | None:
     """Rollback nexo-brain npm package to a specific version.
 
@@ -480,6 +580,22 @@ def _handle_packaged_update(progress_fn=None) -> str:
     if verify_err:
         errors.append(f"verification: {verify_err}")
 
+    hook_sync_warning = None
+    retired_runtime_files: list[str] = []
+    try:
+        _emit_progress(progress_fn, "Refreshing installed hooks and manifests...")
+        _refresh_installed_manifest()
+        _sync_hooks_to_home()
+        retired_runtime_files = _cleanup_retired_runtime_files()
+    except Exception as e:
+        hook_sync_warning = f"{e}"
+
+    client_sync_warning = None
+    _emit_progress(progress_fn, "Refreshing shared client configs...")
+    clients_ok, client_sync_error = _sync_packaged_clients()
+    if not clients_ok:
+        client_sync_warning = client_sync_error or "unknown client sync error"
+
     if errors:
         # 5. Full rollback: restore code tree + DBs + pip deps + rollback npm package
         if code_backup_dir:
@@ -516,6 +632,16 @@ def _handle_packaged_update(progress_fn=None) -> str:
     lines = ["UPDATE SUCCESSFUL (packaged install)"]
     lines.append(f"  Version: {old_version} -> {new_version}")
     lines.append(f"  Backup: {backup_dir}")
+    if not hook_sync_warning:
+        lines.append("  Hooks: synced to NEXO_HOME")
+    else:
+        lines.append(f"  WARNING: hook sync: {hook_sync_warning}")
+    if retired_runtime_files:
+        lines.append(f"  Cleanup: removed {len(retired_runtime_files)} retired runtime file(s)")
+    if not client_sync_warning:
+        lines.append("  Clients: configured client targets synced")
+    else:
+        lines.append(f"  WARNING: client sync: {client_sync_warning}")
     lines.append("")
     lines.append("MCP server restart needed to load new code.")
     return "\n".join(lines)
@@ -627,9 +753,11 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
             cron_sync_result = f"Cron sync warning: {e}"
 
         # Step 9: Sync hooks to NEXO_HOME
+        retired_runtime_files: list[str] = []
         try:
             _emit_progress(progress_fn, "Syncing core Claude hooks...")
             _sync_hooks_to_home()
+            retired_runtime_files = _cleanup_retired_runtime_files()
             steps_done.append("hook-sync")
         except Exception as e:
             pass  # Non-critical, log in function
@@ -681,6 +809,8 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
             lines.append("  Crons: synced with manifest")
         if "hook-sync" in steps_done:
             lines.append("  Hooks: synced to NEXO_HOME")
+        if retired_runtime_files:
+            lines.append(f"  Cleanup: removed {len(retired_runtime_files)} retired runtime file(s)")
         if "client-sync" in steps_done:
             lines.append("  Clients: configured client targets synced")
         lines.append("")

package/src/runtime_home.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+"""Shared helpers to resolve the managed NEXO home path."""
+
+import os
+from pathlib import Path
+
+
+def user_home() -> Path:
+    return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
+
+
+def managed_nexo_home(*, home: Path | None = None) -> Path:
+    return (home or user_home()) / ".nexo"
+
+
+def legacy_nexo_home(*, home: Path | None = None) -> Path:
+    return (home or user_home()) / "claude"
+
+
+def resolve_nexo_home(value: str | os.PathLike[str] | None = None) -> Path:
+    home = user_home()
+    managed = managed_nexo_home(home=home)
+    candidate = Path(value).expanduser() if value else Path(
+        os.environ.get("NEXO_HOME", str(managed))
+    ).expanduser()
+    legacy = legacy_nexo_home(home=home)
+
+    if candidate == managed:
+        return managed
+    if candidate == legacy:
+        return managed if managed.exists() or legacy.is_symlink() else candidate
+
+    try:
+        if managed.exists() and candidate.resolve(strict=False) == managed.resolve(strict=False):
+            return managed
+    except Exception:
+        pass
+
+    return candidate
+
+
+def export_resolved_nexo_home(value: str | os.PathLike[str] | None = None) -> Path:
+    resolved = resolve_nexo_home(value)
+    os.environ["NEXO_HOME"] = str(resolved)
+    return resolved