nexo-brain 7.1.4 → 7.1.7

package/.claude-plugin/plugin.json

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

@@ -18,16 +18,16 @@
 
 [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 `7.1.4` is the current packaged-runtime line. It hardens the real packaged update path after live rollout: packaged Desktop-managed installs now finalize the runtime layout before running import verification, so root shim files are back in place before the health-check runs. The companion NEXO Desktop client (v0.22.4, closed-source distributed separately) embeds the same coordinated hotfix line for guided bootstrap, repair, and update flow.
+Version `7.1.7` is the current packaged-runtime line. It hardens operator-facing email automation language: `email-monitor` now carries the calibrated operator language through its prompt contract and localizes direct `needs_interactive` escalation emails, so Spanish operators stop receiving fallback English monitor mail. No coordinated Desktop release was needed for this patch; the fix lives in Brain.
 
 Previously in `7.0.1`: hotfix over v7.0.0 (db._core.DB_PATH was only caller still hardcoded to legacy ~/.nexo/data/nexo.db; every shared-DB command silently returned empty results post-migration). Previously in `7.0.0`: **BREAKING — Plan Consolidado fase F0.6**: physical separation of the runtime tree into `~/.nexo/{core,personal,runtime}/`. The flat layout (`~/.nexo/scripts/`, `brain/`, `data/`, `operations/`, ...) is gone. Operators on v6.x are auto-migrated on first `nexo update`; fresh installs land directly in the new tree. New `paths.py` helpers are transition-aware.
 
 Previously in `6.5.0`: Plan Consolidado fase F0.2: operators can now `nexo scripts enable|disable|status <name>` any personal automation. The cron wrapper honours the flag at every tick (`exit 0` with `summary='[disabled]'` while the LaunchAgent stays loaded). The companion NEXO Desktop client (a closed-source product, distributed separately) wires the same toggle into its Automatizaciones panel. See [CHANGELOG](CHANGELOG.md) for the full diff.
 
-> **About NEXO Desktop.** NEXO Desktop is a separate closed-source companion app distributed at [systeam.es/nexo-desktop](https://systeam.es/nexo-desktop) — its source does not live in this repo. When release notes mention Desktop they describe a coordinated client release that consumes the Brain's CLI / MCP contract; the Brain itself is fully usable on its own (terminal, Codex, Claude Code, or any MCP client). If you want the product edition rather than the open-source Brain alone, contact `info@wazion.com` and ask about NEXO Desktop.
+> **About NEXO Desktop.** NEXO Desktop is a separate closed-source companion app distributed at [nexo-desktop.com](https://nexo-desktop.com/) — its source does not live in this repo. When release notes mention Desktop they describe a coordinated client release that consumes the Brain's CLI / MCP contract; the Brain itself is fully usable on its own (terminal, Codex, Claude Code, or any MCP client). If you want the product edition rather than the open-source Brain alone, contact `info@wazion.com` and ask about NEXO Desktop.
 
 
-Previously in `6.4.0`: Plan Consolidado fase F1 — multi-tenant email accounts (`email_accounts` table, `nexo email setup` interactive wizard, `nexo email add --password-stdin --json` for machine consumers, idempotent migrator from legacy `~/.nexo/nexo-email/config.json`).
+Previously in `6.4.0`: Plan Consolidado fase F1 — multi-tenant email accounts (`email_accounts` table, `nexo email setup` interactive wizard, `nexo email add --password-stdin --json` for machine consumers, idempotent migrator from legacy `~/.nexo/nexo-email/config.json`). On post-F0.6 installs that legacy-looking path is only a compatibility alias/shim into `~/.nexo/runtime/nexo-email/config.json`; it should never be treated as a second source of truth.
 
 Previously in `6.3.1`: privacy hotfix over v6.3.0. The nightly auditor caught that `src/presets/entities_universal.json` in v6.3.0 shipped operator-specific `vhost_mapping` entries (private IPs, hostnames, tenant names). v6.3.1 pulls those out into `src/presets/entities_local.sample.json` (template) + `.gitignore`'d `~/.nexo/brain/presets/entities_local.json` (operator copy), and the installer drops the sample at `nexo init`. No behaviour change on the Guardian side.
 

package/bin/postinstall.js

@@ -32,9 +32,9 @@ if (fs.existsSync(VERSION_FILE)) {
   // Run the main installer in --yes mode (non-interactive)
   // It will detect the existing version and do migration only
   // Let errors propagate so npm reports the failure correctly
-  const { execSync } = require("child_process");
+  const { execFileSync } = require("child_process");
   try {
-    execSync(`node ${path.join(__dirname, "nexo-brain.js")} --yes`, {
+    execFileSync(process.execPath, [path.join(__dirname, "nexo-brain.js"), "--yes"], {
       stdio: "inherit",
       env: { ...process.env, NEXO_POSTINSTALL: "1", NEXO_HOME: NEXO_HOME }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.1.4",
+  "version": "7.1.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/agent_runner.py

@@ -30,6 +30,7 @@ from client_preferences import (
     resolve_client_runtime_profile,
     resolve_terminal_client,
 )
+from claude_cli import resolve_claude_cli as _shared_resolve_claude_cli
 from core_prompts import render_core_prompt
 
 
@@ -359,25 +360,7 @@ def _record_automation_run(
 
 
 def _resolve_claude_cli() -> str:
-    saved = paths.config_dir() / "claude-cli-path"
-    if saved.exists():
-        candidate = saved.read_text().strip()
-        if candidate and Path(candidate).exists():
-            return candidate
-    env_path = os.environ.get("CLAUDE_BIN", "").strip()
-    if env_path and Path(env_path).exists():
-        return env_path
-    discovered = shutil.which("claude")
-    if discovered:
-        return discovered
-    for candidate in (
-        Path.home() / ".local" / "bin" / "claude",
-        Path.home() / ".npm-global" / "bin" / "claude",
-        Path("/usr/local/bin/claude"),
-    ):
-        if candidate.exists():
-            return str(candidate)
-    return ""
+    return _shared_resolve_claude_cli()
 
 
 def _resolve_codex_cli() -> str:
@@ -781,18 +764,7 @@ def _build_codex_prompt(
     append_system_prompt: str = "",
     allowed_tools: str = "",
 ) -> str:
-    protocol_contract = (
-        "NEXO PROTOCOL (MANDATORY):\n"
-        "- Before non-trivial analyze/edit/execute/delegate work, call `nexo_task_open(...)`. "
-        "If that tool is unavailable, call `nexo_guard_check(...)` and `nexo_cortex_check(...)` first.\n"
-        "- For long multi-step or cross-session work, call `nexo_workflow_open(...)` and keep it updated with "
-        "`nexo_workflow_update(...)` so resume/replay use durable state instead of guesswork.\n"
-        "- Before diagnosing NEXO, explicitly fix the plane first: `product_public`, `runtime_personal`, `installation_live`, `database_real`, or `cooperator`. "
-        "Do not mix planes inside the same diagnosis.\n"
-        "- If a target file has conditioned learnings or blocking guard rules, review them before any read/edit/delete step, and acknowledge guard before any edit/delete step.\n"
-        "- Do not claim done without explicit verification evidence. Close with `nexo_task_close(...)`; if unavailable, capture the change log and state the evidence explicitly.\n"
-        "- When a correction changes the canonical rule, capture or supersede the learning instead of leaving contradictory active rules behind."
-    )
+    protocol_contract = render_core_prompt("codex-protocol-contract")
     instructions: list[str] = []
     instructions.append(protocol_contract)
     if append_system_prompt:
@@ -1217,7 +1189,7 @@ def probe_automation_backend(
         }
     try:
         result = run_automation_prompt(
-            "Reply exactly OK.",
+            render_core_prompt("automation-backend-probe"),
             backend=selected_backend,
             cwd=cwd,
             timeout=timeout,

package/src/auto_update.py

@@ -2229,6 +2229,7 @@ def _f06_legacy_shim_map() -> list[tuple[str, Path]]:
         ("data", NEXO_HOME / "runtime" / "data"),
         ("logs", NEXO_HOME / "runtime" / "logs"),
         ("operations", NEXO_HOME / "runtime" / "operations"),
+        ("state", NEXO_HOME / "runtime" / "state"),
         ("backups", NEXO_HOME / "runtime" / "backups"),
         ("memory", NEXO_HOME / "runtime" / "memory"),
         ("coordination", NEXO_HOME / "runtime" / "coordination"),
@@ -2236,6 +2237,14 @@ def _f06_legacy_shim_map() -> list[tuple[str, Path]]:
         ("nexo-email", NEXO_HOME / "runtime" / "nexo-email"),
         ("snapshots", NEXO_HOME / "runtime" / "snapshots"),
         ("crons", NEXO_HOME / "runtime" / "crons"),
+        ("workdir", paths.personal_lib_dir() / "workdir"),
+        ("working", paths.personal_lib_dir() / "working"),
+    ]
+
+
+def _f06_legacy_file_shim_map() -> list[tuple[str, Path]]:
+    return [
+        ("CLAUDE.md.generated", paths.personal_lib_dir() / "generated" / "CLAUDE.md.generated"),
     ]
 
 
@@ -2270,6 +2279,7 @@ def _f06_live_legacy_paths() -> list[Path]:
             "brain",
             "data",
             "operations",
+            "state",
             "logs",
             "backups",
             "memory",
@@ -2287,6 +2297,8 @@ def _f06_live_legacy_paths() -> list[Path]:
             "db",
             "dashboard",
             "skills-core",
+            "workdir",
+            "working",
         )
     ]
     present = [p for p in legacy_anchors if p.exists() and not p.is_symlink()]
@@ -2297,6 +2309,10 @@ def _f06_live_legacy_paths() -> list[Path]:
         candidate = NEXO_HOME / legacy_name
         if candidate.exists() and not candidate.is_symlink():
             live_files.append(candidate)
+    for legacy_name, _canonical in _f06_legacy_file_shim_map():
+        candidate = NEXO_HOME / legacy_name
+        if candidate.exists() and not candidate.is_symlink():
+            live_files.append(candidate)
     return live_files
 
 
@@ -2554,6 +2570,51 @@ def _ensure_f06_legacy_shims() -> None:
         except Exception as exc:
             _log(f"[F0.6 shim] file symlink create failed for {legacy_name}: {exc}")
 
+    for legacy_name, canonical in _f06_legacy_file_shim_map():
+        legacy = NEXO_HOME / legacy_name
+        canonical.parent.mkdir(parents=True, exist_ok=True)
+
+        if legacy.is_symlink():
+            try:
+                if legacy.resolve(strict=False) == canonical.resolve(strict=False):
+                    continue
+            except Exception:
+                pass
+            try:
+                legacy.unlink()
+            except Exception as exc:
+                _log(f"[F0.6 shim] could not replace misc file symlink {legacy_name}: {exc}")
+                continue
+
+        if legacy.is_file():
+            if canonical.exists():
+                if _same_file(legacy, canonical):
+                    try:
+                        legacy.unlink()
+                    except Exception:
+                        pass
+                else:
+                    backup_target = _conflict_dir() / "legacy-files"
+                    backup_target.mkdir(parents=True, exist_ok=True)
+                    shutil.move(str(legacy), str(backup_target / legacy.name))
+            else:
+                try:
+                    shutil.move(str(legacy), str(canonical))
+                except Exception as exc:
+                    _log(f"[F0.6 shim] move failed for misc flat file {legacy_name}: {exc}")
+                    continue
+        elif legacy.exists():
+            _log(f"[F0.6 shim] legacy misc flat path {legacy_name} is not a file; skipped")
+            continue
+
+        if not canonical.exists():
+            continue
+        try:
+            relative = os.path.relpath(str(canonical), str(legacy.parent))
+            legacy.symlink_to(relative)
+        except Exception as exc:
+            _log(f"[F0.6 shim] misc file symlink create failed for {legacy_name}: {exc}")
+
     marker = NEXO_HOME / ".structure-version"
     try:
         marker.write_text("F0.6\n", encoding="utf-8")
@@ -2613,6 +2674,52 @@ def _cleanup_f06_root_residue() -> None:
             _log(f"[F0.6] residue cleanup skipped for {target}: {exc}")
 
 
+def _heal_misplaced_personal_watchdog_runtime_files() -> list[str]:
+    """Move/remove watchdog runtime artifacts that ended up in personal/scripts.
+
+    These files are runtime state for the core watchdog and must live under
+    ``core/scripts``. Older migrations or manual copies could leave stale
+    duplicates under ``personal/scripts``; that pollutes the personal surface
+    and makes clean installs look dirtier than they are.
+    """
+    actions: list[str] = []
+    personal_scripts = paths.personal_scripts_dir()
+    core_scripts = paths.core_scripts_dir()
+    try:
+        core_scripts.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        return actions
+
+    for name in sorted(_CORE_SCRIPT_RUNTIME_FILES):
+        personal = personal_scripts / name
+        if not personal.exists():
+            continue
+        core = core_scripts / name
+        try:
+            if not core.exists():
+                shutil.move(str(personal), str(core))
+                actions.append(f"watchdog-runtime-file-moved:{name}")
+                continue
+            if name == ".watchdog-nexo-repair.lock":
+                personal.unlink(missing_ok=True)
+                actions.append(f"watchdog-runtime-file-pruned:{name}")
+                continue
+            try:
+                personal_mtime = personal.stat().st_mtime
+                core_mtime = core.stat().st_mtime
+            except OSError:
+                personal_mtime = core_mtime = 0
+            if personal_mtime > core_mtime:
+                shutil.move(str(personal), str(core))
+                actions.append(f"watchdog-runtime-file-promoted:{name}")
+            else:
+                personal.unlink(missing_ok=True)
+                actions.append(f"watchdog-runtime-file-pruned:{name}")
+        except Exception as exc:
+            actions.append(f"watchdog-runtime-file-warning:{name}:{exc.__class__.__name__}")
+    return actions
+
+
 def _maybe_migrate_to_f06_layout() -> None:
     """Plan F0.6 — one-shot physical layout migration. Idempotent.
 
@@ -2674,8 +2781,9 @@ def _maybe_migrate_to_f06_layout() -> None:
         for sub in ("core/scripts", "core-dev/scripts", "personal/scripts",
                     "core/db", "core/cognitive", "core/doctor", "core/dashboard", "core/skills",
                     "personal/brain", "personal/skills", "personal/config",
+                    "personal/lib", "personal/lib/generated",
                     "core/plugins", "core/hooks", "core/rules",
-                    "runtime/data", "runtime/logs", "runtime/operations",
+                    "runtime/data", "runtime/logs", "runtime/operations", "runtime/state",
                     "runtime/backups", "runtime/memory",
                     "runtime/coordination", "runtime/exports",
                     "runtime/nexo-email",
@@ -2744,6 +2852,7 @@ def _maybe_migrate_to_f06_layout() -> None:
             ("data", NEXO_HOME / "runtime" / "data"),
             ("logs", NEXO_HOME / "runtime" / "logs"),
             ("operations", NEXO_HOME / "runtime" / "operations"),
+            ("state", NEXO_HOME / "runtime" / "state"),
             ("backups", NEXO_HOME / "runtime" / "backups"),
             ("memory", NEXO_HOME / "runtime" / "memory"),
             ("cognitive", paths.core_cognitive_dir(allow_legacy_fallback=False)),
@@ -2757,6 +2866,8 @@ def _maybe_migrate_to_f06_layout() -> None:
             ("plugins", NEXO_HOME / "core" / "plugins"),
             ("hooks", NEXO_HOME / "core" / "hooks"),
             ("rules", NEXO_HOME / "core" / "rules"),
+            ("workdir", paths.personal_lib_dir() / "workdir"),
+            ("working", paths.personal_lib_dir() / "working"),
         ]
         for legacy_name, new_dir in TREE_MAP:
             legacy = NEXO_HOME / legacy_name
@@ -4419,6 +4530,14 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
     except Exception as exc:
         actions.append(f"deep-sleep-heal-warning:{exc.__class__.__name__}")
 
+    try:
+        _emit_progress(progress_fn, "Cleaning misplaced watchdog runtime files...")
+        misplaced_actions = _heal_misplaced_personal_watchdog_runtime_files()
+        for action in misplaced_actions:
+            actions.append(action)
+    except Exception as exc:
+        actions.append(f"watchdog-runtime-file-warning:{exc.__class__.__name__}")
+
     # Recover the user's legacy reasoning_effort preference into the new
     # default_resonance knob. v5.10.0 left this gap — users who had
     # `reasoning_effort="max"` in schedule.json silently degraded to

package/src/automation_controls.py

@@ -732,11 +732,12 @@ def get_operator_profile() -> dict[str, Any]:
     operator_accounts: list[dict] = []
 
     try:
+        from calibration_runtime import load_runtime_calibration
         from paths import brain_dir
 
         cal_path = brain_dir() / "calibration.json"
         if cal_path.exists():
-            payload = json.loads(cal_path.read_text())
+            payload = load_runtime_calibration(cal_path)
             user = payload.get("user") if isinstance(payload.get("user"), dict) else {}
             operator_name = (
                 str(user.get("name") or "").strip()

package/src/autonomy_mandate.py

@@ -33,9 +33,12 @@ from datetime import date, datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from core_prompts import render_core_prompt
+
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 STATE_PATH = NEXO_HOME / "runtime" / "data" / "autonomy_mandate.json"
+CLASSIFIER_QUESTION = render_core_prompt("autonomy-mandate-question")
 
 # Marker list per NF-DS-45569A27. Case-insensitive substring match.
 MARKERS = (
@@ -48,6 +51,7 @@ MARKERS = (
     "llevo 3 veces",
     "lo quiero ya",
 )
+_SEMANTIC_MARKER = "semantic-autonomy-mandate"
 
 # Default mandate TTL. Longer than a normal working session but short enough
 # that a stale state does not block followups weeks later.
@@ -93,13 +97,23 @@ class MandateState:
         }
 
 
-def _detect_marker(text: str) -> Optional[str]:
+def _detect_marker(text: str, *, classifier=None) -> Optional[str]:
     if not text:
         return None
     lowered = text.lower()
     for marker in MARKERS:
         if marker in lowered:
             return marker
+    if classifier is None:
+        try:
+            from enforcement_classifier import classify as classifier  # type: ignore
+        except Exception:
+            return None
+    try:
+        if bool(classifier(question=CLASSIFIER_QUESTION, context=text.strip()[:1200])):
+            return _SEMANTIC_MARKER
+    except Exception:
+        return None
     return None
 
 
@@ -163,6 +177,7 @@ def maybe_ingest_from_text(
     session_id: str,
     source: str = "auto",
     ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    classifier=None,
 ) -> Optional[MandateState]:
     """Scan free-form text for a mandate marker and persist if found.
 
@@ -170,7 +185,7 @@ def maybe_ingest_from_text(
     mandate can be set transparently, without a separate explicit tool.
     Returns the new state when a marker was detected, otherwise None.
     """
-    marker = _detect_marker(text or "")
+    marker = _detect_marker(text or "", classifier=classifier)
     if not marker:
         return None
     return set_mandate(

package/src/bootstrap_docs.py

@@ -7,6 +7,7 @@ import os
 import re
 from pathlib import Path
 
+from calibration_runtime import load_runtime_calibration
 from client_preferences import (
     BACKEND_NONE,
     CLIENT_CLAUDE_CODE,
@@ -82,7 +83,7 @@ def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
     env_name = os.environ.get("NEXO_NAME", "").strip()
     if env_name:
         return env_name
-    calibration = _read_json_file(nexo_home / "personal" / "brain" / "calibration.json")
+    calibration = load_runtime_calibration(nexo_home / "personal" / "brain" / "calibration.json")
     user_payload = calibration.get("user")
     if isinstance(user_payload, dict):
         candidate = str(user_payload.get("assistant_name", "")).strip()

package/src/calibration_runtime.py

@@ -0,0 +1,46 @@
+"""Runtime-safe calibration view.
+
+Reads the full on-disk ``calibration.json`` but returns only the subset
+that runtime consumers actually need for identity, preferences, and
+profile decisions. Heavy historical arrays stay on disk untouched.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+
+from paths import brain_dir
+
+_TOP_LEVEL_RUNTIME_KEYS = {
+    "user",
+    "preferences",
+    "meta",
+    "assistant_name",
+    "operator_name",
+    "identity",
+    "language",
+    "lang",
+    "user_name",
+    "name",
+    "version",
+    "created",
+}
+
+
+def load_runtime_calibration(path: Path | None = None) -> dict:
+    target = path or (brain_dir() / "calibration.json")
+    if not target.is_file():
+        return {}
+    try:
+        payload = json.loads(target.read_text())
+    except Exception:
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    view: dict = {}
+    for key in _TOP_LEVEL_RUNTIME_KEYS:
+        if key in payload:
+            view[key] = copy.deepcopy(payload[key])
+    return view

package/src/claude_cli.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+"""Shared Claude CLI resolution helpers.
+
+Desktop-managed installs must never silently escape to a global `claude`
+binary from PATH. This helper centralises that contract so automation
+surfaces can share the same resolution policy.
+"""
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+
+def _user_home(user_home: Path | None = None) -> Path:
+    if user_home is not None:
+        return Path(user_home).expanduser()
+    return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
+
+
+def _desktop_install_markers(home: Path, *, include_global_markers: bool) -> list[Path]:
+    markers: list[Path] = [
+        home / "Applications" / "NEXO Desktop.app",
+        home / "Library" / "Application Support" / "NEXO Desktop",
+        home / ".local" / "share" / "NEXO Desktop",
+        home / ".config" / "NEXO Desktop",
+    ]
+    # Treat the global app bundle path as a stable install marker even when
+    # tests run on non-macOS CI hosts. Explicit homes still suppress it.
+    if include_global_markers:
+        markers.insert(0, Path("/Applications/NEXO Desktop.app"))
+    if os.name == "nt":
+        local = Path(os.environ.get("LOCALAPPDATA", str(home / "AppData" / "Local")))
+        roaming = Path(os.environ.get("APPDATA", str(home / "AppData" / "Roaming")))
+        markers.extend(
+            [
+                local / "Programs" / "NEXO Desktop",
+                roaming / "NEXO Desktop",
+            ]
+        )
+    return markers
+
+
+def desktop_product_requested(user_home: Path | None = None) -> bool:
+    if str(os.environ.get("NEXO_DESKTOP_MANAGED", "")).strip() == "1":
+        return True
+    explicit_home = user_home is not None
+    home = _user_home(user_home)
+    mode_paths = (
+        home / ".nexo" / "personal" / "config" / "product-mode.json",
+        home / ".nexo" / "config" / "product-mode.json",
+    )
+    for mode_path in mode_paths:
+        try:
+            payload = json.loads(mode_path.read_text())
+        except Exception:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("desktop_managed") is True:
+            return True
+        if str(payload.get("product_mode") or "").strip().lower() == "desktop_closed_product":
+            return True
+    for marker in _desktop_install_markers(home, include_global_markers=not explicit_home):
+        try:
+            if marker.exists():
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def managed_claude_prefix(user_home: Path | None = None) -> Path:
+    explicit = str(os.environ.get("NEXO_CLAUDE_PREFIX", "")).strip()
+    if explicit:
+        return Path(explicit).expanduser()
+    return _user_home(user_home) / ".nexo" / "runtime" / "bootstrap" / "npm-global"
+
+
+def _path_within(candidate: Path, parent: Path) -> bool:
+    try:
+        candidate.expanduser().resolve(strict=False).relative_to(parent.expanduser().resolve(strict=False))
+        return True
+    except Exception:
+        return False
+
+
+def managed_claude_binary(user_home: Path | None = None) -> str:
+    home = _user_home(user_home)
+    managed_prefix = managed_claude_prefix(home)
+    persisted_paths = (
+        home / ".nexo" / "config" / "claude-cli-path",
+        home / ".nexo" / "personal" / "config" / "claude-cli-path",
+    )
+    candidates: list[Path] = []
+    for persisted in persisted_paths:
+        try:
+            raw = persisted.read_text(encoding="utf-8").strip()
+        except Exception:
+            raw = ""
+        if raw:
+            candidates.append(Path(raw))
+    env_path = str(os.environ.get("CLAUDE_BIN", "")).strip()
+    if env_path:
+        candidates.append(Path(env_path))
+    candidates.append(managed_prefix / "bin" / "claude")
+    for candidate in candidates:
+        try:
+            if not candidate.exists():
+                continue
+        except Exception:
+            continue
+        if _path_within(candidate, managed_prefix):
+            return str(candidate)
+    return ""
+
+
+def resolve_claude_cli(user_home: Path | None = None) -> str:
+    home = _user_home(user_home)
+    if desktop_product_requested(home):
+        return managed_claude_binary(home)
+
+    persisted_paths = (
+        home / ".nexo" / "config" / "claude-cli-path",
+        home / ".nexo" / "personal" / "config" / "claude-cli-path",
+    )
+    for persisted in persisted_paths:
+        try:
+            candidate = persisted.read_text(encoding="utf-8").strip()
+        except Exception:
+            candidate = ""
+        if candidate and Path(candidate).exists():
+            return candidate
+
+    env_path = str(os.environ.get("CLAUDE_BIN", "")).strip()
+    if env_path and Path(env_path).exists():
+        return env_path
+
+    discovered = shutil.which("claude")
+    if discovered:
+        return discovered
+
+    for candidate in (
+        home / ".local" / "bin" / "claude",
+        home / ".npm-global" / "bin" / "claude",
+        Path("/usr/local/bin/claude"),
+    ):
+        if candidate.exists():
+            return str(candidate)
+    return ""