nexo-brain 7.31.11 → 7.31.12

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.31.11",
+  "version": "7.31.12",
   "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.31.11` is the current packaged-runtime line. Patch release over v7.31.10 - MCP lifecycle robustness + guardrail precision. Version `7.31.10` was a patch release over v7.31.9 - Local Memory search now downranks boilerplate emails when stronger documents match the same query.
+Version `7.31.12` is the current packaged-runtime line. Patch release over v7.31.11 - Local Memory core hardening (Release A: defensive cosine, stable chunk ids, iCloud dataless handling, performance PRAGMAs) plus an offline-first dependency installer. Version `7.31.11` was a patch release over v7.31.10 - MCP lifecycle robustness + guardrail precision.
 
 Previously in `7.31.9`: patch release over v7.31.8 - UI release closeout now has to prove the original reported symptom was reopened with observable evidence before claiming the release is ready.
 

package/bin/nexo-brain.js

@@ -4103,6 +4103,19 @@ async function runSetup() {
     log("Try manually: python3 -m venv ~/.nexo/.venv && ~/.nexo/.venv/bin/pip install -r src/requirements.txt");
     process.exit(1);
   }
+  // Mirror the bundled wheels into NEXO_HOME so the Python runtime (startup
+  // self-heal, update, cron) can reinstall any missing dep OFFLINE later, with no
+  // access to the Desktop bundle path. auto_update._bundled_wheels_dir() looks in
+  // <NEXO_HOME>/runtime/python-wheels. Works for WSL (linux) and macOS.
+  try {
+    if (fs.existsSync(bundledWheelsDir)) {
+      const runtimeWheels = path.join(NEXO_HOME, "runtime", "python-wheels");
+      fs.mkdirSync(runtimeWheels, { recursive: true });
+      fs.cpSync(bundledWheelsDir, runtimeWheels, { recursive: true });
+    }
+  } catch (e) {
+    log("  (note) could not mirror bundled wheels into runtime: " + (e && e.message));
+  }
   // Update python reference to use venv python for the rest of setup
   if (fs.existsSync(venvPython)) {
     python = venvPython;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.31.11",
+  "version": "7.31.12",
   "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/auto_update.py

@@ -1058,8 +1058,46 @@ def _ensure_runtime_venv(runtime_root: Path = NEXO_HOME) -> Path | None:
     return None
 
 
+def _bundled_wheels_dir() -> "Path | None":
+    """Locate the bundled Python wheels for offline install.
+
+    Priority: explicit NEXO_BUNDLED_WHEELS_DIR (set by the Desktop bundle) →
+    a canonical runtime copy under NEXO_HOME. Returns the dir only if it holds
+    at least one .whl, else None (caller falls back to PyPI).
+    """
+    candidates = []
+    env_dir = os.environ.get("NEXO_BUNDLED_WHEELS_DIR", "").strip()
+    if env_dir:
+        candidates.append(Path(env_dir).expanduser())
+    candidates.append(NEXO_HOME / "runtime" / "python-wheels")
+    for directory in candidates:
+        try:
+            if directory.is_dir() and any(directory.glob("*.whl")):
+                return directory
+        except Exception:
+            continue
+    return None
+
+
+def _pip_install_argv(pip_bin, req_file, *, wheels_dir=None, use_python_m=False, break_system=False) -> list:
+    """Build a pip install argv. Offline (--no-index --find-links) when wheels_dir is set."""
+    argv = [str(pip_bin)]
+    if use_python_m:
+        argv += ["-m", "pip"]
+    argv += ["install", "--quiet", "-r", str(req_file)]
+    if wheels_dir is not None:
+        argv += ["--no-index", "--find-links", str(wheels_dir)]
+    if break_system:
+        argv.append("--break-system-packages")
+    return argv
+
+
 def _reinstall_pip_deps() -> bool:
-    """Reinstall Python deps from requirements.txt. Returns True on success."""
+    """Reinstall Python deps from requirements.txt. Returns True on success.
+
+    Prefers the bundled wheels (offline) so a user with no internet still gets a
+    self-repairing runtime; falls back to PyPI if the bundle can't satisfy it.
+    """
     req_file = SRC_DIR / "requirements.txt"
     if not req_file.exists():
         return True
@@ -1069,24 +1107,32 @@ def _reinstall_pip_deps() -> bool:
         alt_pip = NEXO_HOME / ".venv" / "bin" / "pip3"
         if alt_pip.exists():
             venv_pip = alt_pip
+    wheels_dir = _bundled_wheels_dir()
+    # Large wheel sets / slow links need more than the old 120s.
+    timeout_s = 600
+    use_python_m = not venv_pip.exists()
+    if use_python_m and desktop_product_requested():
+        _log(f"managed venv unavailable for Desktop dependency repair: {venv_python}")
+        return False
+    pip_bin = venv_pip if venv_pip.exists() else sys.executable
     try:
-        if venv_pip.exists():
-            result = subprocess.run(
-                [str(venv_pip), "install", "--quiet", "-r", str(req_file)],
-                capture_output=True, text=True, timeout=120,
-            )
-        elif not desktop_product_requested():
-            result = subprocess.run(
-                [sys.executable, "-m", "pip", "install", "--quiet", "-r", str(req_file), "--break-system-packages"],
-                capture_output=True, text=True, timeout=120,
+        argv = _pip_install_argv(
+            pip_bin, req_file, wheels_dir=wheels_dir,
+            use_python_m=use_python_m, break_system=use_python_m,
+        )
+        result = subprocess.run(argv, capture_output=True, text=True, timeout=timeout_s)
+        if result.returncode != 0 and wheels_dir is not None:
+            # Offline set couldn't satisfy it (missing/incompatible wheel) → retry online.
+            _log(f"offline pip install failed, retrying via PyPI: {result.stderr or result.stdout}")
+            argv_online = _pip_install_argv(
+                pip_bin, req_file, wheels_dir=None,
+                use_python_m=use_python_m, break_system=use_python_m,
             )
-        else:
-            _log(f"managed venv unavailable for Desktop dependency repair: {venv_python}")
-            return False
+            result = subprocess.run(argv_online, capture_output=True, text=True, timeout=timeout_s)
         if result.returncode != 0:
             _log(f"pip install failed (exit {result.returncode}): {result.stderr or result.stdout}")
             return False
-        _log("Reinstalled Python dependencies after update")
+        _log("Reinstalled Python dependencies" + (" (offline)" if wheels_dir is not None else ""))
         return True
     except Exception as e:
         _log(f"pip reinstall failed: {e}")
@@ -6107,6 +6153,18 @@ def startup_preflight(*, entrypoint: str, interactive: bool = False) -> dict:
             result["actions"].extend(extra_actions)
             if reconcile_message:
                 _log(reconcile_message)
+            # Self-heal: if the managed venv lost a critical importable module
+            # (e.g. pypdf -> PDFs indexed empty), reinstall it automatically. No
+            # user action, no prompt — the runtime repairs itself on startup.
+            try:
+                from doctor.providers.boot import check_managed_venv_modules
+
+                dep_check = check_managed_venv_modules(fix=True)
+                if getattr(dep_check, "fixed", False):
+                    result["actions"].append("venv-deps-repaired")
+                    _log(f"Managed venv dependencies repaired on startup: {dep_check.summary}")
+            except Exception as dep_exc:
+                _log(f"managed venv module check skipped: {dep_exc}")
         except Exception as e:
             result["error"] = str(e)
             _write_update_summary(result)

package/src/doctor/providers/boot.py

@@ -654,6 +654,99 @@ def check_managed_venv_python(fix: bool = False) -> DoctorCheck:
     )
 
 
+# Critical importable modules the managed venv must always have. A missing one
+# fails silently (e.g. pypdf absent -> every PDF/XLSX/MSG indexed as empty text).
+# Verified by importing INSIDE the managed venv, not the current interpreter.
+MANAGED_VENV_REQUIRED_MODULES = (
+    "fastmcp",
+    "numpy",
+    "anthropic",
+    "openai",
+    "fastembed",
+    "pypdf",
+    "openpyxl",
+    "extract_msg",
+)
+
+
+def _missing_venv_modules(venv_python: Path | str, modules) -> list[str]:
+    """Return the subset of ``modules`` that ``venv_python`` cannot import."""
+    mods = [str(m) for m in modules if str(m).strip()]
+    if not mods:
+        return []
+    probe = (
+        "import importlib.util as u, sys\n"
+        "print('\\n'.join(m for m in sys.argv[1:] if u.find_spec(m) is None))"
+    )
+    try:
+        result = subprocess.run(
+            [str(venv_python), "-c", probe, *mods],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except Exception:
+        return []
+    if result.returncode != 0:
+        return []
+    return [line.strip() for line in (result.stdout or "").splitlines() if line.strip()]
+
+
+def _repair_managed_venv_deps() -> bool:
+    try:
+        import auto_update
+
+        return bool(auto_update._reinstall_pip_deps())
+    except Exception:
+        return False
+
+
+def check_managed_venv_modules(fix: bool = False) -> DoctorCheck:
+    """Ensure the managed venv has every critical importable module.
+
+    A missing optional parser (pypdf/openpyxl/extract_msg) makes the local index
+    read PDF/XLSX/MSG as empty, silently. With ``fix=True`` (run automatically on
+    startup preflight) this reinstalls them, so the runtime repairs itself with no
+    user action.
+    """
+    venv_python = _managed_venv_python_path()
+    if not venv_python.exists():
+        # The python-version check already reports a missing venv; stay quiet here.
+        return DoctorCheck(
+            id="boot.managed_venv_modules",
+            tier="boot",
+            status="healthy",
+            severity="info",
+            summary="Managed Python venv not present yet",
+            evidence=[str(venv_python)],
+        )
+    missing = _missing_venv_modules(venv_python, MANAGED_VENV_REQUIRED_MODULES)
+    if not missing:
+        return DoctorCheck(
+            id="boot.managed_venv_modules",
+            tier="boot",
+            status="healthy",
+            severity="info",
+            summary=f"All {len(MANAGED_VENV_REQUIRED_MODULES)} critical venv modules present",
+            evidence=[str(venv_python)],
+        )
+    if fix and _repair_managed_venv_deps():
+        post = check_managed_venv_modules(fix=False)
+        if post.status == "healthy":
+            post.fixed = True
+            post.summary += " (repaired missing modules)"
+            return post
+    return DoctorCheck(
+        id="boot.managed_venv_modules",
+        tier="boot",
+        status="degraded",
+        severity="warn",
+        summary=f"{len(missing)} critical venv module(s) missing: {', '.join(missing)}",
+        evidence=[str(venv_python), *missing],
+        repair_plan=["Run nexo doctor --tier boot --fix or nexo update to reinstall managed dependencies"],
+    )
+
+
 CRITICAL_CONFIG_FILES = (
     ("schedule.json", ("config", "schedule.json")),
     ("optionals.json", ("config", "optionals.json")),
@@ -909,6 +1002,7 @@ def run_boot_checks(fix: bool = False, plane: str = "") -> list[DoctorCheck]:
         safe_check(check_wrapper_scripts),
         safe_check(check_python_runtime),
         safe_check(check_managed_venv_python, fix=fix),
+        safe_check(check_managed_venv_modules, fix=fix),
         safe_check(check_config_parse),
         safe_check(check_core_dev_packaged_install),
         safe_check(check_dashboard_desktop_contract),

package/src/local_context/api.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import errno
 import json
 import os
 import re
@@ -54,7 +55,7 @@ ENTITY_FACTS_JOB = "entity_facts"
 BACKGROUND_INDEX_JOB_TYPES = {ENTITY_FACTS_JOB}
 ENTITY_DOSSIER_MAX_ASSETS = int(os.environ.get("NEXO_ENTITY_DOSSIER_MAX_ASSETS", "500") or "500")
 ENTITY_DOSSIER_MAX_CHUNKS = int(os.environ.get("NEXO_ENTITY_DOSSIER_MAX_CHUNKS", "1200") or "1200")
-ENTITY_DOSSIER_MAX_FACTS = int(os.environ.get("NEXO_ENTITY_DOSSIER_MAX_FACTS", "3000") or "3000")
+ENTITY_DOSSIER_MAX_FACTS = int(os.environ.get("NEXO_ENTITY_DOSSIER_MAX_FACTS", "120") or "120")
 ENTITY_FACT_MIN_CONFIDENCE = float(os.environ.get("NEXO_ENTITY_FACT_MIN_CONFIDENCE", "0.45") or "0.45")
 # Hard ceilings to stop the entity_facts cartesian blow-up (chunks × entities × candidates).
 # Without these a single document could emit thousands of facts; 258k assets produced 337M rows / 255 GB.
@@ -247,7 +248,7 @@ def _conn():
 
 
 def _read_conn():
-    conn = connect_local_context_db_readonly(timeout_ms=1200)
+    conn = connect_local_context_db_readonly()
     _validate_status_schema(conn)
     return conn
 
@@ -273,7 +274,9 @@ def _with_sqlite_busy_retry(callback, *, attempts: int | None = None):
             if not _sqlite_is_busy(exc) or attempt >= max_attempts - 1:
                 raise
             last_exc = exc
-            close_local_context_db()
+            # Do NOT close the cached writer handle here: it is shared, and closing
+            # it invalidates the connection for every other caller. The busy_timeout
+            # (now in parity for readers and writer) already absorbs transient locks.
             time.sleep(DEFAULT_SQLITE_BUSY_RETRY_DELAY_SECONDS * (attempt + 1))
     if last_exc:
         raise last_exc
@@ -2288,13 +2291,49 @@ def _record_index_error(
     )
 
 
+# macOS sets SF_DATALESS on iCloud files whose data has been evicted to the
+# cloud ("Optimize Mac Storage"). stat() still works on them, but reading their
+# bytes faults in a download; from the headless index daemon that materialization
+# fails with EDEADLK. Detect the flag with pure stdlib (no pyobjc) so such files
+# can be indexed metadata-only until the user materializes them.
+SF_DATALESS = getattr(stat, "SF_DATALESS", 0x40000000)
+
+
+def _is_dataless(st) -> bool:
+    """True when a stat result carries the macOS SF_DATALESS (cloud-evicted) flag."""
+    return bool(getattr(st, "st_flags", 0) & SF_DATALESS)
+
+
+def _is_offloaded_error(exc: BaseException) -> bool:
+    """True for the EDEADLK raised when faulting in a cloud-offloaded file fails.
+
+    errno values are platform-specific (Darwin EDEADLK=11, Linux=35), so this
+    compares the symbol, never a literal.
+    """
+    return isinstance(exc, OSError) and exc.errno == errno.EDEADLK
+
+
 def _record_scan_error(conn, stats: dict | None, path: str, phase: str, exc: Exception) -> None:
+    if _is_offloaded_error(exc):
+        # Cloud-offloaded file, NOT a reliability failure: count it separately and
+        # never let it inflate the error metric or (previously) consume the budget.
+        if stats is not None:
+            stats["offloaded"] = int(stats.get("offloaded", 0) or 0) + 1
+        _record_index_error(
+            conn,
+            path=path,
+            phase=phase,
+            error_code="offloaded",
+            user_message="File is stored in iCloud and not downloaded locally",
+            technical_detail=str(exc),
+            retryable=True,
+        )
+        return
     if stats is not None:
         stats["errors"] = int(stats.get("errors", 0) or 0) + 1
-        logged = int(stats.get("_errors_logged", 0) or 0)
-        if logged >= 20:
-            return
-        stats["_errors_logged"] = logged + 1
+    # No per-run cap: the old "log at most 20" silently hid the true failure scope
+    # (a whole unreadable tree reported as just "20 errors"). The per-cycle scan
+    # limit already bounds how many rows a single run can write.
     _record_index_error(
         conn,
         path=path,
@@ -2870,7 +2909,12 @@ def _replace_chunks(conn, asset_id: str, version_id: str, text: str) -> None:
     conn.execute("DELETE FROM local_chunks WHERE asset_id=?", (asset_id,))
     conn.execute("DELETE FROM local_embeddings WHERE asset_id=?", (asset_id,))
     for index, chunk in enumerate(chunk_text(text)):
-        chunk_id = stable_id("chunk", f"{version_id}:{index}:{chunk[:80]}")
+        # Position-stable id: key on (version_id, index) ONLY, never chunk text.
+        # chunk_index already guarantees uniqueness within the batch; hashing the
+        # text used to make the id churn on every edit, which broke the
+        # entity_facts / alias dedup (UNIQUE on source_chunk_id) across re-indexing
+        # and the embedding-refresh join on chunk_id. Stable ids → idempotent reindex.
+        chunk_id = stable_id("chunk", f"{version_id}:{index}")
         conn.execute(
             """
             INSERT INTO local_chunks(chunk_id, asset_id, version_id, chunk_index, text, token_count, created_at)
@@ -3322,6 +3366,26 @@ def process_jobs(*, limit: int = 100) -> dict:
                 conn.commit()
                 continue
             if job_type == "light_extraction":
+                try:
+                    offloaded = _is_dataless(Path(row["path"]).stat())
+                except OSError:
+                    offloaded = False
+                if offloaded:
+                    # Cloud-offloaded file: index metadata-only. The asset already
+                    # carries its path/size/dates from the scan; reading the bytes
+                    # would trigger a download / EDEADLK. Reconcile re-enqueues
+                    # extraction once the fingerprint changes (user materializes it).
+                    conn.execute(
+                        "UPDATE local_assets SET phase='metadata_only', updated_at=? WHERE asset_id=?",
+                        (now(), asset_id),
+                    )
+                    conn.execute(
+                        "UPDATE local_index_jobs SET status='done', updated_at=?, last_error_code='offloaded' WHERE job_id=?",
+                        (now(), job_id),
+                    )
+                    processed += 1
+                    conn.commit()
+                    continue
                 text, metadata = extract_text(Path(row["path"]))
                 version_id = _latest_version_id(conn, asset_id)
                 if metadata.get("content_secret_detected") or contains_secret(text):
@@ -3363,6 +3427,21 @@ def process_jobs(*, limit: int = 100) -> dict:
             processed += 1
             conn.commit()
         except Exception as exc:
+            if _is_offloaded_error(exc):
+                # A file became offloaded between scan and read (or the flag was
+                # absent but the fault-in still EDEADLK'd): index it metadata-only
+                # and finish cleanly instead of retry-storming on the download.
+                conn.execute(
+                    "UPDATE local_assets SET phase='metadata_only', updated_at=? WHERE asset_id=?",
+                    (now(), asset_id),
+                )
+                conn.execute(
+                    "UPDATE local_index_jobs SET status='done', claimed_by='', lease_expires_at=NULL, last_error_code='offloaded', updated_at=? WHERE job_id=?",
+                    (now(), job_id),
+                )
+                processed += 1
+                conn.commit()
+                continue
             failed += 1
             attempts = int(row["attempt_count"] or 0) + 1
             terminal = attempts >= DEFAULT_MAX_JOB_ATTEMPTS
@@ -3748,6 +3827,33 @@ def _index_timing(conn, *, done: int, active_jobs: int, percent: int, readonly:
     return {"started_at": first_seen, "elapsed_seconds": elapsed_seconds, "eta_seconds": eta_seconds}
 
 
+BACKLOG_DRAIN_WINDOW_SECONDS = 300
+
+
+def _backlog_drain_rate(conn, *, pending: int, window_seconds: int = BACKLOG_DRAIN_WINDOW_SECONDS) -> dict:
+    """How fast the job backlog is draining, from jobs completed in a recent window.
+
+    Unlike the lifetime-average ETA in _index_timing, this reflects *current*
+    throughput, so a stalled indexer (rate→0) is visible and the ETA to clear the
+    pending backlog is honest.
+    """
+    window_seconds = max(1, int(window_seconds))
+    cutoff = now() - float(window_seconds)
+    row = conn.execute(
+        "SELECT COUNT(*) AS done FROM local_index_jobs WHERE status='done' AND updated_at >= ?",
+        (cutoff,),
+    ).fetchone()
+    completed = int((row["done"] if row else 0) or 0)
+    per_second = completed / float(window_seconds)
+    eta_seconds = int(pending / per_second) if per_second > 0 and pending > 0 else None
+    return {
+        "window_seconds": window_seconds,
+        "completed_in_window": completed,
+        "per_minute": round(per_second * 60.0, 3),
+        "eta_seconds": eta_seconds,
+    }
+
+
 def _service_scheduler_has_error(service: dict) -> bool:
     if service.get("manager") == "launchagent":
         code = str(service.get("last_exit_code") or "").strip()
@@ -3983,6 +4089,7 @@ def _status_from_conn(conn, *, readonly: bool = False) -> dict:
             "jobs_failed": failed_jobs,
             "elapsed_seconds": timing["elapsed_seconds"],
             "eta_seconds": timing["eta_seconds"],
+            "backlog_drain_rate": _backlog_drain_rate(conn, pending=pending),
             "index_started_at": index_started_at,
             "initial_scan_complete": bool(initial_index_complete),
             "initial_discovery_complete": bool(initial_scan["complete"]),
@@ -4559,7 +4666,70 @@ def _sync_context_payload_refs(payload: dict) -> None:
         payload["evidence_refs"] = []
 
 
+def _truncate_dossier_payload(payload: dict, *, max_chars: int) -> dict:
+    """Shape-aware truncation for entity_dossier payloads.
+
+    Unlike context_query payloads (assets/chunks only), a dossier also carries
+    ``facts`` and ``aggregates`` — the gold of the answer (importes, fechas). The
+    generic truncator never trimmed those, so a heavy entity overflowed max_chars
+    and fell back to an EMPTY minimal payload (learning #1234). Here we trim the
+    cheap/low-value parts first (extra chunks, low-confidence facts, extra assets)
+    while keeping ``aggregates``, ``entity``, ``recall`` and the highest-confidence
+    facts. We never empty the dossier.
+    """
+    if not max_chars or max_chars <= 0 or _payload_size(payload) <= max_chars:
+        return payload
+    warnings = list(payload.get("warnings") or [])
+    warnings.append(
+        "Entity dossier truncated to fit max_chars: lower-confidence facts and extra "
+        "chunks were trimmed. Aggregates and top facts are preserved — raise max_chars "
+        "or refine the entity for the full set."
+    )
+    payload["warnings"] = warnings
+    payload["truncated"] = True
+    payload["query"] = _compact_text(payload.get("query") or "", max_chars=240)
+    if isinstance(payload.get("candidates"), list) and len(payload["candidates"]) > 3:
+        payload["candidates"] = payload["candidates"][:3]
+    for chunk in payload.get("chunks") or []:
+        chunk["text"] = _compact_text(chunk.get("text") or "", max_chars=240)
+    facts = payload.get("facts") or []
+    if facts:
+        facts.sort(key=lambda fact: float(fact.get("confidence") or 0.0), reverse=True)
+        payload["facts"] = facts
+    # Trim cheapest-first: extra chunks -> low-confidence facts -> extra assets.
+    while _payload_size(payload) > max_chars and len(payload.get("chunks") or []) > 1:
+        payload["chunks"].pop()
+    while _payload_size(payload) > max_chars and len(payload.get("facts") or []) > 1:
+        payload["facts"].pop()
+    while _payload_size(payload) > max_chars and len(payload.get("assets") or []) > 1:
+        payload["assets"].pop()
+    if _payload_size(payload) > max_chars:
+        payload["chunks"] = (payload.get("chunks") or [])[:1]
+        aggregates = payload.get("aggregates")
+        if isinstance(aggregates, dict):
+            # Keep the gold (documents_total, numeric_by_predicate, date_range);
+            # shed only the secondary, repeatable lists.
+            aggregates["frequent_predicates"] = (aggregates.get("frequent_predicates") or [])[:5]
+            aggregates["atypical_documents"] = []
+    _sync_dossier_evidence_refs(payload)
+    payload["usage_hint"] = _context_usage_hint(payload)
+    return payload
+
+
+def _sync_dossier_evidence_refs(payload: dict) -> None:
+    refs: list[str] = []
+    for fact in payload.get("facts") or []:
+        if fact.get("source_chunk_id"):
+            refs.append(f"local_asset:{fact.get('source_asset_id')}#chunk:{fact.get('source_chunk_id')}")
+    for chunk in payload.get("chunks") or []:
+        if chunk.get("chunk_id"):
+            refs.append(f"local_asset:{chunk.get('asset_id')}#chunk:{chunk.get('chunk_id')}")
+    payload["evidence_refs"] = list(dict.fromkeys(refs))
+
+
 def _truncate_context_payload(payload: dict, *, max_chars: int) -> dict:
+    if payload.get("mode") == "entity_dossier":
+        return _truncate_dossier_payload(payload, max_chars=max_chars)
     if not max_chars or max_chars <= 0 or _payload_size(payload) <= max_chars:
         return payload
     warnings = list(payload.get("warnings") or [])
@@ -4859,6 +5029,8 @@ def _context_query_conn(
     evidence_refs = []
     seen_assets = set()
     for score, row in scored[: int(limit)]:
+        if contains_secret(str(row["text"] or "")):
+            continue  # defense-in-depth: never egress a chunk carrying a secret
         if row["asset_id"] not in seen_assets:
             assets.append({
                 "asset_id": row["asset_id"],
@@ -4890,7 +5062,7 @@ def _context_query_conn(
             """,
             [*asset_ids, int(limit) * 3],
         ).fetchall()
-        relations_payload = [dict(row) for row in relation_rows]
+        relations_payload = _egress_safe_relations(relation_rows)
     warnings = list(mode_warnings)
     if query_embedding.get("kind") == "deterministic_embedding":
         warnings.append("Local semantic model unavailable; using deterministic fallback until models are installed.")
@@ -5347,6 +5519,17 @@ def get_asset(asset_id: str, *, readonly: bool = True) -> dict:
             _close_read_conn(conn)
 
 
+def _egress_safe_relations(rows) -> list[dict]:
+    """Drop relations whose evidence text carries a secret (defense-in-depth)."""
+    safe: list[dict] = []
+    for row in rows:
+        record = dict(row)
+        if contains_secret(str(record.get("evidence") or "")):
+            continue
+        safe.append(record)
+    return safe
+
+
 def get_neighbors(asset_id: str, *, limit: int = 30, readonly: bool = True) -> dict:
     conn = _read_conn() if readonly else _conn()
     try:
@@ -5359,7 +5542,7 @@ def get_neighbors(asset_id: str, *, limit: int = 30, readonly: bool = True) -> d
             """,
             (asset_id, int(limit)),
         ).fetchall()
-        return {"ok": True, "relations": [dict(row) for row in rows]}
+        return {"ok": True, "relations": _egress_safe_relations(rows)}
     finally:
         if readonly:
             _close_read_conn(conn)

package/src/local_context/db.py

@@ -80,10 +80,23 @@ def _connect(db_path: Path) -> sqlite3.Connection:
     conn.execute("PRAGMA journal_mode=WAL")
     conn.execute("PRAGMA synchronous=NORMAL")
     conn.execute("PRAGMA temp_store=MEMORY")
+    # Performance PRAGMAs for the index DB: it sees bursty writes from the 60s
+    # cron indexer while read-only retrieval queries run concurrently.
+    # - wal_autocheckpoint above the 1000-page default → fewer checkpoints during
+    #   indexing bursts, WAL still bounded (~8 MB @ 4 KB pages).
+    # - mmap_size 256 MB → memory-mapped reads for the read-heavy workload.
+    # - cache_size -16000 → 16 MB page cache (negative = KiB), up from 2 MB.
+    conn.execute("PRAGMA wal_autocheckpoint=2000")
+    conn.execute("PRAGMA mmap_size=268435456")
+    conn.execute("PRAGMA cache_size=-16000")
     return conn
 
 
-def connect_local_context_db_readonly(*, timeout_ms: int = 1200) -> sqlite3.Connection:
+def connect_local_context_db_readonly(*, timeout_ms: int | None = None) -> sqlite3.Connection:
+    # Parity with the writer: readers must wait as long as the writer can hold the
+    # lock, otherwise they raise 'database is locked' prematurely under load.
+    if timeout_ms is None:
+        timeout_ms = _busy_timeout_ms()
     db_path = local_context_db_path()
     if not db_path.is_file():
         raise FileNotFoundError(str(db_path))

package/src/local_context/embeddings.py

@@ -132,6 +132,23 @@ def embed_text(text: str) -> list[float]:
 
 
 def cosine(a: list[float], b: list[float]) -> float:
+    # Defensive cosine: normalize at comparison time WITHOUT re-embedding.
+    # The fallback hash embedding is already L2-normalized and fastembed
+    # L2-normalizes its output too, so a bare dot product happens to be correct
+    # today — but it silently breaks the moment a model that does not normalize
+    # is swapped in (e.g. e5-small needs custom ONNX MEAN-pool + normalize).
+    # Dividing by the product of norms keeps the score bounded to [-1, 1] for
+    # any vectors, which is what the api.py max() fusion against lexical scores
+    # in [0, 1] relies on. For already-unit vectors this is a no-op.
     if not a or not b or len(a) != len(b):
         return 0.0
-    return float(sum(x * y for x, y in zip(a, b)))
+    dot = 0.0
+    norm_a = 0.0
+    norm_b = 0.0
+    for x, y in zip(a, b):
+        dot += x * y
+        norm_a += x * x
+        norm_b += y * y
+    if norm_a <= 0.0 or norm_b <= 0.0:
+        return 0.0
+    return float(dot / math.sqrt(norm_a * norm_b))

package/src/local_context/extractors.py

@@ -272,7 +272,12 @@ def _extract_pdf(path: Path) -> str:
 
 
 def clean_text(text: str) -> str:
-    text = html.unescape(text or "")
+    text = text or ""
+    # Drop the CONTENT of style/script/head blocks (not just their tags) BEFORE
+    # stripping tags, or CSS/JS boilerplate survives as text and poisons chunks,
+    # embeddings, NER and facts (e.g. 'mso-table-lspace', 'font-family').
+    text = re.sub(r"(?is)<(style|script|head)\b[^>]*>.*?</\1>", " ", text)
+    text = html.unescape(text)
     text = re.sub(r"<[^>]+>", " ", text)
     text = re.sub(r"\s+", " ", text).strip()
     return text[:MAX_CHARS]

package/src/local_context/privacy.py

@@ -371,6 +371,24 @@ def _is_home_hidden_path(path: str) -> bool:
     return bool(rel.parts) and rel.parts[0].startswith(".")
 
 
+def _name_has_sensitive_marker(name: str, stem: str) -> bool:
+    """Token match (not substring) so 'secret' does not flag 'secretaria'/'secreto'."""
+    import re
+
+    norm = re.sub(r"[^a-z0-9]+", "_", f"{name}_{stem}".lower()).strip("_")
+    if not norm:
+        return False
+    tokens = set(norm.split("_"))
+    padded = f"_{norm}_"
+    for marker in SENSITIVE_NAME_MARKERS:
+        if "_" in marker:
+            if f"_{marker}_" in padded:
+                return True
+        elif marker in tokens:
+            return True
+    return False
+
+
 def is_sensitive_path(path: str) -> bool:
     p = Path(path)
     lowered = _normalized(path)
@@ -389,7 +407,7 @@ def is_sensitive_path(path: str) -> bool:
         return True
     if parts & SENSITIVE_PARTS:
         return True
-    if any(marker in name or marker in stem for marker in SENSITIVE_NAME_MARKERS):
+    if _name_has_sensitive_marker(name, stem):
         return True
     return _contains_path_marker(lowered, SENSITIVE_PARTS)
 

package/src/plugins/update.py

@@ -913,25 +913,29 @@ def _reinstall_pip_deps() -> str | None:
         alt_pip = NEXO_HOME / ".venv" / "bin" / "pip3"
         if alt_pip.exists():
             venv_pip = alt_pip
+    # Offline-first: prefer the bundled wheels, fall back to PyPI. Shared with
+    # auto_update so install / update / self-heal all behave identically.
+    from auto_update import _bundled_wheels_dir, _pip_install_argv
+
+    wheels_dir = _bundled_wheels_dir()
     if not venv_pip.exists():
         if desktop_product_requested():
             return "managed Desktop venv pip is unavailable after repair"
-        # No venv, try system pip with --break-system-packages
-        try:
-            result = subprocess.run(
-                [sys.executable, "-m", "pip", "install", "--quiet", "-r", str(req_file), "--break-system-packages"],
-                capture_output=True, text=True, timeout=120,
-            )
-            if result.returncode != 0:
-                return f"pip install failed: {result.stderr or result.stdout}"
-        except Exception as e:
-            return f"pip install error: {e}"
-        return None
+        pip_bin, use_python_m, break_system = sys.executable, True, True
+    else:
+        pip_bin, use_python_m, break_system = venv_pip, False, False
     try:
-        result = subprocess.run(
-            [str(venv_pip), "install", "--quiet", "-r", str(req_file)],
-            capture_output=True, text=True, timeout=120,
+        argv = _pip_install_argv(
+            pip_bin, req_file, wheels_dir=wheels_dir,
+            use_python_m=use_python_m, break_system=break_system,
         )
+        result = subprocess.run(argv, capture_output=True, text=True, timeout=600)
+        if result.returncode != 0 and wheels_dir is not None:
+            argv_online = _pip_install_argv(
+                pip_bin, req_file, wheels_dir=None,
+                use_python_m=use_python_m, break_system=break_system,
+            )
+            result = subprocess.run(argv_online, capture_output=True, text=True, timeout=600)
         if result.returncode != 0:
             return f"pip install failed: {result.stderr or result.stdout}"
     except Exception as e:

package/src/requirements.txt

@@ -17,10 +17,23 @@ anthropic>=0.80.0
 openai>=2.20.0
 
 # Embedding model (optional but recommended for cognitive features).
-# Pin >=0.8.0: older releases require Python <3.12 and pip iterates each
-# obsolete version for ~10 min on Ubuntu 24.04 (Python 3.12) before finding
-# a compatible one. Verified empirically during Win11 clean install bootstrap.
-fastembed>=0.8.0
+# Hard-pinned (==) so the offline wheel bundle (fetch-python-wheels.sh) is
+# reproducible across Win+Mac. onnxruntime is fastembed's transitive native
+# wheel — the fragile, platform-specific one — so it is pinned explicitly too;
+# floating it lets pip resolve an unbundled build and break offline installs.
+# >=0.8.0 was the floor (older releases need Python <3.12 and pip iterates each
+# obsolete version for ~10 min on Ubuntu 24.04 before finding a compatible one,
+# verified during Win11 clean install bootstrap); 0.8.0 is the bundled version.
+fastembed==0.8.0
+onnxruntime==1.26.0
+
+# Local Context Layer — document parsers (REQUIRED for the local memory index).
+# extractors.py imports these lazily; without them a clean bundle silently indexes
+# every PDF / XLSX / MSG as EMPTY text (the try/except returns ''). Real bug: on a
+# clean venv `import pypdf` raised ModuleNotFoundError and all invoices read blank.
+pypdf>=4.0
+openpyxl>=3.1
+extract-msg>=0.48
 
 # Dashboard (optional, only needed for `python -m dashboard.app`)
 fastapi

package/src/scripts/nexo-immune.py

@@ -342,20 +342,31 @@ def check_launch_agents():
         }]
     results = []
 
-    # Get list of loaded agents
+    # Get list of loaded agents and their last exit status.
     rc, stdout, _ = run_cmd("launchctl list")
     loaded_labels = set()
+    launch_statuses = {}
     if rc == 0:
         for line in stdout.splitlines():
             parts = line.split("\t")
             if len(parts) >= 3:
-                loaded_labels.add(parts[2])
+                pid, last_status, label = parts[0], parts[1], parts[2]
+                loaded_labels.add(label)
+                if label.startswith("com.nexo."):
+                    launch_statuses[label] = {
+                        "pid": pid,
+                        "last_status": last_status,
+                    }
 
     for agent in EXPECTED_AGENTS:
         result = {"name": agent, "status": "OK", "detail": "", "repaired": False}
 
         if agent in loaded_labels:
             result["detail"] = "Loaded"
+            last_status = launch_statuses.get(agent, {}).get("last_status", "0")
+            if last_status not in ("0", ""):
+                result["status"] = "WARN"
+                result["detail"] = f"Loaded, last exit status={last_status}"
         else:
             # Try auto-repair
             plist = LAUNCH_AGENTS_DIR / f"{agent}.plist"
@@ -374,6 +385,20 @@ def check_launch_agents():
 
         results.append(result)
 
+    expected_set = set(EXPECTED_AGENTS)
+    for label, status_info in sorted(launch_statuses.items()):
+        if label in expected_set:
+            continue
+        last_status = status_info.get("last_status", "0")
+        if last_status in ("0", ""):
+            continue
+        results.append({
+            "name": label,
+            "status": "WARN",
+            "detail": f"Loaded, last exit status={last_status}",
+            "repaired": False,
+        })
+
     return results
 
 

package/src/server.py

@@ -1437,7 +1437,7 @@ def nexo_entity_dossier(
     query: str,
     max_assets: int = 500,
     max_chunks: int = 1200,
-    max_facts: int = 3000,
+    max_facts: int = 120,
     max_chars: int = 20000,
 ) -> str:
     """Build a full local dossier for one entity with aggregates and evidence."""