nexo-brain 5.3.5 → 5.3.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.5",
+  "version": "5.3.7",
   "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

@@ -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.5` 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.7` closes the remaining packaged-runtime happy-path gap and finally exposes 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.5",
+  "version": "5.3.7",
   "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/client_sync.py

@@ -160,6 +160,11 @@ def _claude_code_settings_path(home: Path | None = None) -> Path:
     return base / ".claude" / "settings.json"
 
 
+def _claude_code_mcp_path(home: Path | None = None) -> Path:
+    base = home or _user_home()
+    return base / ".claude.json"
+
+
 def _claude_desktop_config_path(home: Path | None = None) -> Path:
     base = home or _user_home()
     if sys.platform == "darwin":
@@ -627,10 +632,22 @@ def sync_claude_code(
         python_path=python_path,
         operator_name=operator_name,
     )
+    home_path = Path(user_home).expanduser() if user_home else None
     result = _sync_claude_code_settings(
-        _claude_code_settings_path(Path(user_home).expanduser() if user_home else None),
+        _claude_code_settings_path(home_path),
         server_config,
     )
+    # Claude Code 2.1.x reads user-scoped MCP servers from ~/.claude.json.
+    # Keep settings.json in sync for hooks/runtime preferences, but also write
+    # the managed NEXO MCP server to the root user config so `claude mcp list`
+    # and interactive sessions see the same server.
+    mcp_result = _sync_json_client(
+        _claude_code_mcp_path(home_path),
+        server_config,
+        "claude_code",
+    )
+    result["mcp"] = mcp_result
+    result["mcp_path"] = mcp_result.get("path", "")
     bootstrap_result = sync_client_bootstrap(
         "claude_code",
         nexo_home=nexo_home,

package/src/db/_cron_runs.py

@@ -56,14 +56,19 @@ def cron_runs_summary(hours: int = 24) -> list[dict]:
                cron_id,
                COUNT(*) as total_runs,
                SUM(CASE WHEN exit_code = 0 THEN 1 ELSE 0 END) as succeeded,
-               SUM(CASE WHEN exit_code != 0 OR exit_code IS NULL THEN 1 ELSE 0 END) as failed,
+               SUM(CASE WHEN exit_code IS NOT NULL AND ended_at IS NOT NULL THEN 1 ELSE 0 END) as completed_runs,
+               SUM(CASE WHEN exit_code IS NOT NULL AND exit_code != 0 THEN 1 ELSE 0 END) as failed,
+               SUM(CASE WHEN exit_code IS NULL OR ended_at IS NULL THEN 1 ELSE 0 END) as open_runs,
                ROUND(AVG(duration_secs), 1) as avg_duration,
                MAX(started_at) as last_run,
                (SELECT exit_code FROM cron_runs cr2
                 WHERE cr2.cron_id = cron_runs.cron_id
                 ORDER BY started_at DESC LIMIT 1) as last_exit_code,
-               (SELECT summary FROM cron_runs cr3
-                WHERE cr3.cron_id = cron_runs.cron_id AND cr3.summary != ''
+               (SELECT ended_at FROM cron_runs cr3
+                WHERE cr3.cron_id = cron_runs.cron_id
+                ORDER BY started_at DESC LIMIT 1) as last_ended_at,
+               (SELECT summary FROM cron_runs cr4
+                WHERE cr4.cron_id = cron_runs.cron_id AND cr4.summary != ''
                 ORDER BY started_at DESC LIMIT 1) as last_summary
            FROM cron_runs
            WHERE started_at >= datetime('now', ?)

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/schedule.py

@@ -1,5 +1,6 @@
 """NEXO Schedule — Cron execution history, status, and management tools."""
 
+from datetime import datetime, timezone
 import json
 import os
 import platform
@@ -34,7 +35,13 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
         schedule_meta = get_personal_script_schedule(cron_id) or {}
         lines = [f"CRON RUNS — {cron_id} (last {hours}h): {len(runs)} executions"]
         for r in runs:
-            status, detail = _run_status_marker(r.get("exit_code"), r.get("summary"), schedule_meta=schedule_meta)
+            status, detail = _run_status_marker(
+                r.get("exit_code"),
+                r.get("summary"),
+                schedule_meta=schedule_meta,
+                started_at=r.get("started_at"),
+                ended_at=r.get("ended_at"),
+            )
             if schedule_meta.get("schedule_type") == "keep_alive" and r.get("exit_code") is None:
                 dur = "daemon active"
             else:
@@ -53,11 +60,20 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     lines = [f"CRON STATUS (last {hours}h):"]
     for s in summary:
         schedule_meta = get_personal_script_schedule(s["cron_id"]) or {}
-        status, detail = _run_status_marker(s.get("last_exit_code"), s.get("last_summary"), schedule_meta=schedule_meta)
+        status, detail = _run_status_marker(
+            s.get("last_exit_code"),
+            s.get("last_summary"),
+            schedule_meta=schedule_meta,
+            started_at=s.get("last_run"),
+            ended_at=s.get("last_ended_at"),
+        )
         if schedule_meta.get("schedule_type") == "keep_alive" and s.get("last_exit_code") is None:
             rate = "daemon active"
         else:
-            rate = f"{s['succeeded']}/{s['total_runs']}"
+            completed_runs = s.get("completed_runs")
+            if completed_runs is None:
+                completed_runs = s["total_runs"]
+            rate = f"{s['succeeded']}/{completed_runs}"
         dur = f"{s['avg_duration']:.0f}s avg" if s.get("avg_duration") else ""
         summary_txt = f" — {s['last_summary'][:80]}" if s.get("last_summary") else ""
         suffix = f" [{detail}]" if detail else ""
@@ -87,16 +103,78 @@ def _summary_has_warning(summary: str = "") -> bool:
     return any(token in lowered for token in warning_tokens)
 
 
-def _run_status_marker(exit_code, summary: str = "", *, schedule_meta: dict | None = None) -> tuple[str, str]:
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _parse_db_timestamp(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        return datetime.strptime(text[:19], "%Y-%m-%d %H:%M:%S").replace(tzinfo=timezone.utc)
+    except ValueError:
+        pass
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _format_age(seconds: float) -> str:
+    if seconds < 60:
+        return "<1m"
+    if seconds < 3600:
+        return f"{int(round(seconds / 60))}m"
+    return f"{seconds / 3600:.1f}h"
+
+
+def _open_run_stale_after(schedule_meta: dict | None = None) -> int:
+    schedule_meta = schedule_meta or {}
+    if schedule_meta.get("schedule_type") == "interval":
+        try:
+            interval = int(schedule_meta.get("interval_seconds") or schedule_meta.get("schedule_value") or 0)
+        except (TypeError, ValueError):
+            interval = 0
+        if interval > 0:
+            return max(300, interval * 2)
+    if schedule_meta.get("schedule_type") == "calendar":
+        return 3600
+    return 1800
+
+
+def _open_run_marker(started_at: str | None, *, schedule_meta: dict | None = None) -> tuple[str, str]:
+    started = _parse_db_timestamp(started_at)
+    if started is None:
+        return "⚠", "open run"
+    age_secs = max(0.0, (_now_utc() - started).total_seconds())
+    if age_secs <= _open_run_stale_after(schedule_meta):
+        return "⏳", f"running {_format_age(age_secs)}"
+    return "⚠", f"open run {_format_age(age_secs)}"
+
+
+def _run_status_marker(
+    exit_code,
+    summary: str = "",
+    *,
+    schedule_meta: dict | None = None,
+    started_at: str | None = None,
+    ended_at: str | None = None,
+) -> tuple[str, str]:
     schedule_meta = schedule_meta or {}
     if schedule_meta.get("schedule_type") == "keep_alive" and exit_code is None:
         return "🟢", "keep_alive daemon active"
+    if exit_code is None:
+        return _open_run_marker(started_at, schedule_meta=schedule_meta)
     if exit_code == 0 and _summary_has_warning(summary):
         return "⚠", "exit 0 with warnings"
     if exit_code == 0:
         return "✅", "exit 0"
-    if exit_code is None:
-        return "❌", "missing exit code"
     return "❌", f"exit {exit_code}"
 
 

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/retroactive_learnings.py

@@ -29,7 +29,10 @@ Matching strategy:
          with significant tokens from the decision's
          decision + based_on + alternatives + context_ref. Score is
          intersection_size / max(1, learning_token_count) clipped to 1.0.
-    Combined score: 0.5 * applies_to_score + 0.5 * keyword_score.
+    Guardrail: if a learning defines `applies_to` and that anchor scores
+        below 0.3, auto-dismiss the match even if keyword overlap is high.
+        This blocks keyword-only false positives outside the learning's
+        actual blast radius.
     Default match threshold: 0.4. Default cap: 5 matches per learning.
 
 Anti-spam guards:
@@ -129,16 +132,16 @@ def _score_match(
         keyword_hits = set()
         keyword_score = 0.0
 
-    # max() rather than weighted average so a strong signal alone qualifies.
-    # The two signals (applies_to overlap, keyword overlap) are independent
-    # paths to the same conclusion: this past decision is in the new rule's
-    # blast radius. If either one fires strongly, surface the match.
-    score = max(applies_to_score, keyword_score)
+    gated_by_applies_to = bool(learning_applies_to and applies_to_score < 0.3)
+    # When a learning explicitly scopes its blast radius via applies_to,
+    # keyword overlap alone is too noisy to justify a retroactive review.
+    score = applies_to_score if gated_by_applies_to else max(applies_to_score, keyword_score)
     breakdown = {
         "applies_to_score": round(applies_to_score, 3),
         "applies_to_hits": sorted(applies_to_hits),
         "keyword_score": round(keyword_score, 3),
         "keyword_hits": sorted(keyword_hits),
+        "gated_by_applies_to": gated_by_applies_to,
     }
     return round(score, 3), breakdown
 

package/src/script_registry.py

@@ -93,6 +93,12 @@ SUPPORTED_RUNTIMES = {"python", "shell", "node", "php", "unknown"}
 PERSONAL_SCHEDULE_MANAGED_ENV = "NEXO_MANAGED_PERSONAL_CRON"
 SUPPORTED_RECOVERY_POLICIES = {"none", "run_once_on_wake", "catchup", "restart", "restart_daemon"}
 PERSONAL_SCRIPT_FILENAME_PREFIX = "ps-"
+_LEGACY_CORE_SCRIPT_ALIASES = {
+    "nexo-postcompact.sh": "post-compact.sh",
+    "nexo-memory-precompact.sh": "pre-compact.sh",
+    "nexo-memory-stop.sh": "session-stop.sh",
+    "nexo-session-briefing.sh": "session-start.sh",
+}
 
 
 def get_nexo_home() -> Path:
@@ -130,8 +136,33 @@ def _apply_legacy_personal_script_backfills() -> None:
     wake_recovery.write_text("".join(head + lines[start:]))
 
 
+def _add_runtime_artifact_names(names: set[str], artifact_path: Path) -> None:
+    try:
+        data = json.loads(artifact_path.read_text())
+    except Exception:
+        return
+    for key in ("script_names", "hook_names"):
+        for item in data.get(key, []):
+            if isinstance(item, str) and item.strip():
+                names.add(Path(item).name)
+
+
+def _add_filenames_from_dir(names: set[str], directory: Path, *, skip_if_scripts_dir: bool = False) -> None:
+    if not directory.is_dir():
+        return
+    if skip_if_scripts_dir:
+        try:
+            if directory.resolve() == get_scripts_dir().resolve():
+                return
+        except Exception:
+            pass
+    for item in directory.iterdir():
+        if item.is_file() and not item.name.startswith("."):
+            names.add(item.name)
+
+
 def load_core_script_names() -> set[str]:
-    """Load runtime-managed script names (core, not personal)."""
+    """Load every core-managed runtime artifact name that must never be treated as personal."""
     names: set[str] = set()
     for manifest_path in [NEXO_CODE / "crons" / "manifest.json", NEXO_HOME / "crons" / "manifest.json"]:
         if manifest_path.exists():
@@ -144,25 +175,22 @@ def load_core_script_names() -> set[str]:
                 break
             except Exception:
                 continue
-    runtime_manifest = NEXO_HOME / "config" / "runtime-core-artifacts.json"
-    if runtime_manifest.exists():
-        try:
-            data = json.loads(runtime_manifest.read_text())
-            for key in ("script_names", "hook_names"):
-                for name in data.get(key, []):
-                    clean = Path(str(name)).name
-                    if clean:
-                        names.add(clean)
-        except Exception:
-            pass
-    hooks_dir = NEXO_HOME / "hooks"
-    if hooks_dir.is_dir():
-        try:
-            for item in hooks_dir.iterdir():
-                if item.is_file():
-                    names.add(item.name)
-        except Exception:
-            pass
+
+    for artifact_path in (
+        NEXO_HOME / "config" / "runtime-core-artifacts.json",
+        NEXO_CODE / "config" / "runtime-core-artifacts.json",
+        NEXO_CODE.parent / "config" / "runtime-core-artifacts.json",
+    ):
+        if artifact_path.exists():
+            _add_runtime_artifact_names(names, artifact_path)
+
+    _add_filenames_from_dir(names, NEXO_HOME / "hooks")
+    _add_filenames_from_dir(names, NEXO_CODE / "hooks")
+    _add_filenames_from_dir(names, NEXO_CODE / "scripts", skip_if_scripts_dir=True)
+
+    for legacy_name, canonical_name in _LEGACY_CORE_SCRIPT_ALIASES.items():
+        if canonical_name in names:
+            names.add(legacy_name)
     names.update(_LEGACY_CORE_RUNTIME_FILES)
     return names
 

package/src/skills/run-nexo-audit-phase/guide.md

@@ -0,0 +1,43 @@
+# Run NEXO Audit Phase
+
+Usa esta skill cuando haya que ejecutar una fase de auditoria de NEXO y el cuello de botella sea decidir el alcance de `evolution_apply` y arrancar una tanda de items con disciplina empirica.
+
+## Pasos
+1. Abre `goal + workflow + task` y fija el terreno real antes de interpretar el informe:
+   - repo/runtime activo
+   - DB real
+   - mecanismo de update
+   - tests y estado git
+2. Fija la regla de autonomia antes de empezar:
+   - Francisco no quiere checkpoints uno-a-uno para trabajo mecanico
+   - NEXO hace branches, PRs, merge y reporta despues con evidencia
+   - solo un blast radius arquitectonico enorme merece checkpoint
+3. Trata `evolution_apply` como una decision tecnica de implementacion, no como permiso humano:
+   - el camino de apply ya existe via `evolution_log` + `_apply_accepted_proposals`
+   - el sandbox/snapshot/rollback protege la materializacion del cambio aceptado
+   - no dupliques ese mecanismo en deep sleep ni en el runner de auditoria
+4. Lanza la verificacion empirica de todos los items en paralelo:
+   - `grep + read` del codigo
+   - SQL/schema real
+   - AST/tests/imports/logs cuando aplique
+   - asume FP hasta que la evidencia lo contradiga
+5. Clasifica cada item:
+   - `real_gap`
+   - `casi_fp`
+   - `fp`
+6. Ordena solo los `real_gap` por riesgo/blast radius y ejecutalos con worktree aislado si tocan core.
+7. Por cada `real_gap`:
+   - `guard_check`
+   - `track`
+   - branch propia
+   - implementacion minima
+   - tests adyacentes
+   - PR + auto-merge squash
+   - seguir al siguiente sin esperar CI salvo bloqueo real
+8. Para `fp` o `casi_fp`, captura learning/patron reusable en vez de reimplementar.
+9. Cierra la fase con evidencia real: PRs, tests, merge status y resultados de verificacion.
+
+## Gotchas
+- Learning #198: no confundas "como trabaja NEXO" con "que puede aplicar evolution_apply". Lo primero ya esta resuelto: autonomia total.
+- `apply_findings.py` ya stagea `code_change` en `evolution_log`; `nexo-evolution-run.py` ya consume `accepted` con sandbox/snapshot/rollback. Si el item pide eso, primero verifica si ya existe.
+- En Fase 1+2 la auditoria automatica sobreestimo ~70% de gaps. Si no hay evidencia dura, no abras codigo.

package/src/skills/run-nexo-audit-phase/skill.json

@@ -0,0 +1,59 @@
+{
+  "id": "SK-RUN-NEXO-AUDIT-PHASE",
+  "name": "Run NEXO Audit Phase",
+  "description": "Workflow para ejecutar una fase de auditoria de NEXO con autonomia total y verificacion empirica. Cubre el patron repetido de decidir el scope de evolution_apply y arrancar una tanda de items sin checkpoints manuales.",
+  "level": "published",
+  "mode": "guide",
+  "source_kind": "core",
+  "execution_level": "none",
+  "approval_required": false,
+  "tags": [
+    "nexo",
+    "audit",
+    "evolution",
+    "sandbox",
+    "verification",
+    "core"
+  ],
+  "trigger_patterns": [
+    "evolution_apply sandbox scope",
+    "fase 2 item 1",
+    "arrancar verificacion empirica",
+    "ejecutar fase de auditoria nexo",
+    "audit phase nexo",
+    "7 items audit"
+  ],
+  "steps": [
+    "Abrir goal, workflow y task antes de tocar la auditoria; resolver repo/runtime real, DB real, tests y estado git antes de interpretar el informe.",
+    "Fijar la regla de autonomia: NEXO hace branches, PRs, merge y progreso periodico; no pedir checkpoints uno-a-uno a Francisco para trabajo mecanico.",
+    "Para `evolution_apply`, separar dos planos: el sandbox es para materializar/aplicar cambios aceptados con snapshot/rollback; no es un freno para el modo de trabajo autonomo del agente.",
+    "Lanzar verificacion empirica de TODOS los items en paralelo: grep+read, SQL/schema real, AST/tests, logs. Partir de la hipotesis de FP hasta tener evidencia.",
+    "Clasificar cada item en `real_gap`, `casi_fp` o `fp` y ordenar solo los reales por blast radius/riesgo.",
+    "Si hay que tocar core, usar worktree aislado; por item real: guard_check -> track -> branch -> implement -> tests adyacentes -> PR -> auto-merge squash.",
+    "Para items FP o casi-FP, capturar learning o ajustar el patron reusable en vez de reimplementar.",
+    "Cerrar con evidencia de PRs, tests y merge status reales; no usar diarios o workflow text como sustituto."
+  ],
+  "gotchas": [
+    "No pedir aprobacion manual a Francisco para cada PR: learning #198 confirma autonomia total con transparencia y reportes periodicos.",
+    "No duplicar el sandbox de evolution en otros sitios: el apply de cambios aceptados ya reutiliza evolution_log + sandbox/snapshot/rollback.",
+    "El ratio historico de FPs en esta clase de auditoria es alto; si no hay evidencia concreta, el item no se toca."
+  ],
+  "params_schema": {
+    "audit_file": {
+      "type": "string",
+      "required": true
+    },
+    "phase_label": {
+      "type": "string",
+      "required": false,
+      "default": ""
+    },
+    "repo_path": {
+      "type": "string",
+      "required": false,
+      "default": ""
+    }
+  },
+  "command_template": {},
+  "stable_after_uses": 5
+}

package/src/skills/run-release-final-audit/script.py

@@ -9,15 +9,74 @@ import sys
 from pathlib import Path
 
 
+def _is_repo_root(candidate: Path) -> bool:
+    return (
+        (candidate / "package.json").is_file()
+        and (candidate / "release-contracts").is_dir()
+        and (candidate / "scripts" / "verify_release_readiness.py").is_file()
+    )
+
+
+def _normalize_candidate(raw: str | Path) -> Path:
+    candidate = Path(raw).expanduser().resolve()
+    if candidate.is_file():
+        candidate = candidate.parent
+    if candidate.name == "src" and (candidate / "server.py").is_file():
+        candidate = candidate.parent
+    return candidate
+
+
+def _resolve_repo_root_from_atlas() -> Path | None:
+    homes = []
+    env_home = os.environ.get("NEXO_HOME", "").strip()
+    if env_home:
+        homes.append(Path(env_home).expanduser())
+    homes.extend((Path.home() / ".nexo", Path.home() / "claude"))
+
+    seen = set()
+    for home in homes:
+        key = str(home)
+        if key in seen:
+            continue
+        seen.add(key)
+        atlas_path = home / "brain" / "project-atlas.json"
+        if not atlas_path.is_file():
+            continue
+        try:
+            payload = json.loads(atlas_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            continue
+        nexo = payload.get("nexo") if isinstance(payload, dict) else None
+        locations = nexo.get("locations") if isinstance(nexo, dict) else None
+        source = locations.get("mcp_server", "") if isinstance(locations, dict) else ""
+        if not isinstance(source, str) or not source.strip():
+            continue
+        candidate = _normalize_candidate(source)
+        if _is_repo_root(candidate):
+            return candidate
+    return None
+
+
 def _resolve_repo_root() -> Path:
     env_code = os.environ.get("NEXO_CODE", "").strip()
     if env_code:
-        candidate = Path(env_code).expanduser().resolve()
-        if candidate.is_file():
-            candidate = candidate.parent
-        if (candidate / "cli.py").is_file():
-            return candidate.parent if candidate.name == "src" else candidate
-    return Path(__file__).resolve().parents[3]
+        candidate = _normalize_candidate(env_code)
+        if _is_repo_root(candidate):
+            return candidate
+
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if _is_repo_root(candidate):
+            return candidate
+
+    atlas_repo = _resolve_repo_root_from_atlas()
+    if atlas_repo is not None:
+        return atlas_repo
+
+    script_root = _normalize_candidate(Path(__file__).resolve().parents[3])
+    if _is_repo_root(script_root):
+        return script_root
+    return script_root
 
 
 ROOT = _resolve_repo_root()
@@ -77,7 +136,7 @@ def _env(nexo_home: str) -> dict[str, str]:
     env["PYTHONPATH"] = (
         f"{src_path}{os.pathsep}{existing_pythonpath}" if existing_pythonpath else src_path
     )
-    env.setdefault("NEXO_CODE", str(ROOT / "src"))
+    env["NEXO_CODE"] = src_path
     if nexo_home.strip():
         env["NEXO_HOME"] = str(Path(nexo_home).expanduser())
     return env
@@ -128,13 +187,27 @@ def _run(cmd: list[str], *, env: dict[str, str]) -> None:
         raise SystemExit(result.returncode)
 
 
+def _looks_like_nexo_home(raw: str) -> bool:
+    if not raw.strip():
+        return False
+    candidate = Path(raw).expanduser()
+    return (candidate / "skills-runtime").is_dir() or (candidate / "operations" / "tool-logs").is_dir()
+
+
+def _parse_optional_paths(argv: list[str]) -> tuple[str, str]:
+    if len(argv) > 6:
+        return argv[5], argv[6]
+    if len(argv) > 5:
+        return ("", argv[5]) if _looks_like_nexo_home(argv[5]) else (argv[5], "")
+    return "", ""
+
+
 def main() -> int:
     contract_arg = sys.argv[1] if len(sys.argv) > 1 else "auto"
     require_contract_complete = _parse_bool(sys.argv[2] if len(sys.argv) > 2 else "true", True)
     include_smoke = _parse_bool(sys.argv[3] if len(sys.argv) > 3 else "true", True)
     ci = _parse_bool(sys.argv[4] if len(sys.argv) > 4 else "false", False)
-    website_root = sys.argv[5] if len(sys.argv) > 5 else ""
-    nexo_home = sys.argv[6] if len(sys.argv) > 6 else ""
+    website_root, nexo_home = _parse_optional_paths(sys.argv)
 
     version = _package_version()
     contract_path = _resolve_contract(version, contract_arg)

package/src/user_data_portability.py

@@ -0,0 +1,302 @@
+"""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:
+    with tarfile.open(archive_path, "r:*") as tar:
+        for member in tar.getmembers():
+            target = (dest_dir / member.name).resolve()
+            if not str(target).startswith(str(dest_dir.resolve())):
+                raise ValueError(f"archive path escapes destination: {member.name}")
+        tar.extractall(dest_dir)
+
+
+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,
+        }
+    finally:
+        shutil.rmtree(stage_dir, ignore_errors=True)