nexo-brain 7.3.0 → 7.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "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.3.0` is the current packaged-runtime line. Hotfix minor release correcting three critical bugs that surfaced right after v7.2.0. B11 Guardian wire: new `src/hooks/pre_tool_use.py` entrypoint is now registered in `src/hooks/manifest.json` and `hooks/hooks.json` so the Claude Code PreToolUse event actually reaches Guardian — before this, `guardian-runtime-overrides.json` in hard mode was silently inert for G3-destructive, G3-SSH, and G4-guard_check gates. A parallel SSH prescreen in `hook_guardrails.process_pre_tool_event` forces `op=write` on remote-write patterns the local shell classifier could not see. B10 post-sync: `_run_post_install_hooks_fresh(dest, env)` invokes each whitelisted hook (`_persist_guardian_hard_defaults`, `_maybe_promote_adaptive_weights_empirically`) in a clean subprocess against the newly copied tree, so the first `nexo update` that introduces a new post-install hook actually runs it — previously the hook dispatch used the pre-upgrade module held in memory and silently no-op'd. B12 map distribution: `tool-enforcement-map.json` is now part of the npm `files` whitelist so fresh `npm install -g nexo-brain` ships it, closing the three-way gap (Brain npm + Desktop bundle + runtime sync) that prevented Desktop from ever discovering the map on new installs. Also ships the PE1 rapid items promised for this milestone: 5 additional `destructive_command` entries in `src/presets/entities_universal.json` (`curl_pipe_shell`, `dd_to_device`, `chmod_recursive_wide_open`, `ssh_remote_overwrite`, `scp_rsync_upload`; coverage floor raised from 7 to 12) and the `guardian-metrics` daily cron at 02:15 that feeds Fase C gate and the Guardian Proposals panel.
+Version `7.4.0` is the current packaged-runtime line. Hotfix minor release correcting three critical bugs that surfaced right after v7.2.0. B11 Guardian wire: new `src/hooks/pre_tool_use.py` entrypoint is now registered in `src/hooks/manifest.json` and `hooks/hooks.json` so the Claude Code PreToolUse event actually reaches Guardian — before this, `guardian-runtime-overrides.json` in hard mode was silently inert for G3-destructive, G3-SSH, and G4-guard_check gates. A parallel SSH prescreen in `hook_guardrails.process_pre_tool_event` forces `op=write` on remote-write patterns the local shell classifier could not see. B10 post-sync: `_run_post_install_hooks_fresh(dest, env)` invokes each whitelisted hook (`_persist_guardian_hard_defaults`, `_maybe_promote_adaptive_weights_empirically`) in a clean subprocess against the newly copied tree, so the first `nexo update` that introduces a new post-install hook actually runs it — previously the hook dispatch used the pre-upgrade module held in memory and silently no-op'd. B12 map distribution: `tool-enforcement-map.json` is now part of the npm `files` whitelist so fresh `npm install -g nexo-brain` ships it, closing the three-way gap (Brain npm + Desktop bundle + runtime sync) that prevented Desktop from ever discovering the map on new installs. Also ships the PE1 rapid items promised for this milestone: 5 additional `destructive_command` entries in `src/presets/entities_universal.json` (`curl_pipe_shell`, `dd_to_device`, `chmod_recursive_wide_open`, `ssh_remote_overwrite`, `scp_rsync_upload`; coverage floor raised from 7 to 12) and the `guardian-metrics` daily cron at 02:15 that feeds Fase C gate and the Guardian Proposals panel.
 
 Previously in `7.2.0`: minor release consolidating three parallel workstreams into a single Guardian-active-by-default train. Block K roadmap closure (G1 enforcer active, G3 SSH remote-write detector, `src/guardian_runtime_config.py` resolver, `_persist_guardian_hard_defaults` during `nexo update`). F0.6 hardening wave (`nexo rollback f06` CLI, `src/scripts/prune_runtime_backups.py` promoted to core, `docs/f06-layout-contract.md`, three new doctor boot-tier checks, `scripts/nexo-migrate-nora.sh` + `scripts/f0-safe-apply-remote.sh` idempotent migration). Adaptive weights flipped from "14-day calendar wait" to "14 days OR (≥200 samples AND ≥2 days)" with auto-promotion during `nexo update`. Small-fixes batch: R34 `bool("unknown")==True` fix, `classify_scripts_dir` dedup, B10 module-level path constants lazy-evaluated, schedule override audit log, `scripts/pre-release-verify.sh` + `docs/release-discipline.md`, pre-commit hook that blocks commits when `tool-enforcement-map.json` drifts from `src/plugins/`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 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/cli.py

@@ -3076,6 +3076,22 @@ def main():
     dashboard_parser.add_argument("action", choices=["on", "off", "status"], help="Start, stop, or check dashboard")
 
     # -- desktop bridge (read-only, for NEXO Desktop and any external UI) --
+    # v7.4.0 — lifecycle event bridge (guardian-claude-desktop-plan).
+    lifecycle_parser = sub.add_parser("lifecycle", help="Conversation lifecycle event handler (v7.4 Desktop bridge)")
+    lifecycle_sub = lifecycle_parser.add_subparsers(dest="lifecycle_command")
+
+    lrec_p = lifecycle_sub.add_parser("record", help="Record a lifecycle event")
+    lrec_p.add_argument("--event-id", required=True, help="UUID minted by the client (idempotency key)")
+    lrec_p.add_argument("--action", required=True, help="close|delete|archive|switch|app-exit|window-close")
+    lrec_p.add_argument("--conversation-id", required=True)
+    lrec_p.add_argument("--session-id", default="")
+    lrec_p.add_argument("--reason", default="user_action")
+    lrec_p.add_argument("--payload", default="", help="JSON-encoded payload_snapshot")
+    lrec_p.add_argument("--source", default="desktop")
+
+    lstat_p = lifecycle_sub.add_parser("status", help="Read the current delivery_status of an event")
+    lstat_p.add_argument("--event-id", required=True)
+
     # Fase E.5 — quarantine ops surfaced via Desktop Guardian Proposals panel.
     quarantine_parser = sub.add_parser("quarantine", help="Quarantine proposals (Fase E.5 Desktop UI)")
     quarantine_sub = quarantine_parser.add_subparsers(dest="quarantine_command")
@@ -3288,6 +3304,43 @@ def main():
         # No subcommand — show help.
         quarantine_parser.print_help()
         return 1
+    elif args.command == "lifecycle":
+        # v7.4.0 — bridge for NEXO Desktop's ConversationLifecycleService.
+        # Both subcommands emit a single JSON line to stdout so the
+        # caller (main.js runNexoCommand) can parse the ack directly.
+        import json as _json
+        import plugins.lifecycle_events as _lifecycle_plugin
+        if args.lifecycle_command == "record":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_event(
+                event_id=args.event_id,
+                action=args.action,
+                conversation_id=args.conversation_id,
+                session_id=args.session_id or "",
+                reason=args.reason or "user_action",
+                payload_snapshot=args.payload or "",
+                source=args.source or "desktop",
+                schema_version=1,
+            )
+            print(out)
+            try:
+                parsed = _json.loads(out)
+                status = str(parsed.get("status", ""))
+            except Exception:
+                status = ""
+            # Exit code 0 for terminal ok states, 2 for retryable_error so
+            # Desktop can distinguish "persisted + processed" from "try
+            # again on boot reconciliation". Rejected is exit 3 (bad input).
+            if status in ("processed", "already_processed", "accepted"):
+                return 0
+            if status == "retryable_error":
+                return 2
+            return 3
+        if args.lifecycle_command == "status":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_status(args.event_id)
+            print(out)
+            return 0
+        lifecycle_parser.print_help()
+        return 1
     elif args.command in ("schema", "identity", "onboard", "scan-profile"):
         from desktop_bridge import cmd_schema, cmd_identity, cmd_onboard, cmd_scan_profile
         return {

package/src/db/_schema.py

@@ -1311,6 +1311,46 @@ def _m44_entities_extended_schema(conn):
     _migrate_add_column(conn, "entities", "access_mode", "TEXT DEFAULT 'unknown'")
 
 
+def _m51_lifecycle_events(conn):
+    """v7.4.0 — durable lifecycle event store for the Desktop pipeline.
+
+    Matches the Desktop-side NDJSON queue contract:
+    event_id (PRIMARY KEY, uuid from Desktop), source (desktop|cron|...),
+    action (close|delete|archive|switch|app-exit|window-close),
+    conversation_id, session_id (claude session), reason,
+    payload_snapshot (JSON), delivery_status
+    (pending|accepted|processed|already_processed|rejected|retryable_error),
+    retry_count, created_at, processed_at, last_error.
+
+    Idempotency key is event_id. Re-delivery of the same event_id returns
+    status=already_processed without re-running any canonical side effect
+    (diary, stop, archive bookkeeping). This is the backbone of
+    guardian-claude-desktop-plan.md → "5. Idempotencia real".
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS lifecycle_events (
+            event_id TEXT PRIMARY KEY,
+            schema_version INTEGER NOT NULL DEFAULT 1,
+            source TEXT NOT NULL DEFAULT 'desktop',
+            action TEXT NOT NULL,
+            conversation_id TEXT NOT NULL,
+            session_id TEXT DEFAULT NULL,
+            reason TEXT DEFAULT 'user_action',
+            payload_snapshot TEXT DEFAULT '{}',
+            delivery_status TEXT NOT NULL DEFAULT 'accepted',
+            retry_count INTEGER NOT NULL DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now')),
+            processed_at TEXT DEFAULT NULL,
+            last_error TEXT DEFAULT NULL
+        )
+        """
+    )
+    _migrate_add_index(conn, "idx_lifecycle_events_status", "lifecycle_events", "delivery_status")
+    _migrate_add_index(conn, "idx_lifecycle_events_conv", "lifecycle_events", "conversation_id")
+    _migrate_add_index(conn, "idx_lifecycle_events_action", "lifecycle_events", "action")
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -1362,6 +1402,7 @@ MIGRATIONS = [
     (48, "email_agent_contract_backfill", _m48_email_agent_contract_backfill),
     (49, "protocol_guard_ack_backfill", _m49_protocol_guard_ack_backfill),
     (50, "dedupe_nexo_product_learning_pair", _m50_dedupe_nexo_product_learning_pair),
+    (51, "lifecycle_events", _m51_lifecycle_events),
 ]
 
 

package/src/lifecycle_events.py

@@ -0,0 +1,186 @@
+"""NEXO Brain — canonical lifecycle event handler (v7.4.0).
+
+Companion to nexo-desktop's ConversationLifecycleService. Desktop
+persists every conversation/app transition (close / delete / archive /
+switch / window-close / app-exit) to an append-only NDJSON queue BEFORE
+any UI mutation becomes visible, then calls this handler via the
+``nexo_lifecycle_event`` MCP tool. The handler is strictly idempotent:
+re-delivery of the same ``event_id`` returns ``already_processed``
+without replaying any canonical side effect.
+
+Canonical side effects are intentionally minimal in this first slice:
+
+- ``close`` / ``delete`` / ``archive`` / ``app-exit`` / ``window-close``
+  → mark processed. Diary / stop inside the conversation are driven by
+  Desktop's graceful-close flow (``conv-close`` IPC → nexo CLI) and
+  remain the authority for that per-conversation payload. This table
+  is the durable ledger so the next boot can reconcile.
+- ``switch`` → mark processed. No canonical side effect beyond the
+  audit trail; the ledger still matters for telemetry and guard
+  invariants ("operator switched away from a conversation that still
+  had uncommitted claims").
+
+Return shape matches the plan (lines 94-100):
+
+- ``processed``          first delivery, side effects (if any) done
+- ``already_processed``  duplicate delivery, no re-run
+- ``accepted``           persisted, side effect deferred (not used yet)
+- ``rejected``           malformed input, no persistence
+- ``retryable_error``    transient failure, Desktop should retry
+
+Any row keeps ``delivery_status`` as the latest terminal or retryable
+status so ``nexo_lifecycle_status`` / future reconciliation queries
+can read it directly.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from db import get_db
+
+
+VALID_ACTIONS = {
+    "close",
+    "delete",
+    "archive",
+    "switch",
+    "app-exit",
+    "window-close",
+}
+
+TERMINAL_STATUSES = {"processed", "already_processed", "rejected"}
+_DIARY_TRIGGERING = {"close", "delete", "archive", "app-exit"}
+
+
+def _normalise_payload(obj: Any) -> str:
+    try:
+        return json.dumps(obj or {}, ensure_ascii=False, sort_keys=True)
+    except Exception:
+        return "{}"
+
+
+def record_lifecycle_event(
+    event_id: str,
+    action: str,
+    conversation_id: str,
+    session_id: Optional[str] = None,
+    reason: str = "user_action",
+    payload_snapshot: Optional[Dict[str, Any]] = None,
+    source: str = "desktop",
+    schema_version: int = 1,
+) -> Dict[str, Any]:
+    """Idempotent upsert + process.
+
+    Returns ``{status, event_id, diary_triggered, duplicate}``.
+    """
+    if not event_id or not str(event_id).strip():
+        return {"status": "rejected", "reason": "missing-event-id"}
+    if action not in VALID_ACTIONS:
+        return {"status": "rejected", "reason": f"unknown-action:{action}"}
+    if not conversation_id or not str(conversation_id).strip():
+        return {"status": "rejected", "reason": "missing-conversation-id"}
+
+    conn = get_db()
+    existing = conn.execute(
+        "SELECT delivery_status FROM lifecycle_events WHERE event_id = ?",
+        (str(event_id),),
+    ).fetchone()
+
+    if existing is not None:
+        status = str(existing[0] or "")
+        if status in TERMINAL_STATUSES:
+            return {
+                "status": "already_processed",
+                "event_id": event_id,
+                "duplicate": True,
+                "prior_status": status,
+            }
+        # Non-terminal row (accepted / retryable_error) — flip to processed
+        # now and record the transition.
+        conn.execute(
+            "UPDATE lifecycle_events SET delivery_status = 'processed', "
+            "processed_at = datetime('now'), last_error = NULL "
+            "WHERE event_id = ?",
+            (str(event_id),),
+        )
+        conn.commit()
+        return {
+            "status": "processed",
+            "event_id": event_id,
+            "diary_triggered": action in _DIARY_TRIGGERING,
+            "duplicate": False,
+            "reopened": True,
+        }
+
+    conn.execute(
+        """
+        INSERT INTO lifecycle_events (
+            event_id, schema_version, source, action, conversation_id,
+            session_id, reason, payload_snapshot, delivery_status,
+            retry_count, processed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'processed', 0, datetime('now'))
+        """,
+        (
+            str(event_id),
+            int(schema_version or 1),
+            str(source or "desktop"),
+            str(action),
+            str(conversation_id),
+            str(session_id) if session_id else None,
+            str(reason or "user_action"),
+            _normalise_payload(payload_snapshot),
+        ),
+    )
+    conn.commit()
+
+    return {
+        "status": "processed",
+        "event_id": event_id,
+        "diary_triggered": action in _DIARY_TRIGGERING,
+        "duplicate": False,
+    }
+
+
+def get_lifecycle_event(event_id: str) -> Optional[Dict[str, Any]]:
+    if not event_id:
+        return None
+    row = get_db().execute(
+        "SELECT event_id, schema_version, source, action, conversation_id, "
+        "session_id, reason, payload_snapshot, delivery_status, retry_count, "
+        "created_at, processed_at, last_error "
+        "FROM lifecycle_events WHERE event_id = ?",
+        (str(event_id),),
+    ).fetchone()
+    if row is None:
+        return None
+    try:
+        payload = json.loads(row[7] or "{}")
+    except Exception:
+        payload = {}
+    return {
+        "event_id": row[0],
+        "schema_version": row[1],
+        "source": row[2],
+        "action": row[3],
+        "conversation_id": row[4],
+        "session_id": row[5],
+        "reason": row[6],
+        "payload_snapshot": payload,
+        "delivery_status": row[8],
+        "retry_count": row[9],
+        "created_at": row[10],
+        "processed_at": row[11],
+        "last_error": row[12],
+    }
+
+
+def list_lifecycle_events_by_status(status: str, limit: int = 100) -> list[Dict[str, Any]]:
+    if not status:
+        return []
+    rows = get_db().execute(
+        "SELECT event_id FROM lifecycle_events "
+        "WHERE delivery_status = ? ORDER BY created_at ASC LIMIT ?",
+        (str(status), int(limit or 100)),
+    ).fetchall()
+    return [e for e in (get_lifecycle_event(r[0]) for r in rows) if e]

package/src/plugins/lifecycle_events.py

@@ -0,0 +1,113 @@
+"""Lifecycle Events MCP plugin — nexo_lifecycle_event tool (v7.4.0).
+
+Exposes the canonical handler as an MCP tool so nexo-desktop's
+ConversationLifecycleService can relay close/delete/archive/app-exit/
+window-close intents to Brain and get a formal acknowledgement.
+
+See src/lifecycle_events.py for the handler contract and
+guardian-claude-desktop-plan.md for the overall architecture.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import lifecycle_events
+
+
+def handle_nexo_lifecycle_event(
+    event_id: str,
+    action: str,
+    conversation_id: str,
+    session_id: str = "",
+    reason: str = "user_action",
+    payload_snapshot: str = "",
+    source: str = "desktop",
+    schema_version: int = 1,
+) -> str:
+    """Record a durable lifecycle event and return the canonical ack.
+
+    Desktop (or any future client) MUST persist the event locally first
+    (NDJSON queue) before calling this tool. The handler is idempotent:
+    re-delivery of the same event_id returns ``already_processed``.
+
+    Args:
+        event_id: UUID minted by the client. Primary idempotency key.
+        action: One of ``close`` / ``delete`` / ``archive`` / ``switch``
+            / ``app-exit`` / ``window-close``.
+        conversation_id: Client-side conversation identifier.
+        session_id: Claude session id that backs the conversation, when
+            known. Optional.
+        reason: Free-form origin tag. Default ``user_action``.
+        payload_snapshot: JSON-encoded snapshot of the conversation at
+            the moment of the click (title, last_message_at, is_active,
+            etc). Accepts an empty string if nothing was snapped.
+        source: Client identifier. Default ``desktop``.
+        schema_version: Event schema version the client emitted. Default 1.
+
+    Returns:
+        JSON string ``{status, event_id, ...}``. ``status`` is one of
+        ``processed`` / ``already_processed`` / ``accepted`` /
+        ``rejected`` / ``retryable_error``.
+    """
+    payload_obj: Any = {}
+    if payload_snapshot:
+        try:
+            parsed = json.loads(payload_snapshot)
+            if isinstance(parsed, dict):
+                payload_obj = parsed
+        except Exception:
+            payload_obj = {"_raw": str(payload_snapshot)[:4096]}
+
+    try:
+        result = lifecycle_events.record_lifecycle_event(
+            event_id=event_id,
+            action=action,
+            conversation_id=conversation_id,
+            session_id=session_id or None,
+            reason=reason or "user_action",
+            payload_snapshot=payload_obj,
+            source=source or "desktop",
+            schema_version=int(schema_version or 1),
+        )
+    except Exception as exc:
+        return json.dumps({
+            "status": "retryable_error",
+            "reason": f"{type(exc).__name__}: {exc}",
+            "handler_threw": True,
+        }, ensure_ascii=False)
+
+    return json.dumps(result, ensure_ascii=False)
+
+
+def handle_nexo_lifecycle_status(event_id: str) -> str:
+    """Read the current delivery_status of a lifecycle event.
+
+    Primarily used by reconciliation at Desktop boot: for each
+    still-pending or retryable event in the local NDJSON queue, ask
+    Brain whether it already processed it (Desktop crashed between the
+    append and the ack) or whether we need to re-submit.
+    """
+    if not event_id:
+        return json.dumps({"status": "rejected", "reason": "missing-event-id"})
+    try:
+        row = lifecycle_events.get_lifecycle_event(event_id)
+    except Exception as exc:
+        return json.dumps({"status": "retryable_error", "reason": f"{type(exc).__name__}: {exc}"})
+    if row is None:
+        return json.dumps({"status": "not_found", "event_id": event_id})
+    return json.dumps(row, ensure_ascii=False)
+
+
+TOOLS = [
+    (
+        handle_nexo_lifecycle_event,
+        "nexo_lifecycle_event",
+        "Record a durable lifecycle event (close/delete/archive/switch/app-exit/window-close) and return a canonical ack.",
+    ),
+    (
+        handle_nexo_lifecycle_status,
+        "nexo_lifecycle_status",
+        "Read the current delivery_status of a lifecycle event. Used by Desktop boot reconciliation.",
+    ),
+]

package/tool-enforcement-map.json

@@ -1843,6 +1843,32 @@
       },
       "triggers_after": []
     },
+    "nexo_lifecycle_event": {
+      "description": "Record a durable conversation lifecycle event (close/delete/archive/switch/app-exit/window-close) with idempotency by event_id.",
+      "category": "lifecycle",
+      "source": "plugin:lifecycle_events",
+      "requires": [],
+      "provides": [],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_lifecycle_status": {
+      "description": "Read the current delivery_status of a lifecycle event (used by Desktop boot reconciliation).",
+      "category": "lifecycle",
+      "source": "plugin:lifecycle_events",
+      "requires": [],
+      "provides": [],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_media_memory_add": {
       "description": "Store non-text artifact metadata",
       "category": "media",