nexo-brain 5.3.5 → 5.3.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.5",
+  "version": "5.3.6",
   "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.6` hardens the Claude Code bootstrap path and related runtime hygiene: managed client sync now writes the NEXO MCP server where current Claude Code actually reads it (`~/.claude.json`), script classification is stricter about core-vs-personal runtime artifacts, schedule status distinguishes genuinely running jobs from broken ones, and retroactive learnings stop opening keyword-only false positives outside their declared `applies_to` scope. Version `5.3.5` already keeps CLI version visibility honest right after `nexo update`: if the cached npm version lags behind the runtime you just installed, `nexo` / `nexo chat` now clamp `Latest` to the installed version and refresh the cache instead of showing a stale older release. Version `5.3.4` already cleaned up legacy core alias leakage and added the version-status banner. Version `5.3.3` closed the remaining packaged-runtime doctor mismatch: the built-in hourly backup helper is now inventoried as a core LaunchAgent, so clean installs no longer get a false unknown-LaunchAgent warning. Version `5.3.2` already hardened the runtime boundary by persisting which runtime scripts/hooks are core product artifacts, keeping `nexo scripts` from mixing those into the personal bucket, and migrating the legacy Claude Code heartbeat wrappers into managed core hooks.
 
 Version `5.3.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.6",
   "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/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/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/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)