nexo-brain 5.3.6 → 5.3.8

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.6",
+  "version": "5.3.8",
   "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 `5.3.4` closes the last packaged-runtime core/personal leak from the hook migration work: legacy hook aliases stay out of the personal bucket, `nexo update` removes those retired aliases when the canonical hooks already exist, and both `nexo` and `nexo chat` now show latest vs installed version at a glance.
+Version `5.3.8` is the current packaged-runtime line: packaged installs now self-heal more of the update path, portable user-data export/import is explicit, tracked Codex drift no longer leaves runtime doctor red after cleanup, and the packaged migrator copies newly added root runtime modules into `~/.nexo` instead of leaving them stranded in the npm tarball.
 
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)
@@ -89,7 +89,7 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
-Version `5.3.6` hardens the Claude Code bootstrap path and related runtime hygiene: managed client sync now writes the NEXO MCP server where current Claude Code actually reads it (`~/.claude.json`), script classification is stricter about core-vs-personal runtime artifacts, schedule status distinguishes genuinely running jobs from broken ones, and retroactive learnings stop opening keyword-only false positives outside their declared `applies_to` scope. Version `5.3.5` already keeps CLI version visibility honest right after `nexo update`: if the cached npm version lags behind the runtime you just installed, `nexo` / `nexo chat` now clamp `Latest` to the installed version and refresh the cache instead of showing a stale older release. Version `5.3.4` already cleaned up legacy core alias leakage and added the version-status banner. Version `5.3.3` closed the remaining packaged-runtime doctor mismatch: the built-in hourly backup helper is now inventoried as a core LaunchAgent, so clean installs no longer get a false unknown-LaunchAgent warning. Version `5.3.2` already hardened the runtime boundary by persisting which runtime scripts/hooks are core product artifacts, keeping `nexo scripts` from mixing those into the personal bucket, and migrating the legacy Claude Code heartbeat wrappers into managed core hooks.
+Version `5.3.8` is the immediate packaged-migration hotfix for `5.3.7`: the installer/runtime migrator now discovers all top-level runtime Python modules from `src/` dynamically instead of relying on a manual allowlist, so new product surfaces like `nexo export` / `nexo import` actually arrive in `~/.nexo` after update instead of being present only in the published npm tarball. Version `5.3.7` closed the remaining packaged-runtime happy-path gap and finally exposed portable user-data migration commands: packaged `nexo update` now self-heals cron definitions and LaunchAgents after a successful npm bump, new `nexo export` / `nexo import` commands move operator data as a safe bundle instead of leaving that flow implicit, and runtime doctor now distinguishes tracked historical Codex drift from an actually broken runtime so cleaned installs stop staying red for stale transcript debt alone. Version `5.3.6` hardened the Claude Code bootstrap path and related runtime hygiene: managed client sync now writes the NEXO MCP server where current Claude Code actually reads it (`~/.claude.json`), script classification is stricter about core-vs-personal runtime artifacts, schedule status distinguishes genuinely running jobs from broken ones, and retroactive learnings stop opening keyword-only false positives outside their declared `applies_to` scope. Version `5.3.5` already keeps CLI version visibility honest right after `nexo update`: if the cached npm version lags behind the runtime you just installed, `nexo` / `nexo chat` now clamp `Latest` to the installed version and refresh the cache instead of showing a stale older release. Version `5.3.4` already cleaned up legacy core alias leakage and added the version-status banner. Version `5.3.3` closed the remaining packaged-runtime doctor mismatch: the built-in hourly backup helper is now inventoried as a core LaunchAgent, so clean installs no longer get a false unknown-LaunchAgent warning. Version `5.3.2` already hardened the runtime boundary by persisting which runtime scripts/hooks are core product artifacts, keeping `nexo scripts` from mixing those into the personal bucket, and migrating the legacy Claude Code heartbeat wrappers into managed core hooks.
 
 Version `5.3.1` normalizes packaged npm installs so they behave like packaged npm installs: `nexo update` now keeps the runtime anchored to `~/.nexo`, refreshes packaged bootstrap/client artifacts after upgrade, avoids repo-only release-artifact drift in installed runtimes, and keeps personal scripts on the canonical packaged path.
 

package/bin/nexo-brain.js

@@ -120,8 +120,8 @@ function writeRuntimeCoreArtifactsManifest(nexoHome, srcDir) {
   }
 }
 
-function getCoreRuntimeFlatFiles() {
-  return [
+function getCoreRuntimeFlatFiles(srcDir = path.join(__dirname, "..", "src")) {
+  const staticFiles = [
     "server.py",
     "plugin_loader.py",
     "knowledge_graph.py",
@@ -155,6 +155,11 @@ function getCoreRuntimeFlatFiles() {
     "runtime_power.py",
     "requirements.txt",
   ];
+  const discoveredRootModules = fs.existsSync(srcDir)
+    ? fs.readdirSync(srcDir)
+      .filter((name) => name.endsWith(".py") && fs.statSync(path.join(srcDir, name)).isFile())
+    : [];
+  return [...new Set([...staticFiles, ...discoveredRootModules])];
 }
 
 function getCoreRuntimePackages() {
@@ -1480,7 +1485,7 @@ async function main() {
         log("  Hooks updated.");
 
         // Update core Python files (flat .py files in src/)
-        const coreFlatFiles = getCoreRuntimeFlatFiles();
+        const coreFlatFiles = getCoreRuntimeFlatFiles(srcDir);
         coreFlatFiles.forEach((f) => {
           const src = path.join(srcDir, f);
           if (fs.existsSync(src)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.6",
+  "version": "5.3.8",
   "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/cli.py

@@ -3,6 +3,8 @@
 
 Entry points:
   nexo chat [PATH]
+  nexo export [PATH] [--json]
+  nexo import PATH [--json]
   nexo scripts list [--all] [--json]
   nexo scripts create NAME [--runtime python|shell] [--description TEXT]
   nexo scripts classify [--json]
@@ -558,6 +560,43 @@ def _scripts_doctor(args):
     return 0
 
 
+def _export_bundle(args):
+    from user_data_portability import export_user_bundle
+
+    result = export_user_bundle(args.path or "")
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        if not result.get("ok"):
+            print(result.get("error", "Export failed"), file=sys.stderr)
+            return 1
+        sections = result.get("sections", {})
+        script_count = sections.get("personal_scripts", {}).get("files", 0)
+        print(f"User data export written to {result['path']}")
+        print(f"  Personal scripts: {script_count}")
+        print(f"  Sections: {', '.join(sorted(sections))}")
+    return 0 if result.get("ok") else 1
+
+
+def _import_bundle(args):
+    from user_data_portability import import_user_bundle
+
+    result = import_user_bundle(args.path)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        if not result.get("ok"):
+            print(result.get("error", "Import failed"), file=sys.stderr)
+            return 1
+        restored = result.get("restored", {})
+        script_count = restored.get("personal_scripts", {}).get("files", 0)
+        print(f"User data imported from {result['path']}")
+        print(f"  Safety backup: {result['safety_backup']}")
+        print(f"  Personal scripts restored: {script_count}")
+        print(f"  Sections: {', '.join(sorted(restored))}")
+    return 0 if result.get("ok") else 1
+
+
 def _runtime_python_candidates() -> list[str]:
     candidates: list[str] = []
     seen: set[str] = set()
@@ -1588,6 +1627,8 @@ def _print_help():
 
 Commands:
   nexo chat [path] [--client claude_code|codex]      Launch a NEXO terminal client
+  nexo export [path]                                 Export a portable user-data bundle
+  nexo import PATH                                   Import a portable user-data bundle
   nexo doctor [--tier boot|runtime|deep|all] [--fix]   System diagnostics
   nexo scripts list|create|classify|sync|reconcile|ensure-schedules|schedules|run|doctor|call|unschedule|remove
                                                       Personal scripts
@@ -1618,6 +1659,16 @@ def main():
         help="Override the chat picker and launch a specific terminal client",
     )
 
+    # -- export --
+    export_parser = sub.add_parser("export", help="Export a portable user-data bundle")
+    export_parser.add_argument("path", nargs="?", default="", help="Output bundle path (default: NEXO_HOME/exports/...)")
+    export_parser.add_argument("--json", action="store_true", help="JSON output")
+
+    # -- import --
+    import_parser = sub.add_parser("import", help="Import a portable user-data bundle")
+    import_parser.add_argument("path", help="Bundle path created by `nexo export`")
+    import_parser.add_argument("--json", action="store_true", help="JSON output")
+
     # -- scripts --
     scripts_parser = sub.add_parser("scripts", help="Manage personal scripts")
     scripts_sub = scripts_parser.add_subparsers(dest="scripts_command")
@@ -1828,6 +1879,10 @@ def main():
             return 0
     elif args.command == "chat":
         return _chat(args)
+    elif args.command == "export":
+        return _export_bundle(args)
+    elif args.command == "import":
+        return _import_bundle(args)
     elif args.command == "update":
         return _update(args)
     elif args.command == "clients":

package/src/doctor/providers/runtime.py

@@ -2157,10 +2157,8 @@ def check_codex_conditioned_file_discipline() -> DoctorCheck:
         and audit["delete_without_protocol"] == 0
         and audit["delete_without_guard_ack"] == 0
     )
-    historical_write_drift = (
+    tracked_write_without_open_debt = (
         no_open_conditioned_debt
-        and audit.get("latest_violation_age_seconds") is not None
-        and float(audit["latest_violation_age_seconds"]) >= 172800
         and audit["write_without_protocol"] > 0
         and audit["write_without_guard_ack"] == 0
         and audit["delete_without_protocol"] == 0
@@ -2168,7 +2166,7 @@ def check_codex_conditioned_file_discipline() -> DoctorCheck:
     )
 
     if audit["write_without_protocol"] or audit["write_without_guard_ack"]:
-        if historical_write_drift:
+        if tracked_write_without_open_debt:
             status = "healthy"
             severity = "info"
         else:
@@ -2191,7 +2189,9 @@ def check_codex_conditioned_file_discipline() -> DoctorCheck:
         severity=severity,
         summary=(
             "Historical Codex conditioned-file drift has no open protocol debt"
-            if historical_read_only or historical_write_drift
+            if historical_read_only
+            else "Tracked Codex conditioned-file drift has no open protocol debt"
+            if tracked_write_without_open_debt
             else "Recent Codex sessions respect conditioned-file discipline"
             if status == "healthy"
             else "Recent Codex sessions are bypassing conditioned-file discipline"

package/src/plugins/update.py

@@ -89,7 +89,10 @@ def _refresh_installed_manifest():
             dst_crons.mkdir(parents=True, exist_ok=True)
             for f in src_crons.iterdir():
                 if f.is_file():
-                    shutil.copy2(str(f), str(dst_crons / f.name))
+                    dest = dst_crons / f.name
+                    if _paths_match(f, dest):
+                        continue
+                    shutil.copy2(str(f), str(dest))
         config_dir = NEXO_HOME / "config"
         config_dir.mkdir(parents=True, exist_ok=True)
         payload = {
@@ -355,7 +358,8 @@ def _sync_hooks_to_home():
     for f in hooks_src.iterdir():
         if f.is_file() and f.suffix == ".sh":
             dest = hooks_dest / f.name
-            shutil.copy2(str(f), str(dest))
+            if not _paths_match(f, dest):
+                shutil.copy2(str(f), str(dest))
             os.chmod(str(dest), 0o755)
             synced += 1
     if synced:
@@ -499,6 +503,93 @@ def _emit_progress(progress_fn, message: str) -> None:
             pass
 
 
+def _paths_match(src: Path, dest: Path) -> bool:
+    try:
+        return src.exists() and dest.exists() and src.samefile(dest)
+    except Exception:
+        return False
+
+
+def _sync_packaged_crons(progress_fn=None) -> tuple[bool, str | None]:
+    sync_path = NEXO_HOME / "crons" / "sync.py"
+    if not sync_path.is_file():
+        _refresh_installed_manifest()
+        return True, None
+    try:
+        _emit_progress(progress_fn, "Syncing core cron definitions...")
+        result = subprocess.run(
+            [sys.executable, str(sync_path)],
+            cwd=str(NEXO_HOME),
+            capture_output=True,
+            text=True,
+            timeout=30,
+            env={**os.environ, "NEXO_HOME": str(NEXO_HOME), "NEXO_CODE": str(NEXO_HOME)},
+        )
+        if result.returncode != 0:
+            return False, result.stderr.strip() or result.stdout.strip() or "cron sync failed"
+        _refresh_installed_manifest()
+        return True, None
+    except Exception as e:
+        return False, f"cron sync error: {e}"
+
+
+def _reload_launch_agents_after_bump() -> dict:
+    result: dict = {
+        "scanned": 0,
+        "reloaded": 0,
+        "skipped_missing": 0,
+        "errors": [],
+        "platform": sys.platform,
+    }
+
+    if sys.platform != "darwin":
+        return result
+
+    launch_agents_dir = Path.home() / "Library" / "LaunchAgents"
+    if not launch_agents_dir.is_dir():
+        return result
+
+    try:
+        plists = sorted(launch_agents_dir.glob("com.nexo.*.plist"))
+    except Exception as e:
+        result["errors"].append({"plist": "*", "stderr": f"glob failed: {e}"})
+        return result
+
+    result["scanned"] = len(plists)
+    for plist in plists:
+        try:
+            if not plist.is_file():
+                result["skipped_missing"] += 1
+                continue
+            subprocess.run(
+                ["launchctl", "unload", str(plist)],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            load_proc = subprocess.run(
+                ["launchctl", "load", "-w", str(plist)],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if load_proc.returncode == 0:
+                result["reloaded"] += 1
+            else:
+                result["errors"].append(
+                    {
+                        "plist": plist.name,
+                        "stderr": (load_proc.stderr or load_proc.stdout or "load failed")[:300],
+                    }
+                )
+        except subprocess.TimeoutExpired:
+            result["errors"].append({"plist": plist.name, "stderr": "launchctl timeout"})
+        except Exception as e:
+            result["errors"].append({"plist": plist.name, "stderr": str(e)[:300]})
+
+    return result
+
+
 def _handle_packaged_update(progress_fn=None) -> str:
     """Update a packaged (npm) install — no git repo available."""
     old_version = _read_version()
@@ -581,10 +672,16 @@ def _handle_packaged_update(progress_fn=None) -> str:
         errors.append(f"verification: {verify_err}")
 
     hook_sync_warning = None
+    cron_sync_warning = None
     retired_runtime_files: list[str] = []
+    launchagent_reload_warning = None
+    launchagent_reload_summary = None
+    cron_sync_ok, cron_sync_error = _sync_packaged_crons(progress_fn=progress_fn)
+    if not cron_sync_ok:
+        errors.append(f"cron sync: {cron_sync_error}")
+        cron_sync_warning = cron_sync_error
     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:
@@ -596,6 +693,19 @@ def _handle_packaged_update(progress_fn=None) -> str:
     if not clients_ok:
         client_sync_warning = client_sync_error or "unknown client sync error"
 
+    if old_version != new_version:
+        _emit_progress(progress_fn, "Reloading LaunchAgents after version bump...")
+        try:
+            launchagent_reload_summary = _reload_launch_agents_after_bump()
+            if launchagent_reload_summary.get("errors"):
+                launchagent_reload_warning = (
+                    f"reloaded {launchagent_reload_summary['reloaded']}/"
+                    f"{launchagent_reload_summary['scanned']} with "
+                    f"{len(launchagent_reload_summary['errors'])} error(s)"
+                )
+        except Exception as e:
+            launchagent_reload_warning = f"launchagent reload error: {e}"
+
     if errors:
         # 5. Full rollback: restore code tree + DBs + pip deps + rollback npm package
         if code_backup_dir:
@@ -632,6 +742,10 @@ 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 cron_sync_warning:
+        lines.append("  Crons: synced with manifest")
+    else:
+        lines.append(f"  WARNING: cron sync: {cron_sync_warning}")
     if not hook_sync_warning:
         lines.append("  Hooks: synced to NEXO_HOME")
     else:
@@ -642,6 +756,15 @@ def _handle_packaged_update(progress_fn=None) -> str:
         lines.append("  Clients: configured client targets synced")
     else:
         lines.append(f"  WARNING: client sync: {client_sync_warning}")
+    if launchagent_reload_summary and launchagent_reload_summary.get("scanned"):
+        if not launchagent_reload_warning:
+            lines.append(
+                "  LaunchAgents: reloaded "
+                f"{launchagent_reload_summary['reloaded']}/"
+                f"{launchagent_reload_summary['scanned']}"
+            )
+        else:
+            lines.append(f"  WARNING: launchagent reload: {launchagent_reload_warning}")
     lines.append("")
     lines.append("MCP server restart needed to load new code.")
     return "\n".join(lines)

package/src/user_data_portability.py

@@ -0,0 +1,328 @@
+"""Portable export/import helpers for operator user data."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sqlite3
+import tarfile
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+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)))
+EXPORTS_DIR = NEXO_HOME / "exports"
+STAGING_DIR = EXPORTS_DIR / ".staging"
+USER_DIRS = ("brain", "coordination", "nexo-email", "assets")
+USER_CONFIG_FILES = ("schedule.json",)
+IGNORED_FILENAMES = {".DS_Store"}
+IGNORED_DIRS = {"__pycache__"}
+IGNORED_SUFFIXES = {".pyc", ".pyo"}
+
+
+def _now_stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+
+
+def _runtime_version() -> str:
+    for candidate, key in (
+        (NEXO_HOME / "version.json", "version"),
+        (NEXO_CODE.parent / "version.json", "version"),
+        (NEXO_CODE.parent / "package.json", "version"),
+        (NEXO_HOME / "package.json", "version"),
+    ):
+        try:
+            if candidate.is_file():
+                return str(json.loads(candidate.read_text()).get(key, "?"))
+        except Exception:
+            continue
+    return "?"
+
+
+def _sqlite_backup(src: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    src_conn = sqlite3.connect(str(src))
+    try:
+        dst_conn = sqlite3.connect(str(dest))
+        try:
+            src_conn.backup(dst_conn)
+        finally:
+            dst_conn.close()
+    finally:
+        src_conn.close()
+
+
+def _should_skip_file(path: Path, exclude_names: set[str] | None = None) -> bool:
+    exclude = exclude_names or set()
+    if path.name in exclude:
+        return True
+    if path.name in IGNORED_FILENAMES:
+        return True
+    if path.suffix in IGNORED_SUFFIXES:
+        return True
+    return False
+
+
+def _copy_tree_filtered(src: Path, dest: Path, *, exclude_names: set[str] | None = None) -> int:
+    if not src.is_dir():
+        return 0
+    copied = 0
+    for root, dirs, files in os.walk(src):
+        root_path = Path(root)
+        rel = root_path.relative_to(src)
+        dirs[:] = [item for item in dirs if item not in IGNORED_DIRS]
+        target_root = dest / rel
+        target_root.mkdir(parents=True, exist_ok=True)
+        for name in files:
+            file_path = root_path / name
+            if _should_skip_file(file_path, exclude_names=exclude_names):
+                continue
+            shutil.copy2(str(file_path), str(target_root / name))
+            copied += 1
+    return copied
+
+
+def _copy_file_if_present(src: Path, dest: Path) -> bool:
+    if not src.is_file():
+        return False
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(str(src), str(dest))
+    return True
+
+
+def _safe_extract(archive_path: Path, dest_dir: Path) -> None:
+    resolved_dest = dest_dir.resolve()
+    with tarfile.open(archive_path, "r:*") as tar:
+        members = tar.getmembers()
+        for member in members:
+            target = (dest_dir / member.name).resolve()
+            if target != resolved_dest and resolved_dest not in target.parents:
+                raise ValueError(f"archive path escapes destination: {member.name}")
+            if member.issym() or member.islnk():
+                raise ValueError(f"archive contains unsupported link member: {member.name}")
+
+        for member in members:
+            target = (dest_dir / member.name).resolve()
+            if member.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+                target.chmod(member.mode & 0o777)
+                continue
+            if not member.isfile():
+                raise ValueError(f"archive contains unsupported member type: {member.name}")
+
+            target.parent.mkdir(parents=True, exist_ok=True)
+            extracted = tar.extractfile(member)
+            if extracted is None:
+                raise ValueError(f"archive member could not be read: {member.name}")
+            with extracted, target.open("wb") as handle:
+                shutil.copyfileobj(extracted, handle)
+            target.chmod(member.mode & 0o777)
+
+
+def _load_personal_scripts() -> tuple[list[dict], list[dict]]:
+    from script_registry import classify_scripts_dir, discover_personal_schedules
+
+    classification = classify_scripts_dir()
+    scripts = [entry for entry in classification.get("entries", []) if entry.get("classification") == "personal"]
+    script_paths = {entry["path"] for entry in scripts}
+    schedules = [
+        schedule for schedule in discover_personal_schedules()
+        if schedule.get("script_path") in script_paths
+    ]
+    return scripts, schedules
+
+
+def export_user_bundle(output_path: str = "") -> dict:
+    output = Path(output_path).expanduser() if output_path.strip() else (EXPORTS_DIR / f"nexo-user-data-{_now_stamp()}.tar.gz")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    STAGING_DIR.mkdir(parents=True, exist_ok=True)
+    stage_dir = Path(tempfile.mkdtemp(prefix="nexo-export-", dir=str(STAGING_DIR)))
+    bundle_root = stage_dir / "bundle"
+    bundle_root.mkdir(parents=True, exist_ok=True)
+
+    sections: dict[str, dict] = {}
+
+    try:
+        data_db = NEXO_HOME / "data" / "nexo.db"
+        if data_db.is_file():
+            _sqlite_backup(data_db, bundle_root / "data" / "nexo.db")
+            sections["data_db"] = {"path": "data/nexo.db"}
+
+        brain_dir = NEXO_HOME / "brain"
+        if brain_dir.is_dir():
+            copied = _copy_tree_filtered(brain_dir, bundle_root / "brain", exclude_names={"nexo.db"})
+            brain_db = brain_dir / "nexo.db"
+            if brain_db.is_file():
+                _sqlite_backup(brain_db, bundle_root / "brain" / "nexo.db")
+                copied += 1
+            sections["brain"] = {"path": "brain", "files": copied}
+
+        for dirname in USER_DIRS[1:]:
+            src_dir = NEXO_HOME / dirname
+            if not src_dir.is_dir():
+                continue
+            copied = _copy_tree_filtered(src_dir, bundle_root / dirname)
+            sections[dirname] = {"path": dirname, "files": copied}
+
+        copied_configs: list[str] = []
+        for filename in USER_CONFIG_FILES:
+            if _copy_file_if_present(NEXO_HOME / "config" / filename, bundle_root / "config" / filename):
+                copied_configs.append(filename)
+        if copied_configs:
+            sections["config"] = {"path": "config", "files": copied_configs}
+
+        scripts, schedules = _load_personal_scripts()
+        exported_scripts: list[dict] = []
+        scripts_dir = bundle_root / "personal-scripts"
+        scripts_dir.mkdir(parents=True, exist_ok=True)
+        for entry in scripts:
+            src_path = Path(entry["path"])
+            if not src_path.is_file():
+                continue
+            shutil.copy2(str(src_path), str(scripts_dir / src_path.name))
+            exported_scripts.append(
+                {
+                    "name": entry.get("name", src_path.stem),
+                    "path": f"personal-scripts/{src_path.name}",
+                    "runtime": entry.get("runtime", "unknown"),
+                    "description": entry.get("description", ""),
+                }
+            )
+        (scripts_dir / "manifest.json").write_text(
+            json.dumps(
+                {
+                    "scripts": exported_scripts,
+                    "schedules": schedules,
+                },
+                indent=2,
+                ensure_ascii=False,
+            ) + "\n"
+        )
+        sections["personal_scripts"] = {
+            "path": "personal-scripts",
+            "files": len(exported_scripts),
+            "schedules": len(schedules),
+        }
+
+        manifest = {
+            "kind": "nexo-user-data-bundle",
+            "version": _runtime_version(),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "nexo_home": str(NEXO_HOME),
+            "sections": sections,
+        }
+        (bundle_root / "manifest.json").write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
+
+        with tarfile.open(output, "w:gz") as tar:
+            tar.add(bundle_root, arcname="bundle")
+
+        return {
+            "ok": True,
+            "path": str(output),
+            "kind": manifest["kind"],
+            "version": manifest["version"],
+            "sections": sections,
+        }
+    finally:
+        shutil.rmtree(stage_dir, ignore_errors=True)
+
+
+def import_user_bundle(bundle_path: str) -> dict:
+    archive_path = Path(bundle_path).expanduser()
+    if not archive_path.is_file():
+        return {"ok": False, "error": f"bundle not found: {archive_path}"}
+
+    backups_dir = NEXO_HOME / "backups"
+    backups_dir.mkdir(parents=True, exist_ok=True)
+    safety_backup = backups_dir / f"pre-import-user-data-{_now_stamp()}.tar.gz"
+    safety_result = export_user_bundle(str(safety_backup))
+    if not safety_result.get("ok"):
+        return {"ok": False, "error": "failed to create safety backup", "safety_backup": str(safety_backup)}
+
+    STAGING_DIR.mkdir(parents=True, exist_ok=True)
+    stage_dir = Path(tempfile.mkdtemp(prefix="nexo-import-", dir=str(STAGING_DIR)))
+
+    try:
+        _safe_extract(archive_path, stage_dir)
+        bundle_root = stage_dir / "bundle"
+        manifest_path = bundle_root / "manifest.json"
+        if not manifest_path.is_file():
+            return {"ok": False, "error": "bundle manifest missing", "safety_backup": str(safety_backup)}
+
+        manifest = json.loads(manifest_path.read_text())
+        if manifest.get("kind") != "nexo-user-data-bundle":
+            return {
+                "ok": False,
+                "error": f"unsupported bundle kind: {manifest.get('kind', 'unknown')}",
+                "safety_backup": str(safety_backup),
+            }
+
+        restored: dict[str, dict] = {}
+
+        data_db = bundle_root / "data" / "nexo.db"
+        if data_db.is_file():
+            _sqlite_backup(data_db, NEXO_HOME / "data" / "nexo.db")
+            restored["data_db"] = {"path": "data/nexo.db"}
+
+        brain_dir = bundle_root / "brain"
+        if brain_dir.is_dir():
+            copied = _copy_tree_filtered(brain_dir, NEXO_HOME / "brain", exclude_names={"nexo.db"})
+            brain_db = brain_dir / "nexo.db"
+            if brain_db.is_file():
+                _sqlite_backup(brain_db, NEXO_HOME / "brain" / "nexo.db")
+                copied += 1
+            restored["brain"] = {"path": "brain", "files": copied}
+
+        for dirname in USER_DIRS[1:]:
+            src_dir = bundle_root / dirname
+            if not src_dir.is_dir():
+                continue
+            copied = _copy_tree_filtered(src_dir, NEXO_HOME / dirname)
+            restored[dirname] = {"path": dirname, "files": copied}
+
+        restored_configs: list[str] = []
+        for filename in USER_CONFIG_FILES:
+            if _copy_file_if_present(bundle_root / "config" / filename, NEXO_HOME / "config" / filename):
+                restored_configs.append(filename)
+        if restored_configs:
+            restored["config"] = {"path": "config", "files": restored_configs}
+
+        imported_scripts = 0
+        scripts_dir = bundle_root / "personal-scripts"
+        target_scripts_dir = NEXO_HOME / "scripts"
+        target_scripts_dir.mkdir(parents=True, exist_ok=True)
+        if scripts_dir.is_dir():
+            for script_path in sorted(scripts_dir.iterdir()):
+                if not script_path.is_file() or script_path.name == "manifest.json":
+                    continue
+                shutil.copy2(str(script_path), str(target_scripts_dir / script_path.name))
+                imported_scripts += 1
+        restored["personal_scripts"] = {"path": "personal-scripts", "files": imported_scripts}
+
+        from db import init_db
+        from script_registry import reconcile_personal_scripts
+
+        init_db()
+        reconcile_result = reconcile_personal_scripts(dry_run=False)
+
+        return {
+            "ok": True,
+            "path": str(archive_path),
+            "kind": manifest.get("kind"),
+            "bundle_version": manifest.get("version"),
+            "safety_backup": str(safety_backup),
+            "restored": restored,
+            "reconciled": reconcile_result,
+        }
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": str(exc),
+            "safety_backup": str(safety_backup),
+        }
+    finally:
+        shutil.rmtree(stage_dir, ignore_errors=True)