nexo-brain 5.3.30 → 5.4.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -18,9 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `5.3.30` is the current packaged-runtime line: four read-only CLI commands (`nexo schema`, `nexo identity`, `nexo onboard`, `nexo scan-profile`) let external UIs like NEXO Desktop auto-adapt to the editable schema, canonical identity, onboarding wizard, and profile heuristics without hardcoding fields.
+Version `5.4.1` is the current packaged-runtime line: hook hygiene fix — the PostToolUse `capture-session.sh` hook had been reading a nonexistent env var since 2026-04-12, silently writing `"tool":"unknown"` to the Sensory Register for 48 hours. v5.4.1 parses the tool name from stdin JSON, removes the filter that was hiding `Bash`, and purges pre-fix entries from the buffer on update.
 
-Previously in `5.3.29`: duplicate `* 2` artifacts now fail hygiene gates instead of hiding in the tree, packaged/runtime update paths converge on one canonical core, startup preflight runs synchronously, corrupt DB state no longer respawns an empty brain by default, and cron runs spool locally when SQLite is unavailable.
+Previously in `5.4.0`: runtime event bus at `~/.nexo/runtime/events.ndjson`, `nexo notify`, `nexo health --json`, `nexo logs --tail --json`, and a safe flat→nested migration for `calibration.json`.
 
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.30",
+  "version": "5.4.1",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/calibration_migration.py

@@ -0,0 +1,242 @@
+"""Calibration migration — flat → nested schema for calibration.json.
+
+Older NEXO installations wrote calibration.json with flat top-level keys
+(user_name, autonomy, role…). The canonical shape is nested
+(user.name, personality.autonomy, meta.role). This module detects the
+flat shape and migrates to nested with a backup.
+
+Design:
+  - Backup lives at calibration.json.pre-migrate-<version>
+  - Unknown fields are preserved verbatim under `legacy_unmapped`
+  - Revert is just: cp backup → calibration.json
+  - Idempotent: if already nested, returns OK without touching the file
+
+No network, no DB. Pure file I/O so it can run from any runtime.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+
+FLAT_TO_NESTED = {
+    # user.*
+    "user_name": ("user", "name"),
+    "name": ("user", "name"),
+    "language": ("user", "language"),
+    "lang": ("user", "language"),
+    "timezone": ("user", "timezone"),
+    "tz": ("user", "timezone"),
+    "assistant_name": ("user", "assistant_name"),
+    # personality.*
+    "autonomy": ("personality", "autonomy"),
+    "communication": ("personality", "communication"),
+    "honesty": ("personality", "honesty"),
+    "proactivity": ("personality", "proactivity"),
+    "error_handling": ("personality", "error_handling"),
+    # preferences.*
+    "menu_on_demand": ("preferences", "menu_on_demand"),
+    "show_pending_items": ("preferences", "show_pending_items"),
+    "execution_first": ("preferences", "execution_first"),
+    "report_style": ("preferences", "report_style"),
+    # meta.*
+    "role": ("meta", "role"),
+    "technical_level": ("meta", "technical_level"),
+}
+
+# Keys that always live at the top level regardless of shape
+TOP_LEVEL_KEYS = {"version", "created", "mood_history", "operator_name"}
+
+
+def _calibration_path(nexo_home: Path | None = None) -> Path:
+    home = nexo_home or Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    return home / "brain" / "calibration.json"
+
+
+def _is_nested(cal: dict) -> bool:
+    """Nested shape has at least one of {user, personality, preferences, meta} as dict."""
+    for key in ("user", "personality", "preferences", "meta"):
+        if isinstance(cal.get(key), dict):
+            return True
+    return False
+
+
+def _has_flat_markers(cal: dict) -> bool:
+    """Flat shape has top-level keys that normally belong inside nested groups."""
+    for flat_key in FLAT_TO_NESTED:
+        if flat_key in cal:
+            return True
+    return False
+
+
+def detect(cal: dict | None = None, *, path: Path | None = None) -> dict:
+    """Return {'shape': 'nested'|'flat'|'mixed'|'empty', 'reason': str}."""
+    if cal is None:
+        target = path or _calibration_path()
+        if not target.is_file():
+            return {"shape": "empty", "reason": "file does not exist"}
+        try:
+            cal = json.loads(target.read_text())
+        except Exception as exc:
+            return {"shape": "empty", "reason": f"unreadable: {exc}"}
+    if not isinstance(cal, dict) or not cal:
+        return {"shape": "empty", "reason": "empty or not an object"}
+
+    nested = _is_nested(cal)
+    flat = _has_flat_markers(cal)
+    if nested and flat:
+        return {"shape": "mixed", "reason": "both nested groups and flat keys present"}
+    if nested:
+        return {"shape": "nested", "reason": "already canonical"}
+    if flat:
+        return {"shape": "flat", "reason": "top-level flat keys, no nested groups"}
+    return {"shape": "empty", "reason": "no recognizable keys"}
+
+
+def migrate(
+    cal: dict,
+    *,
+    preserve_unmapped: bool = True,
+) -> dict:
+    """Convert a flat calibration payload to nested. Returns a new dict."""
+    if _is_nested(cal) and not _has_flat_markers(cal):
+        return dict(cal)
+
+    result: dict[str, Any] = {}
+    legacy_unmapped: dict[str, Any] = {}
+
+    # Preserve nested groups already present
+    for group in ("user", "personality", "preferences", "meta"):
+        if isinstance(cal.get(group), dict):
+            result[group] = dict(cal[group])
+
+    # Preserve top-level metadata
+    for key in TOP_LEVEL_KEYS:
+        if key in cal:
+            result[key] = cal[key]
+
+    # Walk flat keys
+    for key, value in cal.items():
+        if key in ("user", "personality", "preferences", "meta"):
+            continue
+        if key in TOP_LEVEL_KEYS:
+            continue
+        if key in FLAT_TO_NESTED:
+            group, leaf = FLAT_TO_NESTED[key]
+            result.setdefault(group, {})
+            # Nested value wins over flat if both exist
+            if leaf not in result[group]:
+                result[group][leaf] = value
+        else:
+            legacy_unmapped[key] = value
+
+    if legacy_unmapped and preserve_unmapped:
+        result["legacy_unmapped"] = legacy_unmapped
+
+    # Bump version marker if present
+    if "version" not in result:
+        result["version"] = 1
+
+    return result
+
+
+def backup_path(path: Path, version: str = "5.4.0") -> Path:
+    return path.with_name(path.name + f".pre-migrate-{version}")
+
+
+def apply_migration(
+    path: Path | None = None,
+    *,
+    version: str = "5.4.0",
+    dry_run: bool = False,
+) -> dict:
+    """Migrate calibration.json on disk. Returns a status dict."""
+    target = path or _calibration_path()
+    if not target.is_file():
+        return {"status": "skipped", "reason": "calibration.json not found", "path": str(target)}
+
+    try:
+        original = json.loads(target.read_text())
+    except Exception as exc:
+        return {"status": "error", "reason": f"unreadable: {exc}", "path": str(target)}
+
+    shape = detect(original)
+    if shape["shape"] in ("nested", "empty"):
+        return {
+            "status": "noop",
+            "reason": f"already {shape['shape']}",
+            "path": str(target),
+            "shape": shape["shape"],
+        }
+
+    migrated = migrate(original)
+    if dry_run:
+        return {
+            "status": "preview",
+            "reason": "dry run",
+            "path": str(target),
+            "shape": shape["shape"],
+            "original": original,
+            "migrated": migrated,
+            "backup_would_be": str(backup_path(target, version)),
+        }
+
+    backup = backup_path(target, version)
+    try:
+        shutil.copy2(target, backup)
+    except Exception as exc:
+        return {"status": "error", "reason": f"backup failed: {exc}", "path": str(target)}
+
+    try:
+        target.write_text(json.dumps(migrated, ensure_ascii=False, indent=2))
+    except Exception as exc:
+        # Attempt revert
+        try:
+            shutil.copy2(backup, target)
+        except Exception:
+            pass
+        return {"status": "error", "reason": f"write failed: {exc}", "path": str(target)}
+
+    # Re-detect to confirm
+    post = detect(migrated)
+    if post["shape"] != "nested":
+        # Revert
+        try:
+            shutil.copy2(backup, target)
+        except Exception:
+            pass
+        return {
+            "status": "error",
+            "reason": f"post-migration shape is {post['shape']}",
+            "path": str(target),
+        }
+
+    return {
+        "status": "migrated",
+        "reason": "flat → nested",
+        "path": str(target),
+        "backup": str(backup),
+        "shape": post["shape"],
+        "migrated_at": time.time(),
+    }
+
+
+def revert(
+    path: Path | None = None,
+    *,
+    version: str = "5.4.0",
+) -> dict:
+    """Revert calibration.json to the most recent pre-migrate backup."""
+    target = path or _calibration_path()
+    backup = backup_path(target, version)
+    if not backup.is_file():
+        return {"status": "error", "reason": f"no backup found at {backup}", "path": str(target)}
+    try:
+        shutil.copy2(backup, target)
+    except Exception as exc:
+        return {"status": "error", "reason": f"copy failed: {exc}", "path": str(target)}
+    return {"status": "reverted", "from": str(backup), "path": str(target)}

package/src/cli.py

@@ -922,6 +922,40 @@ def _update(args):
                 print(f"  Model recommendation check skipped: {exc}", file=sys.stderr)
         else:
             print(f"UPDATE FAILED: {result.get('error', 'sync failed')}", file=sys.stderr)
+
+    # Auto-migrate calibration.json flat → nested once per user. Silent on
+    # no-op; logs a line if an actual migration happened.
+    try:
+        from calibration_migration import detect as _cal_detect, apply_migration as _cal_apply
+        if _cal_detect()["shape"] == "flat":
+            mig = _cal_apply()
+            if mig.get("status") == "migrated" and not args.json:
+                print(f"[NEXO] calibration.json migrated flat → nested (backup: {mig.get('backup')})",
+                      flush=True)
+    except Exception:
+        pass
+
+    # v5.4.1 one-time hygiene: purge pre-fix "tool":"unknown" entries from
+    # the sensory-register buffer. Keeps a .pre-v5.4.1.bak backup the first
+    # time it runs on a given host.
+    try:
+        buf = NEXO_HOME / "brain" / "session_buffer.jsonl"
+        marker = buf.with_suffix(".jsonl.pre-v5.4.1.bak")
+        if buf.is_file() and not marker.is_file():
+            raw = buf.read_text(errors="ignore").splitlines()
+            unknown = sum(1 for ln in raw if '"tool":"unknown"' in ln)
+            if unknown > 0:
+                buf.rename(marker)
+                cleaned = "\n".join(ln for ln in raw if '"tool":"unknown"' not in ln)
+                if cleaned:
+                    cleaned += "\n"
+                buf.write_text(cleaned)
+                if not args.json:
+                    print(f"[NEXO] session_buffer.jsonl: purged {unknown} legacy "
+                          f"\"tool\":\"unknown\" entries (backup: {marker.name})", flush=True)
+    except Exception:
+        pass
+
     return 0 if result.get("ok") else 1
 
 
@@ -1295,6 +1329,105 @@ def _chat(args):
     return int(result.returncode)
 
 
+def _notify(args):
+    """Emit an event to the runtime events bus (events.ndjson)."""
+    from events_bus import emit
+    try:
+        event = emit(
+            args.type,
+            text=getattr(args, "text", "") or "",
+            reason=getattr(args, "reason", "") or "",
+            priority=getattr(args, "priority", "normal"),
+            source=getattr(args, "source", "nexo-brain"),
+        )
+    except ValueError as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps({"ok": True, "event": event}, ensure_ascii=False, indent=2))
+    else:
+        print(f"notify: id={event['id']} type={event['type']} priority={event['priority']}")
+    return 0
+
+
+def _health(args):
+    """Collect a health snapshot and print it."""
+    from health_check import collect
+    report = collect()
+    if getattr(args, "json", True) is False:
+        # minimal text mode
+        print(f"status: {report.get('status', 'unknown')}")
+        for name, sub in report.get("subsystems", {}).items():
+            print(f"  {name:10s} {sub.get('status', '?')}")
+        return 0 if report.get("status") == "ok" else 1
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+def _logs(args):
+    """Tail recent logs: events bus + operations/*.log."""
+    import glob as _glob
+    lines_want = max(1, int(getattr(args, "lines", 100)))
+    source = (getattr(args, "source", "all") or "all").lower()
+
+    results: dict = {"source": source, "lines": lines_want, "entries": []}
+    home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+    def _collect_events(n: int) -> list[dict]:
+        try:
+            from events_bus import tail as _tail
+            return _tail(lines=n)
+        except Exception as exc:
+            return [{"error": f"events tail failed: {exc}"}]
+
+    def _collect_ops(n: int) -> list[dict]:
+        ops_dir = home / "operations"
+        if not ops_dir.is_dir():
+            return []
+        files = sorted(
+            ops_dir.glob("*.log"),
+            key=lambda p: p.stat().st_mtime if p.exists() else 0,
+            reverse=True,
+        )[:5]
+        out: list[dict] = []
+        for log in files:
+            try:
+                text = log.read_text(errors="ignore").splitlines()[-n:]
+            except Exception as exc:
+                out.append({"file": str(log), "error": str(exc)})
+                continue
+            for line in text:
+                out.append({"file": log.name, "line": line})
+        return out[-n:]
+
+    if source in ("all", "events"):
+        results["entries"].extend({"kind": "event", **e} for e in _collect_events(lines_want))
+    if source in ("all", "operations"):
+        results["entries"].extend({"kind": "log", **e} for e in _collect_ops(lines_want))
+    if source not in ("all", "events", "operations"):
+        # Treat as filename match inside operations/
+        specific = home / "operations" / source
+        if specific.is_file():
+            try:
+                text = specific.read_text(errors="ignore").splitlines()[-lines_want:]
+                results["entries"] = [{"kind": "log", "file": specific.name, "line": ln} for ln in text]
+            except Exception as exc:
+                results["error"] = str(exc)
+        else:
+            results["error"] = f"unknown log source: {source}"
+
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        for entry in results["entries"][-lines_want:]:
+            if entry.get("kind") == "event":
+                print(f"[event] id={entry.get('id')} {entry.get('type')} "
+                      f"{entry.get('priority')} {entry.get('text','')}")
+            else:
+                print(f"[{entry.get('file','?')}] {entry.get('line','')}")
+    return 0
+
+
 def _doctor(args):
     """Run unified doctor diagnostics."""
     try:
@@ -1306,6 +1439,22 @@ def _doctor(args):
         return 1
 
     init_db()
+
+    # Calibration migration hook — runs before the orchestrator so the rest
+    # of doctor sees the canonical nested shape.
+    want_migrate = getattr(args, "migrate_calibration", False) or args.fix
+    dry = getattr(args, "calibration_dry_run", False)
+    if want_migrate or dry:
+        from calibration_migration import detect, apply_migration
+        shape = detect()
+        if shape["shape"] == "flat":
+            mig = apply_migration(dry_run=dry)
+            if args.json:
+                print(json.dumps({"calibration_migration": mig}, ensure_ascii=False, indent=2))
+            else:
+                print(f"[NEXO] calibration migration: {mig.get('status')} — {mig.get('reason','')}",
+                      file=sys.stderr, flush=True)
+
     tier_label = getattr(args, "tier", "boot") or "boot"
     print(f"[NEXO] Inspecting {tier_label} diagnostics... please wait.", file=sys.stderr, flush=True)
     report = run_doctor(tier=args.tier, fix=args.fix, plane=getattr(args, "plane", ""))
@@ -1855,6 +2004,10 @@ def main():
     )
     doctor_parser.add_argument("--json", action="store_true", help="JSON output")
     doctor_parser.add_argument("--fix", action="store_true", help="Apply deterministic fixes")
+    doctor_parser.add_argument("--migrate-calibration", action="store_true",
+                               help="Force calibration.json flat → nested migration")
+    doctor_parser.add_argument("--calibration-dry-run", action="store_true",
+                               help="Preview the calibration migration without writing")
 
     # -- contributor --
     contributor_parser = sub.add_parser("contributor", help="Public Draft PR contribution mode")
@@ -1959,6 +2112,28 @@ def main():
     scan_profile_parser.add_argument("--apply", action="store_true", help="Write profile.json (default is preview)")
     scan_profile_parser.add_argument("--force", action="store_true", help="Overwrite existing profile.json on --apply")
 
+    # -- runtime events bus + operational observability --
+    notify_parser = sub.add_parser("notify", help="Emit an event to the runtime event bus")
+    notify_parser.add_argument("type", choices=[
+        "attention_required", "proactive_message", "followup_alert",
+        "health_alert", "info",
+    ], help="Event type")
+    notify_parser.add_argument("--text", default="", help="Short user-facing message")
+    notify_parser.add_argument("--reason", default="", help="Internal reason / trigger")
+    notify_parser.add_argument("--priority", choices=["low", "normal", "high", "urgent"], default="normal")
+    notify_parser.add_argument("--source", default="nexo-brain", help="Who emitted this event")
+    notify_parser.add_argument("--json", action="store_true", help="JSON output")
+
+    health_parser = sub.add_parser("health", help="Snapshot of NEXO Brain subsystem health")
+    health_parser.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    logs_parser = sub.add_parser("logs", help="Tail recent operational logs")
+    logs_parser.add_argument("--tail", action="store_true", help="Tail mode (default)")
+    logs_parser.add_argument("--lines", type=int, default=100, help="How many lines to return")
+    logs_parser.add_argument("--source", default="all",
+                             help="Log source: all | events | operations | <logname>")
+    logs_parser.add_argument("--json", action="store_true", help="JSON output")
+
     args = parser.parse_args()
 
     if args.help or (not args.command and not args.version):
@@ -2060,6 +2235,12 @@ def main():
             "onboard": cmd_onboard,
             "scan-profile": cmd_scan_profile,
         }[args.command](args)
+    elif args.command == "notify":
+        return _notify(args)
+    elif args.command == "health":
+        return _health(args)
+    elif args.command == "logs":
+        return _logs(args)
     else:
         _print_help()
         return 0

package/src/events_bus.py

@@ -0,0 +1,155 @@
+"""Runtime events bus — append-only NDJSON stream at ~/.nexo/runtime/events.ndjson.
+
+NEXO Brain writes events that external UIs (NEXO Desktop, mobile, web)
+can tail for real-time attention signals, proactive messages, health
+alerts, and general notifications.
+
+Contract:
+  - One JSON object per line. No multi-line JSON.
+  - Monotonic `id` (integer) and `ts` (unix seconds, float).
+  - Stable event envelope keys: id, ts, type, priority, text, reason,
+    source, extra. Unknown keys are preserved.
+  - File is append-only. Rotation happens at 5 MB: current file is
+    renamed to events-<ts>.ndjson and a fresh empty file is created.
+  - Readers tail the current file; rotation is transparent because the
+    file is reopened after rename detection.
+
+Event types (stable):
+  attention_required  — user should look at something
+  proactive_message   — Brain wants to initiate dialogue
+  followup_alert      — overdue or urgent followup
+  health_alert        — a core system is degraded
+  info                — general update, no attention needed
+
+Priorities: "low" | "normal" | "high" | "urgent"
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+EVENT_TYPES = {
+    "attention_required",
+    "proactive_message",
+    "followup_alert",
+    "health_alert",
+    "info",
+}
+PRIORITIES = {"low", "normal", "high", "urgent"}
+ROTATION_BYTES = 5 * 1024 * 1024  # 5 MB
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+def events_path() -> Path:
+    return _nexo_home() / "runtime" / "events.ndjson"
+
+
+def _next_id(path: Path) -> int:
+    """Return the next monotonic id by reading the last line's id, or 1."""
+    if not path.is_file():
+        return 1
+    try:
+        # Read last 4 KB — more than enough for the tail line
+        with path.open("rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            size = fh.tell()
+            fh.seek(max(0, size - 4096))
+            tail = fh.read().decode("utf-8", errors="ignore")
+        lines = [ln for ln in tail.splitlines() if ln.strip()]
+        if not lines:
+            return 1
+        last = json.loads(lines[-1])
+        return int(last.get("id", 0)) + 1
+    except Exception:
+        return int(time.time())
+
+
+def _rotate_if_needed(path: Path) -> None:
+    try:
+        if path.is_file() and path.stat().st_size > ROTATION_BYTES:
+            stamp = int(time.time())
+            rotated = path.with_name(f"events-{stamp}.ndjson")
+            path.rename(rotated)
+    except Exception:
+        # Rotation failure is non-fatal; worst case the file grows
+        pass
+
+
+def emit(
+    event_type: str,
+    *,
+    text: str = "",
+    reason: str = "",
+    priority: str = "normal",
+    source: str = "nexo-brain",
+    extra: dict[str, Any] | None = None,
+) -> dict:
+    """Append a new event to the bus. Returns the full event dict."""
+    if event_type not in EVENT_TYPES:
+        raise ValueError(f"unknown event_type: {event_type}")
+    if priority not in PRIORITIES:
+        raise ValueError(f"unknown priority: {priority}")
+
+    path = events_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _rotate_if_needed(path)
+
+    event = {
+        "id": _next_id(path),
+        "ts": time.time(),
+        "type": event_type,
+        "priority": priority,
+        "text": text,
+        "reason": reason,
+        "source": source,
+        "extra": extra or {},
+    }
+
+    line = json.dumps(event, ensure_ascii=False) + "\n"
+    # fcntl flock for cross-process safety on macOS/Linux
+    with path.open("a", encoding="utf-8") as fh:
+        try:
+            fcntl.flock(fh, fcntl.LOCK_EX)
+            fh.write(line)
+            fh.flush()
+        finally:
+            try:
+                fcntl.flock(fh, fcntl.LOCK_UN)
+            except Exception:
+                pass
+
+    return event
+
+
+def tail(lines: int = 50, since_id: int | None = None) -> list[dict]:
+    """Return the most recent events, newest last. Optionally filter by id."""
+    path = events_path()
+    if not path.is_file():
+        return []
+    try:
+        with path.open("r", encoding="utf-8", errors="ignore") as fh:
+            raw = fh.readlines()
+    except Exception:
+        return []
+
+    events: list[dict] = []
+    for ln in raw[-max(lines, 1) * 4:]:  # generous buffer for malformed lines
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            evt = json.loads(ln)
+        except Exception:
+            continue
+        if since_id is not None and int(evt.get("id", 0)) <= since_id:
+            continue
+        events.append(evt)
+
+    return events[-lines:]

package/src/health_check.py

@@ -0,0 +1,195 @@
+"""Health check — one-shot snapshot of NEXO Brain subsystems.
+
+Output is stable JSON consumable by any UI or monitoring tool.
+No side effects, no network, no mutation.
+
+Subsystems reported:
+  - runtime     : NEXO_HOME exists, version.json readable, version string
+  - database    : SQLite reachable, integrity check, basic row counts
+  - crons       : count of active personal LaunchAgents (macOS) or unknown
+  - mcp         : Claude Code MCP config present and mentions nexo-brain
+  - errors      : count of recent errors in ~/.nexo/operations/*.log (24h)
+  - events      : count of events emitted in last 24h
+
+Top-level `status` is "ok" | "degraded" | "error".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+def _check_runtime() -> dict:
+    home = _nexo_home()
+    ver_file = home / "version.json"
+    out: dict[str, Any] = {"nexo_home": str(home), "exists": home.is_dir()}
+    if ver_file.is_file():
+        try:
+            payload = json.loads(ver_file.read_text())
+            out["version"] = payload.get("version", "unknown")
+        except Exception as exc:
+            out["version"] = "unreadable"
+            out["error"] = str(exc)
+    else:
+        out["version"] = "missing"
+    out["status"] = "ok" if out["exists"] and out.get("version") not in ("missing", "unreadable") else "degraded"
+    return out
+
+
+def _check_database() -> dict:
+    db_path = _nexo_home() / "data" / "nexo.db"
+    out: dict[str, Any] = {"path": str(db_path), "exists": db_path.is_file()}
+    if not out["exists"]:
+        out["status"] = "error"
+        return out
+    try:
+        conn = sqlite3.connect(str(db_path), timeout=2.0)
+        try:
+            cur = conn.execute("PRAGMA integrity_check")
+            row = cur.fetchone()
+            out["integrity"] = row[0] if row else "unknown"
+        finally:
+            conn.close()
+        out["status"] = "ok" if out["integrity"] == "ok" else "degraded"
+    except Exception as exc:
+        out["status"] = "error"
+        out["error"] = str(exc)
+    return out
+
+
+def _check_crons() -> dict:
+    out: dict[str, Any] = {}
+    # macOS LaunchAgents
+    agents_dir = Path.home() / "Library" / "LaunchAgents"
+    if agents_dir.is_dir():
+        try:
+            plists = [p for p in agents_dir.glob("com.nexo.*.plist")]
+            out["launch_agents"] = len(plists)
+            out["platform"] = "macos"
+        except Exception as exc:
+            out["error"] = str(exc)
+    else:
+        out["platform"] = "unknown"
+    out["status"] = "ok"
+    return out
+
+
+def _check_mcp() -> dict:
+    out: dict[str, Any] = {}
+    candidates = [
+        Path.home() / ".claude.json",
+        Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+    ]
+    found = []
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(errors="ignore")
+        except Exception:
+            continue
+        if "nexo" in text.lower():
+            found.append(str(path))
+    out["configs_with_nexo"] = found
+    out["status"] = "ok" if found else "degraded"
+    if not found:
+        out["reason"] = "no client config mentions nexo-brain"
+    return out
+
+
+def _check_errors(hours: int = 24) -> dict:
+    ops_dir = _nexo_home() / "operations"
+    out: dict[str, Any] = {"dir": str(ops_dir)}
+    if not ops_dir.is_dir():
+        out["recent_errors"] = 0
+        out["status"] = "ok"
+        return out
+
+    cutoff = time.time() - hours * 3600
+    recent = 0
+    sample: list[str] = []
+    error_re = re.compile(r"(?i)\b(error|traceback|exception|fail(ed)?)\b")
+
+    for log in ops_dir.glob("*.log"):
+        try:
+            if log.stat().st_mtime < cutoff:
+                continue
+            with log.open("r", errors="ignore") as fh:
+                for line in fh:
+                    if error_re.search(line):
+                        recent += 1
+                        if len(sample) < 5:
+                            sample.append(line.strip()[:200])
+        except Exception:
+            continue
+
+    out["recent_errors"] = recent
+    out["sample"] = sample
+    out["status"] = "ok" if recent < 20 else "degraded"
+    return out
+
+
+def _check_events(hours: int = 24) -> dict:
+    events_file = _nexo_home() / "runtime" / "events.ndjson"
+    out: dict[str, Any] = {"path": str(events_file), "exists": events_file.is_file()}
+    if not events_file.is_file():
+        out["recent_events"] = 0
+        out["status"] = "ok"
+        return out
+    cutoff = time.time() - hours * 3600
+    count = 0
+    urgent = 0
+    try:
+        with events_file.open("r", errors="ignore") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    evt = json.loads(line)
+                except Exception:
+                    continue
+                if float(evt.get("ts", 0)) < cutoff:
+                    continue
+                count += 1
+                if evt.get("priority") == "urgent":
+                    urgent += 1
+    except Exception as exc:
+        out["error"] = str(exc)
+    out["recent_events"] = count
+    out["urgent"] = urgent
+    out["status"] = "degraded" if urgent > 0 else "ok"
+    return out
+
+
+def collect() -> dict:
+    """Run every subsystem check and return a unified report."""
+    report: dict[str, Any] = {
+        "ts": time.time(),
+        "subsystems": {
+            "runtime": _check_runtime(),
+            "database": _check_database(),
+            "crons": _check_crons(),
+            "mcp": _check_mcp(),
+            "errors": _check_errors(),
+            "events": _check_events(),
+        },
+    }
+    statuses = [sub.get("status", "unknown") for sub in report["subsystems"].values()]
+    if "error" in statuses:
+        report["status"] = "error"
+    elif "degraded" in statuses:
+        report["status"] = "degraded"
+    else:
+        report["status"] = "ok"
+    return report

package/src/hooks/capture-session.sh

@@ -1,21 +1,43 @@
 #!/bin/bash
 # NEXO PostToolUse hook — captures tool usage to session_buffer.jsonl
-# This feeds the Sensory Register (Atkinson-Shiffrin Layer 1)
+# Feeds the Sensory Register (Atkinson-Shiffrin Layer 1).
+#
+# IMPORTANT: Claude Code passes the tool name in a JSON payload over stdin,
+# NOT as the $CLAUDE_TOOL_NAME env var. Earlier revisions of this hook
+# assumed the env var existed and always wrote "unknown", masking the
+# entire sensory-register stream. Do not reintroduce that pattern.
+
+set -uo pipefail
 
 NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
 BUFFER="$NEXO_HOME/brain/session_buffer.jsonl"
-
 mkdir -p "$NEXO_HOME/brain"
 
-# Capture basic event: timestamp + tool name
-# Read stdin (Claude Code passes JSON via stdin for PostToolUse hooks)
 INPUT=$(cat 2>/dev/null || true)
-TOOL_NAME="${CLAUDE_TOOL_NAME:-unknown}"
-TS=$(date -u +"%Y-%m-%dT%H:%M:%S")
+[ -z "$INPUT" ] && exit 0
+
+# Extract tool_name from the stdin JSON payload. Fall back to env var for
+# compatibility with any platform that still sets it; final fallback is an
+# empty string, in which case we exit without writing so "unknown" noise
+# never reaches the buffer.
+TOOL_NAME=$(echo "$INPUT" \
+    | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null \
+    || true)
+if [ -z "$TOOL_NAME" ]; then
+    TOOL_NAME="${CLAUDE_TOOL_NAME:-}"
+fi
+[ -z "$TOOL_NAME" ] && exit 0
 
-# Only log meaningful tool calls (skip reads, globs, greps)
+# Skip high-frequency read-only tools: they add noise without signal.
+# Bash / Write / Edit / MultiEdit / Task / MCP tools ARE kept — that is
+# where real state change happens and where the sensory register matters.
 case "$TOOL_NAME" in
-    Read|Glob|Grep|LS|Bash) exit 0 ;;
+    Read|Glob|Grep|LS|Skill|ToolSearch|TodoWrite) exit 0 ;;
 esac
 
-echo "{\"ts\":\"$TS\",\"tool\":\"$TOOL_NAME\",\"source\":\"hook\"}" >> "$BUFFER"
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+# Escape embedded quotes / special chars in tool names (MCP names can be
+# long and contain colons, underscores, and dashes).
+ESCAPED_NAME=$(printf '%s' "$TOOL_NAME" \
+    | python3 -c "import sys,json; print(json.dumps(sys.stdin.read().strip()))")
+echo "{\"ts\":\"$TS\",\"tool\":$ESCAPED_NAME,\"source\":\"hook\"}" >> "$BUFFER"

package/src/user_context.py

@@ -18,14 +18,32 @@ class UserContext:
         self.user_name = ""
         self.user_language = "en"
 
-        # calibration.json has operator_name + user info
+        # calibration.json has operator_name + user info.
+        # v5.4.0+: tolerate both nested ({user:{name,language}}) and legacy flat
+        # ({user_name, language}) shapes. Nested wins when both exist.
         if cal_path.exists():
             try:
                 cal = json.loads(cal_path.read_text())
-                self.assistant_name = cal.get("operator_name", "") or \
-                    cal.get("user", {}).get("assistant_name", "") or "NEXO"
-                self.user_name = cal.get("user", {}).get("name", "")
-                self.user_language = cal.get("user", {}).get("language", "en")
+                user_block = cal.get("user") if isinstance(cal.get("user"), dict) else {}
+
+                self.assistant_name = (
+                    user_block.get("assistant_name", "")
+                    or cal.get("operator_name", "")
+                    or cal.get("assistant_name", "")
+                    or "NEXO"
+                )
+                self.user_name = (
+                    user_block.get("name", "")
+                    or cal.get("user_name", "")
+                    or cal.get("name", "")
+                    or ""
+                )
+                self.user_language = (
+                    user_block.get("language", "")
+                    or cal.get("language", "")
+                    or cal.get("lang", "")
+                    or "en"
+                )
             except Exception:
                 pass