nexo-brain 7.20.0 → 7.20.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.20.0` is the current packaged-runtime line. Minor release over v7.19.0 — the Local Context index now reconciles known files and folders on every service cycle, so created, modified, deleted and newly excluded local files are reflected automatically between full scans.
+Version `7.20.1` is the current packaged-runtime line. Patch release over v7.20.0 — the Local Context service now recovers from orphaned locks and mixed-version cycle failures instead of leaving the background index stuck.
+
+Previously in `7.20.0`: minor release over v7.19.0 — the Local Context index now reconciles known files and folders on every service cycle, so created, modified, deleted and newly excluded local files are reflected automatically between full scans.
 
 Previously in `7.19.0`: minor release over v7.18.1 - bundle-managed installations (NEXO Desktop `brain-bundle/`) can now pin Brain to the host application release cycle via `NEXO_BRAIN_AUTO_UPDATE=false`, and the server auto-exits with code 75 on fingerprint mismatch so MCP clients respawn the server with the new code instead of leaving stale `server.py` processes alive.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.0",
+  "version": "7.20.1",
   "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/local_context/api.py

@@ -1019,7 +1019,7 @@ def _problem_rows(conn) -> list[dict]:
         LIMIT 20
         """
     ).fetchall()
-    return [
+    problems = [
         {
             "user_message": row["user_message"],
             "recommended_action": "NEXO lo volvera a intentar mas tarde" if row["retryable"] else "Revisa permisos o archivo",
@@ -1033,6 +1033,35 @@ def _problem_rows(conn) -> list[dict]:
         }
         for row in rows
     ]
+    last_success = conn.execute(
+        "SELECT MAX(created_at) AS created_at FROM local_index_logs WHERE event='service_cycle_finished'"
+    ).fetchone()["created_at"] or 0
+    service_rows = conn.execute(
+        """
+        SELECT created_at, level, event, message, metadata_json
+        FROM local_index_logs
+        WHERE event IN ('service_cycle_failed', 'service_cycle_compat_fallback')
+          AND created_at > ?
+        ORDER BY id DESC
+        LIMIT 5
+        """,
+        (last_success,),
+    ).fetchall()
+    problems.extend(
+        {
+            "user_message": "La memoria local tuvo un problema temporal y NEXO la reintentara automaticamente",
+            "recommended_action": "No tienes que hacer nada. Si se repite, abre soporte y diagnostico para ver el detalle.",
+            "technical_detail": f"{row['event']}: {row['message']} {row['metadata_json']}",
+            "support_code": row["event"],
+            "severity": "warning" if row["level"] == "warn" else "error",
+            "retryable": True,
+            "path": "",
+            "phase": "service",
+            "created_at": row["created_at"],
+        }
+        for row in service_rows
+    )
+    return problems
 
 
 def _command_output(args: list[str], *, timeout: int = 2) -> tuple[int, str, str]:

package/src/scripts/deep-sleep/extract.py

@@ -70,6 +70,57 @@ TRANSIENT_ERROR_KINDS = {
 }
 REQUIRED_PROTOCOL_SUMMARY_KEYS = ("guard_check", "heartbeat", "change_log")
 
+# Compact few-shot rendered into the prompt on a `json_schema` retry. Keeps
+# the placeholder structure intact so the model sees the exact contract that
+# `_is_valid_extraction` enforces. Kept as a string to avoid pulling in a
+# template engine for a one-shot block.
+JSON_SCHEMA_FEWSHOT = (
+    "RETRY_HINT: the previous attempt produced JSON that did not match the "
+    "Deep Sleep extraction contract. The response must be a SINGLE JSON "
+    "object with the following minimum shape (extra keys allowed):\n"
+    "{\n"
+    '  "session_id": "<exact session id, string>",\n'
+    '  "findings": [ { "type": "...", "summary": "...", "evidence": "..." } ],\n'
+    '  "protocol_summary": {\n'
+    '    "guard_check": { "ran": true|false, "notes": "..." },\n'
+    '    "heartbeat":   { "count": 0, "notes": "..." },\n'
+    '    "change_log":  { "entries": 0, "notes": "..." }\n'
+    "  }\n"
+    "}\n"
+    "Mandatory: session_id is a non-empty string equal to {{SESSION_ID}}; "
+    "findings is a list of objects; protocol_summary contains the three "
+    "object keys above. Return ONLY the JSON object, no prose, no fences."
+)
+
+
+def _record_protocol_debt(
+    session_id: str,
+    *,
+    debt_type: str,
+    severity: str,
+    evidence: str,
+) -> None:
+    """Best-effort registration of an extraction failure as protocol debt.
+
+    Imported lazily so the extractor still runs in environments where the
+    DB layer is unavailable (e.g. partial installs, unit tests). Any error
+    inside the debt path is swallowed: we never want a debt-logging issue
+    to mask the real extraction failure already being reported.
+    """
+    try:
+        from db._protocol import create_protocol_debt
+    except Exception:  # pragma: no cover - best effort
+        return
+    try:
+        create_protocol_debt(
+            session_id,
+            debt_type,
+            severity=severity,
+            evidence=evidence[:3500],
+        )
+    except Exception as exc:  # pragma: no cover - best effort
+        print(f"    Warning: could not record protocol_debt: {exc}", file=sys.stderr)
+
 
 def _classify_cli_result(result) -> tuple[str, str]:
     """Return (kind, short_message) describing a failed automation backend call.
@@ -211,11 +262,18 @@ def analyze_session(
     date_dir: Path,
     shared_context_file: Path | None,
     session_txt_map: dict[str, str] | None = None,
+    *,
+    prior_error_kind: str = "",
 ) -> tuple[dict | None, str | None]:
     """Send a session to the automation backend for extraction analysis.
 
     Returns (parsed_result, error_kind). `error_kind` is only set on failure.
     See `_classify_cli_result` for possible values.
+
+    ``prior_error_kind`` is consumed by the retry path: when the previous
+    attempt failed validation with ``json_schema`` we append a few-shot of
+    the contract so the model sees the exact shape it must produce instead
+    of repeating the same structurally wrong payload.
     """
     session_file = find_session_file(session_id, date_dir, session_txt_map=session_txt_map)
     if not session_file:
@@ -236,6 +294,15 @@ def analyze_session(
     prompt = prompt_template.replace("{{CONTEXT_FILE}}", str(session_file))
     prompt = prompt.replace("{{SESSION_ID}}", session_id)
     prompt += shared_ctx_instruction
+    if prior_error_kind == "json_schema":
+        prompt += "\n\n" + JSON_SCHEMA_FEWSHOT.replace("{{SESSION_ID}}", session_id)
+
+    # Bootstrap the subagent with the day's deep-sleep dir as cwd so its
+    # default Read allowlist already covers the session transcript, the
+    # shared context, and the day's working files. Without this, the CLI
+    # subprocess inherits the parent's cwd (often "/") and fails with
+    # `cannot_comply` the first time it tries to Read the session file.
+    subagent_cwd = str(date_dir) if date_dir and Path(date_dir).exists() else None
 
     try:
         json_system_prompt = render_core_prompt(
@@ -246,6 +313,7 @@ def analyze_session(
         result = run_automation_prompt(
             prompt,
             caller="deep-sleep/extract",
+            cwd=subagent_cwd,
             timeout=CLAUDE_TIMEOUT,
             output_format="text",
             append_system_prompt=json_system_prompt,
@@ -276,6 +344,7 @@ def analyze_session(
             convert_result = run_automation_prompt(
                 convert_prompt,
                 caller="deep-sleep/extract",
+                cwd=subagent_cwd,
                 timeout=120,
                 output_format="text",
                 append_system_prompt=json_system_prompt,
@@ -471,6 +540,7 @@ def main():
                 date_dir,
                 shared_context_file,
                 session_txt_map=session_txt_map,
+                prior_error_kind=last_error_kind,
             )
             if result:
                 break
@@ -522,6 +592,21 @@ def main():
             }
             all_extractions.append(failed_entry)
             _save_checkpoint(checkpoint_file, failed_entry)
+            # Surface deterministic extractor failures as protocol debt so
+            # the aggregate self-audit cannot silently absorb the pattern.
+            # Severity escalates once the session is poisoned because by
+            # then it stops being a per-run hiccup and becomes a recurring
+            # runtime issue worth a louder signal.
+            _record_protocol_debt(
+                session_id,
+                debt_type=f"deep-sleep.extract.{last_error_kind}",
+                severity="error" if state == "poisoned" else "warn",
+                evidence=(
+                    f"date={target_date} state={state} attempts={new_count}/"
+                    f"{MAX_POISON_ATTEMPTS} kind={last_error_kind} "
+                    f"checkpoint={checkpoint_file}"
+                ),
+            )
             if state == "poisoned":
                 poisoned += 1
 

package/src/scripts/nexo-local-index.py

@@ -51,6 +51,27 @@ def log(message: str) -> None:
         handle.write(line + "\n")
 
 
+def _read_lock() -> dict:
+    try:
+        return json.loads(LOCK_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _pid_running(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
 def acquire_lock() -> bool:
     try:
         fd = os.open(str(LOCK_FILE), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
@@ -59,9 +80,16 @@ def acquire_lock() -> bool:
         return True
     except FileExistsError:
         try:
-            age = time.time() - LOCK_FILE.stat().st_mtime
+            lock = _read_lock()
+            pid = int(lock.get("pid") or 0)
+            age = time.time() - float(lock.get("created_at") or LOCK_FILE.stat().st_mtime)
+            if pid and not _pid_running(pid):
+                LOCK_FILE.unlink(missing_ok=True)
+                log(f"Removed stale local-index lock for dead pid {pid}.")
+                return acquire_lock()
             if age > LOCK_STALE_SECONDS:
                 LOCK_FILE.unlink(missing_ok=True)
+                log(f"Removed stale local-index lock older than {int(age)} seconds.")
                 return acquire_lock()
         except Exception:
             pass
@@ -70,25 +98,47 @@ def acquire_lock() -> bool:
 
 def release_lock() -> None:
     try:
+        lock = _read_lock()
+        pid = int(lock.get("pid") or 0)
+        if pid and pid != os.getpid():
+            return
         LOCK_FILE.unlink(missing_ok=True)
     except Exception:
         pass
 
 
-def main() -> int:
-    if not acquire_lock():
-        log("Skipped: previous local-index cycle is still running.")
-        return 0
+def _run_index_cycle() -> dict:
     try:
-        if os.environ.get("NEXO_LOCAL_INDEX_DISABLE_DEFAULT_ROOTS", "").strip() != "1":
-            api.ensure_default_roots()
-        result = api.run_once(
+        return api.run_once(
             limit=SCAN_LIMIT,
             process_limit=PROCESS_LIMIT,
             live_asset_limit=LIVE_ASSET_LIMIT,
             live_dir_limit=LIVE_DIR_LIMIT,
             live_file_limit=LIVE_FILE_LIMIT,
         )
+    except TypeError as exc:
+        message = str(exc)
+        live_kwargs = ("live_asset_limit", "live_dir_limit", "live_file_limit")
+        if not any(name in message for name in live_kwargs):
+            raise
+        log_event(
+            "warn",
+            "service_cycle_compat_fallback",
+            "Local memory service used compatibility fallback",
+            error=message,
+        )
+        log(f"Compatibility fallback: api.run_once does not accept live reconcile limits ({message}).")
+        return api.run_once(limit=SCAN_LIMIT, process_limit=PROCESS_LIMIT)
+
+
+def main() -> int:
+    if not acquire_lock():
+        log("Skipped: previous local-index cycle is still running.")
+        return 0
+    try:
+        if os.environ.get("NEXO_LOCAL_INDEX_DISABLE_DEFAULT_ROOTS", "").strip() != "1":
+            api.ensure_default_roots()
+        result = _run_index_cycle()
         log_event("info", "service_cycle_finished", "Local memory service cycle finished", result=result)
         log(json.dumps(result, ensure_ascii=False, sort_keys=True))
         return 0 if result.get("ok") else 2