nexo-brain 5.6.0 → 5.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "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,9 @@
 
 [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.6.0` is the current packaged-runtime line: default model upgrade from Opus 4.6 to **Opus 4.7** with `reasoning_effort: "max"` (the new highest tier). Auto-migration on `nexo update` silently upgrades existing users from `claude-opus-4-6*` to `claude-opus-4-7` preserving the 1M context suffix. Codex profiles are untouched.
+Version `5.7.0` is the current packaged-runtime line: `nexo update` now keeps Claude Code and Codex CLIs in lockstep with NEXO Brain itself. When the global `@anthropic-ai/claude-code` or `@openai/codex` packages are installed, the updater checks the npm registry and runs `npm install -g <pkg>@latest` in-line — so the terminal boot model stays aligned with the settings NEXO already wrote to `~/.claude/settings.json`. Packages the operator never installed are skipped silently. Pass `nexo update --no-clis` to keep the terminal CLIs pinned.
+
+Previously in `5.6.1`: update-path hardening — 0-byte `.db` orphans from interrupted installs are now purged from `~/.nexo/` and `~/.nexo/data/` before the pre-update backup, and `sync_claude_code_model()` propagates the NEXO-recommended model into `~/.claude/settings.json` whenever `heal_runtime_profiles()` migrates the `claude_code` default.
 
 Previously in `5.5.5`: data-loss guardrails + automatic self-heal. The updater now refuses to capture an already-wiped `nexo.db` into a `pre-update-*` snapshot (validated `sqlite3.backup` + pre-flight wipe guard + post-migration row-count gate), and an auto-heal restores `data/nexo.db` from the newest hourly backup on the next server boot when a wipe is detected. New `nexo recover` CLI + `nexo_recover` MCP tool.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 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/auto_update.py

@@ -836,10 +836,53 @@ def _self_heal_if_wiped() -> dict | None:
     }
 
 
+def _purge_zero_byte_db_files() -> list[Path]:
+    """Delete 0-byte .db files in NEXO_HOME and its ``data/`` subdir.
+
+    These are orphans from interrupted installs / aborted ``sqlite3.connect``
+    calls. They break backup validation by (a) masking the real DB during
+    :func:`_find_primary_db_path` selection when two ``nexo.db`` paths
+    coexist, and (b) being copied into the backup as empty shells that later
+    confuse :func:`_restore_dbs` on rollback.
+
+    Never touches SRC_DIR (the repo checkout) or the ``backups/`` tree.
+    Returns the list of removed paths for logging; failures are swallowed
+    so backup never aborts because of orphan cleanup.
+    """
+    removed: list[Path] = []
+    scan_dirs: list[Path] = []
+    if NEXO_HOME.is_dir():
+        scan_dirs.append(NEXO_HOME)
+    if DATA_DIR.is_dir() and DATA_DIR != NEXO_HOME:
+        scan_dirs.append(DATA_DIR)
+    for scan_dir in scan_dirs:
+        try:
+            candidates = [f for f in scan_dir.glob("*.db") if f.is_file()]
+        except Exception:
+            continue
+        for path in candidates:
+            try:
+                if path.stat().st_size != 0:
+                    continue
+            except Exception:
+                continue
+            try:
+                path.unlink()
+                removed.append(path)
+                _log(f"Purged zero-byte DB orphan: {path}")
+            except Exception as e:
+                _log(f"Failed to purge zero-byte DB {path}: {e}")
+    return removed
+
+
 def _backup_dbs() -> str | None:
     """Snapshot all .db files before migration. Returns backup dir or None."""
     import sqlite3
     import time as _time
+    # Drop 0-byte .db orphans first — they mask the real DB during primary
+    # path selection and turn into empty shells in the backup, breaking both
+    # validation and rollback paths. Safe no-op when there are none.
+    _purge_zero_byte_db_files()
     timestamp = _time.strftime("%Y-%m-%d-%H%M%S")
     backup_dir = NEXO_HOME / "backups" / f"pre-autoupdate-{timestamp}"
 
@@ -1125,6 +1168,202 @@ def _check_npm_version() -> str | None:
     return None
 
 
+# ── External CLI auto-update (Claude Code, Codex) ────────────────────
+# Keep this list aligned with the third-party CLIs that NEXO drives end-to-end.
+# Adding a new CLI here makes `nexo update` auto-install/bump it unless the
+# caller passes include_clis=False. Learning #323: use canonical npm names.
+_EXTERNAL_CLIS: tuple[str, ...] = (
+    "@anthropic-ai/claude-code",
+    "@openai/codex",
+)
+
+
+def _update_external_clis(progress_fn=None) -> dict:
+    """Detect and update NEXO's external terminal CLIs.
+
+    For each package in :data:`_EXTERNAL_CLIS`:
+      1. Read the installed global version via ``npm list -g --json --depth=0``.
+      2. Fetch the latest version from the npm registry via ``npm view <pkg> version``.
+      3. When newer, run ``npm install -g <pkg>@latest``.
+
+    Silently skips packages that are not installed globally — NEXO does not
+    push unsolicited installs of third-party CLIs onto operators.
+
+    Returns a dict keyed by package name. Each entry shape::
+
+        {
+            "old": "2.1.109" | None,
+            "new": "2.1.115" | None,
+            "updated": True | False,
+            "status": "updated" | "already_latest" | "not_installed"
+                      | "skipped" | "failed",
+            "error": "<message>"           # only when status == "failed"/"skipped"
+        }
+    """
+    # Reuse the npm helpers already hardened in plugins/update.py (version
+    # parsing, TimeoutExpired handling, invalid-name validation). Falling back
+    # to "skipped" keeps a partially-copied runtime from crashing the update.
+    try:
+        from plugins.update import (
+            _get_npm_global_version,
+            _get_npm_registry_version,
+            _validate_npm_name,
+        )
+    except Exception as e:  # pragma: no cover — only mid-upgrade installs hit this
+        return {
+            cli: {
+                "old": None,
+                "new": None,
+                "updated": False,
+                "status": "skipped",
+                "error": f"plugins.update helpers unavailable: {e}",
+            }
+            for cli in _EXTERNAL_CLIS
+        }
+
+    results: dict[str, dict] = {}
+
+    for pkg in _EXTERNAL_CLIS:
+        entry: dict = {"old": None, "new": None, "updated": False, "status": "unknown"}
+
+        if not _validate_npm_name(pkg):
+            entry.update({"status": "failed", "error": f"invalid npm name: {pkg!r}"})
+            results[pkg] = entry
+            continue
+
+        old_version = _get_npm_global_version(pkg)
+        if old_version is None:
+            # Not installed globally — don't auto-install third-party CLIs the
+            # operator didn't opt into. Silent skip in the final summary.
+            entry["status"] = "not_installed"
+            results[pkg] = entry
+            continue
+
+        entry["old"] = old_version
+
+        latest = _get_npm_registry_version(pkg)
+        if latest is None:
+            entry.update({
+                "new": old_version,
+                "status": "failed",
+                "error": "npm registry lookup failed",
+            })
+            results[pkg] = entry
+            continue
+
+        if old_version == latest:
+            entry.update({"new": old_version, "status": "already_latest"})
+            results[pkg] = entry
+            continue
+
+        if progress_fn is not None:
+            try:
+                progress_fn(f"Updating {pkg}: {old_version} -> {latest}...")
+            except Exception:
+                pass
+
+        try:
+            r = subprocess.run(
+                ["npm", "install", "-g", f"{pkg}@latest"],
+                capture_output=True,
+                text=True,
+                timeout=180,
+            )
+        except subprocess.TimeoutExpired:
+            # Learning #294: always capture TimeoutExpired explicitly.
+            entry.update({
+                "new": old_version,
+                "status": "failed",
+                "error": "npm install timed out after 180s",
+            })
+            results[pkg] = entry
+            continue
+        except FileNotFoundError:
+            # npm itself missing — no Node.js on PATH. Mark the rest as skipped
+            # and bail: no point retrying subsequent packages.
+            entry.update({
+                "new": old_version,
+                "status": "skipped",
+                "error": "npm not found on PATH",
+            })
+            results[pkg] = entry
+            for remaining in _EXTERNAL_CLIS:
+                results.setdefault(remaining, {
+                    "old": None,
+                    "new": None,
+                    "updated": False,
+                    "status": "skipped",
+                    "error": "npm not found on PATH",
+                })
+            return results
+        except Exception as e:  # pragma: no cover — defensive
+            entry.update({
+                "new": old_version,
+                "status": "failed",
+                "error": str(e)[:500],
+            })
+            results[pkg] = entry
+            continue
+
+        if r.returncode != 0:
+            entry.update({
+                "new": old_version,
+                "status": "failed",
+                "error": (r.stderr or r.stdout or "npm install failed").strip()[:500],
+            })
+            results[pkg] = entry
+            continue
+
+        new_version = _get_npm_global_version(pkg) or latest
+        entry.update({
+            "new": new_version,
+            "updated": new_version != old_version,
+            "status": "updated" if new_version != old_version else "already_latest",
+        })
+        results[pkg] = entry
+
+    return results
+
+
+def _format_external_clis_results(results: dict) -> list[str]:
+    """Render CLI update results as lines for the ``nexo update`` summary.
+
+    Emits a visible warning per bumped CLI (operator must restart the terminal
+    for the new version to take effect), a warning per failure, and a single
+    informational line when nothing changed but something was checked.
+    """
+    if not results:
+        return []
+
+    lines: list[str] = []
+    any_updated = False
+    any_failed = False
+    any_checked_latest = False
+
+    for pkg, entry in results.items():
+        status = entry.get("status")
+        if status == "updated":
+            any_updated = True
+            lines.append(
+                f"  CLI updated: {pkg} {entry.get('old')} -> {entry.get('new')} "
+                f"— reinicia terminal para activar"
+            )
+        elif status == "already_latest":
+            any_checked_latest = True
+        elif status == "failed":
+            any_failed = True
+            lines.append(
+                f"  WARNING: CLI {pkg} update failed: {entry.get('error', 'unknown')}"
+            )
+        # "not_installed" and "skipped" are intentionally silent — third-party
+        # CLIs that the operator never installed shouldn't spam the summary.
+
+    if not any_updated and not any_failed and any_checked_latest:
+        lines.append("  CLIs externos: ya en última versión")
+
+    return lines
+
+
 # ── File-based migrations (migrations/ directory) ────────────────────
 
 def _get_applied_migration_version() -> int:
@@ -2271,6 +2510,32 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
             for msg in heal_messages:
                 _emit_progress(progress_fn, msg)
                 actions.append("model-heal")
+            # Claude Code reads the default model from ~/.claude/settings.json,
+            # not from client_runtime_profiles. If the heal migrated the
+            # claude_code model (e.g. Opus 4.6 → 4.7) the internal profile is
+            # now correct but Claude Code keeps booting on the old model until
+            # settings.json is also updated. Propagate conservatively: only
+            # touch settings.json when it already has a "model" field.
+            existing_cc = existing_profiles.get("claude_code") if isinstance(existing_profiles.get("claude_code"), dict) else None
+            healed_cc = healed_profiles.get("claude_code") if isinstance(healed_profiles.get("claude_code"), dict) else None
+            old_cc_model = str((existing_cc or {}).get("model") or "")
+            new_cc_model = str((healed_cc or {}).get("model") or "")
+            if new_cc_model and new_cc_model != old_cc_model:
+                try:
+                    from client_sync import sync_claude_code_model
+                    sync_result = sync_claude_code_model(new_cc_model)
+                    if sync_result.get("action") == "updated":
+                        _emit_progress(
+                            progress_fn,
+                            f"Synced Claude Code settings.json model → '{new_cc_model}'.",
+                        )
+                        actions.append("claude-settings-model")
+                    elif not sync_result.get("ok"):
+                        actions.append(
+                            f"claude-settings-model-warning:{sync_result.get('reason', 'unknown')}"
+                        )
+                except Exception as e:
+                    actions.append(f"claude-settings-model-warning:{e}")
         normalized_preferences = normalize_client_preferences(schedule_payload)
         if normalized_preferences != {
             key: schedule_payload.get(key)
@@ -2380,7 +2645,13 @@ def _personal_schedule_reconcile_summary(reconcile_result: dict) -> tuple[list[s
     return actions, "Personal schedules: " + ", ".join(parts) + "."
 
 
-def manual_sync_update(*, interactive: bool = False, allow_source_pull: bool = True, progress_fn=None) -> dict:
+def manual_sync_update(
+    *,
+    interactive: bool = False,
+    allow_source_pull: bool = True,
+    progress_fn=None,
+    include_clis: bool = True,
+) -> dict:
     src_dir, repo_dir = _resolve_sync_source()
     if src_dir is None or repo_dir is None:
         return {"ok": False, "mode": "sync", "error": "No source repo recorded for this runtime."}
@@ -2444,6 +2715,18 @@ def manual_sync_update(*, interactive: bool = False, allow_source_pull: bool = T
         except Exception:
             pass  # Non-critical
 
+        # Auto-update external terminal CLIs (Claude Code, Codex). Best-effort:
+        # a failed third-party install never aborts the NEXO sync itself.
+        if include_clis:
+            try:
+                _emit_progress(progress_fn, "Checking external CLI updates...")
+                cli_results = _update_external_clis(progress_fn=progress_fn)
+                sync_result["external_clis"] = cli_results
+            except Exception as e:
+                sync_result.setdefault("warnings", []).append(
+                    f"external CLI update skipped: {e}"
+                )
+
         _emit_progress(progress_fn, "Runtime update completed.")
     except Exception as e:
         _emit_progress(progress_fn, "Update failed; restoring previous runtime state...")

package/src/cli.py

@@ -823,6 +823,7 @@ def _update(args):
 
     dest = NEXO_HOME
     src_dir, repo_dir = _resolve_sync_source()
+    include_clis = not getattr(args, "no_clis", False)
 
     if src_dir is None or repo_dir is None:
         try:
@@ -835,7 +836,7 @@ def _update(args):
             )
             return 1
 
-        result = handle_update(progress_fn=progress)
+        result = handle_update(progress_fn=progress, include_clis=include_clis)
         runtime_power = _load_runtime_power_support()
         public_contribution = _load_public_contribution_support()
         choice = runtime_power["ensure_power_policy_choice"](interactive=interactive, reason="update")
@@ -873,7 +874,12 @@ def _update(args):
                 print(f"Contributor mode: {contrib_choice.get('message')}")
         return 0 if "UPDATE SUCCESSFUL" in result or "Already up to date" in result else 1
 
-    result = manual_sync_update(interactive=interactive, allow_source_pull=True, progress_fn=progress)
+    result = manual_sync_update(
+        interactive=interactive,
+        allow_source_pull=True,
+        progress_fn=progress,
+        include_clis=include_clis,
+    )
     runtime_power = _load_runtime_power_support()
     public_contribution = _load_public_contribution_support()
     choice = runtime_power["ensure_power_policy_choice"](interactive=interactive, reason="update")
@@ -2015,6 +2021,12 @@ def main():
     # -- update --
     update_parser = sub.add_parser("update", help="Update installed runtime")
     update_parser.add_argument("--json", action="store_true", help="JSON output")
+    update_parser.add_argument(
+        "--no-clis",
+        dest="no_clis",
+        action="store_true",
+        help="Skip auto-updating external terminal CLIs (Claude Code, Codex)",
+    )
 
     # -- recover --
     recover_parser = sub.add_parser(

package/src/client_sync.py

@@ -802,6 +802,70 @@ def _sync_claude_code_settings(path: Path, server_config: dict) -> dict:
     }
 
 
+def sync_claude_code_model(
+    model: str,
+    *,
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    """Propagate the NEXO-recommended ``model`` into ``~/.claude/settings.json``.
+
+    Claude Code actually reads the default model from ``settings.json``, not
+    from NEXO's internal ``client_runtime_profiles``. When a NEXO update
+    migrates a user's recommended default (e.g. Opus 4.6 → 4.7) the internal
+    profile changes but Claude Code keeps booting on the old model until this
+    file is rewritten.
+
+    Intentionally conservative — do NOT seed a field the user never had:
+      - ``settings.json`` missing              → skip.
+      - ``settings.json`` exists but has no
+        top-level ``"model"`` key              → skip.
+      - Current value already equals ``model`` → skip (no write).
+      - JSON read/write error                  → ``ok=False``, skip.
+      - Otherwise replace the value.
+
+    Returns a small result dict: ``{ok, action, path, reason?, previous_model?, new_model?}``.
+    ``action`` is ``"updated"`` only when the file was actually rewritten.
+    """
+    result: dict = {"ok": True, "action": "skipped", "path": ""}
+    if not model:
+        result["reason"] = "empty model"
+        return result
+    home_path = Path(user_home).expanduser() if user_home else None
+    path = _claude_code_settings_path(home_path)
+    result["path"] = str(path)
+    if not path.is_file():
+        result["reason"] = "settings.json missing"
+        return result
+    try:
+        raw = path.read_text()
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception as e:
+        result["ok"] = False
+        result["reason"] = f"read failed: {e}"
+        return result
+    if not isinstance(payload, dict):
+        result["reason"] = "settings.json is not a JSON object"
+        return result
+    if "model" not in payload:
+        result["reason"] = "no model field in settings.json"
+        return result
+    current = payload.get("model")
+    if current == model:
+        result["reason"] = "already matches"
+        return result
+    payload["model"] = model
+    try:
+        _write_json_object(path, payload)
+    except Exception as e:
+        result["ok"] = False
+        result["reason"] = f"write failed: {e}"
+        return result
+    result["action"] = "updated"
+    result["previous_model"] = current
+    result["new_model"] = model
+    return result
+
+
 def sync_claude_code(
     *,
     nexo_home: str | os.PathLike[str] | None = None,

package/src/plugins/update.py

@@ -961,7 +961,7 @@ def _reload_launch_agents_after_bump() -> dict:
     return result
 
 
-def _handle_packaged_update(progress_fn=None) -> str:
+def _handle_packaged_update(progress_fn=None, *, include_clis: bool = True) -> str:
     """Update a packaged (npm) install — no git repo available."""
     old_version = _read_version()
 
@@ -1078,6 +1078,19 @@ def _handle_packaged_update(progress_fn=None) -> str:
     except Exception:
         pass  # Non-critical
 
+    # Auto-update external terminal CLIs (Claude Code, Codex). Best-effort;
+    # a third-party install failure here never rolls the update back.
+    external_cli_lines: list[str] = []
+    if include_clis:
+        try:
+            from auto_update import _update_external_clis, _format_external_clis_results
+            _emit_progress(progress_fn, "Checking external CLI updates...")
+            external_cli_lines = _format_external_clis_results(
+                _update_external_clis(progress_fn=progress_fn)
+            )
+        except Exception:
+            pass  # Non-critical
+
     client_sync_warning = None
     _emit_progress(progress_fn, "Refreshing shared client configs...")
     clients_ok, client_sync_error = _sync_packaged_clients()
@@ -1144,6 +1157,7 @@ def _handle_packaged_update(progress_fn=None) -> str:
     if retired_runtime_files:
         lines.append(f"  Cleanup: removed {len(retired_runtime_files)} retired runtime file(s)")
     lines.extend(_format_dep_results(dep_results))
+    lines.extend(external_cli_lines)
     if not client_sync_warning:
         lines.append("  Clients: configured client targets synced")
     else:
@@ -1162,7 +1176,13 @@ def _handle_packaged_update(progress_fn=None) -> str:
     return "\n".join(lines)
 
 
-def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None) -> str:
+def handle_update(
+    remote: str = "origin",
+    branch: str = "main",
+    progress_fn=None,
+    *,
+    include_clis: bool = True,
+) -> str:
     """Pull latest NEXO code, backup databases, run migrations, and verify.
 
     Supports both git checkouts and packaged (npm) installs.
@@ -1179,10 +1199,13 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
     Args:
         remote: Git remote name (default: origin)
         branch: Git branch to pull (default: main)
+        include_clis: When True (default), auto-update external terminal CLIs
+            (Claude Code, Codex). Pass False (``nexo update --no-clis``) to
+            keep the third-party CLIs at their current version.
     """
     # Packaged install — no git repo
     if not _is_git_repo():
-        return _handle_packaged_update(progress_fn=progress_fn)
+        return _handle_packaged_update(progress_fn=progress_fn, include_clis=include_clis)
 
     steps_done = []
     old_commit = None
@@ -1302,6 +1325,23 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
         except Exception:
             pass  # Non-critical
 
+        # Step 10b: Update external terminal CLIs (Claude Code, Codex). Runs
+        # after migrations and before the verify-style post-steps so a stale
+        # CLI never hides bug fixes shipped with the new NEXO release. Failures
+        # here never abort the git update — the rollback only covers NEXO itself.
+        external_cli_lines: list[str] = []
+        if include_clis:
+            try:
+                from auto_update import _update_external_clis, _format_external_clis_results
+                _emit_progress(progress_fn, "Checking external CLI updates...")
+                external_cli_lines = _format_external_clis_results(
+                    _update_external_clis(progress_fn=progress_fn)
+                )
+                if external_cli_lines:
+                    steps_done.append("external-clis")
+            except Exception:
+                pass  # Non-critical
+
         # Step 11: Sync shared client configs
         try:
             _emit_progress(progress_fn, "Refreshing shared client configs...")
@@ -1345,8 +1385,9 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
         dep_summary_lines = _format_dep_results(dep_results)
         if pull_out == "Already up to date.":
             msg = f"Already up to date (v{old_version}). No changes pulled."
-            if dep_summary_lines:
-                msg += "\n" + "\n".join(dep_summary_lines)
+            trailing = [*dep_summary_lines, *external_cli_lines]
+            if trailing:
+                msg += "\n" + "\n".join(trailing)
             return msg
 
         lines = ["UPDATE SUCCESSFUL"]
@@ -1367,6 +1408,7 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
         if retired_runtime_files:
             lines.append(f"  Cleanup: removed {len(retired_runtime_files)} retired runtime file(s)")
         lines.extend(dep_summary_lines)
+        lines.extend(external_cli_lines)
         if "client-sync" in steps_done:
             lines.append("  Clients: configured client targets synced")
         lines.append("")