nexo-brain 3.0.0 → 3.0.2

package/.claude-plugin/plugin.json

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

@@ -50,7 +50,7 @@ That means NEXO now manages not only the shared runtime and MCP wiring, but also
 
 Versions `2.6.14` through `2.7.0` established the practical shared-brain baseline: managed Claude/Codex bootstrap, Codex config sync, transcript-aware Deep Sleep, 60-day long-horizon analysis, weekly/monthly summary artifacts, retrieval auto-mode, and the first measured engineering loop.
 
-Version `3.0.0` closes the next execution gap:
+Versions `3.0.0` and `3.0.1` close the next execution gap:
 
 - protocol discipline is now a runtime contract, not just instructions:
   - `nexo_task_open`
@@ -982,6 +982,26 @@ If NEXO Brain is useful to you, consider:
 
 ## Changelog
 
+### v3.0.1 — Python 3.10 Compatibility Patch (2026-04-06)
+- Restored Python 3.10 compatibility by replacing Python 3.11-only `datetime.UTC` with `timezone.utc`.
+- Added `tomllib` → `tomli` fallback plus declared runtime dependency for Python < 3.11.
+- Boot doctor now validates all critical JSON config artifacts: `schedule.json`, `optionals.json`, `crons/manifest.json`.
+
+### v3.0.0 — Protocol Discipline, Durable Execution, Measured Runtime (2026-04-06)
+- **Protocol discipline runtime**: Enforceable `nexo_task_open`/`nexo_task_close`, persistent `protocol_debt`, `Cortex` gates with durable `check_id`, conditioned-file guardrails across Claude hooks and Codex transcript audits.
+- **Durable workflow runtime**: `nexo_workflow_open`/`update`/`resume`/`replay`/`list` with persistent runs, steps, checkpoints, replay history, retry bookkeeping, and idempotent open keys.
+- **Durable goals**: `nexo_goal_open`/`update`/`get`/`list` for long-running work that stays active/blocked/abandoned/completed.
+- **Operational truth**: Deep Sleep survives schema drift, `keep_alive` reports alive/degraded/duplicated honestly, warning storms no longer count as healthy.
+- **Measured product surface**: 5-minute quickstart, Python SDK, reference verticals, measured compare scorecard with LoCoMo baselines and `cost_per_solved_task`.
+- **Skill lifecycle**: Testing, promotion, retirement, and composition flows. Evolution public-core peer-review for opt-in PRs.
+
+### v2.7.0 — Shared Brain Baseline (2026-04-06)
+- Managed Claude Code + Codex bootstrap with explicit `CORE`/`USER` contract.
+- Codex config sync and transcript-aware Deep Sleep across both clients.
+- 60-day long-horizon analysis, weekly/monthly summary artifacts.
+- Retrieval auto-mode and first measured engineering loop.
+- `nexo chat` opens the configured client instead of assuming Claude Code.
+
 ### v2.6.9 — Integration Sync, CI/CD Pipeline (2026-04-04)
 - **Release artifact sync**: Automated version synchronization across Claude Code plugin, OpenClaw package, and ClawHub skill before every publish.
 - **CI/CD pipeline**: Full GitHub Actions workflow for publish + verification of all integration channels.

package/package.json

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

@@ -9,9 +9,13 @@ import shutil
 import subprocess
 import tempfile
 import time
-import tomllib
 from pathlib import Path
 
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python < 3.11
+    import tomli as tomllib
+
 from client_preferences import (
     BACKEND_NONE,
     CLIENT_CLAUDE_CODE,

package/src/auto_update.py

@@ -311,14 +311,21 @@ def _backup_dbs() -> str | None:
 
     backup_dir.mkdir(parents=True, exist_ok=True)
     for db_file in db_files:
+        src_conn = None
+        dst_conn = None
         try:
             src_conn = sqlite3.connect(str(db_file))
             dst_conn = sqlite3.connect(str(backup_dir / db_file.name))
             src_conn.backup(dst_conn)
-            dst_conn.close()
-            src_conn.close()
         except Exception as e:
             _log(f"DB backup warning ({db_file.name}): {e}")
+        finally:
+            for conn in (dst_conn, src_conn):
+                if conn is not None:
+                    try:
+                        conn.close()
+                    except Exception:
+                        pass
     return str(backup_dir)
 
 
@@ -331,15 +338,22 @@ def _restore_dbs(backup_dir: str):
     for db_backup in bdir.glob("*.db"):
         for candidate in [DATA_DIR / db_backup.name, NEXO_HOME / db_backup.name, SRC_DIR / db_backup.name]:
             if candidate.is_file():
+                src_conn = None
+                dst_conn = None
                 try:
                     src_conn = sqlite3.connect(str(db_backup))
                     dst_conn = sqlite3.connect(str(candidate))
                     src_conn.backup(dst_conn)
-                    dst_conn.close()
-                    src_conn.close()
                     _log(f"Restored DB: {db_backup.name}")
                 except Exception as e:
                     _log(f"DB restore warning ({db_backup.name}): {e}")
+                finally:
+                    for conn in (dst_conn, src_conn):
+                        if conn is not None:
+                            try:
+                                conn.close()
+                            except Exception:
+                                pass
                 break
 
 
@@ -626,6 +640,10 @@ def _run_file_migration(path: Path) -> tuple[bool, str]:
 def run_file_migrations() -> list[dict]:
     """Run any pending file-based migrations from the migrations/ directory.
 
+    Migrations are ordered and sequential: if migration N fails, all subsequent
+    migrations are skipped so that N is retried on the next startup and no
+    migration is permanently skipped by a version-pointer gap.
+
     Returns list of results: [{"version": N, "file": "...", "status": "ok"|"failed", "message": "..."}]
     """
     current_version = _get_applied_migration_version()
@@ -655,8 +673,7 @@ def run_file_migrations() -> list[dict]:
                 "message": message,
             })
             _log(f"Migration {path.name}: FAILED — {message}")
-            # Don't advance version past a failure, but continue trying others
-            # so independent migrations still run. Version stays at last success.
+            break  # Stop on first failure so it retries next startup
 
     return results
 

package/src/client_preferences.py

@@ -5,9 +5,13 @@ from __future__ import annotations
 import os
 import shutil
 import sys
-import tomllib
 from pathlib import Path
 
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python < 3.11
+    import tomli as tomllib
+
 from runtime_power import load_schedule_config, save_schedule_config
 
 

package/src/client_sync.py

@@ -10,9 +10,13 @@ import shlex
 import shutil
 import subprocess
 import sys
-import tomllib
 from pathlib import Path
 
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python < 3.11
+    import tomli as tomllib
+
 from bootstrap_docs import sync_client_bootstrap
 
 try:

package/src/cognitive/_memory.py

@@ -1,7 +1,14 @@
 """NEXO Cognitive — Memory operations: format, stats, consolidation, somatic."""
 import json, math, re
 import numpy as np
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
+
+
+def _utcnow_naive() -> datetime:
+    """Timezone-aware UTC clock returned as a naive datetime to preserve
+    the legacy ``datetime.utcnow()`` string format on disk.
+    """
+    return datetime.now(timezone.utc).replace(tzinfo=None)
 from cognitive._core import _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob, EMBEDDING_DIM, DISCRIMINATING_ENTITIES
 from cognitive._ingest import _sanitize_memory_content
 
@@ -74,7 +81,7 @@ def get_metrics(days: int = 7) -> dict:
         score_distribution: histogram buckets [<0.5, 0.5-0.6, 0.6-0.7, 0.7-0.8, >0.8]
     """
     db = _get_db()
-    cutoff = (datetime.utcnow() - timedelta(days=days)).isoformat()
+    cutoff = (_utcnow_naive() - timedelta(days=days)).isoformat()
 
     rows = db.execute(
         "SELECT top_score FROM retrieval_log WHERE created_at >= ?", (cutoff,)
@@ -130,7 +137,7 @@ def check_repeat_errors() -> dict:
     Returns count of new learnings that are semantically duplicate (cosine > 0.8).
     """
     db = _get_db()
-    cutoff_7d = (datetime.utcnow() - timedelta(days=7)).isoformat()
+    cutoff_7d = (_utcnow_naive() - timedelta(days=7)).isoformat()
 
     # Recent learning STM entries
     new_learnings = db.execute(
@@ -192,7 +199,7 @@ def rehearse_by_content(content_keywords: str, source_type: str = ""):
         if np.linalg.norm(query_vec) == 0:
             return
 
-        now = datetime.utcnow().isoformat()
+        now = _utcnow_naive().isoformat()
 
         # Search both stores for matches >= 0.7
         for table in ("stm_memories", "ltm_memories"):
@@ -803,7 +810,7 @@ def security_scan(content: str) -> dict:
 def somatic_accumulate(target: str, target_type: str, delta: float):
     """Increase risk_score for a target (file or area). Capped at 1.0."""
     db = _get_db()
-    now = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
+    now = _utcnow_naive().strftime("%Y-%m-%dT%H:%M:%S")
     existing = db.execute(
         "SELECT id, risk_score, incident_count FROM somatic_markers WHERE target = ? AND target_type = ?",
         (target, target_type)
@@ -827,8 +834,8 @@ def somatic_accumulate(target: str, target_type: str, delta: float):
 def somatic_guard_decay(target: str, target_type: str):
     """Validated recovery: multiplicative x0.7 on successful guard check. Max once/day/target."""
     db = _get_db()
-    today = datetime.utcnow().strftime("%Y-%m-%d")
-    now = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
+    today = _utcnow_naive().strftime("%Y-%m-%d")
+    now = _utcnow_naive().strftime("%Y-%m-%dT%H:%M:%S")
     row = db.execute(
         "SELECT id, risk_score, last_guard_decay_date FROM somatic_markers WHERE target = ? AND target_type = ?",
         (target, target_type)

package/src/cognitive/_search.py

@@ -3,7 +3,14 @@ import math
 import re
 import sqlite3
 import numpy as np
-from datetime import datetime
+from datetime import datetime, timezone
+
+
+def _utcnow_naive() -> datetime:
+    """Timezone-aware UTC clock returned as a naive datetime to preserve
+    the legacy ``datetime.utcnow()`` string format on disk.
+    """
+    return datetime.now(timezone.utc).replace(tzinfo=None)
 from cognitive._core import (
     _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob,
     _get_model, _get_reranker, rerank_results, EMBEDDING_DIM,
@@ -461,7 +468,7 @@ def record_co_activation(memory_ids: list[tuple[str, int]]):
         return
 
     db = _get_db()
-    now = datetime.utcnow().isoformat()
+    now = _utcnow_naive().isoformat()
 
     hashes = [_canonical_co_id(store, mid) for store, mid in memory_ids]
 
@@ -571,7 +578,7 @@ def _match_triggers(
         text_vec = embed(text)
 
     matched_triggers = []
-    now = datetime.utcnow().isoformat()
+    now = _utcnow_naive().isoformat()
 
     for trigger in armed:
         pattern = trigger["trigger_pattern"].lower()
@@ -667,7 +674,7 @@ def rearm_trigger(trigger_id: int) -> str:
 
 def _auto_restore_snoozed(db: sqlite3.Connection):
     """Restore snoozed memories whose snooze_until date has passed."""
-    now = datetime.utcnow().isoformat()
+    now = _utcnow_naive().isoformat()
     for table in ("stm_memories", "ltm_memories"):
         db.execute(
             f"UPDATE {table} SET lifecycle_state = 'active', snooze_until = NULL "
@@ -682,7 +689,7 @@ def _rehearse_results(results: list[dict], skip_ids: set = None):
     if not results:
         return
     db = _get_db()
-    now = datetime.utcnow().isoformat()
+    now = _utcnow_naive().isoformat()
     skip = skip_ids or set()
     for r in results:
         if (r["store"], r["id"]) in skip:

package/src/crons/sync.py

@@ -446,7 +446,8 @@ StandardError=append:{stderr_log}
             s = cron["schedule"]
             h, m = s.get("hour", 0), s.get("minute", 0)
             if "weekday" in s:
-                days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+                # Manifest weekday uses launchd convention: 0=Sunday … 6=Saturday (7=Sunday alias)
+                days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
                 timer_spec = f"OnCalendar={days[s['weekday']]} *-*-* {h:02d}:{m:02d}:00"
             else:
                 timer_spec = f"OnCalendar=*-*-* {h:02d}:{m:02d}:00"

package/src/dashboard/app.py

@@ -30,7 +30,7 @@ if _PARENT not in sys.path:
 
 from agent_runner import AgentRunnerError, build_followup_terminal_shell_command
 
-app = FastAPI(title="NEXO Brain Dashboard", version="3.0.0")
+app = FastAPI(title="NEXO Brain Dashboard", version="3.0.1")
 
 TEMPLATES_DIR = Path(__file__).resolve().parent / "templates"
 STATIC_DIR = Path(__file__).resolve().parent / "static"

package/src/db/_workflow.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import json
 import secrets
 import time
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 
 from db._core import get_db
 
@@ -48,7 +48,7 @@ def _workflow_goal_id() -> str:
 
 
 def _now_sql() -> str:
-    return datetime.now(UTC).strftime("%Y-%m-%d %H:%M:%S")
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
 
 
 def _as_json(value, default):

package/src/doctor/models.py

@@ -1,7 +1,9 @@
 """Doctor data models — check results and report structure."""
 from __future__ import annotations
 
+import traceback
 from dataclasses import dataclass, field
+from typing import Callable
 
 
 @dataclass
@@ -42,3 +44,26 @@ class DoctorReport:
             "critical": statuses.count("critical"),
             "total": len(statuses),
         }
+
+
+def safe_check(fn: Callable[..., DoctorCheck], *args, **kwargs) -> DoctorCheck:
+    """Run a single check function, returning a crash DoctorCheck on exception.
+
+    This isolates individual checks so one failure doesn't take down
+    all sibling checks within a tier.
+    """
+    try:
+        return fn(*args, **kwargs)
+    except Exception as exc:
+        tb = traceback.format_exception(type(exc), exc, exc.__traceback__)
+        last_frame = tb[-1].strip() if tb else str(exc)
+        check_name = getattr(fn, "__name__", "unknown")
+        return DoctorCheck(
+            id=f"check.{check_name}_crashed",
+            tier="unknown",
+            status="critical",
+            severity="error",
+            summary=f"Check {check_name} crashed: {type(exc).__name__}: {exc}",
+            evidence=[last_frame],
+            repair_plan=[f"Investigate {check_name} — exception during check execution"],
+        )

package/src/doctor/orchestrator.py

@@ -1,9 +1,11 @@
 """Doctor orchestrator — runs providers by tier, aggregates results."""
 from __future__ import annotations
 
+import sys
 import time
+import traceback
 
-from doctor.models import DoctorReport
+from doctor.models import DoctorCheck, DoctorReport
 from doctor.providers.boot import run_boot_checks
 from doctor.providers.runtime import run_runtime_checks
 from doctor.providers.deep import run_deep_checks
@@ -17,6 +19,8 @@ _TIER_RUNNERS = {
 
 _TIER_ORDER = ["boot", "runtime", "deep"]
 
+VALID_TIERS = frozenset(_TIER_ORDER) | {"all"}
+
 
 def run_doctor(tier: str = "boot", fix: bool = False) -> DoctorReport:
     """Run diagnostic checks for the specified tier(s).
@@ -28,14 +32,40 @@ def run_doctor(tier: str = "boot", fix: bool = False) -> DoctorReport:
     report = DoctorReport(overall_status="healthy")
     start = time.monotonic()
 
+    if tier not in VALID_TIERS:
+        report.add(DoctorCheck(
+            id="orchestrator.invalid_tier",
+            tier="orchestrator",
+            status="critical",
+            severity="error",
+            summary=f"Unknown tier '{tier}' — valid options: {', '.join(sorted(VALID_TIERS))}",
+        ))
+        report.compute_status()
+        report.duration_ms = int((time.monotonic() - start) * 1000)
+        return report
+
     tiers = _TIER_ORDER if tier == "all" else [tier]
 
     for t in tiers:
         runner = _TIER_RUNNERS.get(t)
-        if runner:
+        if not runner:
+            continue
+        try:
             checks = runner(fix=fix)
             for check in checks:
                 report.add(check)
+        except Exception as exc:
+            tb = traceback.format_exception(type(exc), exc, exc.__traceback__)
+            last_frame = tb[-1].strip() if tb else str(exc)
+            report.add(DoctorCheck(
+                id=f"orchestrator.{t}_crashed",
+                tier=t,
+                status="critical",
+                severity="error",
+                summary=f"{t} tier checks crashed: {type(exc).__name__}: {exc}",
+                evidence=[last_frame],
+                repair_plan=[f"Investigate {t} provider — exception during check execution"],
+            ))
 
     report.compute_status()
     report.duration_ms = int((time.monotonic() - start) * 1000)

package/src/doctor/providers/boot.py

@@ -6,7 +6,7 @@ import shutil
 import sys
 from pathlib import Path
 
-from doctor.models import DoctorCheck
+from doctor.models import DoctorCheck, safe_check
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 
@@ -148,47 +148,73 @@ def check_python_runtime() -> DoctorCheck:
     )
 
 
+CRITICAL_CONFIG_FILES = (
+    ("schedule.json", ("config", "schedule.json")),
+    ("optionals.json", ("config", "optionals.json")),
+    ("crons/manifest.json", ("crons", "manifest.json")),
+)
+
+
 def check_config_parse() -> DoctorCheck:
-    """Check schedule.json parses correctly if present."""
-    schedule_file = NEXO_HOME / "config" / "schedule.json"
-    if not schedule_file.exists():
+    """Validate that critical JSON config files parse correctly."""
+    import json
+
+    errors: list[str] = []
+    checked: list[str] = []
+
+    for label, relative in CRITICAL_CONFIG_FILES:
+        path = NEXO_HOME.joinpath(*relative)
+        if not path.exists():
+            continue
+        try:
+            data = json.loads(path.read_text())
+        except Exception as exc:
+            errors.append(f"{label}: {exc}")
+            continue
+        if not isinstance(data, dict):
+            errors.append(f"{label}: expected JSON object, got {type(data).__name__}")
+            continue
+        checked.append(label)
+
+    if errors:
         return DoctorCheck(
             id="boot.config_parse",
             tier="boot",
-            status="healthy",
-            severity="info",
-            summary="No schedule.json (using defaults)",
+            status="degraded",
+            severity="warn",
+            summary=f"{len(errors)} config file parse error" + ("s" if len(errors) != 1 else ""),
+            evidence=errors,
+            repair_plan=["Fix JSON syntax in the listed config files, or delete them to fall back to defaults"],
         )
-    try:
-        import json
-        json.loads(schedule_file.read_text())
+
+    if not checked:
         return DoctorCheck(
             id="boot.config_parse",
             tier="boot",
             status="healthy",
             severity="info",
-            summary="schedule.json parses OK",
-        )
-    except Exception as e:
-        return DoctorCheck(
-            id="boot.config_parse",
-            tier="boot",
-            status="degraded",
-            severity="warn",
-            summary=f"schedule.json parse error: {e}",
-            repair_plan=["Fix JSON syntax in schedule.json or delete to use defaults"],
+            summary="No config files present (using defaults)",
         )
 
+    return DoctorCheck(
+        id="boot.config_parse",
+        tier="boot",
+        status="healthy",
+        severity="info",
+        summary=f"{len(checked)} config file" + ("s" if len(checked) != 1 else "") + " parse OK",
+        evidence=checked,
+    )
+
 
 def run_boot_checks(fix: bool = False) -> list[DoctorCheck]:
     """Run all boot-tier checks."""
     checks = [
-        check_db_exists(),
-        check_required_dirs(),
-        check_disk_space(),
-        check_wrapper_scripts(),
-        check_python_runtime(),
-        check_config_parse(),
+        safe_check(check_db_exists),
+        safe_check(check_required_dirs),
+        safe_check(check_disk_space),
+        safe_check(check_wrapper_scripts),
+        safe_check(check_python_runtime),
+        safe_check(check_config_parse),
     ]
 
     if fix:

package/src/doctor/providers/deep.py

@@ -6,7 +6,7 @@ import os
 import time
 from pathlib import Path
 
-from doctor.models import DoctorCheck
+from doctor.models import DoctorCheck, safe_check
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 
@@ -106,8 +106,10 @@ def check_schema_version() -> DoctorCheck:
                 summary="No database to check schema",
             )
         conn = sqlite3.connect(str(db_path), timeout=2)
-        version = conn.execute("PRAGMA user_version").fetchone()[0]
-        conn.close()
+        try:
+            version = conn.execute("PRAGMA user_version").fetchone()[0]
+        finally:
+            conn.close()
         return DoctorCheck(
             id="deep.schema_version",
             tier="deep",
@@ -250,20 +252,21 @@ def check_learning_count() -> DoctorCheck:
                 summary="No DB to check learnings",
             )
         conn = sqlite3.connect(str(db_path), timeout=2)
-        tables = conn.execute(
-            "SELECT name FROM sqlite_master WHERE type='table' AND name='learnings'"
-        ).fetchone()
-        if not tables:
+        try:
+            tables = conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='learnings'"
+            ).fetchone()
+            if not tables:
+                return DoctorCheck(
+                    id="deep.learning_count",
+                    tier="deep",
+                    status="healthy",
+                    severity="info",
+                    summary="No learnings table yet",
+                )
+            count = conn.execute("SELECT COUNT(*) FROM learnings WHERE archived=0").fetchone()[0]
+        finally:
             conn.close()
-            return DoctorCheck(
-                id="deep.learning_count",
-                tier="deep",
-                status="healthy",
-                severity="info",
-                summary="No learnings table yet",
-            )
-        count = conn.execute("SELECT COUNT(*) FROM learnings WHERE archived=0").fetchone()[0]
-        conn.close()
         return DoctorCheck(
             id="deep.learning_count",
             tier="deep",
@@ -284,9 +287,9 @@ def check_learning_count() -> DoctorCheck:
 def run_deep_checks(fix: bool = False) -> list[DoctorCheck]:
     """Run all deep-tier checks. Read-only."""
     return [
-        check_self_audit_summary(),
-        check_schema_version(),
-        check_preflight_summary(),
-        check_watchdog_smoke(),
-        check_learning_count(),
+        safe_check(check_self_audit_summary),
+        safe_check(check_schema_version),
+        safe_check(check_preflight_summary),
+        safe_check(check_watchdog_smoke),
+        safe_check(check_learning_count),
     ]