nexo-brain 7.23.0 → 7.23.2

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.23.0` is the current packaged-runtime line. Minor release over v7.22.0 - pre-answer routing now consults continuity evidence before visible replies, Memory Observations queue processing converges through a bounded processor, and audits expose saved-but-not-used stores, automation drift, MCP live/catalog gaps, artifact location and transcript coverage.
+Version `7.23.1` is the current packaged-runtime line. Express patch over v7.23.0 - headless automations no longer hang on silent Claude children, synthetic followup prompts no longer trigger session-end loops, and runtime backups self-prune under a hard cap before creating new large artifacts.
+
+Previously in `7.23.0`: minor release over v7.22.0 - pre-answer routing now consults continuity evidence before visible replies, Memory Observations queue processing converges through a bounded processor, and audits expose saved-but-not-used stores, automation drift, MCP live/catalog gaps, artifact location and transcript coverage.
 
 Previously in `7.22.0`: minor release over v7.21.0 - heartbeat stays fast in Desktop-managed sessions, MCP writes can be accepted through a durable file-backed queue before SQLite commit, Brain exposes compliance state for Desktop gates, and Local Context adds Entity Dossier for open-domain local evidence aggregation.
 

package/package.json

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

@@ -1052,9 +1052,10 @@ BARE_MODE_SAFE_CALLERS: frozenset[str] = frozenset({
 # Execution contracts keep background agents disciplined without polluting
 # machine-only child calls that must return strict JSON.
 AUTOMATION_CONTRACT_FULL_NEXO_AGENT = "full_nexo_agent"
+AUTOMATION_CONTRACT_SUPERVISED_CHILD = "supervised_child"
 AUTOMATION_CONTRACT_STRICT_CHILD = "strict_child_json"
 AUTOMATION_CONTRACT_PUBLIC_CHILD = "public_isolated_child"
-AUTOMATION_CONTRACT_DEFAULT = AUTOMATION_CONTRACT_FULL_NEXO_AGENT
+AUTOMATION_CONTRACT_DEFAULT = AUTOMATION_CONTRACT_SUPERVISED_CHILD
 
 FULL_NEXO_AGENT_CALLERS: frozenset[str] = frozenset({
     "catchup/morning",
@@ -1087,17 +1088,30 @@ MACHINE_ONLY_LANGUAGE_CONTRACT_CALLERS: frozenset[str] = frozenset({
 
 def _automation_contract_for_caller(caller: str) -> str:
     clean = str(caller or "").strip()
+    if clean in FULL_NEXO_AGENT_CALLERS:
+        return AUTOMATION_CONTRACT_FULL_NEXO_AGENT
     if clean in STRICT_CHILD_CALLERS:
         return AUTOMATION_CONTRACT_STRICT_CHILD
     if clean in PUBLIC_CHILD_CALLERS:
         return AUTOMATION_CONTRACT_PUBLIC_CHILD
-    return AUTOMATION_CONTRACT_FULL_NEXO_AGENT
+    return AUTOMATION_CONTRACT_DEFAULT
 
 
 def _caller_uses_global_discipline(caller: str) -> bool:
     return _automation_contract_for_caller(caller) == AUTOMATION_CONTRACT_FULL_NEXO_AGENT
 
 
+def _build_supervised_child_system_prompt() -> str:
+    return (
+        "You are running as a supervised NEXO automation child. "
+        "Return the requested result for this job only. Do not open or close "
+        "NEXO tasks, reminders, diary entries, sessions, or followups from "
+        "inside this child process; the parent NEXO runner owns lifecycle, "
+        "timeouts, evidence, retries, and durable state. If the requested "
+        "work cannot be completed safely, return a concise failure reason."
+    )
+
+
 def _should_apply_operator_language_contract(caller: str) -> bool:
     clean = str(caller or "").strip()
     if not clean:
@@ -1191,6 +1205,12 @@ def run_automation_prompt(
             append_system_prompt = append_system_prompt + "\n\n" + enforcement_fragment
         else:
             append_system_prompt = enforcement_fragment
+    elif automation_contract == AUTOMATION_CONTRACT_SUPERVISED_CHILD:
+        supervised_fragment = _build_supervised_child_system_prompt()
+        if append_system_prompt:
+            append_system_prompt = append_system_prompt + "\n\n" + supervised_fragment
+        else:
+            append_system_prompt = supervised_fragment
 
     prompt = _apply_operator_language_contract(prompt, caller=caller)
 

package/src/auto_update.py

@@ -108,6 +108,69 @@ def _backup_validation_tables(db_file: Path) -> tuple[str, ...]:
     return PROTECTED_BACKUP_TABLES
 
 
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
+BACKUP_MAX_BYTES = _env_int("NEXO_BACKUP_MAX_BYTES", 50 * 1024 * 1024 * 1024)
+BACKUP_MIN_FREE_BYTES = _env_int("NEXO_BACKUP_MIN_FREE_BYTES", 5 * 1024 * 1024 * 1024)
+LOCAL_CONTEXT_MAX_BACKUP_BYTES = _env_int("NEXO_LOCAL_CONTEXT_MAX_BACKUP_BYTES", 2 * 1024 * 1024 * 1024)
+_LAST_BACKUP_ERROR = ""
+
+
+def _run_runtime_backup_prune() -> None:
+    script = SRC_DIR / "scripts" / "prune_runtime_backups.py"
+    if not script.is_file():
+        return
+    try:
+        subprocess.run(
+            [
+                sys.executable,
+                str(script),
+                "--root",
+                str(paths.backups_dir()),
+                "--apply",
+                "--max-bytes",
+                str(BACKUP_MAX_BYTES),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except Exception as e:
+        _log(f"Backup self-clean warning: {e}")
+
+
+def _backup_free_bytes() -> int | None:
+    backup_root = paths.backups_dir()
+    try:
+        usage = shutil.disk_usage(backup_root if backup_root.exists() else backup_root.parent)
+        return int(usage.free)
+    except Exception:
+        return None
+
+
+def _backup_space_error() -> str | None:
+    _run_runtime_backup_prune()
+    free = _backup_free_bytes()
+    if free is not None and free < BACKUP_MIN_FREE_BYTES:
+        return (
+            "free disk below NEXO backup safety floor after automatic cleanup "
+            f"({free}B < {BACKUP_MIN_FREE_BYTES}B)"
+        )
+    return None
+
+
+def _should_include_local_context_backup(path: Path) -> bool:
+    try:
+        return path.stat().st_size <= LOCAL_CONTEXT_MAX_BACKUP_BYTES
+    except OSError:
+        return False
+
+
 CLASSIFIER_INSTALL_TIMEOUT_SECONDS = 1800
 CLASSIFIER_INSTALL_JOIN_SECONDS = 1500
 CLASSIFIER_INSTALL_LOG = paths.logs_dir() / "classifier-install.log"
@@ -380,6 +443,17 @@ def _create_validated_db_backup() -> tuple[str | None, dict | None]:
     """Create a DB backup and validate that critical tables still contain data."""
     backup_dir = _backup_dbs()
     if not backup_dir:
+        if _LAST_BACKUP_ERROR:
+            return None, {
+                "ok": False,
+                "reports": [{
+                    "ok": False,
+                    "source_db": "",
+                    "backup_db": "",
+                    "errors": [_LAST_BACKUP_ERROR],
+                    "regressions": [],
+                }],
+            }
         return None, None
 
     source_dbs: list[Path] = []
@@ -387,7 +461,7 @@ def _create_validated_db_backup() -> tuple[str | None, dict | None]:
     if primary_db is not None:
         source_dbs.append(primary_db)
     local_context_db = paths.memory_dir() / "local-context.db"
-    if local_context_db.is_file():
+    if local_context_db.is_file() and _should_include_local_context_backup(local_context_db):
         source_dbs.append(local_context_db)
     if not source_dbs:
         return backup_dir, None
@@ -2061,6 +2135,8 @@ def _backup_dbs() -> str | None:
     """Snapshot all .db files before migration. Returns backup dir or None."""
     import sqlite3
     import time as _time
+    global _LAST_BACKUP_ERROR
+    _LAST_BACKUP_ERROR = ""
     # Drop 0-byte .db orphans first — they mask the real DB during primary
     # path selection and turn into empty shells in the backup, breaking both
     # validation and rollback paths. Safe no-op when there are none.
@@ -2070,7 +2146,7 @@ def _backup_dbs() -> str | None:
 
     db_files = list(DATA_DIR.glob("*.db")) if DATA_DIR.is_dir() else []
     local_context_db = paths.memory_dir() / "local-context.db"
-    if local_context_db.is_file():
+    if local_context_db.is_file() and _should_include_local_context_backup(local_context_db):
         db_files.append(local_context_db)
     db_files += [f for f in NEXO_HOME.glob("*.db") if f.is_file()]
     src_db = SRC_DIR / "nexo.db"
@@ -2080,6 +2156,12 @@ def _backup_dbs() -> str | None:
     if not db_files:
         return None
 
+    space_err = _backup_space_error()
+    if space_err:
+        _LAST_BACKUP_ERROR = space_err
+        _log(f"DB backup aborted: {space_err}")
+        return None
+
     backup_dir.mkdir(parents=True, exist_ok=True)
     for db_file in db_files:
         src_conn = None

package/src/cli.py

@@ -413,13 +413,29 @@ def _version_sort_key(raw: str) -> tuple[tuple[int, ...], int, str]:
     return (tuple(parts), 1 if not suffix else 0, suffix)
 
 
-def _version_status_payload() -> dict:
+def _version_status_payload(*, force_refresh: bool = False) -> dict:
     installed = _get_version()
     latest = _load_latest_version_cache()
     latest_source = "cache" if latest else ""
-    if latest is None and _should_refresh_latest_version():
-        latest = _fetch_latest_version()
-        latest_source = "npm" if latest else ""
+    should_refresh = False
+    if force_refresh and _should_refresh_latest_version():
+        # Desktop reads `nexo --version --json` to decide whether to show the
+        # Brain update CTA. If a user checked minutes before a release, the
+        # 6-hour cache can otherwise hide the new npm dist-tag until it expires.
+        should_refresh = (
+            latest is None
+            or (
+                bool(installed)
+                and _version_sort_key(latest) <= _version_sort_key(installed)
+            )
+        )
+    elif latest is None and _should_refresh_latest_version():
+        should_refresh = True
+    if should_refresh:
+        refreshed = _fetch_latest_version()
+        if refreshed:
+            latest = refreshed
+            latest_source = "npm"
     if latest and installed and _version_sort_key(latest) < _version_sort_key(installed):
         latest = installed
         latest_source = "installed"
@@ -4030,7 +4046,7 @@ def main():
         _print_help()
         return 0
     if args.version:
-        payload = _version_status_payload()
+        payload = _version_status_payload(force_refresh=bool(args.json))
         if args.json:
             print(json.dumps(payload, ensure_ascii=False))
         else:

package/src/enforcement_engine.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import queue
 import subprocess
 import threading
 import time
@@ -2816,7 +2817,10 @@ def run_with_enforcement(
     # headless runtime. Without this, correction detection and project-
     # context rules only run when tests invoke on_user_message directly.
     try:
-        enforcer.on_user_message(prompt or "")
+        enforcer.on_user_message(
+            prompt or "",
+            session_end_detector=lambda _text: False,
+        )
     except Exception as _init_exc:  # noqa: BLE001 — fail-closed
         _logger.warning("on_user_message (initial prompt) failed: %s", _init_exc)
 
@@ -2831,6 +2835,16 @@ def run_with_enforcement(
     stderr_lines = []
     start_time = time.time()
     waiting_for_injection_response = False
+    timed_out = False
+    stdout_closed = False
+    stdout_lines: queue.Queue[str | None] = queue.Queue()
+
+    def _kill_proc(reason: str) -> None:
+        _logger.warning("%s after %ds", reason, timeout)
+        try:
+            proc.kill()
+        except Exception:
+            pass
 
     def _inject(text: str):
         nonlocal waiting_for_injection_response
@@ -2847,6 +2861,15 @@ def run_with_enforcement(
         except Exception as e:
             _logger.error("INJECT_FAILED: %s", e)
 
+    def _read_stdout():
+        try:
+            for line in proc.stdout:
+                stdout_lines.put(line)
+        except Exception:
+            pass
+        finally:
+            stdout_lines.put(None)
+
     def _read_stderr():
         try:
             for line in proc.stderr:
@@ -2854,92 +2877,125 @@ def run_with_enforcement(
         except Exception:
             pass
 
+    stdout_thread = threading.Thread(target=_read_stdout, daemon=True)
     stderr_thread = threading.Thread(target=_read_stderr, daemon=True)
+    stdout_thread.start()
     stderr_thread.start()
 
     last_periodic_check = time.time()
 
-    try:
-        for raw_line in proc.stdout:
-            line = raw_line.strip()
-            if not line:
-                continue
-
-            if time.time() - start_time > timeout:
-                _logger.warning("TIMEOUT after %ds", timeout)
-                proc.kill()
-                break
+    def _handle_stdout_line(raw_line: str) -> bool:
+        """Process one Claude stream-json line.
 
-            try:
-                event = json.loads(line)
-            except json.JSONDecodeError:
-                continue
+        Return True when the stream turn is complete and the caller should
+        leave the main read loop.
+        """
+        nonlocal waiting_for_injection_response
+        line = raw_line.strip()
+        if not line:
+            return False
 
-            event_type = event.get("type", "")
-
-            if event_type == "assistant" and event.get("message", {}).get("content"):
-                for block in event["message"]["content"]:
-                    if block.get("type") == "tool_use":
-                        # v7.7 Gap 7.3 — wire before_tool in the live
-                        # stream. Desktop already calls onBeforeToolCall
-                        # before onToolCall; Brain's stream was only
-                        # calling on_tool_call, silently skipping every
-                        # before_tool rule the map declared.
-                        enforcer.on_tool_call_before(block.get("name", ""), block.get("input"))
-                        enforcer.on_tool_call(block.get("name", ""), block.get("input"))
-            elif event_type == "content_block_start":
-                cb = event.get("content_block", {})
-                if cb.get("type") == "tool_use":
-                    enforcer.on_tool_call_before(cb.get("name", ""), cb.get("input"))
-                    enforcer.on_tool_call(cb.get("name", ""), cb.get("input"))
-
-            if event_type == "assistant" and not waiting_for_injection_response:
-                msg = event.get("message", {})
-                for block in msg.get("content", []):
-                    if block.get("type") == "text":
-                        collected_text.append(block["text"])
-                        # R16 — probe each assistant text block as it arrives
-                        # so a declared-done line is caught on the same turn
-                        # rather than only at session end.
-                        try:
-                            enforcer.on_assistant_text(block["text"])
-                        except Exception as _r16_exc:  # noqa: BLE001
-                            _logger.warning("on_assistant_text failed: %s", _r16_exc)
-                        try:
-                            enforcer.on_assistant_text_r17(block["text"])
-                        except Exception as _r17_exc:  # noqa: BLE001
-                            _logger.warning("on_assistant_text_r17 failed: %s", _r17_exc)
-
-            if event_type == "result":
-                if waiting_for_injection_response:
-                    waiting_for_injection_response = False
-                    _logger.info("INJECTION_RESPONSE received")
-                    item = enforcer.flush()
-                    if item:
-                        _inject(item["prompt"])
-                    continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            return False
 
-                enforcer.check_periodic()
+        event_type = event.get("type", "")
+
+        if event_type == "assistant" and event.get("message", {}).get("content"):
+            for block in event["message"]["content"]:
+                if block.get("type") == "tool_use":
+                    # v7.7 Gap 7.3 — wire before_tool in the live
+                    # stream. Desktop already calls onBeforeToolCall
+                    # before onToolCall; Brain's stream was only
+                    # calling on_tool_call, silently skipping every
+                    # before_tool rule the map declared.
+                    enforcer.on_tool_call_before(block.get("name", ""), block.get("input"))
+                    enforcer.on_tool_call(block.get("name", ""), block.get("input"))
+        elif event_type == "content_block_start":
+            cb = event.get("content_block", {})
+            if cb.get("type") == "tool_use":
+                enforcer.on_tool_call_before(cb.get("name", ""), cb.get("input"))
+                enforcer.on_tool_call(cb.get("name", ""), cb.get("input"))
+
+        if event_type == "assistant" and not waiting_for_injection_response:
+            msg = event.get("message", {})
+            for block in msg.get("content", []):
+                if block.get("type") == "text":
+                    collected_text.append(block["text"])
+                    # R16 — probe each assistant text block as it arrives
+                    # so a declared-done line is caught on the same turn
+                    # rather than only at session end.
+                    try:
+                        enforcer.on_assistant_text(block["text"])
+                    except Exception as _r16_exc:  # noqa: BLE001
+                        _logger.warning("on_assistant_text failed: %s", _r16_exc)
+                    try:
+                        enforcer.on_assistant_text_r17(block["text"])
+                    except Exception as _r17_exc:  # noqa: BLE001
+                        _logger.warning("on_assistant_text_r17 failed: %s", _r17_exc)
+
+        if event_type == "result":
+            if waiting_for_injection_response:
+                waiting_for_injection_response = False
+                _logger.info("INJECTION_RESPONSE received")
                 item = enforcer.flush()
                 if item:
                     _inject(item["prompt"])
-                else:
-                    _logger.info("TURN_END — no pending enforcements, done")
+                return False
+
+            enforcer.check_periodic()
+            item = enforcer.flush()
+            if item:
+                _inject(item["prompt"])
+            else:
+                _logger.info("TURN_END — no pending enforcements, done")
+                return True
+
+        return False
+
+    try:
+        while True:
+            if time.time() - start_time > timeout:
+                timed_out = True
+                _kill_proc("TIMEOUT")
+                break
+
+            try:
+                raw_line = stdout_lines.get(timeout=0.2)
+            except queue.Empty:
+                if stdout_closed and proc.poll() is not None:
                     break
+                if time.time() - last_periodic_check > 30:
+                    enforcer.check_periodic()
+                    last_periodic_check = time.time()
+                continue
 
-            if time.time() - last_periodic_check > 30:
-                enforcer.check_periodic()
-                last_periodic_check = time.time()
+            if raw_line is None:
+                stdout_closed = True
+                break
+
+            if _handle_stdout_line(raw_line):
+                break
 
     except Exception as e:
         _logger.error("EXCEPTION: %s", e)
     finally:
-        end_prompts = enforcer.get_end_prompts()
+        end_prompts = [] if timed_out else enforcer.get_end_prompts()
         for ep in end_prompts:
             try:
                 _inject(ep)
                 deadline = time.time() + 15
-                for raw_line in proc.stdout:
+                while time.time() <= deadline:
+                    try:
+                        raw_line = stdout_lines.get(timeout=0.2)
+                    except queue.Empty:
+                        if proc.poll() is not None:
+                            break
+                        continue
+                    if raw_line is None:
+                        stdout_closed = True
+                        break
                     if time.time() > deadline:
                         _logger.warning("END_PROMPT timeout")
                         break
@@ -2968,10 +3024,18 @@ def run_with_enforcement(
         except subprocess.TimeoutExpired:
             proc.kill()
 
+    stdout_thread.join(timeout=2)
     stderr_thread.join(timeout=2)
     final_text = "\n".join(collected_text)
     final_stderr = "".join(stderr_lines)
+    returncode = proc.returncode
+    if timed_out:
+        returncode = 124
+        timeout_msg = f"NEXO enforcement timeout after {timeout}s"
+        final_stderr = f"{final_stderr.rstrip()}\n{timeout_msg}".lstrip()
+    elif returncode is None:
+        returncode = 0
 
     return subprocess.CompletedProcess(
-        stream_cmd, proc.returncode or 0, final_text, final_stderr
+        stream_cmd, returncode, final_text, final_stderr
     )

package/src/plugins/update.py

@@ -147,6 +147,18 @@ DATA_DIR = paths.data_dir()
 BACKUP_BASE = paths.backups_dir()
 TECHNICAL_BACKUP_KEEP = 5
 
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
+BACKUP_MAX_BYTES = _env_int("NEXO_BACKUP_MAX_BYTES", 50 * 1024 * 1024 * 1024)
+BACKUP_MIN_FREE_BYTES = _env_int("NEXO_BACKUP_MIN_FREE_BYTES", 5 * 1024 * 1024 * 1024)
+LOCAL_CONTEXT_MAX_BACKUP_BYTES = _env_int("NEXO_LOCAL_CONTEXT_MAX_BACKUP_BYTES", 2 * 1024 * 1024 * 1024)
+
 # In packaged installs, update.py lives at <NEXO_HOME>/plugins/update.py.
 _PACKAGED_INSTALL = _is_packaged_install()
 REPO_DIR = CODE_ROOT if _PACKAGED_INSTALL else _REPO_CANDIDATE
@@ -186,6 +198,55 @@ def _rotate_backup_family(prefix: str, keep: int = TECHNICAL_BACKUP_KEEP) -> int
     return removed
 
 
+def _run_runtime_backup_prune() -> None:
+    script = SRC_DIR / "scripts" / "prune_runtime_backups.py"
+    if not script.is_file():
+        return
+    try:
+        subprocess.run(
+            [
+                sys.executable,
+                str(script),
+                "--root",
+                str(BACKUP_BASE),
+                "--apply",
+                "--max-bytes",
+                str(BACKUP_MAX_BYTES),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except Exception:
+        pass
+
+
+def _backup_free_bytes() -> int | None:
+    try:
+        usage = shutil.disk_usage(BACKUP_BASE if BACKUP_BASE.exists() else BACKUP_BASE.parent)
+        return int(usage.free)
+    except Exception:
+        return None
+
+
+def _backup_space_error() -> str | None:
+    _run_runtime_backup_prune()
+    free = _backup_free_bytes()
+    if free is not None and free < BACKUP_MIN_FREE_BYTES:
+        return (
+            "free disk below NEXO backup safety floor after automatic cleanup "
+            f"({free}B < {BACKUP_MIN_FREE_BYTES}B)"
+        )
+    return None
+
+
+def _should_include_local_context_backup(path: Path) -> bool:
+    try:
+        return path.stat().st_size <= LOCAL_CONTEXT_MAX_BACKUP_BYTES
+    except OSError:
+        return False
+
+
 def _venv_python_path(runtime_root: Path | None = None) -> Path:
     root = runtime_root or _nexo_home()
     if sys.platform == "win32":
@@ -522,7 +583,7 @@ def _backup_databases() -> tuple[str, str | None]:
 
     db_files = list(DATA_DIR.glob("*.db")) if DATA_DIR.is_dir() else []
     local_context_db = paths.memory_dir() / "local-context.db"
-    if local_context_db.is_file():
+    if local_context_db.is_file() and _should_include_local_context_backup(local_context_db):
         db_files.append(local_context_db)
     # Also check NEXO_HOME root for legacy db location
     db_files += [f for f in NEXO_HOME.glob("*.db") if f.is_file()]
@@ -534,6 +595,10 @@ def _backup_databases() -> tuple[str, str | None]:
     if not db_files:
         return str(backup_dir), None  # No DBs to backup, not an error
 
+    space_err = _backup_space_error()
+    if space_err:
+        return str(backup_dir), space_err
+
     backup_dir.mkdir(parents=True, exist_ok=True)
 
     for db_file in db_files:

package/src/scripts/nexo-backup.sh

@@ -17,10 +17,21 @@ LOCAL_CONTEXT_RETENTION_HOURS="${NEXO_LOCAL_CONTEXT_BACKUP_RETENTION_HOURS:-24}"
 LOCAL_CONTEXT_KEEP_LAST="${NEXO_LOCAL_CONTEXT_BACKUP_KEEP_LAST:-2}"
 BUSY_TIMEOUT_MS="${NEXO_BACKUP_BUSY_TIMEOUT_MS:-5000}"
 RECENT_BACKUP_HOURS="${NEXO_BACKUP_RECENT_BACKUP_HOURS:-6}"
+BACKUP_MAX_BYTES="${NEXO_BACKUP_MAX_BYTES:-53687091200}"
+MIN_FREE_BYTES="${NEXO_BACKUP_MIN_FREE_BYTES:-5368709120}"
+LOCAL_CONTEXT_MAX_BACKUP_BYTES="${NEXO_LOCAL_CONTEXT_MAX_BACKUP_BYTES:-2147483648}"
 
 mkdir -p "$BACKUP_DIR" "$WEEKLY_DIR"
 
 cleanup_backups() {
+    PRUNER="$NEXO_HOME/core/scripts/prune_runtime_backups.py"
+    if [ ! -f "$PRUNER" ]; then
+        PRUNER="$(dirname "$0")/prune_runtime_backups.py"
+    fi
+    if [ -f "$PRUNER" ]; then
+        python3 "$PRUNER" --root "$BACKUP_DIR" --apply --max-bytes "$BACKUP_MAX_BYTES" >/dev/null 2>&1 || true
+    fi
+
     python3 - "$BACKUP_DIR" "$RETENTION_HOURS" "$KEEP_LAST" "$FAMILY_KEEP_LAST" "$LOCAL_CONTEXT_RETENTION_HOURS" "$LOCAL_CONTEXT_KEEP_LAST" <<'PY'
 from __future__ import annotations
 
@@ -110,7 +121,30 @@ has_recent_local_context_backup() {
     find "$BACKUP_DIR" -maxdepth 1 -name "local-context-*.db" -mmin "-$((RECENT_BACKUP_HOURS * 60))" -print -quit | grep -q .
 }
 
-cleanup_backups
+available_backup_bytes() {
+    df -Pk "$BACKUP_DIR" 2>/dev/null | awk 'NR==2 { printf "%.0f\n", $4 * 1024 }'
+}
+
+file_size_bytes() {
+    wc -c < "$1" 2>/dev/null | tr -d ' '
+}
+
+ensure_backup_space() {
+    cleanup_backups
+    avail="$(available_backup_bytes)"
+    if [ -n "$avail" ] && [ "$avail" -lt "$MIN_FREE_BYTES" ]; then
+        echo "NEXO backup skipped: free disk below safety floor after self-cleanup (${avail}B < ${MIN_FREE_BYTES}B)" >&2
+        return 1
+    fi
+    return 0
+}
+
+if ! ensure_backup_space; then
+    if has_recent_backup; then
+        exit 0
+    fi
+    exit 1
+fi
 
 # Hourly backup
 TIMESTAMP=$(date +%Y-%m-%d-%H%M)
@@ -148,7 +182,12 @@ if [ -f "$LOCAL_CONTEXT_DB" ]; then
     LOCAL_CONTEXT_BACKUP_FILE="$BACKUP_DIR/local-context-$TIMESTAMP.db"
     LOCAL_CONTEXT_TMP_BACKUP="$LOCAL_CONTEXT_BACKUP_FILE.tmp.$$"
     rm -f "$LOCAL_CONTEXT_TMP_BACKUP"
-    if [ -f "$LOCK_FILE" ] && find "$LOCK_FILE" -mmin -30 -print -quit | grep -q . && has_recent_local_context_backup; then
+    LOCAL_CONTEXT_SIZE="$(file_size_bytes "$LOCAL_CONTEXT_DB")"
+    if [ -n "$LOCAL_CONTEXT_SIZE" ] && [ "$LOCAL_CONTEXT_SIZE" -gt "$LOCAL_CONTEXT_MAX_BACKUP_BYTES" ]; then
+        echo "NEXO local memory backup skipped: local-context.db exceeds automatic backup cap (${LOCAL_CONTEXT_SIZE}B > ${LOCAL_CONTEXT_MAX_BACKUP_BYTES}B)"
+    elif ! ensure_backup_space; then
+        echo "NEXO local memory backup skipped: free disk below safety floor"
+    elif [ -f "$LOCK_FILE" ] && find "$LOCK_FILE" -mmin -30 -print -quit | grep -q . && has_recent_local_context_backup; then
         echo "NEXO local memory backup skipped: index is active and a recent local backup exists"
     elif sqlite3 -cmd ".timeout $BUSY_TIMEOUT_MS" "$LOCAL_CONTEXT_DB" <<SQL
 PRAGMA busy_timeout=$BUSY_TIMEOUT_MS;

package/src/scripts/prune_runtime_backups.py

@@ -22,7 +22,7 @@ Class taxonomy (prefix-based) and retention policy:
     Prefixes:
       pre-update-*, pre-autoupdate-*, pre-backfill-owner-*,
       pre-runtime-sync-*, pre-sleep-wrapper-*, pre-obs-clean-*,
-      pre-import-user-data-*, pre-backfill-*,
+      pre-import-user-data-*, pre-backfill-*, pre-heal-*, pre-recover-*,
       code-tree-*, runtime-tree-*,
       app-install-*, app-reinstall-*, desktop-local-install-*,
       packaged-code-f06-conflicts-*, legacy-shim-conflicts-*,
@@ -82,6 +82,8 @@ TECHNICAL_PREFIXES = (
     "pre-sleep-wrapper-",
     "pre-obs-clean-",
     "pre-import-user-data-",
+    "pre-heal-",
+    "pre-recover-",
     "pre-freshinstall-",
     "code-tree-",
     "runtime-tree-",
@@ -108,8 +110,11 @@ TECHNICAL_PREFIXES = (
 PROTECTED_NAMES = {"shopify-backups", "weekly"}
 # Hourly DB dumps at the root of runtime/backups — managed by nexo-backup.sh.
 HOURLY_DB_RE = re.compile(r"^nexo-\d{4}-\d{2}-\d{2}-\d{4}\.db$")
+LOCAL_CONTEXT_DB_RE = re.compile(r"^local-context-\d{4}-\d{2}-\d{2}-\d{4}(\d{2})?\.db$")
+TEMPORARY_RE = re.compile(r"(^|.*[.])tmp([.-].*)?$|.*\.tmp\..*|.*-journal$|.*\.db-(wal|shm)$")
 # Big ad-hoc DB files at the root — rare, include for reporting but never auto-prune.
 ROOT_DB_RE = re.compile(r"^(pre-obs-clean|pre-sleep-wrapper-apply|pre-.*)-\d{4}-\d{2}-\d{2}-\d{4}\.db$")
+DEFAULT_MAX_BYTES = 50 * 1024 * 1024 * 1024
 
 # Timestamp patterns embedded in directory names.
 TS_PATTERNS = (
@@ -147,6 +152,10 @@ def classify(name: str) -> tuple[str, str] | None:
     """Return (class, family) or None if the entry should be ignored."""
     if name in PROTECTED_NAMES:
         return ("BUSINESS", name)
+    if TEMPORARY_RE.match(name):
+        return ("TEMPORARY", "temporary")
+    if LOCAL_CONTEXT_DB_RE.match(name):
+        return ("LOCAL_CONTEXT_DB", "local-context")
     if HOURLY_DB_RE.match(name):
         return ("HOURLY_DB", "nexo-db")
     if ROOT_DB_RE.match(name):
@@ -181,6 +190,30 @@ def human_size(n: int) -> str:
     return f"{n:.1f}P"
 
 
+def parse_size_bytes(value: str | int | None, *, default: int = DEFAULT_MAX_BYTES) -> int:
+    if value is None or value == "":
+        return default
+    if isinstance(value, int):
+        return max(0, value)
+    raw = str(value).strip().lower()
+    if not raw:
+        return default
+    multiplier = 1
+    if raw[-1:] in {"k", "m", "g", "t"}:
+        unit = raw[-1]
+        raw = raw[:-1].strip()
+        multiplier = {
+            "k": 1024,
+            "m": 1024 ** 2,
+            "g": 1024 ** 3,
+            "t": 1024 ** 4,
+        }[unit]
+    try:
+        return max(0, int(float(raw) * multiplier))
+    except ValueError:
+        return default
+
+
 def gather_entries(backups_root: Path) -> list[dict]:
     items: list[dict] = []
     for entry in backups_root.iterdir():
@@ -195,7 +228,10 @@ def gather_entries(backups_root: Path) -> list[dict]:
                 ts = datetime.fromtimestamp(entry.stat().st_mtime, tz=timezone.utc)
             except OSError:
                 ts = None
-        size = dir_size_bytes(entry) if entry.is_dir() else entry.stat().st_size
+        try:
+            size = dir_size_bytes(entry) if entry.is_dir() else entry.stat().st_size
+        except OSError:
+            continue
         items.append({
             "name": name,
             "path": str(entry),
@@ -214,11 +250,16 @@ def plan_prunes(
     n_recent: int,
     window_days: int,
     only: str | None,
+    max_bytes: int,
+    tmp_ttl_seconds: int,
+    local_context_keep: int,
+    hourly_keep: int,
 ) -> tuple[list[dict], list[dict]]:
-    """Return (to_delete, to_keep) among TECHNICAL items only."""
+    """Return (to_delete, to_keep) for product-generated backup artifacts."""
     now = datetime.now(tz=timezone.utc)
     to_delete: list[dict] = []
     to_keep: list[dict] = []
+    delete_ids: set[int] = set()
     by_family: dict[str, list[dict]] = {}
     for it in items:
         if it["class"] != "TECHNICAL":
@@ -245,8 +286,75 @@ def plan_prunes(
                     seen_months.add(ym)
                     to_keep.append(it)
                     continue
-            to_delete.append(it)
+            if id(it) not in delete_ids:
+                to_delete.append(it)
+                delete_ids.add(id(it))
         to_keep.extend(keep_recent)
+
+    for it in items:
+        if it["class"] != "TEMPORARY":
+            continue
+        ts = it["ts"]
+        age_seconds = (now - ts).total_seconds() if ts else 10_000_000
+        if age_seconds >= tmp_ttl_seconds:
+            if id(it) not in delete_ids:
+                to_delete.append(it)
+                delete_ids.add(id(it))
+        else:
+            to_keep.append(it)
+
+    for klass, keep_count in (("LOCAL_CONTEXT_DB", local_context_keep), ("HOURLY_DB", hourly_keep)):
+        group = [it for it in items if it["class"] == klass]
+        group.sort(key=lambda x: (x["ts"] or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
+        for it in group[:max(0, keep_count)]:
+            to_keep.append(it)
+        for it in group[max(0, keep_count):]:
+            if id(it) not in delete_ids:
+                to_delete.append(it)
+                delete_ids.add(id(it))
+
+    if max_bytes > 0:
+        total_after_planned = sum(i["size"] for i in items if id(i) not in delete_ids)
+        if total_after_planned > max_bytes:
+            protected_keep_ids: set[int] = set()
+            by_budget_family: dict[tuple[str, str], list[dict]] = {}
+            for it in items:
+                by_budget_family.setdefault((it["class"], it["family"]), []).append(it)
+            for (klass, _family), group in by_budget_family.items():
+                if klass not in {"TECHNICAL", "LOCAL_CONTEXT_DB", "HOURLY_DB", "TEMPORARY"}:
+                    continue
+                min_keep = 0
+                if klass == "HOURLY_DB":
+                    min_keep = max(1, hourly_keep)
+                elif klass == "LOCAL_CONTEXT_DB":
+                    min_keep = max(0, local_context_keep)
+                group.sort(key=lambda x: (x["ts"] or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
+                for it in group[:min_keep]:
+                    protected_keep_ids.add(id(it))
+
+            budget_candidates = [
+                it for it in items
+                if id(it) not in delete_ids
+                and id(it) not in protected_keep_ids
+                and it["class"] in {"TECHNICAL", "LOCAL_CONTEXT_DB", "HOURLY_DB", "TEMPORARY"}
+            ]
+            budget_candidates.sort(
+                key=lambda x: (
+                    x["ts"] or datetime.min.replace(tzinfo=timezone.utc),
+                    -int(x["size"] or 0),
+                )
+            )
+            for it in budget_candidates:
+                if total_after_planned <= max_bytes:
+                    break
+                to_delete.append(it)
+                delete_ids.add(id(it))
+                total_after_planned -= int(it["size"] or 0)
+
+    keep_ids = {id(i) for i in to_keep}
+    for it in items:
+        if id(it) not in delete_ids and id(it) not in keep_ids:
+            to_keep.append(it)
     return to_delete, to_keep
 
 
@@ -260,13 +368,20 @@ def run(args: argparse.Namespace) -> int:
     biz_items = [i for i in items if i["class"] == "BUSINESS"]
     hourly_items = [i for i in items if i["class"] == "HOURLY_DB"]
     root_db_items = [i for i in items if i["class"] == "ROOT_DB"]
+    local_context_items = [i for i in items if i["class"] == "LOCAL_CONTEXT_DB"]
+    temporary_items = [i for i in items if i["class"] == "TEMPORARY"]
     unknown_items = [i for i in items if i["class"] == "UNKNOWN"]
+    max_bytes = parse_size_bytes(args.max_bytes)
 
     to_delete, to_keep = plan_prunes(
         items,
         n_recent=args.recent,
         window_days=args.window_days,
         only=args.only,
+        max_bytes=max_bytes,
+        tmp_ttl_seconds=max(0, args.tmp_ttl_minutes) * 60,
+        local_context_keep=max(0, args.local_context_keep),
+        hourly_keep=max(0, args.hourly_keep),
     )
 
     total_all = sum(i["size"] for i in items)
@@ -279,6 +394,11 @@ def run(args: argparse.Namespace) -> int:
             "n_recent": args.recent,
             "window_days": args.window_days,
             "only": args.only,
+            "max_bytes": max_bytes,
+            "max_human": human_size(max_bytes),
+            "tmp_ttl_minutes": args.tmp_ttl_minutes,
+            "local_context_keep": args.local_context_keep,
+            "hourly_keep": args.hourly_keep,
         },
         "totals": {
             "all_bytes": total_all,
@@ -291,6 +411,8 @@ def run(args: argparse.Namespace) -> int:
             "technical": len(tech_items),
             "business": len(biz_items),
             "hourly_db": len(hourly_items),
+            "local_context_db": len(local_context_items),
+            "temporary": len(temporary_items),
             "root_db": len(root_db_items),
             "unknown": len(unknown_items),
         },
@@ -315,9 +437,11 @@ def run(args: argparse.Namespace) -> int:
         print(f"    technical:     {len(tech_items)}")
         print(f"    business:      {len(biz_items)} (protected)")
         print(f"    hourly_db:     {len(hourly_items)} (managed by nexo-backup.sh)")
+        print(f"    local_context: {len(local_context_items)}")
+        print(f"    temporary:     {len(temporary_items)}")
         print(f"    root_db:       {len(root_db_items)} (never auto-pruned)")
         print(f"    unknown:       {len(unknown_items)}")
-        print(f"  policy: keep {args.recent} most-recent + 1 per month within {args.window_days}d")
+        print(f"  policy: keep {args.recent} most-recent + 1 per month within {args.window_days}d; hard-cap {human_size(max_bytes)}")
         if args.only:
             print(f"  restricted to family: {args.only}")
         print()
@@ -364,6 +488,10 @@ def main() -> int:
     ap.add_argument("--recent", type=int, default=5, help="N most recent per family to always keep (default: 5)")
     ap.add_argument("--window-days", type=int, default=90, help="month-spaced retention window (default: 90)")
     ap.add_argument("--only", help="restrict to one technical family (e.g. 'pre-backfill-owner')")
+    ap.add_argument("--max-bytes", default=os.environ.get("NEXO_BACKUP_MAX_BYTES", str(DEFAULT_MAX_BYTES)), help="global product-generated backup hard cap, bytes or K/M/G/T (default: 50G)")
+    ap.add_argument("--tmp-ttl-minutes", type=int, default=int(os.environ.get("NEXO_BACKUP_TMP_TTL_MINUTES", "30")), help="delete orphan temporary backup files older than this (default: 30)")
+    ap.add_argument("--local-context-keep", type=int, default=int(os.environ.get("NEXO_LOCAL_CONTEXT_BACKUP_KEEP_LAST", "1")), help="local-context backup files to keep under the global cap (default: 1)")
+    ap.add_argument("--hourly-keep", type=int, default=int(os.environ.get("NEXO_BACKUP_KEEP_LAST", "3")), help="hourly nexo DB backups to keep under the global cap (default: 3)")
     args = ap.parse_args()
     try:
         return run(args)