nexo-brain 7.9.9 → 7.9.11

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.9",
+  "version": "7.9.11",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,7 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.9.9` is the current packaged-runtime line. Hotfix release over `7.9.8`: after the packaged updater fix, the installer now also repairs installs whose metadata already says the new version but whose active runtime still points to an older `~/.nexo/core/current -> versions/<old>`. Running `nexo-brain --yes` or the postinstall path now recopies the packaged runtime, re-activates `core/current`, and leaves installed users on the real new code instead of a stale snapshot. Coordinated Desktop v0.28.11 bundles the matching quit-path fix.
+Version `7.9.11` is the current packaged-runtime line. Patch release over `7.9.10`: canonical Desktop lifecycle completion now requires both diary evidence and real stop evidence before Brain marks archive/delete/app-exit done, canonical plans add `wait_for_stop`, and Brain exposes the exact stop-wait primitives Desktop uses to avoid leaving duplicate live NEXO sessions behind a reopened conversation. Coordinated Desktop release: v0.28.12.
 
 Previously in `7.9.5`: patch release that fixes canonical diary confirmation for Desktop: Brain resolves the Desktop/Claude session UUID through NEXO SID aliases before checking `session_diary`, so archive/delete/app-exit can confirm diaries written by `nexo_session_diary_write` under the active `nexo-...` SID. Verification: `pytest tests/test_lifecycle_events.py` (28 passing) plus coordinated Desktop v0.28.6 shutdown/archive/delete/app-exit checks.
 

package/bin/nexo-brain.js

@@ -252,6 +252,24 @@ function readRuntimeCalibration(nexoHome = NEXO_HOME) {
   return { path: null, payload: null };
 }
 
+function profilePathCandidates(nexoHome = NEXO_HOME) {
+  return [
+    path.join(nexoHome, "personal", "brain", "profile.json"),
+    path.join(nexoHome, "brain", "profile.json"),
+  ];
+}
+
+function readRuntimeProfile(nexoHome = NEXO_HOME) {
+  for (const filePath of profilePathCandidates(nexoHome)) {
+    if (!fs.existsSync(filePath)) continue;
+    const payload = readJsonFile(filePath);
+    if (payload && typeof payload === "object") {
+      return { path: filePath, payload };
+    }
+  }
+  return { path: null, payload: null };
+}
+
 function nonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
@@ -288,6 +306,55 @@ function hasPartialPlaceholderCalibration(calibration) {
   return isPlaceholderUserName(name) || !nonEmptyString(language);
 }
 
+function firstMeaningfulString(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const clean = value.trim();
+    if (clean) return clean;
+  }
+  return "";
+}
+
+function normalizeLanguageCode(value) {
+  const clean = String(value || "").trim().toLowerCase().replace("_", "-");
+  if (!clean) return "";
+  return clean.split("-")[0];
+}
+
+function resolveExistingIdentityDefaults(nexoHome = NEXO_HOME) {
+  const calibration = readRuntimeCalibration(nexoHome).payload || {};
+  const user = calibration.user && typeof calibration.user === "object" ? calibration.user : {};
+  const profile = readRuntimeProfile(nexoHome).payload || {};
+  const version = readJsonFile(path.join(nexoHome, "version.json")) || {};
+
+  const userName = firstMeaningfulString(
+    user.name,
+    calibration.user_name,
+    profile.user_name,
+    version.user_name,
+  );
+  const language = normalizeLanguageCode(firstMeaningfulString(
+    user.language,
+    calibration.language,
+    profile.language,
+    version.language,
+  ));
+  const operatorName = firstMeaningfulString(
+    user.assistant_name,
+    calibration.assistant_name,
+    calibration.operator_name,
+    profile.assistant_name,
+    profile.operator_name,
+    version.operator_name,
+  );
+
+  return {
+    userName: !isPlaceholderUserName(userName) ? userName : "",
+    language,
+    operatorName: !isReservedAssistantName(operatorName) ? operatorName : "",
+  };
+}
+
 function ensureOnboardingCompletionMarker(nexoHome = NEXO_HOME) {
   const record = readRuntimeCalibration(nexoHome);
   if (!record.path || !isOnboardingComplete(record.payload)) {
@@ -2966,9 +3033,11 @@ async function runSetup() {
     },
   };
 
+  const existingIdentity = resolveExistingIdentityDefaults(NEXO_HOME);
+
   // Detect language from input or use default
-  let lang = "en";
-  let t = i18n.en;
+  let lang = existingIdentity.language || "en";
+  let t = i18n[lang] || i18n.en;
   if (!useDefaults) {
     const langInput = await ask("  What's your preferred language? / ¿En qué idioma prefieres hablar?\n  > ");
     const langLower = langInput.trim().toLowerCase();
@@ -3009,7 +3078,7 @@ async function runSetup() {
   // Step 2: User's name (P2) — v6.0.0 empty input falls through to "Usuario"
   // instead of keeping an empty string. The calibration file always ships
   // with a concrete user.name so downstream tooling does not need guards.
-  let userName = "Usuario";
+  let userName = existingIdentity.userName || "Usuario";
   if (!useDefaults) {
     const nameInput = await ask(t.askUserName);
     const trimmedName = nameInput.trim();
@@ -3021,7 +3090,7 @@ async function runSetup() {
   }
 
   // Step 3: Agent name (P3)
-  let operatorName = DEFAULT_ASSISTANT_NAME;
+  let operatorName = existingIdentity.operatorName || DEFAULT_ASSISTANT_NAME;
   if (!useDefaults) {
     while (true) {
       const name = await ask(t.askAgentName);

package/package.json

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

@@ -792,6 +792,8 @@ def _build_enforcement_system_prompt() -> str:
     map_path = NEXO_HOME / "tool-enforcement-map.json"
     if not map_path.exists():
         for candidate in [
+            # .resolve() handles the $NEXO_HOME symlink -> core/ case.
+            Path(__file__).resolve().parent / "tool-enforcement-map.json",
             Path(__file__).parent / "tool-enforcement-map.json",
             Path(__file__).parent.parent / "tool-enforcement-map.json",
         ]:

package/src/cli.py

@@ -3232,6 +3232,20 @@ def main():
     lwait_p.add_argument("--timeout-ms", type=int, default=45_000)
     lwait_p.add_argument("--poll-ms", type=int, default=500)
 
+    lwait_stop_p = lifecycle_sub.add_parser(
+        "wait-for-stop",
+        help="v7.9.10: wait until the linked NEXO session is no longer active",
+    )
+    lwait_stop_p.add_argument("--event-id", required=True)
+    lwait_stop_p.add_argument("--timeout-ms", type=int, default=10_000)
+    lwait_stop_p.add_argument("--poll-ms", type=int, default=500)
+
+    lstop_sid_p = lifecycle_sub.add_parser(
+        "stop-nexo-session",
+        help="v7.9.10: explicit best-effort stop of a NEXO SID for Desktop lifecycle cleanup",
+    )
+    lstop_sid_p.add_argument("--sid", required=True)
+
     # Fase E.5 — quarantine ops surfaced via Desktop Guardian Proposals panel.
     quarantine_parser = sub.add_parser("quarantine", help="Quarantine proposals (Fase E.5 Desktop UI)")
     quarantine_sub = quarantine_parser.add_subparsers(dest="quarantine_command")
@@ -3533,6 +3547,38 @@ def main():
             if status == "retryable_error":
                 return 2
             return 3
+        if args.lifecycle_command == "wait-for-stop":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_wait_for_stop(
+                event_id=args.event_id,
+                timeout_ms=args.timeout_ms,
+                poll_ms=args.poll_ms,
+            )
+            print(out)
+            try:
+                parsed = _json.loads(out)
+                status = str(parsed.get("status", ""))
+            except Exception:
+                status = ""
+            if status == "ok":
+                return 0
+            if status == "retryable_error":
+                return 2
+            return 3
+        if args.lifecycle_command == "stop-nexo-session":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_stop_nexo_session(
+                sid=args.sid,
+            )
+            print(out)
+            try:
+                parsed = _json.loads(out)
+                status = str(parsed.get("status", ""))
+            except Exception:
+                status = ""
+            if status == "ok":
+                return 0
+            if status == "retryable_error":
+                return 2
+            return 3
         lifecycle_parser.print_help()
         return 1
     elif args.command in ("schema", "identity", "onboard", "scan-profile"):

package/src/doctor/planes.py

@@ -28,6 +28,7 @@ VALID_DIAGNOSTIC_PLANES = {
 }
 
 DOCTOR_COMPATIBLE_PLANES = {"runtime_personal", "installation_live", "database_real"}
+DEFAULT_DOCTOR_PLANE = "runtime_personal"
 
 
 def normalize_diagnostic_plane(plane: str = "") -> str:
@@ -40,15 +41,19 @@ def diagnostic_plane_choices() -> list[str]:
 
 
 def diagnostic_plane_preflight(plane: str = "") -> tuple[str, DoctorCheck | None]:
-    clean_plane = normalize_diagnostic_plane(plane)
+    raw_plane = str(plane or "").strip()
+    if not raw_plane:
+        return DEFAULT_DOCTOR_PLANE, None
+
+    clean_plane = normalize_diagnostic_plane(raw_plane)
     if not clean_plane:
         options = ", ".join(diagnostic_plane_choices())
         return "", DoctorCheck(
-            id="orchestrator.diagnostic_plane_required",
+            id="orchestrator.diagnostic_plane_invalid",
             tier="orchestrator",
             status="critical",
             severity="error",
-            summary="El diagnóstico está bloqueado hasta fijar explícitamente el plano",
+            summary=f"Plano diagnóstico desconocido: {raw_plane}",
             evidence=[
                 f"planes válidos: {options}",
                 "Usa `runtime_personal` para ~/.nexo y hábitos del runtime; `installation_live` para hooks/clientes/instalación; `database_real` para filas y schema reales.",
@@ -58,8 +63,7 @@ def diagnostic_plane_preflight(plane: str = "") -> tuple[str, DoctorCheck | None
                 "Si el problema pertenece a producto público o al co-operador, usa el surface correcto en vez de NEXO Doctor.",
             ],
             escalation_prompt=(
-                "NEXO mezcló planos en diagnósticos anteriores. El doctor no debe correr hasta que se elija "
-                "explícitamente si el problema está en producto público, runtime personal, instalación viva, BD real o co-operador."
+                "El plano elegido no existe. Repite el diagnóstico con un plano válido para evitar mezclar runtime, instalación, BD real o surfaces ajenas al doctor."
             ),
         )
 

package/src/enforcement_engine.py

@@ -321,7 +321,13 @@ def _redact_for_log(text: str, max_len: int = 200) -> str:
 
 
 def _load_map() -> dict | None:
+    # .resolve() is required: at runtime this module is usually imported via
+    # the symlink $NEXO_HOME/enforcement_engine.py -> core/enforcement_engine.py,
+    # so the non-resolved Path(__file__).parent points at NEXO_HOME instead
+    # of the core/ dir where the map actually sits. Keeping the non-resolved
+    # variant too covers in-repo test imports.
     for candidate in [
+        Path(__file__).resolve().parent / MAP_FILENAME,
         Path(__file__).parent / MAP_FILENAME,
         paths.home() / MAP_FILENAME,
         paths.brain_dir() / MAP_FILENAME,

package/src/lifecycle_events.py

@@ -55,6 +55,7 @@ import time
 from typing import Any, Dict, List, Optional
 
 from db import get_db
+from db._core import SESSION_STALE_SECONDS
 import lifecycle_prompts
 
 
@@ -259,6 +260,103 @@ def _session_diary_since(conn, session_id: str, dispatched_at: Optional[str], ac
     return _session_diary_evidence(conn, session_id, dispatched_at, actions_json) is not None
 
 
+def _session_stop_state(conn, session_id: str) -> Dict[str, Any]:
+    """Return whether the lifecycle session can be verified as fully stopped."""
+    raw = str(session_id or "").strip()
+    if not raw:
+        return {
+            "verifiable": False,
+            "session_registered": False,
+            "stop_confirmed": False,
+            "active_session_ids": [],
+        }
+
+    candidate_ids: List[str] = []
+    verifiable = False
+
+    if raw.startswith("nexo-"):
+        candidate_ids.append(raw)
+        verifiable = True
+
+    try:
+        rows = conn.execute(
+            "SELECT sid FROM session_claude_aliases "
+            "WHERE claude_session_id = ? ORDER BY last_seen DESC",
+            (raw,),
+        ).fetchall()
+        alias_ids = [str(row[0]) for row in rows if row and row[0]]
+        if alias_ids:
+            candidate_ids.extend(alias_ids)
+            verifiable = True
+    except Exception:
+        pass
+
+    try:
+        rows = conn.execute(
+            "SELECT sid FROM sessions "
+            "WHERE external_session_id = ? OR claude_session_id = ? OR sid = ? "
+            "ORDER BY last_update_epoch DESC",
+            (raw, raw, raw),
+        ).fetchall()
+        live_ids = [str(row[0]) for row in rows if row and row[0]]
+        if live_ids:
+            candidate_ids.extend(live_ids)
+            verifiable = True
+    except Exception:
+        pass
+
+    deduped_candidates: List[str] = []
+    seen = set()
+    for sid in candidate_ids:
+        if sid and sid not in seen:
+            seen.add(sid)
+            deduped_candidates.append(sid)
+
+    if not verifiable:
+        return {
+            "verifiable": False,
+            "session_registered": False,
+            "stop_confirmed": False,
+            "active_session_ids": [],
+        }
+
+    cutoff = time.time() - float(SESSION_STALE_SECONDS)
+    active_ids: List[str] = []
+    try:
+        if deduped_candidates:
+            placeholders = ",".join("?" for _ in deduped_candidates)
+            rows = conn.execute(
+                "SELECT sid FROM sessions "
+                f"WHERE last_update_epoch > ? AND (sid IN ({placeholders}) OR external_session_id = ? OR claude_session_id = ?) "
+                "ORDER BY last_update_epoch DESC",
+                (cutoff, *deduped_candidates, raw, raw),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT sid FROM sessions "
+                "WHERE last_update_epoch > ? AND (external_session_id = ? OR claude_session_id = ?) "
+                "ORDER BY last_update_epoch DESC",
+                (cutoff, raw, raw),
+            ).fetchall()
+        active_ids = [str(row[0]) for row in rows if row and row[0]]
+    except Exception:
+        active_ids = []
+
+    deduped_active: List[str] = []
+    seen.clear()
+    for sid in active_ids:
+        if sid and sid not in seen:
+            seen.add(sid)
+            deduped_active.append(sid)
+
+    return {
+        "verifiable": True,
+        "session_registered": True,
+        "stop_confirmed": len(deduped_active) == 0,
+        "active_session_ids": deduped_active,
+    }
+
+
 def record_lifecycle_event(
     event_id: str,
     action: str,
@@ -324,17 +422,18 @@ def record_lifecycle_event(
                 "prior_status": status,
             }
 
-        # Case B: canonical was dispatched but never confirmed. Check
-        # whether the live session wrote a diary after dispatch; if so
-        # the intent has already been satisfied by the model and we
-        # must NOT ask Desktop to re-run the plan.
+        # Case B: canonical was dispatched but never confirmed. Only
+        # short-circuit if the session already wrote the diary AND no
+        # linked NEXO session remains active.
         if prior_plan_id and prior_dispatched_at and not prior_done_at:
+            stop_state = _session_stop_state(conn, str(session_id)) if session_id else None
+            stop_confirmed = bool(stop_state and stop_state.get("verifiable") and stop_state.get("stop_confirmed"))
             if session_id and _session_diary_since(
                 conn,
                 str(session_id),
                 str(prior_dispatched_at),
                 str(prior_actions_json or ""),
-            ):
+            ) and stop_confirmed:
                 conn.execute(
                     "UPDATE lifecycle_events "
                     "SET delivery_status = 'already_processed', "
@@ -349,7 +448,7 @@ def record_lifecycle_event(
                     "event_id": event_id,
                     "duplicate": True,
                     "prior_status": status,
-                    "reason": "session_diary-already-written",
+                    "reason": "session_diary-and-stop-already-written",
                 }
             # Re-hand the exact same plan so Desktop can resume / finish
             # any actions it didn't complete before the crash.
@@ -538,11 +637,18 @@ def record_complete_canonical(
         for r in results_list
     )
     diary_evidence = _session_diary_evidence(conn, session_id, dispatched_at, actions_json)
+    stop_state = _session_stop_state(conn, session_id) if session_id else {
+        "verifiable": False,
+        "session_registered": False,
+        "stop_confirmed": True,
+        "active_session_ids": [],
+    }
     diary_required = action in _DIARY_TRIGGERING and bool(session_id)
     session_registered = _session_is_linked_to_nexo(conn, session_id) if diary_required else bool(session_id)
     session_unregistered = diary_required and not session_registered
     diary_missing = diary_required and diary_evidence is None
-    effective = "retryable_error" if (any_failure or diary_missing) else "canonical_done"
+    stop_missing = diary_required and bool(stop_state.get("verifiable")) and not bool(stop_state.get("stop_confirmed"))
+    effective = "retryable_error" if (any_failure or diary_missing or stop_missing) else "canonical_done"
     last_error = None
     if session_unregistered:
         last_error = SESSION_NOT_LINKED_REASON
@@ -550,6 +656,8 @@ def record_complete_canonical(
         last_error = "one-or-more-actions-failed"
     elif diary_missing:
         last_error = "canonical-diary-not-confirmed"
+    elif stop_missing:
+        last_error = "canonical-stop-not-confirmed"
     conn.execute(
         "UPDATE lifecycle_events "
         "SET delivery_status = ?, "
@@ -573,8 +681,11 @@ def record_complete_canonical(
         "failed_actions": any_failure,
         "diary_confirmed": diary_evidence is not None,
         "diary_required": diary_required,
+        "stop_confirmed": not stop_missing,
+        "stop_required": diary_required,
         "session_registered": session_registered,
         "session_diary_id": diary_evidence.get("session_diary_id") if diary_evidence else None,
+        "active_session_ids": list(stop_state.get("active_session_ids") or []),
         "reason": last_error if effective == "retryable_error" else None,
     }
 
@@ -635,6 +746,74 @@ def wait_for_canonical_diary(
         time.sleep(min(poll_s, max(0.0, deadline - time.monotonic())))
 
 
+def wait_for_canonical_stop(
+    event_id: str,
+    timeout_ms: int = 10_000,
+    poll_ms: int = 500,
+) -> Dict[str, Any]:
+    """Poll until the canonical lifecycle session no longer has active linked SIDs."""
+    if not event_id:
+        return {"status": "rejected", "reason": "missing-event-id"}
+
+    timeout_s = max(0.0, float(timeout_ms or 0) / 1000.0)
+    poll_s = max(0.05, float(poll_ms or 500) / 1000.0)
+    deadline = time.monotonic() + timeout_s
+
+    while True:
+        conn = get_db()
+        row = conn.execute(
+            "SELECT session_id, action FROM lifecycle_events WHERE event_id = ?",
+            (str(event_id),),
+        ).fetchone()
+        if row is None:
+            return {"status": "rejected", "reason": "unknown-event-id", "event_id": event_id}
+
+        session_id = str(row[0] or "")
+        action = str(row[1] or "")
+        stop_required = action in _DIARY_TRIGGERING and bool(session_id)
+        if not stop_required:
+            return {
+                "status": "ok",
+                "event_id": event_id,
+                "stop_required": False,
+                "stop_confirmed": True,
+                "session_registered": bool(session_id),
+                "active_session_ids": [],
+            }
+
+        stop_state = _session_stop_state(conn, session_id)
+        if not stop_state.get("verifiable"):
+            return {
+                "status": "retryable_error",
+                "event_id": event_id,
+                "stop_required": True,
+                "stop_confirmed": False,
+                "session_registered": False,
+                "active_session_ids": [],
+                "reason": SESSION_NOT_LINKED_REASON,
+            }
+        if stop_state.get("stop_confirmed"):
+            return {
+                "status": "ok",
+                "event_id": event_id,
+                "stop_required": True,
+                "stop_confirmed": True,
+                "session_registered": True,
+                "active_session_ids": [],
+            }
+        if time.monotonic() >= deadline:
+            return {
+                "status": "retryable_error",
+                "event_id": event_id,
+                "stop_required": True,
+                "stop_confirmed": False,
+                "session_registered": True,
+                "active_session_ids": list(stop_state.get("active_session_ids") or []),
+                "reason": "canonical-stop-not-confirmed",
+            }
+        time.sleep(min(poll_s, max(0.0, deadline - time.monotonic())))
+
+
 def get_lifecycle_event(event_id: str) -> Optional[Dict[str, Any]]:
     if not event_id:
         return None

package/src/lifecycle_prompts.py

@@ -19,7 +19,7 @@ import json
 from typing import Any, Dict, List, Optional
 
 
-PLAN_VERSION = 3
+PLAN_VERSION = 4
 
 
 # Actions that trigger a canonical diary+stop plan. `switch` and
@@ -37,6 +37,7 @@ DEFAULT_RESUME_TIMEOUT_MS = 2_000
 DEFAULT_INJECT_TIMEOUT_MS = 30_000
 DEFAULT_DIARY_WAIT_TIMEOUT_MS = 45_000
 DEFAULT_STOP_TIMEOUT_MS = 3_000
+DEFAULT_STOP_WAIT_TIMEOUT_MS = 10_000
 
 
 def canonical_plan_id(event_id: str, plan_version: int = PLAN_VERSION) -> str:
@@ -150,6 +151,15 @@ def build_canonical_plan(
             evidence="session_diary",
         ),
         _canonical_action("a4", "stop_session", str(session_id), DEFAULT_STOP_TIMEOUT_MS),
+        _canonical_action(
+            "a5",
+            "wait_for_stop",
+            str(session_id),
+            DEFAULT_STOP_WAIT_TIMEOUT_MS,
+            event_id=str(event_id),
+            expected_tool_call="nexo_stop",
+            evidence="session_stop",
+        ),
     ]
     return {
         "canonical_plan_id": canonical_plan_id(event_id, PLAN_VERSION),

package/src/plugins/doctor.py

@@ -22,26 +22,11 @@ def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text", p
     """
     from doctor.orchestrator import run_doctor
     from doctor.formatters import format_report
-    from doctor.planes import diagnostic_plane_choices
 
     if tier not in ("boot", "runtime", "deep", "all"):
         return f"Invalid tier '{tier}'. Use: boot, runtime, deep, all"
     if output not in ("text", "json"):
         return f"Invalid output '{output}'. Use: text, json"
-    if not (plane or "").strip():
-        valid_planes = diagnostic_plane_choices()
-        if output == "json":
-            return (
-                "{"
-                f"\"ok\": false, \"error\": \"Missing required argument: plane\", "
-                "\"missing_argument\": \"plane\", "
-                f"\"valid_planes\": {valid_planes!r}"
-                "}"
-            ).replace("'", '"')
-        return (
-            "Missing required argument: plane. "
-            f"Use one of: {', '.join(valid_planes)}."
-        )
 
     report = run_doctor(tier=tier, fix=fix, plane=plane)
     return format_report(report, fmt=output)

package/src/plugins/lifecycle_events.py

@@ -168,6 +168,48 @@ def handle_nexo_lifecycle_wait_for_diary(
     return json.dumps(ack, ensure_ascii=False)
 
 
+def handle_nexo_lifecycle_wait_for_stop(
+    event_id: str,
+    timeout_ms: int = 10_000,
+    poll_ms: int = 500,
+) -> str:
+    """Wait until a canonical lifecycle event no longer has an active NEXO session."""
+    try:
+        ack = lifecycle_events.wait_for_canonical_stop(
+            event_id=str(event_id or ""),
+            timeout_ms=int(timeout_ms or 0),
+            poll_ms=int(poll_ms or 500),
+        )
+    except Exception as exc:
+        return json.dumps({
+            "status": "retryable_error",
+            "reason": f"{type(exc).__name__}: {exc}",
+            "handler_threw": True,
+        }, ensure_ascii=False)
+    return json.dumps(ack, ensure_ascii=False)
+
+
+def handle_nexo_lifecycle_stop_nexo_session(
+    sid: str,
+) -> str:
+    """Best-effort explicit stop of a NEXO SID for Desktop lifecycle cleanup."""
+    try:
+        from tools_sessions import handle_stop
+
+        message = handle_stop(str(sid or ""))
+        return json.dumps({
+            "status": "ok",
+            "sid": str(sid or ""),
+            "message": message,
+        }, ensure_ascii=False)
+    except Exception as exc:
+        return json.dumps({
+            "status": "retryable_error",
+            "sid": str(sid or ""),
+            "reason": f"{type(exc).__name__}: {exc}",
+        }, ensure_ascii=False)
+
+
 TOOLS = [
     (
         handle_nexo_lifecycle_event,
@@ -189,4 +231,14 @@ TOOLS = [
         "nexo_lifecycle_wait_for_diary",
         "Wait for concrete session_diary evidence for a canonical lifecycle event before Desktop stops the session.",
     ),
+    (
+        handle_nexo_lifecycle_wait_for_stop,
+        "nexo_lifecycle_wait_for_stop",
+        "Wait until the linked NEXO session is no longer active for a canonical lifecycle event.",
+    ),
+    (
+        handle_nexo_lifecycle_stop_nexo_session,
+        "nexo_lifecycle_stop_nexo_session",
+        "Best-effort explicit nexo_stop by SID for Desktop lifecycle cleanup.",
+    ),
 ]