nexo-brain 7.31.1 → 7.31.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.31.1",
+  "version": "7.31.2",
   "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,9 +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 `7.31.1` is the current packaged-runtime line. Patch release over v7.31.0 - headless automations pause and queue when the selected engine is unavailable (credits, rate limits, expired auth) and resume automatically with one operator notice in their language; protocol nudge shaping ships in shadow mode; and the client config push stops writing an invalid `mcp__*` permission rule to Claude Code settings.
+Version `7.31.2` is the current packaged-runtime line. Patch release over v7.31.1 - the session ID becomes a durable identity (sessions survive quiet work periods; physical cleanup at 24h), runtime residents are isolated per generation so two installs can never kill each other's resident, and obsolete residents retire themselves once clients disconnect.
 
-Previously in `7.31.0`: minor release over v7.30.33 - the recommended Claude Code model moves from Opus 4.8 to Fable 5 with max reasoning (`claude-fable-5`) across all four main resonance tiers (the `muy_bajo` tier keeps Haiku for cheap internal classifiers and Codex stays on GPT-5.5), existing installs riding NEXO defaults auto-migrate on update while customized models are respected, and learning housekeeping no longer aborts when the embedding backend is missing.
+Previously in `7.31.1`: patch release over v7.31.0 - headless automations pause and queue when the selected engine is unavailable (credits, rate limits, expired auth) and resume automatically with one operator notice in their language; protocol nudge shaping ships in shadow mode; and the client config push stops writing an invalid `mcp__*` permission rule to Claude Code settings.
 
 Previously in `7.30.33`: patch release over v7.30.32 - personal agent/script status now keeps the newest real run between manual executions and cron history, so a successful manual agent run cannot be hidden behind an older scheduled failure.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.31.1",
+  "version": "7.31.2",
   "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/db/_core.py

@@ -36,10 +36,18 @@ _data_dir = os.path.dirname(DB_PATH)
 os.makedirs(_data_dir, exist_ok=True)
 
 # TTLs in seconds (match session-coord.sh behavior)
-SESSION_STALE_SECONDS = 900    # 15 min (documented TTL)
+SESSION_STALE_SECONDS = 900    # 15 min (documented TTL) — visibility horizon only
 MESSAGE_TTL_SECONDS = 3600     # 1 hour
 QUESTION_TTL_SECONDS = 600     # 10 min
 
+# Phase 2.1 — purge horizon, deliberately FAR above the visibility TTL.
+# SESSION_STALE_SECONDS only governs what counts as "active" in listings;
+# physically DELETING rows at 15 min destroyed the continuity of any session
+# that spent >15 min in code tools without touching a nexo_* tool (incident
+# 10-jun: two working sessions lost mid-task, orphaning their open protocol
+# tasks). Rows now survive 24h so revival/heartbeat can find them.
+SESSION_PURGE_SECONDS = 24 * 3600
+
 # Single shared connection per process with write serialization.
 # SQLite allows only one writer at a time. Using a shared connection with
 # check_same_thread=False and a write lock ensures:

package/src/db/_sessions.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 """NEXO DB — Sessions module."""
 import time, secrets, string, sqlite3
 from datetime import datetime
-from db._core import get_db, _gen_id, now_epoch, local_time_str, SESSION_STALE_SECONDS, MESSAGE_TTL_SECONDS, QUESTION_TTL_SECONDS
+from db._core import get_db, _gen_id, now_epoch, local_time_str, SESSION_STALE_SECONDS, SESSION_PURGE_SECONDS, MESSAGE_TTL_SECONDS, QUESTION_TTL_SECONDS
 
 # ── Session operations ──────────────────────────────────────────────
 
@@ -166,9 +166,17 @@ def get_active_sessions() -> list[dict]:
 
 
 def clean_stale_sessions() -> int:
-    """Remove stale sessions. Returns count removed."""
+    """Purge sessions older than the PURGE horizon. Returns count removed.
+
+    Phase 2.1 — this used to delete at SESSION_STALE_SECONDS (15 min), which
+    destroyed any session that worked quietly in code tools for a while: the
+    next session/cron to start would erase it, its next nexo_track failed
+    with "Session not found" and its open protocol tasks were orphaned.
+    Deletion now happens at SESSION_PURGE_SECONDS (24h); the 15-min TTL keeps
+    governing VISIBILITY (get_active_sessions/search_sessions) unchanged.
+    """
     conn = get_db()
-    cutoff = now_epoch() - SESSION_STALE_SECONDS
+    cutoff = now_epoch() - SESSION_PURGE_SECONDS
     stale = conn.execute(
         "SELECT sid FROM sessions WHERE last_update_epoch <= ?", (cutoff,)
     ).fetchall()
@@ -309,13 +317,42 @@ def search_sessions(keyword: str) -> list[dict]:
 
 # ── File tracking ───────────────────────────────────────────────────
 
+def revive_session(sid: str, task_hint: str = "(revived session)") -> bool:
+    """Phase 2.1 — re-create a session row for a valid SID that vanished.
+
+    A session can disappear legitimately (purge horizon, manual cleanup,
+    DB swap) while its client keeps working with the same SID. The durable
+    identity is the SID, not the row: revive it instead of erroring, so the
+    "Session not found. Register first." class of breakage cannot occur.
+    Returns True when a row was actually (re)created.
+    """
+    sid = _validate_sid(sid)
+    conn = get_db()
+    now = now_epoch()
+    cursor = conn.execute(
+        "INSERT OR IGNORE INTO sessions (sid, task, started_epoch, last_update_epoch, local_time) "
+        "VALUES (?, ?, ?, ?, ?)",
+        (sid, task_hint, now, now, local_time_str()),
+    )
+    conn.commit()
+    return cursor.rowcount > 0
+
+
 def track_files(sid: str, paths: list[str]) -> dict:
-    """Track files for a session. Returns conflicts if any."""
+    """Track files for a session. Returns conflicts if any.
+
+    Phase 2.1 — a valid SID whose row vanished is REVIVED instead of being
+    told "Session not found. Register first." (the heartbeat already revived
+    missing sessions; this layer was internally inconsistent). The result
+    carries ``revived: True`` so callers can log the recovery.
+    """
+    sid = _validate_sid(sid)
     conn = get_db()
     now = now_epoch()
+    revived = False
     session = conn.execute("SELECT sid FROM sessions WHERE sid = ?", (sid,)).fetchone()
     if not session:
-            return {"error": f"Session {sid} not found. Register first."}
+        revived = revive_session(sid, task_hint="(revived by nexo_track)")
 
     for path in paths:
         conn.execute(
@@ -324,7 +361,10 @@ def track_files(sid: str, paths: list[str]) -> dict:
         )
     conn.commit()
     conflicts = _check_conflicts(conn, sid)
-    return {"tracked": paths, "conflicts": conflicts}
+    result = {"tracked": paths, "conflicts": conflicts}
+    if revived:
+        result["revived"] = True
+    return result
 
 
 def untrack_files(sid: str, paths: list[str] | None = None):

package/src/runtime_service.py

@@ -34,6 +34,16 @@ STATE_FILE = "runtime-service.json"
 LOCK_FILE = "runtime-service.lock"
 LOG_FILE = "runtime-service.log"
 
+# Phase 2.1/2.2 — state isolation per runtime generation. Two different Brain
+# installs (e.g. the managed ~/.nexo/core runtime and an npm-global one)
+# used to share ONE state file: each side saw a "stale_runtime" resident and
+# KILLED the other's in an endless ping-pong (1,314 resident restarts logged
+# on the operator machine; every restart forced the next conversation to pay
+# a 10-48s cold Brain boot and expired client sessions). With the state file
+# keyed by runtime generation, a runtime can only ever see — and manage —
+# its OWN resident. Foreign residents become invisible instead of killable.
+
+
 
 def env_flag(name: str, *, default: bool = False) -> bool:
     value = os.environ.get(name)
@@ -55,12 +65,29 @@ def service_url(host: str | None = None, port: int | None = None, path: str | No
     return f"http://{host or service_host()}:{int(port or service_port())}{path or service_path()}"
 
 
-def service_state_path() -> Path:
+def _generation_state_token(generation: str) -> str:
+    """Stable filesystem-safe token for a runtime generation."""
+    text = str(generation or "unknown").strip() or "unknown"
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]
+
+
+def _current_generation_token() -> str:
+    return _generation_state_token(current_runtime_identity().get("runtime_generation", "unknown"))
+
+
+def _legacy_service_state_path() -> Path:
     root = paths.runtime_state_dir()
     root.mkdir(parents=True, exist_ok=True)
     return root / STATE_FILE
 
 
+def service_state_path() -> Path:
+    root = paths.runtime_state_dir()
+    root.mkdir(parents=True, exist_ok=True)
+    token = _current_generation_token()
+    return root / f"runtime-service-{token}.json"
+
+
 def service_log_path() -> Path:
     root = paths.logs_dir()
     root.mkdir(parents=True, exist_ok=True)
@@ -70,7 +97,8 @@ def service_log_path() -> Path:
 def service_lock_path() -> Path:
     root = paths.runtime_state_dir()
     root.mkdir(parents=True, exist_ok=True)
-    return root / LOCK_FILE
+    token = _current_generation_token()
+    return root / f"runtime-service-{token}.lock"
 
 
 @contextmanager
@@ -128,10 +156,22 @@ def service_start_lock(*, timeout: float = 10.0):
 def read_service_state() -> dict[str, Any]:
     try:
         path = service_state_path()
-        if not path.is_file():
-            return {}
-        data = json.loads(path.read_text(encoding="utf-8"))
-        return data if isinstance(data, dict) else {}
+        if path.is_file():
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return data if isinstance(data, dict) else {}
+        # Phase 2.1 — one-time soft migration: adopt a pre-generation legacy
+        # state file ONLY if it belongs to this same runtime. A foreign
+        # install's legacy state stays invisible (never "stale to kill").
+        legacy = _legacy_service_state_path()
+        if legacy.is_file():
+            data = json.loads(legacy.read_text(encoding="utf-8"))
+            if isinstance(data, dict) and state_matches_current_runtime(data):
+                try:
+                    legacy.replace(path)
+                except Exception:
+                    pass
+                return data
+        return {}
     except Exception:
         return {}
 
@@ -445,6 +485,107 @@ def runtime_service_status() -> dict[str, Any]:
     }
 
 
+# Phase 2.1/2.2 — resident obsolescence watch.
+#
+# With per-generation state files, residents no longer kill each other; the
+# missing piece is cleanup: after a runtime update, the OLD resident must
+# eventually exit, while the CURRENT one must stay warm forever (a hot Brain
+# is what turns 10-48s conversation starts into fast ones). Rules:
+#   - a resident whose on-disk runtime generation still matches its own NEVER
+#     self-terminates, idle or not;
+#   - an OBSOLETE resident (disk generation changed under it) exits cleanly
+#     once it has had no established client connections for two consecutive
+#     checks (anti-flap), removing its state file on the way out;
+#   - if connections cannot be counted (no lsof/netstat), it stays alive —
+#     fail-safe towards living.
+
+OBSOLESCENCE_CHECK_SECONDS = 300
+
+
+def _count_established_connections(port: int) -> int | None:
+    """Best-effort count of ESTABLISHED TCP connections to ``port``.
+
+    Returns None when it cannot tell (missing tooling) so callers can fail
+    safe. Uses lsof on POSIX and netstat on Windows; both ship with the OS.
+    """
+    try:
+        if os.name == "nt":
+            out = subprocess.run(
+                ["netstat", "-ano", "-p", "tcp"],
+                capture_output=True, text=True, timeout=10,
+            ).stdout
+            needle = f":{port} "
+            return sum(
+                1 for line in out.splitlines()
+                if "ESTABLISHED" in line and needle in line.split("ESTABLISHED")[0]
+            )
+        out = subprocess.run(
+            ["lsof", "-nP", f"-iTCP:{port}", "-sTCP:ESTABLISHED"],
+            capture_output=True, text=True, timeout=10,
+        ).stdout
+        rows = [line for line in out.splitlines() if "ESTABLISHED" in line]
+        # lsof lists both directions of loopback pairs; the resident's own
+        # accept side is one row per client connection.
+        return len(rows)
+    except Exception:
+        return None
+
+
+def _resident_is_obsolete(boot_generation: str) -> bool:
+    try:
+        from runtime_versioning import compute_mcp_runtime_fingerprint, read_version_for_path, runtime_generation
+
+        root = current_server_path().parent
+        version = read_version_for_path(root) or read_version_for_path(root.parent)
+        fingerprint = compute_mcp_runtime_fingerprint(root, use_cache=False)
+        current = runtime_generation(version, fingerprint, str(root))
+        return bool(boot_generation) and bool(current) and current != boot_generation
+    except Exception:
+        return False  # cannot tell -> assume still current (fail-safe)
+
+
+def start_resident_obsolescence_watch(*, port: int, on_exit=None) -> None:
+    """Spawn the daemon thread that retires obsolete residents gracefully."""
+    import threading
+
+    boot_generation = str(current_runtime_identity().get("runtime_generation") or "")
+
+    def _watch() -> None:
+        strikes = 0
+        while True:
+            time.sleep(OBSOLESCENCE_CHECK_SECONDS)
+            try:
+                if not _resident_is_obsolete(boot_generation):
+                    strikes = 0
+                    continue
+                connections = _count_established_connections(port)
+                if connections is None or connections > 0:
+                    strikes = 0
+                    continue
+                strikes += 1
+                if strikes < 2:
+                    continue
+                print(
+                    f"[runtime-service] obsolete resident (gen {boot_generation[:24]}…) idle for two checks — exiting cleanly",
+                    file=sys.stderr,
+                )
+                try:
+                    service_state_path().unlink(missing_ok=True)
+                except Exception:
+                    pass
+                if callable(on_exit):
+                    try:
+                        on_exit()
+                    except Exception:
+                        pass
+                os._exit(0)
+            except Exception:
+                strikes = 0  # the watch must never kill a healthy resident
+
+    thread = threading.Thread(target=_watch, name="resident-obsolescence-watch", daemon=True)
+    thread.start()
+
+
 def run_mcp_proxy_adapter(*, name: str, instructions: str, run_kwargs: dict[str, Any]) -> None:
     from fastmcp.server import create_proxy
 

package/src/server.py

@@ -3093,4 +3093,14 @@ if __name__ == "__main__":
                     "mode": "runtime-service",
                 }
             )
+            # Phase 2.1/2.2 — retire this resident gracefully if the on-disk
+            # runtime is updated under it AND no clients remain connected.
+            # The current-generation resident never self-terminates: a warm
+            # Brain is what keeps conversation starts fast.
+            from runtime_service import start_resident_obsolescence_watch
+
+            start_resident_obsolescence_watch(
+                port=port,
+                on_exit=lambda: (close_local_context_db(), close_db()),
+            )
         mcp.run(**run_kwargs)