nexo-brain 7.4.0 → 7.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.4.0",
+  "version": "7.5.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,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.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.
+Version `7.5.0` is the current packaged-runtime line. Minor release that promotes `nexo_lifecycle_event` from ledger + reconciliation authority to **canonical authority of session-end**. Brain now owns the prompt, the sequence, and the timing of diary+stop; Desktop v0.25.0 (closed-source companion) is the conduit that executes Brain's plan against the live Claude process. The new 2-call contract — `nexo_lifecycle_event` returns a versioned `canonical_plan` (resume_session → inject_prompt → stop_session, with stable ids and per-action timeouts) and `nexo_lifecycle_complete_canonical` confirms execution with a per-action results array — replaces polling with explicit acknowledgement. `canonical_plan_id` is deterministic: `sha256(event_id + "|v" + plan_version)[:24]`, so retries reuse the same id. Migration m52 extends `lifecycle_events` with six `canonical_*` columns plus an index; pre-v7.5 rows simply carry NULL. `session_diary` is the dedupe key on re-delivery: if Desktop crashes between executing the inject and sending the complete call, the next `nexo_lifecycle_event` for the same `event_id` checks for a diary written after `canonical_dispatched_at`; if one exists, Brain short-circuits to `already_processed` and refuses to re-dispatch. The seven explicit `delivery_status` values (`accepted`, `processed`, `canonical_pending`, `canonical_done`, `already_processed`, `retryable_error`, `rejected`) give the pipeline a diffable state machine. `switch` and `window-close` stay observational (no plan ever issued, even with a live `session_id`). `nexo lifecycle record` now returns exit code 0 for `canonical_pending`; older wrappers that treated it as an error are incompatible with v7.5. MCP tool count: 262 → 263.
+
+Previously in `7.4.1`: patch release correcting the over-promise in v7.4.0's release notes and locking in the exact role of `nexo_lifecycle_event` as a ledger + reconciliation authority — NOT the canonical executor of diary+stop, which lived in Desktop. That responsibility moved to Brain in v7.5.
 
 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.4.0",
+  "version": "7.5.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

@@ -3092,6 +3092,18 @@ def main():
     lstat_p = lifecycle_sub.add_parser("status", help="Read the current delivery_status of an event")
     lstat_p.add_argument("--event-id", required=True)
 
+    lcomp_p = lifecycle_sub.add_parser(
+        "complete-canonical",
+        help="v7.5: confirm Desktop finished executing the canonical_actions a prior record returned",
+    )
+    lcomp_p.add_argument("--event-id", required=True)
+    lcomp_p.add_argument("--plan-id", required=True, help="canonical_plan_id returned by the original record call")
+    lcomp_p.add_argument(
+        "--results",
+        default="",
+        help="JSON array of per-action outcomes, e.g. '[{\"action_id\":\"a1\",\"status\":\"ok\"}]'",
+    )
+
     # 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")
@@ -3327,10 +3339,12 @@ def main():
                 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"):
+            # Exit code 0 for terminal ok states AND for canonical_pending
+            # (v7.5: plan handed to Desktop, awaiting complete_canonical).
+            # 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", "canonical_pending"):
                 return 0
             if status == "retryable_error":
                 return 2
@@ -3339,6 +3353,23 @@ def main():
             out = _lifecycle_plugin.handle_nexo_lifecycle_status(args.event_id)
             print(out)
             return 0
+        if args.lifecycle_command == "complete-canonical":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_complete_canonical(
+                event_id=args.event_id,
+                canonical_plan_id=args.plan_id,
+                results=args.results or "",
+            )
+            print(out)
+            try:
+                parsed = _json.loads(out)
+                status = str(parsed.get("status", ""))
+            except Exception:
+                status = ""
+            if status in ("canonical_done", "already_processed"):
+                return 0
+            if status == "retryable_error":
+                return 2
+            return 3
         lifecycle_parser.print_help()
         return 1
     elif args.command in ("schema", "identity", "onboard", "scan-profile"):

package/src/db/_schema.py

@@ -1351,6 +1351,48 @@ def _m51_lifecycle_events(conn):
     _migrate_add_index(conn, "idx_lifecycle_events_action", "lifecycle_events", "action")
 
 
+def _m52_lifecycle_canonical_plan(conn):
+    """v7.5.0 — Brain promoted to canonical authority for session-end.
+
+    When the Desktop pipeline posts a close / delete / archive / app-exit
+    lifecycle event with a live session_id, Brain now decides the exact
+    prompt + sequence to run against the live Claude process and hands
+    that plan back to Desktop in the same MCP call. Desktop executes
+    the plan inline and confirms via a second call
+    (``nexo_lifecycle_complete_canonical``).
+
+    New columns on ``lifecycle_events``:
+
+    - ``canonical_plan_id`` — deterministic id hash(event_id+plan_version).
+      Used for idempotent retries: Desktop can ask "did you already
+      finish this plan_id" and Brain can dedupe without re-running any
+      diary write.
+    - ``canonical_plan_version`` — schema version of the plan payload
+      (INTEGER, default 1). Lets us evolve the action shape without
+      breaking older Desktop builds.
+    - ``canonical_actions_json`` — the actions array Brain returned,
+      verbatim. Persisted so boot reconciliation can re-send the exact
+      same plan on a crash between dispatch and confirm.
+    - ``canonical_dispatched_at`` — first time Brain returned the plan.
+      Used as the "since" cursor for the session_diary dedup query.
+    - ``canonical_done_at`` — set only when Desktop calls
+      ``nexo_lifecycle_complete_canonical``. Absence + presence of
+      ``canonical_dispatched_at`` == "dispatched but not confirmed".
+    - ``canonical_done_results`` — JSON array of per-action results
+      reported by Desktop, used for telemetry and retry classification.
+
+    Idempotent. Fresh installs already created the table in m51; this
+    migration only ADDs the new columns.
+    """
+    _migrate_add_column(conn, "lifecycle_events", "canonical_plan_id", "TEXT DEFAULT NULL")
+    _migrate_add_column(conn, "lifecycle_events", "canonical_plan_version", "INTEGER DEFAULT NULL")
+    _migrate_add_column(conn, "lifecycle_events", "canonical_actions_json", "TEXT DEFAULT NULL")
+    _migrate_add_column(conn, "lifecycle_events", "canonical_dispatched_at", "TEXT DEFAULT NULL")
+    _migrate_add_column(conn, "lifecycle_events", "canonical_done_at", "TEXT DEFAULT NULL")
+    _migrate_add_column(conn, "lifecycle_events", "canonical_done_results", "TEXT DEFAULT NULL")
+    _migrate_add_index(conn, "idx_lifecycle_events_plan_id", "lifecycle_events", "canonical_plan_id")
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -1403,6 +1445,7 @@ MIGRATIONS = [
     (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),
+    (52, "lifecycle_canonical_plan", _m52_lifecycle_canonical_plan),
 ]
 
 

package/src/lifecycle_events.py

@@ -1,36 +1,52 @@
-"""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.
+"""NEXO Brain — canonical lifecycle event handler (v7.5).
+
+v7.4.x shipped this tool as a pure ledger + reconciliation surface:
+Desktop persisted every conversation lifecycle transition locally,
+called ``nexo_lifecycle_event`` for book-keeping, and ran its own
+hardcoded ``diary + stop`` prompts against the live Claude process
+during ``closeConversationGraceful``.
+
+v7.5 promotes this handler to the **canonical authority** for
+session-end. For every ``close`` / ``delete`` / ``archive`` /
+``app-exit`` event with a live ``session_id``, Brain now generates a
+deterministic **canonical plan** (``canonical_plan_id``, versioned
+action list) and hands it back in the same MCP call. Desktop executes
+the plan inline (Desktop is still the only process that can reach the
+Claude proc's stdin) and then calls
+``nexo_lifecycle_complete_canonical`` with per-action results. Brain
+records ``canonical_done_at`` only on that second call — no polling.
+
+Idempotency is real, not cosmetic:
+
+1. ``canonical_plan_id`` is deterministic: ``sha256(event_id + version)``.
+   A retry of the same event returns the same plan id, which Desktop
+   can use to skip actions it already completed locally.
+2. Before regenerating a plan for a previously dispatched event, Brain
+   checks whether the session already wrote a ``session_diary`` row
+   after the original ``canonical_dispatched_at``. If it did → the
+   answer is ``already_processed``; no re-dispatch, no duplicate diary.
+
+Status values:
+
+- ``processed``           first delivery, no canonical plan applicable
+                          (e.g. switch / window-close / missing
+                          session_id).
+- ``canonical_pending``   plan generated and returned. Desktop is
+                          expected to execute + confirm.
+- ``canonical_dispatched`` alias for ``canonical_pending`` on a row
+                          that already has ``canonical_dispatched_at``
+                          set (re-delivery case).
+- ``canonical_done``      Desktop confirmed via complete_canonical.
+- ``already_processed``   idempotent duplicate, no re-run.
+- ``accepted``            persisted, no canonical side effect required.
+- ``rejected``            malformed input.
+- ``retryable_error``     a canonical action failed (inject timeout,
+                          stdin closed, etc). Reconciler can retry
+                          with the same plan_id.
+
+Actions that carry a canonical plan: ``close``, ``delete``, ``archive``,
+``app-exit``. ``switch`` and ``window-close`` still return
+``accepted`` (no live-session work to do).
 """
 from __future__ import annotations
 
@@ -38,6 +54,7 @@ import json
 from typing import Any, Dict, Optional
 
 from db import get_db
+import lifecycle_prompts
 
 
 VALID_ACTIONS = {
@@ -49,8 +66,14 @@ VALID_ACTIONS = {
     "window-close",
 }
 
-TERMINAL_STATUSES = {"processed", "already_processed", "rejected"}
-_DIARY_TRIGGERING = {"close", "delete", "archive", "app-exit"}
+# Terminal for the user of the ledger (no further action expected).
+TERMINAL_STATUSES = {
+    "processed",
+    "canonical_done",
+    "already_processed",
+    "rejected",
+}
+_DIARY_TRIGGERING = lifecycle_prompts.DIARY_TRIGGERING_ACTIONS
 
 
 def _normalise_payload(obj: Any) -> str:
@@ -60,6 +83,26 @@ def _normalise_payload(obj: Any) -> str:
         return "{}"
 
 
+def _session_diary_since(conn, session_id: str, dispatched_at: Optional[str]) -> bool:
+    """True if session_diary has a row for ``session_id`` created after
+    ``dispatched_at``. Used by the canonical-authority idempotency
+    guard: if the live session already produced a diary since the
+    plan was handed out, we must NOT re-dispatch it.
+    """
+    if not session_id or not dispatched_at:
+        return False
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM session_diary "
+            "WHERE session_id = ? AND created_at > ? LIMIT 1",
+            (str(session_id), str(dispatched_at)),
+        ).fetchone()
+    except Exception:
+        # Missing table on a minimal test harness — treat as "no diary".
+        return False
+    return row is not None
+
+
 def record_lifecycle_event(
     event_id: str,
     action: str,
@@ -70,9 +113,15 @@ def record_lifecycle_event(
     source: str = "desktop",
     schema_version: int = 1,
 ) -> Dict[str, Any]:
-    """Idempotent upsert + process.
+    """Idempotent upsert + canonical plan generation (v7.5).
 
-    Returns ``{status, event_id, diary_triggered, duplicate}``.
+    Returns ``{status, event_id, ...}`` where ``status`` is one of:
+    ``rejected`` | ``already_processed`` | ``processed`` |
+    ``canonical_pending`` | ``accepted``. When the answer is
+    ``canonical_pending``, the response also carries
+    ``canonical_plan_id``, ``canonical_plan_version`` and
+    ``canonical_actions[]`` — Desktop must execute those actions and
+    confirm via ``record_complete_canonical``.
     """
     if not event_id or not str(event_id).strip():
         return {"status": "rejected", "reason": "missing-event-id"}
@@ -83,12 +132,32 @@ def record_lifecycle_event(
 
     conn = get_db()
     existing = conn.execute(
-        "SELECT delivery_status FROM lifecycle_events WHERE event_id = ?",
+        "SELECT delivery_status, canonical_plan_id, canonical_plan_version, "
+        "canonical_actions_json, canonical_dispatched_at, canonical_done_at "
+        "FROM lifecycle_events WHERE event_id = ?",
         (str(event_id),),
     ).fetchone()
 
+    plan = lifecycle_prompts.build_canonical_plan(
+        event_id=str(event_id),
+        action=str(action),
+        conversation_id=str(conversation_id),
+        session_id=str(session_id) if session_id else None,
+        payload_snapshot=payload_snapshot or {},
+    )
+
     if existing is not None:
         status = str(existing[0] or "")
+        prior_plan_id = existing[1]
+        prior_actions_json = existing[3]
+        prior_dispatched_at = existing[5]  # column 5 is canonical_done_at — reuse?
+        # column indices (0-5): delivery_status, canonical_plan_id,
+        # canonical_plan_version, canonical_actions_json,
+        # canonical_dispatched_at, canonical_done_at.
+        prior_dispatched_at = existing[4]
+        prior_done_at = existing[5]
+
+        # Case A: terminal status already recorded — hard idempotency.
         if status in TERMINAL_STATUSES:
             return {
                 "status": "already_processed",
@@ -96,8 +165,73 @@ def record_lifecycle_event(
                 "duplicate": True,
                 "prior_status": status,
             }
-        # Non-terminal row (accepted / retryable_error) — flip to processed
-        # now and record the transition.
+
+        # Case B: canonical was dispatched but never confirmed. Check
+        # whether the live session wrote a diary after dispatch; if so
+        # the intent has already been satisfied by the model and we
+        # must NOT ask Desktop to re-run the plan.
+        if prior_plan_id and prior_dispatched_at and not prior_done_at:
+            if session_id and _session_diary_since(conn, str(session_id), str(prior_dispatched_at)):
+                conn.execute(
+                    "UPDATE lifecycle_events "
+                    "SET delivery_status = 'already_processed', "
+                    "    canonical_done_at = datetime('now'), "
+                    "    last_error = NULL "
+                    "WHERE event_id = ?",
+                    (str(event_id),),
+                )
+                conn.commit()
+                return {
+                    "status": "already_processed",
+                    "event_id": event_id,
+                    "duplicate": True,
+                    "prior_status": status,
+                    "reason": "session_diary-already-written",
+                }
+            # Re-hand the exact same plan so Desktop can resume / finish
+            # any actions it didn't complete before the crash.
+            try:
+                actions = json.loads(prior_actions_json) if prior_actions_json else []
+            except Exception:
+                actions = []
+            return {
+                "status": "canonical_pending",
+                "event_id": event_id,
+                "canonical_plan_id": prior_plan_id,
+                "canonical_plan_version": int(existing[2] or lifecycle_prompts.PLAN_VERSION),
+                "canonical_actions": actions,
+                "resumed_from_dispatch": True,
+            }
+
+        # Case C: non-terminal, no canonical plan yet — flip to processed
+        # (legacy ledger semantics) OR upgrade to canonical_pending if a
+        # plan applies.
+        if plan is not None:
+            conn.execute(
+                "UPDATE lifecycle_events "
+                "SET delivery_status = 'canonical_pending', "
+                "    canonical_plan_id = ?, "
+                "    canonical_plan_version = ?, "
+                "    canonical_actions_json = ?, "
+                "    canonical_dispatched_at = datetime('now'), "
+                "    last_error = NULL "
+                "WHERE event_id = ?",
+                (
+                    plan["canonical_plan_id"],
+                    int(plan["canonical_plan_version"]),
+                    json.dumps(plan["canonical_actions"], ensure_ascii=False),
+                    str(event_id),
+                ),
+            )
+            conn.commit()
+            return {
+                "status": "canonical_pending",
+                "event_id": event_id,
+                "canonical_plan_id": plan["canonical_plan_id"],
+                "canonical_plan_version": plan["canonical_plan_version"],
+                "canonical_actions": plan["canonical_actions"],
+                "reopened": True,
+            }
         conn.execute(
             "UPDATE lifecycle_events SET delivery_status = 'processed', "
             "processed_at = datetime('now'), last_error = NULL "
@@ -113,6 +247,45 @@ def record_lifecycle_event(
             "reopened": True,
         }
 
+    # Brand new event.
+    if plan is not None:
+        conn.execute(
+            """
+            INSERT INTO lifecycle_events (
+                event_id, schema_version, source, action, conversation_id,
+                session_id, reason, payload_snapshot, delivery_status,
+                retry_count, canonical_plan_id, canonical_plan_version,
+                canonical_actions_json, canonical_dispatched_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'canonical_pending', 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),
+                plan["canonical_plan_id"],
+                int(plan["canonical_plan_version"]),
+                json.dumps(plan["canonical_actions"], ensure_ascii=False),
+            ),
+        )
+        conn.commit()
+        return {
+            "status": "canonical_pending",
+            "event_id": event_id,
+            "canonical_plan_id": plan["canonical_plan_id"],
+            "canonical_plan_version": plan["canonical_plan_version"],
+            "canonical_actions": plan["canonical_actions"],
+            "duplicate": False,
+        }
+
+    # No plan: ledger-only record (switch/window-close or missing
+    # session_id on a diary-triggering action). Mark processed
+    # immediately so callers get the v7.4.x contract back.
     conn.execute(
         """
         INSERT INTO lifecycle_events (
@@ -133,7 +306,6 @@ def record_lifecycle_event(
         ),
     )
     conn.commit()
-
     return {
         "status": "processed",
         "event_id": event_id,
@@ -142,13 +314,94 @@ def record_lifecycle_event(
     }
 
 
+def record_complete_canonical(
+    event_id: str,
+    canonical_plan_id: str,
+    results: Optional[list] = None,
+) -> Dict[str, Any]:
+    """Close the 2-call contract: Desktop confirms it executed the plan.
+
+    Inputs:
+    - ``event_id``: the original event id.
+    - ``canonical_plan_id``: must match the one Brain handed out. A
+      mismatch means Desktop is confirming a stale plan — we ignore
+      it and answer ``rejected``.
+    - ``results``: list of ``{action_id, status, ...}``. If any
+      ``status != 'ok'`` we flip the row to ``retryable_error`` and
+      keep ``canonical_dispatched_at`` intact so reconciliation can
+      re-ask.
+
+    Returns the effective row status after the call.
+    """
+    if not event_id:
+        return {"status": "rejected", "reason": "missing-event-id"}
+    if not canonical_plan_id:
+        return {"status": "rejected", "reason": "missing-canonical-plan-id"}
+
+    conn = get_db()
+    row = conn.execute(
+        "SELECT delivery_status, canonical_plan_id, canonical_done_at "
+        "FROM lifecycle_events WHERE event_id = ?",
+        (str(event_id),),
+    ).fetchone()
+    if row is None:
+        return {"status": "rejected", "reason": "unknown-event-id"}
+    current_status = str(row[0] or "")
+    expected_plan = row[1]
+    already_done_at = row[2]
+
+    if expected_plan and canonical_plan_id != expected_plan:
+        return {
+            "status": "rejected",
+            "reason": "canonical_plan_id-mismatch",
+            "expected": expected_plan,
+            "received": canonical_plan_id,
+        }
+    if already_done_at and current_status == "canonical_done":
+        return {
+            "status": "already_processed",
+            "event_id": event_id,
+            "duplicate": True,
+        }
+
+    results_list = list(results or [])
+    any_failure = any(
+        str((r or {}).get("status", "")).lower() not in {"ok", "success", "already_processed"}
+        for r in results_list
+    )
+    effective = "retryable_error" if any_failure else "canonical_done"
+    conn.execute(
+        "UPDATE lifecycle_events "
+        "SET delivery_status = ?, "
+        "    canonical_done_at = datetime('now'), "
+        "    canonical_done_results = ?, "
+        "    last_error = ? "
+        "WHERE event_id = ?",
+        (
+            effective,
+            json.dumps(results_list, ensure_ascii=False),
+            "one-or-more-actions-failed" if any_failure else None,
+            str(event_id),
+        ),
+    )
+    conn.commit()
+    return {
+        "status": effective,
+        "event_id": event_id,
+        "canonical_plan_id": canonical_plan_id,
+        "failed_actions": any_failure,
+    }
+
+
 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 "
+        "created_at, processed_at, last_error, "
+        "canonical_plan_id, canonical_plan_version, canonical_actions_json, "
+        "canonical_dispatched_at, canonical_done_at, canonical_done_results "
         "FROM lifecycle_events WHERE event_id = ?",
         (str(event_id),),
     ).fetchone()
@@ -158,6 +411,14 @@ def get_lifecycle_event(event_id: str) -> Optional[Dict[str, Any]]:
         payload = json.loads(row[7] or "{}")
     except Exception:
         payload = {}
+    try:
+        actions = json.loads(row[15]) if row[15] else None
+    except Exception:
+        actions = None
+    try:
+        results = json.loads(row[18]) if row[18] else None
+    except Exception:
+        results = None
     return {
         "event_id": row[0],
         "schema_version": row[1],
@@ -172,6 +433,12 @@ def get_lifecycle_event(event_id: str) -> Optional[Dict[str, Any]]:
         "created_at": row[10],
         "processed_at": row[11],
         "last_error": row[12],
+        "canonical_plan_id": row[13],
+        "canonical_plan_version": row[14],
+        "canonical_actions": actions,
+        "canonical_dispatched_at": row[16],
+        "canonical_done_at": row[17],
+        "canonical_done_results": results,
     }
 
 

package/src/lifecycle_prompts.py

@@ -0,0 +1,138 @@
+"""NEXO Brain — canonical lifecycle action templates (v7.5).
+
+Brain owns the prompt that Desktop injects into a live Claude session
+at close / delete / archive / app-exit time. Desktop never hardcodes
+the wording; it just receives a list of ``canonical_actions`` and
+executes them against the conversation's stdin / lifecycle.
+
+The template version is bumped whenever the prompt or the action
+schema changes. The version is part of ``canonical_plan_id`` so two
+dispatches of the same event produced by two different Brain versions
+do NOT collide (a retry from an older Desktop hitting a newer Brain
+will get the newer plan; a retry of a previous plan reuses the same
+id because the event_id hasn't changed).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Dict, List, Optional
+
+
+PLAN_VERSION = 1
+
+
+# Actions that trigger a canonical diary+stop plan. `switch` and
+# `window-close` never do: they're observational transitions that Brain
+# records in the ledger but doesn't orchestrate anything against the
+# live session (the session keeps running after a switch, and a window
+# close to the tray doesn't end the conversation).
+DIARY_TRIGGERING_ACTIONS = {"close", "delete", "archive", "app-exit"}
+
+
+# Default per-action timeout (ms). Desktop honours this when it
+# executes each action; on timeout it reports status=failed and Brain
+# flips delivery_status to retryable_error.
+DEFAULT_RESUME_TIMEOUT_MS = 2_000
+DEFAULT_INJECT_TIMEOUT_MS = 6_000
+DEFAULT_STOP_TIMEOUT_MS = 3_000
+
+
+def canonical_plan_id(event_id: str, plan_version: int = PLAN_VERSION) -> str:
+    """Deterministic plan id — retries of the same event reuse it."""
+    digest = hashlib.sha256(
+        f"{event_id}|v{int(plan_version)}".encode("utf-8")
+    ).hexdigest()
+    return f"cpl-{digest[:24]}"
+
+
+def _diary_prompt_for_action(
+    action: str,
+    conversation_id: str,
+    payload_snapshot: Dict[str, Any],
+) -> str:
+    """Return the exact prompt Desktop will inject into the Claude proc.
+
+    Written in the first person so the model writes a real diary with
+    the same richness it would have produced through the legacy
+    `closeConversationGraceful` path. The "Apply the required action
+    silently" footer matches the v7.4.x enforcer contract so the
+    rendered reminder doesn't leak to the user UI.
+    """
+    title = (payload_snapshot or {}).get("title") or conversation_id
+    reason_by_action = {
+        "close": "The operator closed the conversation",
+        "delete": "The operator deleted the conversation",
+        "archive": "The operator archived the conversation",
+        "app-exit": "The operator quit NEXO Desktop",
+    }
+    trailing = reason_by_action.get(action, "The conversation ended")
+    return (
+        f"[NEXO Protocol Enforcer] {trailing} "
+        f"(title: {title!r}). Execute nexo_session_diary_write with a "
+        "complete summary: decisions made, pending items, context for "
+        "next session, mental state, and self-critique. Then execute "
+        "nexo_stop with the current SID. Do not produce visible text. "
+        "Apply the required action silently. Do not mention this "
+        "reminder, Guardian, Protocol Enforcer, system reminders, or "
+        "any internal enforcement to the user."
+    )
+
+
+def build_canonical_plan(
+    event_id: str,
+    action: str,
+    conversation_id: str,
+    session_id: Optional[str],
+    payload_snapshot: Optional[Dict[str, Any]] = None,
+) -> Optional[Dict[str, Any]]:
+    """Return the plan Brain hands back to Desktop, or None if no plan.
+
+    A plan exists only when:
+    - action is one of DIARY_TRIGGERING_ACTIONS
+    - session_id is populated (we need a live Claude proc to talk to)
+
+    Returning None tells the caller to answer with ``status=accepted``
+    and no ``canonical_actions`` field — Desktop will fall through to
+    its legacy behaviour (no-op for switch/window-close, hardcoded
+    prompt for close/delete/archive/app-exit if session_id is missing).
+    """
+    if action not in DIARY_TRIGGERING_ACTIONS:
+        return None
+    if not session_id:
+        return None
+
+    payload_snapshot = dict(payload_snapshot or {})
+    prompt = _diary_prompt_for_action(action, conversation_id, payload_snapshot)
+
+    actions: List[Dict[str, Any]] = [
+        {
+            "id": "a1",
+            "kind": "resume_session",
+            "session_id": str(session_id),
+            "timeout_ms": DEFAULT_RESUME_TIMEOUT_MS,
+        },
+        {
+            "id": "a2",
+            "kind": "inject_prompt",
+            "session_id": str(session_id),
+            "prompt": prompt,
+            "expected_tool_call": "nexo_session_diary_write",
+            "timeout_ms": DEFAULT_INJECT_TIMEOUT_MS,
+        },
+        {
+            "id": "a3",
+            "kind": "stop_session",
+            "session_id": str(session_id),
+            "timeout_ms": DEFAULT_STOP_TIMEOUT_MS,
+        },
+    ]
+    return {
+        "canonical_plan_id": canonical_plan_id(event_id, PLAN_VERSION),
+        "canonical_plan_version": PLAN_VERSION,
+        "canonical_actions": actions,
+    }
+
+
+def canonical_plan_as_json(plan: Dict[str, Any]) -> str:
+    return json.dumps(plan, ensure_ascii=False, sort_keys=True)

package/src/plugins/lifecycle_events.py

@@ -99,15 +99,68 @@ def handle_nexo_lifecycle_status(event_id: str) -> str:
     return json.dumps(row, ensure_ascii=False)
 
 
+def handle_nexo_lifecycle_complete_canonical(
+    event_id: str,
+    canonical_plan_id: str,
+    results: str = "",
+) -> str:
+    """Close the v7.5 canonical-authority 2-call contract.
+
+    Desktop calls this tool after executing every action Brain returned
+    in the ``canonical_actions`` array from ``nexo_lifecycle_event``.
+    Brain then records ``canonical_done_at`` and flips the row status
+    to ``canonical_done`` (or ``retryable_error`` if any action
+    failed).
+
+    Args:
+        event_id: UUID of the original lifecycle event.
+        canonical_plan_id: The plan id Brain returned. Mismatch → rejected.
+        results: JSON-encoded array of per-action outcomes:
+            ``[{"action_id": "a1", "status": "ok"|"failed", ...}, ...]``
+
+    Returns:
+        JSON ack with the effective row status.
+    """
+    parsed_results: list = []
+    if results:
+        try:
+            parsed = json.loads(results)
+            if isinstance(parsed, list):
+                parsed_results = parsed
+            else:
+                parsed_results = [{"status": "failed", "reason": "results-not-array", "raw": str(results)[:200]}]
+        except Exception as exc:
+            parsed_results = [{"status": "failed", "reason": f"malformed-results:{exc}"}]
+
+    try:
+        ack = lifecycle_events.record_complete_canonical(
+            event_id=str(event_id or ""),
+            canonical_plan_id=str(canonical_plan_id or ""),
+            results=parsed_results,
+        )
+    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(ack, 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.",
+        "Record a durable lifecycle event (close/delete/archive/switch/app-exit/window-close). In v7.5 Brain returns a canonical_actions plan for diary-triggering actions with a live session_id.",
     ),
     (
         handle_nexo_lifecycle_status,
         "nexo_lifecycle_status",
         "Read the current delivery_status of a lifecycle event. Used by Desktop boot reconciliation.",
     ),
+    (
+        handle_nexo_lifecycle_complete_canonical,
+        "nexo_lifecycle_complete_canonical",
+        "Confirm that Desktop finished executing the canonical_actions Brain handed out in a prior nexo_lifecycle_event call. Brain marks canonical_done_at only on this confirmation.",
+    ),
 ]

package/tool-enforcement-map.json

@@ -1869,6 +1869,19 @@
       },
       "triggers_after": []
     },
+    "nexo_lifecycle_complete_canonical": {
+      "description": "Close the v7.5 canonical-authority 2-call contract: confirm that Desktop finished executing the canonical_actions Brain handed out.",
+      "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",