nexo-brain 5.2.1 → 5.3.1

package/src/cli.py

@@ -25,6 +25,7 @@ Entry points:
   nexo clients sync [--json]
   nexo contributor status|on|off [--json]
   nexo doctor [--tier boot|runtime|deep|all] [--json] [--fix]
+  nexo uninstall [--dry-run] [--delete-data] [--json]
 """
 from __future__ import annotations
 
@@ -39,7 +40,9 @@ import subprocess
 import sys
 from pathlib import Path
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+from runtime_home import export_resolved_nexo_home
+
+NEXO_HOME = export_resolved_nexo_home()
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
 TERMINAL_CLIENT_LABELS = {
     "claude_code": "Claude Code",
@@ -1281,6 +1284,218 @@ def _skills_compose(args):
     return 0 if result.get("ok") else 1
 
 
+def _uninstall(args):
+    """Stop all crons, remove MCP config and hooks, preserve user data."""
+    from pathlib import Path
+
+    nexo_home = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo"))
+    dry_run = args.dry_run
+    delete_data = args.delete_data
+    use_json = args.json
+    platform = sys.platform
+
+    actions: list[dict] = []
+    errors: list[str] = []
+
+    def log_action(category: str, detail: str, path: str = ""):
+        actions.append({"category": category, "detail": detail, "path": path})
+        if not use_json:
+            tag = "[DRY-RUN] " if dry_run else ""
+            print(f"  {tag}{category}: {detail}")
+
+    # ── 1. Stop and remove LaunchAgents (macOS) ──
+    if platform == "darwin":
+        la_dir = Path.home() / "Library" / "LaunchAgents"
+        if la_dir.exists():
+            uid = os.getuid()
+            for plist in sorted(la_dir.glob("com.nexo.*.plist")):
+                label = plist.stem
+                # Stop the agent
+                if not dry_run:
+                    subprocess.run(
+                        ["launchctl", "bootout", f"gui/{uid}", str(plist)],
+                        capture_output=True,
+                    )
+                log_action("stop-cron", f"launchctl bootout {label}", str(plist))
+                # Remove plist file
+                if not dry_run:
+                    plist.unlink(missing_ok=True)
+                log_action("remove-plist", label, str(plist))
+    # ── systemd (Linux) ──
+    elif platform == "linux":
+        systemd_dir = Path.home() / ".config" / "systemd" / "user"
+        if systemd_dir.exists():
+            for unit in sorted(list(systemd_dir.glob("nexo-*.timer")) + list(systemd_dir.glob("nexo-*.service"))):
+                if not dry_run:
+                    if unit.suffix == ".timer":
+                        subprocess.run(["systemctl", "--user", "stop", unit.name], capture_output=True)
+                        subprocess.run(["systemctl", "--user", "disable", unit.name], capture_output=True)
+                    unit.unlink(missing_ok=True)
+                log_action("remove-systemd", unit.name, str(unit))
+            if not dry_run:
+                subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True)
+
+    # ── 2. Remove MCP server and hooks from Claude Code settings ──
+    claude_settings = Path.home() / ".claude" / "settings.json"
+    if claude_settings.exists():
+        try:
+            settings = json.loads(claude_settings.read_text())
+            changed = False
+
+            # Remove nexo MCP server
+            mcp = settings.get("mcpServers", {})
+            if "nexo" in mcp:
+                if not dry_run:
+                    del mcp["nexo"]
+                    changed = True
+                log_action("remove-mcp", "nexo server from settings.json", str(claude_settings))
+
+            # Remove NEXO hooks (hooks referencing NEXO_HOME)
+            hooks = settings.get("hooks", {})
+            nexo_home_str = str(nexo_home)
+            for event_name in list(hooks.keys()):
+                hook_list = hooks[event_name]
+                if isinstance(hook_list, list):
+                    original_len = len(hook_list)
+                    filtered = [
+                        h for h in hook_list
+                        if not (
+                            isinstance(h, dict)
+                            and nexo_home_str in (h.get("command", "") + " ".join(h.get("args", [])))
+                        )
+                    ]
+                    if len(filtered) < original_len:
+                        if not dry_run:
+                            hooks[event_name] = filtered
+                            changed = True
+                        removed_count = original_len - len(filtered)
+                        log_action("remove-hooks", f"{removed_count} hook(s) from {event_name}", str(claude_settings))
+                # Clean up empty hook lists
+                if isinstance(hooks.get(event_name), list) and len(hooks.get(event_name, [])) == 0:
+                    if not dry_run:
+                        del hooks[event_name]
+                        changed = True
+
+            if changed and not dry_run:
+                claude_settings.write_text(json.dumps(settings, indent=2, ensure_ascii=False))
+        except Exception as exc:
+            errors.append(f"Failed to clean settings.json: {exc}")
+
+    # ── 3. Remove Codex AGENTS.md bootstrap ──
+    codex_agents = Path.home() / "AGENTS.md"
+    if codex_agents.exists():
+        try:
+            content = codex_agents.read_text()
+            if "NEXO" in content or "nexo" in content:
+                log_action("preserve-note", "AGENTS.md contains NEXO references — remove manually if desired", str(codex_agents))
+        except Exception:
+            pass
+
+    # ── 4. Remove runtime files, PRESERVE user data ──
+    # User data directories that are NEVER deleted (unless --delete-data)
+    user_data_dirs = {"data", "brain", "operations", "coordination", "config", "logs", "backups"}
+    user_data_files = {"version.json"}  # keeps reinstall detection working
+
+    # Runtime directories that get removed
+    runtime_dirs = {"plugins", "hooks", "dashboard", "cognitive", "db", "rules", "crons", "doctor", "skills"}
+    # Runtime flat files: any .py/.txt at NEXO_HOME root is core runtime.
+    # User data always lives in subdirectories (data/, brain/, scripts/, etc.)
+    # so this is safe and doesn't need updating when new core files are added.
+    runtime_file_extensions = {".py", ".txt"}
+
+    if nexo_home.exists():
+        # Remove runtime directories
+        for d in sorted(runtime_dirs):
+            dir_path = nexo_home / d
+            if dir_path.is_dir():
+                if not dry_run:
+                    shutil.rmtree(dir_path, ignore_errors=True)
+                log_action("remove-runtime-dir", d, str(dir_path))
+
+        # Remove runtime flat files (any .py/.txt at root level)
+        for file_path in sorted(nexo_home.iterdir()):
+            if file_path.is_file() and file_path.suffix in runtime_file_extensions:
+                if not dry_run:
+                    file_path.unlink(missing_ok=True)
+                log_action("remove-runtime-file", file_path.name, str(file_path))
+
+        # Remove core scripts (nexo-*.py/sh in scripts/)
+        scripts_dir = nexo_home / "scripts"
+        if scripts_dir.is_dir():
+            for script in sorted(scripts_dir.glob("nexo-*")):
+                if script.is_file():
+                    if not dry_run:
+                        script.unlink(missing_ok=True)
+                    log_action("remove-core-script", script.name, str(script))
+            # Remove deep-sleep directory (core)
+            ds_dir = scripts_dir / "deep-sleep"
+            if ds_dir.is_dir():
+                if not dry_run:
+                    shutil.rmtree(ds_dir, ignore_errors=True)
+                log_action("remove-runtime-dir", "scripts/deep-sleep", str(ds_dir))
+
+        # List preserved user data
+        for d in sorted(user_data_dirs):
+            dir_path = nexo_home / d
+            if dir_path.is_dir():
+                if delete_data:
+                    if not dry_run:
+                        shutil.rmtree(dir_path, ignore_errors=True)
+                    log_action("DELETE-user-data", d, str(dir_path))
+                else:
+                    log_action("preserve-data", d, str(dir_path))
+
+        # Preserve personal scripts (non nexo-* files in scripts/)
+        if scripts_dir.is_dir():
+            personal = [f.name for f in scripts_dir.iterdir() if f.is_file() and not f.name.startswith("nexo-")]
+            if personal:
+                log_action("preserve-scripts", f"{len(personal)} personal script(s)", str(scripts_dir))
+
+        # Preserve templates/
+        templates_dir = nexo_home / "templates"
+        if templates_dir.is_dir():
+            log_action("preserve-data", "templates", str(templates_dir))
+
+    # ── 5. Write uninstall marker for reinstall detection ──
+    if not dry_run and nexo_home.exists():
+        marker = nexo_home / ".uninstalled"
+        marker.write_text(json.dumps({
+            "uninstalled_at": __import__("datetime").datetime.now().isoformat(),
+            "nexo_home": str(nexo_home),
+            "data_preserved": not delete_data,
+        }, indent=2))
+        log_action("write-marker", ".uninstalled marker for reinstall detection", str(marker))
+
+    # ── Summary ──
+    result = {
+        "ok": len(errors) == 0,
+        "dry_run": dry_run,
+        "nexo_home": str(nexo_home),
+        "actions": actions,
+        "errors": errors,
+        "data_preserved": not delete_data,
+    }
+
+    if use_json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print()
+        if dry_run:
+            print(f"  DRY RUN complete. {len(actions)} action(s) would be taken.")
+            print("  Run without --dry-run to execute.")
+        else:
+            print(f"  Uninstall complete. {len(actions)} action(s) taken.")
+            if not delete_data:
+                print(f"\n  Your data is preserved in: {nexo_home}")
+                print("  To reinstall: npm install -g nexo-brain && nexo-brain")
+            if errors:
+                print(f"\n  {len(errors)} error(s):")
+                for e in errors:
+                    print(f"    - {e}")
+
+    return 1 if errors else 0
+
+
 def _print_help():
     v = _get_version()
     print(f"""NEXO Runtime CLI v{v}
@@ -1293,6 +1508,7 @@ Commands:
   nexo skills list|apply|sync|approve                  Executable skills
   nexo clients sync                                    Sync Claude/Codex shared-brain configs and bootstrap files
   nexo update                                          Update installed runtime
+  nexo uninstall [--dry-run] [--delete-data]            Stop crons, remove runtime (keeps data)
   nexo contributor status|on|off                       Public Draft PR contribution mode
   nexo dashboard on|off|status                         Web dashboard control
 
@@ -1477,6 +1693,12 @@ def main():
     skills_compose_p.add_argument("--trigger-patterns", default="[]", help="JSON array or comma-separated trigger patterns")
     skills_compose_p.add_argument("--json", action="store_true", help="JSON output")
 
+    # -- uninstall --
+    uninstall_parser = sub.add_parser("uninstall", help="Stop all crons, remove runtime, keep user data")
+    uninstall_parser.add_argument("--dry-run", action="store_true", help="Show what would be done without doing it")
+    uninstall_parser.add_argument("--delete-data", action="store_true", help="Also delete databases and user data (DESTRUCTIVE)")
+    uninstall_parser.add_argument("--json", action="store_true", help="JSON output")
+
     # -- dashboard --
     dashboard_parser = sub.add_parser("dashboard", help="Web dashboard control")
     dashboard_parser.add_argument("action", choices=["on", "off", "status"], help="Start, stop, or check dashboard")
@@ -1566,6 +1788,8 @@ def main():
         else:
             skills_parser.print_help()
             return 0
+    elif args.command == "uninstall":
+        return _uninstall(args)
     elif args.command == "dashboard":
         return _dashboard(args)
     else:

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:

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/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"
 
@@ -330,8 +332,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 +389,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 +545,20 @@ def _handle_packaged_update(progress_fn=None) -> str:
     if verify_err:
         errors.append(f"verification: {verify_err}")
 
+    hook_sync_warning = None
+    try:
+        _emit_progress(progress_fn, "Refreshing installed hooks and manifests...")
+        _refresh_installed_manifest()
+        _sync_hooks_to_home()
+    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 +595,14 @@ 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 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)

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