nexo-brain 7.13.3 → 7.13.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.13.3",
+  "version": "7.13.5",
   "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.13.3` is the current packaged-runtime line. Unified release — doctor now repairs orphan personal script metadata and ignores historical `versions/**` snapshots, `nexo update` prunes runtime snapshots older than two back, protocol compliance self-heals missing task-open/change-log/stale-session gaps, headless automation uses bounded timeouts, Guardian false positives are tightened, and Codex CLI parity is release-gated. Result: coordinated Desktop bundles can ship the new Brain without changing the Mac/Windows installation contract.
+Version `7.13.5` is the current packaged-runtime line. Corrective release — D.5 correction-learning enforcement is durable, doctor `--fix` explicitly repairs orphan personal schedule metadata, G5 now warns on protected `com.nexo.*.plist` unload/remove flows with the three-layer recovery path, and Codex now gets a managed `PreToolUse` guard for shell/exec_command calls plus `installation_live.codex_protocol_compliance` drift checks. Result: coordinated Desktop bundles can ship the fixed Brain without changing the Mac/Windows installation contract.
+
+Previously in `7.13.3`: unified release — doctor now repairs orphan personal script metadata and ignores historical `versions/**` snapshots, `nexo update` prunes runtime snapshots older than two back, protocol compliance self-heals missing task-open/change-log/stale-session gaps, headless automation uses bounded timeouts, Guardian false positives are tightened, and Codex CLI config/default checks are release-gated. Result: coordinated Desktop bundles can ship the new Brain without changing the Mac/Windows installation contract.
 
 Previously in `7.12.15`: patch release — same-version packaged updates now still run the safe maintenance path, Deep Sleep clears process locks on shutdown, sent replies are recorded in durable continuity, and personal script schedule-marker drift is surfaced during reconcile. Result: coordinated Desktop bundles can refresh Brain safely without breaking install/update parity on macOS, Windows via WSL, or Linux.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "7.13.3",
+  "version": "7.13.5",
   "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.",
+  "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",
   "bin": {
     "nexo-brain": "bin/nexo-brain.js",

package/src/client_sync.py

@@ -527,6 +527,11 @@ def _codex_config_path(home: Path | None = None) -> Path:
     return base / ".codex" / "config.toml"
 
 
+def _codex_hooks_path(home: Path | None = None) -> Path:
+    base = home or _user_home()
+    return base / ".codex" / "hooks.json"
+
+
 def _toml_key(key: str) -> str:
     if key.replace("_", "").replace("-", "").isalnum():
         return key
@@ -632,6 +637,12 @@ def _sync_codex_managed_config(
     if "reasoning_effort" in runtime_profile:
         payload["model_reasoning_effort"] = runtime_profile.get("reasoning_effort") or ""
 
+    features = payload.setdefault("features", {})
+    if isinstance(features, dict):
+        features["codex_hooks"] = True
+    else:
+        payload["features"] = {"codex_hooks": True}
+
     payload["initial_messages"] = [
         {
             "role": "system",
@@ -643,6 +654,7 @@ def _sync_codex_managed_config(
     codex_table = nexo_table.setdefault("codex", {})
     codex_table["bootstrap_managed"] = True
     codex_table["mcp_managed"] = True
+    codex_table["hooks_managed"] = True
     codex_table["bootstrap_bytes"] = len(bootstrap_prompt.encode("utf-8")) if bootstrap_prompt else 0
     if runtime_profile.get("model"):
         # Record the healed/actual model in use, not the raw (possibly Claude) profile.
@@ -670,11 +682,127 @@ def _sync_codex_managed_config(
         "path": str(path),
         "bootstrap_managed": True,
         "mcp_managed": True,
+        "hooks_enabled": True,
         "model": runtime_profile.get("model", ""),
         "reasoning_effort": runtime_profile.get("reasoning_effort", "") or "",
     }
 
 
+CODEX_SUPPORTED_HOOK_EVENTS = {"PreToolUse"}
+CODEX_PRETOOL_MATCHER = r"^(Bash|shell_command|exec_command)$"
+
+
+def _codex_core_hook_specs(runtime_root: Path) -> list[dict]:
+    specs: list[dict] = []
+    for spec in _core_hook_specs(runtime_root):
+        if spec.get("event") not in CODEX_SUPPORTED_HOOK_EVENTS:
+            continue
+        item = dict(spec)
+        if item.get("event") == "PreToolUse":
+            item["matcher"] = CODEX_PRETOOL_MATCHER
+            item["statusMessage"] = "NEXO guard"
+        specs.append(item)
+    return specs
+
+
+def _merge_codex_hooks(existing_hooks, *, runtime_root: Path, nexo_home: Path) -> tuple[dict, int]:
+    hooks_payload = dict(existing_hooks) if isinstance(existing_hooks, dict) else {}
+    hooks_dir = _resolve_hook_source_dir(runtime_root)
+    managed_count = 0
+    core_hook_specs = _codex_core_hook_specs(runtime_root)
+    current_identities_by_event = _current_core_hook_identities_by_event(core_hook_specs)
+    managed_identities_by_event = _managed_core_hook_identities_by_event(current_identities_by_event)
+
+    for event, managed_identities in managed_identities_by_event.items():
+        sections = _normalize_hook_sections(hooks_payload.get(event))
+        desired_identities = current_identities_by_event.get(event, set())
+        cleaned_sections: list[dict] = []
+        for section in sections:
+            cleaned_hooks = []
+            for hook in section["hooks"]:
+                identity = _hook_identity(hook.get("command", ""))
+                if identity in managed_identities and identity not in desired_identities:
+                    continue
+                cleaned_hooks.append(hook)
+            if cleaned_hooks:
+                cleaned_sections.append(
+                    {
+                        "matcher": section.get("matcher", "*") or "*",
+                        "hooks": cleaned_hooks,
+                    }
+                )
+        if cleaned_sections:
+            hooks_payload[event] = cleaned_sections
+        elif event in hooks_payload and event in current_identities_by_event:
+            hooks_payload.pop(event, None)
+
+    for spec in core_hook_specs:
+        event = spec["event"]
+        sections = _normalize_hook_sections(hooks_payload.get(event))
+        hooks_payload[event] = sections
+        command = _render_hook_command(spec, nexo_home=nexo_home, runtime_root=runtime_root, hooks_dir=hooks_dir)
+        identity = spec["identity"]
+        matcher = spec.get("matcher") or "*"
+
+        found = False
+        for section in sections:
+            for hook in section["hooks"]:
+                if _hook_identity(hook.get("command", "")) != identity:
+                    continue
+                section["matcher"] = matcher
+                hook["type"] = "command"
+                hook["command"] = command
+                if spec.get("timeout"):
+                    hook["timeout"] = spec["timeout"]
+                if spec.get("statusMessage"):
+                    hook["statusMessage"] = spec["statusMessage"]
+                found = True
+                managed_count += 1
+                break
+            if found:
+                break
+
+        if found:
+            continue
+
+        target = None
+        for section in sections:
+            if section.get("matcher", "*") == matcher:
+                target = section
+                break
+        if target is None:
+            target = {"matcher": matcher, "hooks": []}
+            sections.append(target)
+
+        new_hook = {"type": "command", "command": command}
+        if spec.get("timeout"):
+            new_hook["timeout"] = spec["timeout"]
+        if spec.get("statusMessage"):
+            new_hook["statusMessage"] = spec["statusMessage"]
+        target["hooks"].append(new_hook)
+        managed_count += 1
+
+    return hooks_payload, managed_count
+
+
+def _sync_codex_hooks(path: Path, *, runtime_root: Path, nexo_home: Path) -> dict:
+    payload = _load_json_object(path)
+    action = "updated" if payload else "created"
+    payload["hooks"], managed_count = _merge_codex_hooks(
+        payload.get("hooks", {}),
+        runtime_root=runtime_root,
+        nexo_home=nexo_home,
+    )
+    _write_json_object(path, payload)
+    return {
+        "ok": True,
+        "action": action,
+        "path": str(path),
+        "managed_hook_count": managed_count,
+        "pretool_matcher": CODEX_PRETOOL_MATCHER,
+    }
+
+
 def _load_json_object(path: Path) -> dict:
     if not path.is_file():
         return {}
@@ -1187,6 +1315,7 @@ def sync_codex(
     )
     codex_bin = shutil.which("codex")
     config_path = _codex_config_path(home_path)
+    hooks_path = _codex_hooks_path(home_path)
     if not codex_bin:
         result = {
             "ok": True,
@@ -1210,6 +1339,11 @@ def sync_codex(
                 runtime_profile=runtime_profile,
                 server_config=server_config,
             )
+            result["hooks"] = _sync_codex_hooks(
+                hooks_path,
+                runtime_root=Path(runtime_root).expanduser() if runtime_root else _resolve_runtime_root(nexo_home_path),
+                nexo_home=nexo_home_path,
+            )
         return result
 
     cmd = [codex_bin, "mcp", "add", "nexo"]
@@ -1248,6 +1382,11 @@ def sync_codex(
         runtime_profile=runtime_profile,
         server_config=server_config,
     )
+    sync_result["hooks"] = _sync_codex_hooks(
+        hooks_path,
+        runtime_root=Path(runtime_root).expanduser() if runtime_root else _resolve_runtime_root(nexo_home_path),
+        nexo_home=nexo_home_path,
+    )
     if result.returncode != 0:
         sync_result["warning"] = (result.stderr or result.stdout or "codex mcp add failed").strip()
     return sync_result

package/src/db/__init__.py

@@ -169,6 +169,9 @@ from db._protocol import (
     create_protocol_task, get_protocol_task, close_protocol_task,
     set_protocol_task_guard_acknowledged,
     create_protocol_debt, resolve_protocol_debts, list_protocol_debts,
+    record_session_correction_requirement, list_session_correction_requirements,
+    session_has_open_correction_requirement, resolve_session_correction_requirements,
+    correction_requirement_summary,
     protocol_compliance_summary,
     create_cortex_evaluation, get_cortex_evaluation, list_cortex_evaluations,
     cortex_evaluation_summary,

package/src/db/_protocol.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 """NEXO DB — Protocol discipline runtime."""
 
 import json
+import hashlib
 import secrets
 import time
 
@@ -34,6 +35,12 @@ def _row_to_dict(row):
     return dict(row) if row else None
 
 
+def _correction_context_hash(session_id: str, text: str) -> str:
+    clean = " ".join(str(text or "").strip().split())[:1200]
+    digest = hashlib.sha1(f"{session_id.strip()}\0{clean}".encode("utf-8"), usedforsecurity=False)
+    return digest.hexdigest()[:20]
+
+
 def validate_task_type(task_type: str) -> str:
     clean_type = (task_type or "").strip()
     if clean_type not in VALID_TASK_TYPES:
@@ -529,6 +536,155 @@ def list_protocol_debts(
     return [dict(row) for row in rows]
 
 
+def record_session_correction_requirement(
+    session_id: str,
+    correction_text: str,
+    *,
+    source: str = "heartbeat",
+) -> dict:
+    """Persist that a detected user correction requires a learning_add."""
+    conn = get_db()
+    clean_sid = str(session_id or "").strip()
+    if not clean_sid:
+        return {"ok": False, "error": "session_id is required"}
+    clean_text = " ".join(str(correction_text or "").strip().split())
+    context_hash = _correction_context_hash(clean_sid, clean_text)
+    conn.execute(
+        """INSERT OR IGNORE INTO session_correction_requirements
+           (session_id, context_hash, correction_text, source)
+           VALUES (?, ?, ?, ?)""",
+        (clean_sid, context_hash, clean_text[:4000], str(source or "heartbeat").strip()[:80]),
+    )
+    conn.commit()
+    row = conn.execute(
+        """SELECT *
+           FROM session_correction_requirements
+           WHERE session_id = ? AND context_hash = ?
+           LIMIT 1""",
+        (clean_sid, context_hash),
+    ).fetchone()
+    out = _row_to_dict(row) or {}
+    out["ok"] = True
+    return out
+
+
+def list_session_correction_requirements(
+    *,
+    session_id: str = "",
+    status: str = "open",
+    limit: int = 50,
+) -> list[dict]:
+    conn = get_db()
+    clauses: list[str] = []
+    params: list[object] = []
+    if session_id:
+        clauses.append("session_id = ?")
+        params.append(str(session_id).strip())
+    if status:
+        clauses.append("status = ?")
+        params.append(str(status).strip())
+    where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+    rows = conn.execute(
+        f"""SELECT *
+            FROM session_correction_requirements
+            {where}
+            ORDER BY detected_at DESC, id DESC
+            LIMIT ?""",
+        params + [max(1, int(limit or 50))],
+    ).fetchall()
+    return [dict(row) for row in rows]
+
+
+def session_has_open_correction_requirement(session_id: str) -> bool:
+    if not str(session_id or "").strip():
+        return False
+    conn = get_db()
+    row = conn.execute(
+        """SELECT 1
+           FROM session_correction_requirements
+           WHERE session_id = ? AND status = 'open'
+           LIMIT 1""",
+        (str(session_id).strip(),),
+    ).fetchone()
+    return bool(row)
+
+
+def resolve_session_correction_requirements(
+    *,
+    session_id: str = "",
+    learning_id: int | None = None,
+) -> int:
+    """Resolve open correction requirements after a real learning_add."""
+    conn = get_db()
+    clean_sid = str(session_id or "").strip()
+    if not clean_sid:
+        rows = conn.execute(
+            """SELECT session_id, COUNT(*) AS total
+               FROM session_correction_requirements
+               WHERE status = 'open'
+               GROUP BY session_id
+               ORDER BY MAX(detected_at) DESC"""
+        ).fetchall()
+        if len(rows) == 1:
+            clean_sid = str(rows[0]["session_id"] or "").strip()
+        else:
+            try:
+                row = conn.execute(
+                    """SELECT r.session_id
+                       FROM session_correction_requirements r
+                       LEFT JOIN sessions s ON s.sid = r.session_id
+                       WHERE r.status = 'open'
+                       ORDER BY COALESCE(s.last_heartbeat_ts, s.last_update_epoch, s.started_epoch, 0) DESC,
+                                r.detected_at DESC
+                       LIMIT 1"""
+                ).fetchone()
+            except Exception:
+                row = None
+            clean_sid = str(row["session_id"] or "").strip() if row else ""
+        if not clean_sid:
+            return 0
+    cursor = conn.execute(
+        """UPDATE session_correction_requirements
+           SET status = 'resolved',
+               resolved_at = datetime('now'),
+               resolved_learning_id = ?
+           WHERE session_id = ? AND status = 'open'""",
+        (int(learning_id) if learning_id else None, clean_sid),
+    )
+    conn.commit()
+    if cursor.rowcount:
+        resolve_protocol_debts(
+            session_id=clean_sid,
+            debt_types=["missing_learning_after_correction"],
+            resolution=f"Learning #{learning_id} persisted after user correction.",
+        )
+    return int(cursor.rowcount or 0)
+
+
+def correction_requirement_summary(session_id: str = "") -> dict:
+    conn = get_db()
+    clauses: list[str] = []
+    params: list[object] = []
+    if session_id:
+        clauses.append("session_id = ?")
+        params.append(str(session_id).strip())
+    where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+    rows = conn.execute(
+        f"""SELECT status, COUNT(*) AS total
+            FROM session_correction_requirements
+            {where}
+            GROUP BY status"""
+    ).fetchall()
+    counts = {str(row["status"]): int(row["total"] or 0) for row in rows}
+    return {
+        "session_id": str(session_id or "").strip(),
+        "corrections_detected": sum(counts.values()),
+        "learnings_persisted": counts.get("resolved", 0),
+        "open_requirements": counts.get("open", 0),
+        "by_status": counts,
+    }
+
+
 def protocol_compliance_summary(days: int = 7) -> dict:
     conn = get_db()
     window = f"-{max(1, int(days))} days"

package/src/db/_schema.py

@@ -923,6 +923,28 @@ def _m55_cortex_critique_trace(conn):
     _migrate_add_column(conn, "cortex_evaluations", "decision_mode", "TEXT DEFAULT 'heuristic'")
 
 
+def _m56_session_correction_requirements(conn):
+    """Track user corrections that must be turned into durable learnings."""
+    conn.execute(
+        """CREATE TABLE IF NOT EXISTS session_correction_requirements (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id TEXT NOT NULL,
+            context_hash TEXT NOT NULL,
+            correction_text TEXT DEFAULT '',
+            source TEXT DEFAULT 'heartbeat',
+            status TEXT NOT NULL DEFAULT 'open',
+            detected_at TEXT DEFAULT (datetime('now')),
+            resolved_at TEXT DEFAULT NULL,
+            resolved_learning_id INTEGER DEFAULT NULL,
+            followup_id TEXT DEFAULT '',
+            UNIQUE(session_id, context_hash)
+        )"""
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_session_correction_requirements_session ON session_correction_requirements(session_id)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_session_correction_requirements_status ON session_correction_requirements(status)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_session_correction_requirements_detected ON session_correction_requirements(detected_at)")
+
+
 def _m39_hook_runs(conn):
     """Persist hook lifecycle observability — closes Fase 3 item 7.
 
@@ -1494,6 +1516,7 @@ MIGRATIONS = [
     (53, "session_conversation_identity", _m53_session_conversation_identity),
     (54, "continuity_snapshots", _m54_continuity_snapshots),
     (55, "cortex_critique_trace", _m55_cortex_critique_trace),
+    (56, "session_correction_requirements", _m56_session_correction_requirements),
 ]
 
 

package/src/doctor/providers/runtime.py

@@ -185,6 +185,52 @@ def _codex_bootstrap_config_status() -> dict:
     }
 
 
+def _codex_hooks_config_status() -> dict:
+    path = Path.home() / ".codex" / "hooks.json"
+    if not path.is_file():
+        return {
+            "exists": False,
+            "path": str(path),
+            "pretool_managed": False,
+            "pretool_command": "",
+        }
+    try:
+        payload = json.loads(path.read_text())
+    except Exception as exc:
+        return {
+            "exists": True,
+            "path": str(path),
+            "pretool_managed": False,
+            "pretool_command": "",
+            "error": str(exc),
+        }
+    hooks = payload.get("hooks") if isinstance(payload, dict) else {}
+    pretool = hooks.get("PreToolUse") if isinstance(hooks, dict) else []
+    for section in pretool or []:
+        if not isinstance(section, dict):
+            continue
+        matcher = str(section.get("matcher") or "")
+        for hook in section.get("hooks") or []:
+            if not isinstance(hook, dict):
+                continue
+            command = str(hook.get("command") or "")
+            if "pre_tool_use.py" not in command:
+                continue
+            return {
+                "exists": True,
+                "path": str(path),
+                "pretool_managed": True,
+                "pretool_command": command,
+                "pretool_matcher": matcher,
+            }
+    return {
+        "exists": True,
+        "path": str(path),
+        "pretool_managed": False,
+        "pretool_command": "",
+    }
+
+
 def _claude_desktop_shared_brain_status() -> dict:
     path = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
     if not path.is_file():
@@ -1860,9 +1906,11 @@ def check_personal_script_registry(fix: bool = False) -> DoctorCheck:
     """Check the DB-backed personal script registry against filesystem/plists."""
     try:
         from db import init_db, get_personal_script_health_report
-        from script_registry import sync_personal_scripts
+        from script_registry import repair_orphan_personal_schedule_metadata, sync_personal_scripts
 
         init_db()
+        if fix:
+            repair_orphan_personal_schedule_metadata(dry_run=False)
         sync_personal_scripts(prune_missing=True)
         report = get_personal_script_health_report(fix=fix)
     except Exception as e:
@@ -2128,6 +2176,7 @@ def check_client_bootstrap_parity(fix: bool = False) -> DoctorCheck:
             repair_plan.append("Refresh bootstrap files from the current NEXO templates")
         if client_key == "codex":
             codex_config = _codex_bootstrap_config_status()
+            codex_hooks = _codex_hooks_config_status()
             if codex_config.get("error"):
                 status = "degraded"
                 severity = "warn"
@@ -2150,6 +2199,20 @@ def check_client_bootstrap_parity(fix: bool = False) -> DoctorCheck:
                         f" ({codex_config.get('model') or 'default'}, {codex_config.get('reasoning_effort') or 'default'})"
                     )
                 )
+            if codex_hooks.get("error"):
+                status = "degraded"
+                severity = "warn"
+                evidence.append(f"codex hooks JSON invalid at {codex_hooks.get('path')}: {codex_hooks.get('error')}")
+                repair_plan.append("Repair ~/.codex/hooks.json so NEXO can manage Codex PreToolUse enforcement")
+            elif not codex_hooks.get("pretool_managed"):
+                status = "degraded"
+                severity = "warn"
+                evidence.append(f"codex PreToolUse hook missing at {codex_hooks.get('path')}")
+                repair_plan.append("Run `nexo clients sync --client codex` to install the managed PreToolUse guard")
+            else:
+                evidence.append(
+                    f"codex PreToolUse hook managed ({codex_hooks.get('pretool_matcher') or '*'})"
+                )
 
     if fix and status != "healthy":
         try:
@@ -2425,6 +2488,120 @@ def check_codex_conditioned_file_discipline() -> DoctorCheck:
     )
 
 
+def check_codex_protocol_compliance() -> DoctorCheck:
+    try:
+        schedule = _load_json(SCHEDULE_FILE) if SCHEDULE_FILE.is_file() else {}
+    except Exception:
+        schedule = {}
+    prefs = normalize_client_preferences(schedule)
+    wants_codex = bool(
+        prefs.get("interactive_clients", {}).get("codex")
+        or prefs.get("default_terminal_client") == "codex"
+        or (prefs.get("automation_enabled", True) and prefs.get("automation_backend") == "codex")
+    )
+    if not wants_codex:
+        return DoctorCheck(
+            id="installation_live.codex_protocol_compliance",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary="Codex protocol compliance skipped (Codex not selected)",
+        )
+
+    hooks = _codex_hooks_config_status()
+    if hooks.get("error"):
+        return DoctorCheck(
+            id="installation_live.codex_protocol_compliance",
+            tier="runtime",
+            status="critical",
+            severity="error",
+            summary="Codex live protocol enforcement is not readable",
+            evidence=[f"codex hooks JSON invalid at {hooks.get('path')}: {hooks.get('error')}"],
+            repair_plan=["Repair ~/.codex/hooks.json or run `nexo clients sync --client codex`"],
+            escalation_prompt=(
+                "Codex cannot be treated as protocol-compliant while its live PreToolUse hook config is unreadable."
+            ),
+        )
+    if not hooks.get("pretool_managed"):
+        return DoctorCheck(
+            id="installation_live.codex_protocol_compliance",
+            tier="runtime",
+            status="critical",
+            severity="error",
+            summary="Codex live PreToolUse enforcement is not installed",
+            evidence=[f"missing managed PreToolUse hook at {hooks.get('path')}"],
+            repair_plan=["Run `nexo clients sync --client codex` so shell/exec_command calls are checked before execution"],
+            escalation_prompt=(
+                "Codex can still execute shell commands without the live NEXO guard; this is not functional parity."
+            ),
+        )
+
+    startup = _recent_codex_session_parity_status(days=1)
+    conditioned = _recent_codex_conditioned_file_discipline_status(days=1)
+    sessions = int(startup.get("files") or conditioned.get("files") or 0)
+    if sessions <= 0:
+        return DoctorCheck(
+            id="installation_live.codex_protocol_compliance",
+            tier="runtime",
+            status="degraded",
+            severity="warn",
+            summary="No Codex sessions in the last 24h to verify protocol compliance",
+            repair_plan=[
+                "Run Codex through the managed NEXO bootstrap so doctor can verify live protocol compliance",
+            ],
+        )
+
+    startup_violation_sessions = 0
+    for sample in startup.get("samples", []):
+        if not sample.get("bootstrap") or not sample.get("startup") or not sample.get("heartbeat"):
+            startup_violation_sessions += 1
+    conditioned_violations = (
+        int(conditioned.get("read_without_protocol") or 0)
+        + int(conditioned.get("write_without_protocol") or 0)
+        + int(conditioned.get("write_without_guard_ack") or 0)
+        + int(conditioned.get("delete_without_protocol") or 0)
+        + int(conditioned.get("delete_without_guard_ack") or 0)
+    )
+    violation_units = startup_violation_sessions + conditioned_violations
+    violation_rate = round((violation_units / max(1, sessions)) * 100, 1)
+    status = "critical" if violation_rate > 5.0 else "healthy"
+    severity = "error" if status == "critical" else "info"
+    evidence = [
+        f"codex PreToolUse hook: managed ({hooks.get('pretool_matcher') or '*'})",
+        f"codex sessions inspected 24h: {sessions}",
+        f"startup/protocol violating sessions: {startup_violation_sessions}",
+        f"conditioned-file violations: {conditioned_violations}",
+        f"violation rate: {violation_rate}%",
+        "threshold: 5.0%",
+    ]
+    for sample in (startup.get("samples") or [])[:3]:
+        if not sample.get("bootstrap") or not sample.get("startup") or not sample.get("heartbeat"):
+            evidence.append(f"startup drift: {sample.get('file')}")
+    for sample in (conditioned.get("samples") or [])[:3]:
+        evidence.append(f"conditioned drift: {sample.get('kind')} {sample.get('file')}")
+
+    return DoctorCheck(
+        id="installation_live.codex_protocol_compliance",
+        tier="runtime",
+        status=status,
+        severity=severity,
+        summary=(
+            "Codex protocol compliance is within the 5% live threshold"
+            if status == "healthy"
+            else "Codex protocol compliance exceeds the 5% live violation threshold"
+        ),
+        evidence=evidence,
+        repair_plan=[
+            "Start Codex via `nexo chat` so SessionStart bootstrap is injected",
+            "Keep nexo_startup and nexo_heartbeat visible in every Codex session",
+            "Run nexo_guard_check before conditioned-file reads/writes and acknowledge blocking rules before mutation",
+        ] if status != "healthy" else [],
+        escalation_prompt=(
+            "Codex CLI parity is not clean: recent sessions miss startup/heartbeat or bypass conditioned-file guard discipline."
+        ) if status != "healthy" else "",
+    )
+
+
 def check_claude_desktop_shared_brain() -> DoctorCheck:
     try:
         schedule = _load_json(SCHEDULE_FILE) if SCHEDULE_FILE.is_file() else {}
@@ -3415,6 +3592,7 @@ def run_runtime_checks(fix: bool = False) -> list[DoctorCheck]:
         safe_check(check_client_bootstrap_parity, fix=fix),
         safe_check(check_codex_session_parity),
         safe_check(check_codex_conditioned_file_discipline),
+        safe_check(check_codex_protocol_compliance),
         safe_check(check_claude_desktop_shared_brain),
         safe_check(check_transcript_source_parity),
         safe_check(check_client_assumption_regressions),

package/src/hook_guardrails.py

@@ -261,6 +261,14 @@ def _short_tool_name(tool_name: str) -> str:
     return clean.rsplit("__", 1)[-1] if "__" in clean else clean
 
 
+def _canonical_hook_tool_name(tool_name: str) -> str:
+    clean = _short_tool_name(tool_name)
+    lowered = clean.strip().lower()
+    if lowered in {"bash", "shell", "shell_command", "exec_command", "local_shell"}:
+        return "Bash"
+    return clean
+
+
 def _normalize_file_path(path: str) -> str:
     return _normalize_path_token(str(Path(path)))
 
@@ -1177,6 +1185,15 @@ def _collect_runtime_core_write_blocks(
 _LAUNCHAGENT_PLIST_RE = re.compile(
     r"library/launchagents/com\.nexo\.[^/]+\.plist$"
 )
+_LAUNCHAGENT_PLIST_TOKEN_RE = re.compile(
+    r"library/launchagents/com\.nexo\.[^/\s]+\.plist(?:\*|$)"
+)
+_LAUNCHAGENT_SERVICE_RE = re.compile(r"\bcom\.nexo\.[A-Za-z0-9_.-]+\b")
+_LAUNCHAGENT_3_LAYER_FLOW = (
+    "Use the 3-layer schedule removal flow: launchctl unload/bootout the service, "
+    "remove `# nexo: schedule_required=true` and `# nexo: cron_id=...` markers from "
+    "the source script, then verify with `nexo scripts reconcile --dry-run`."
+)
 
 
 def _is_protected_launchagent_path(filepath: str) -> bool:
@@ -1194,6 +1211,112 @@ def _is_protected_launchagent_path(filepath: str) -> bool:
     return _LAUNCHAGENT_PLIST_RE.search(normalized) is not None
 
 
+def _is_protected_launchagent_token(value: str) -> bool:
+    normalized = _normalize_file_path(value)
+    return bool(_LAUNCHAGENT_PLIST_TOKEN_RE.search(normalized))
+
+
+def _launchagent_operation_kind(command: str) -> str:
+    tokens = _shell_tokens(command)
+    if not tokens:
+        return ""
+    base = Path(tokens[0]).name.lower()
+    command_text = str(command or "")
+    if base == "launchctl":
+        if any(token in {"unload", "bootout"} for token in tokens[1:]):
+            if any(_is_protected_launchagent_token(token) for token in tokens[1:]):
+                return "launchctl_plist"
+            if _LAUNCHAGENT_SERVICE_RE.search(command_text):
+                return "launchctl_service"
+    if base in {"rm", "unlink", "mv"}:
+        if any(_is_protected_launchagent_token(token) for token in tokens[1:]):
+            return base
+    return ""
+
+
+def _collect_launchagent_operation_warnings(
+    conn,
+    *,
+    sid: str,
+    tool_name: str,
+    command: str,
+) -> list[dict]:
+    if core_writes_allowed():
+        return []
+    kind = _launchagent_operation_kind(command)
+    if not kind:
+        return []
+    debt = _ensure_protocol_debt(
+        conn,
+        session_id=sid,
+        task_id="",
+        debt_type="launchagent_plist_protected_operation",
+        severity="warn",
+        evidence=(
+            f"{tool_name} requested {kind} on a NEXO-managed LaunchAgent. "
+            f"{_LAUNCHAGENT_3_LAYER_FLOW} Command head: {str(command or '')[:180]}"
+        ),
+        file_token="launchagent_plist_protected",
+    )
+    return [
+        {
+            "file": "com.nexo.*.plist",
+            "task_id": "",
+            "debt_id": debt.get("id"),
+            "debt_type": "launchagent_plist_protected_operation",
+            "reason_code": "launchagent_plist_protected",
+            "severity": "warn",
+            "message": _LAUNCHAGENT_3_LAYER_FLOW,
+            "operation_kind": kind,
+        }
+    ]
+
+
+def _is_scheduled_personal_script(filepath: str) -> bool:
+    normalized = _normalize_file_path(filepath)
+    if "/.nexo/personal/scripts/" not in normalized or not normalized.endswith(".py"):
+        return False
+    try:
+        path = Path(filepath).expanduser()
+        if not path.exists() or not path.is_file():
+            return False
+        head = "".join(path.read_text(errors="ignore").splitlines(keepends=True)[:40])
+    except Exception:
+        return False
+    return "# nexo: schedule_required=true" in head
+
+
+def _collect_scheduled_personal_script_warnings(conn, *, sid: str, tool_name: str, files: list[str]) -> list[dict]:
+    warnings: list[dict] = []
+    for filepath in files:
+        if not _is_scheduled_personal_script(filepath):
+            continue
+        debt = _ensure_protocol_debt(
+            conn,
+            session_id=sid,
+            task_id="",
+            debt_type="scheduled_personal_script_conditioned",
+            severity="warn",
+            evidence=(
+                f"{tool_name} touched scheduled personal script {filepath}. "
+                "Run nexo_guard_check and keep LaunchAgent metadata in sync before editing schedule markers."
+            ),
+            file_token=filepath,
+        )
+        warnings.append(
+            {
+                "file": filepath,
+                "task_id": "",
+                "debt_id": debt.get("id"),
+                "debt_type": "scheduled_personal_script_conditioned",
+                "reason_code": "scheduled_personal_script_conditioned",
+                "severity": "warn",
+                "message": "Scheduled personal script: run nexo_guard_check and keep schedule metadata/plist in sync.",
+            }
+        )
+    return warnings
+
+
 def _collect_launchagent_write_blocks(
     conn,
     *,
@@ -1277,7 +1400,7 @@ def _read_claude_session_id_from_coordination() -> str:
 
 
 def process_pre_tool_event(payload: dict) -> dict:
-    tool_name = str(payload.get("tool_name", "")).strip()
+    tool_name = _canonical_hook_tool_name(str(payload.get("tool_name", "")).strip())
     tool_input = payload.get("tool_input")
     op = _operation_kind(tool_name)
     shell_files: list[str] = []
@@ -1321,6 +1444,10 @@ def process_pre_tool_event(payload: dict) -> dict:
             _shell_cmd_ssh = _extract_bash_command(tool_input)
             if _classify_ssh_remote_write(_shell_cmd_ssh):
                 op = "write"  # force the main gate to keep evaluating
+    if tool_name == "Bash" and op not in {"write", "delete"}:
+        _shell_cmd_launchagent = _extract_bash_command(tool_input)
+        if _launchagent_operation_kind(_shell_cmd_launchagent):
+            op = "delete"
     if op not in {"write", "delete"}:
         return {"ok": True, "skipped": True, "reason": "operation not blocked", "strictness": get_protocol_strictness()}
 
@@ -1353,6 +1480,32 @@ def process_pre_tool_event(payload: dict) -> dict:
         claude_sid = _read_claude_session_id_from_coordination()
     sid = _resolve_nexo_sid(conn, claude_sid)
     open_task = _find_any_open_task(conn, sid) if sid else None
+    warnings: list[dict] = []
+    if tool_name == "Bash":
+        launchagent_operation_warnings = _collect_launchagent_operation_warnings(
+            conn,
+            sid=sid,
+            tool_name=tool_name,
+            command=_extract_bash_command(tool_input),
+        )
+        if launchagent_operation_warnings:
+            return {
+                "ok": True,
+                "session_id": sid,
+                "tool_name": tool_name,
+                "operation": op,
+                "strictness": strictness,
+                "warnings": launchagent_operation_warnings,
+                "status": "warn",
+            }
+    warnings.extend(
+        _collect_scheduled_personal_script_warnings(
+            conn,
+            sid=sid,
+            tool_name=tool_name,
+            files=files,
+        )
+    )
     automation_blocks = _collect_automation_live_repo_blocks(
         conn,
         sid=sid,
@@ -1367,6 +1520,7 @@ def process_pre_tool_event(payload: dict) -> dict:
             "operation": op,
             "strictness": strictness,
             "blocks": automation_blocks,
+            "warnings": warnings,
             "status": "blocked",
         }
 
@@ -1384,6 +1538,7 @@ def process_pre_tool_event(payload: dict) -> dict:
             "operation": op,
             "strictness": strictness,
             "blocks": core_blocks,
+            "warnings": warnings,
             "status": "blocked",
         }
 
@@ -1401,6 +1556,7 @@ def process_pre_tool_event(payload: dict) -> dict:
             "operation": op,
             "strictness": strictness,
             "blocks": launchagent_blocks,
+            "warnings": warnings,
             "status": "blocked",
         }
 
@@ -1602,7 +1758,7 @@ def process_pre_tool_event(payload: dict) -> dict:
             _shadow_cache[sid] = g4_warnings
 
     if strictness == "lenient":
-        return {"ok": True, "skipped": True, "reason": "lenient mode", "strictness": strictness}
+        return {"ok": True, "skipped": True, "reason": "lenient mode", "strictness": strictness, "warnings": warnings, "status": "warn" if warnings else "clean"}
 
     blocks: list[dict] = []
 
@@ -1632,6 +1788,7 @@ def process_pre_tool_event(payload: dict) -> dict:
             "operation": op,
             "strictness": strictness,
             "blocks": blocks,
+            "warnings": warnings,
             "status": "blocked",
         }
 
@@ -1683,7 +1840,8 @@ def process_pre_tool_event(payload: dict) -> dict:
             "strictness": strictness,
             "blocks": blocks,
             "auto_opened_task": auto_opened_task,
-            "status": "blocked" if blocks else "clean",
+            "warnings": warnings,
+            "status": "blocked" if blocks else ("warn" if warnings else "clean"),
         }
 
     for filepath in files:
@@ -1767,7 +1925,8 @@ def process_pre_tool_event(payload: dict) -> dict:
         "strictness": strictness,
         "blocks": blocks,
         "auto_opened_task": auto_opened_task,
-        "status": "blocked" if blocks else "clean",
+        "warnings": warnings,
+        "status": "blocked" if blocks else ("warn" if warnings else "clean"),
     }
 
 
@@ -1918,11 +2077,14 @@ def format_hook_message(result: dict) -> str:
 
 def format_pretool_block_message(result: dict) -> str:
     blocks = result.get("blocks") or []
-    if not blocks:
+    warnings = result.get("warnings") or []
+    if not blocks and not warnings:
         return ""
     strictness = str(result.get("strictness") or "strict")
     if any(item.get("reason_code") == "automation_live_repo" for item in blocks):
         header = "NEXO AUTOMATION SAFETY BLOCKED THIS EDIT:"
+    elif warnings and not blocks:
+        header = "NEXO SAFETY WARNING:"
     else:
         header = (
             "NEXO LEARNING MODE BLOCKED THIS EDIT:"
@@ -1930,6 +2092,11 @@ def format_pretool_block_message(result: dict) -> str:
             else "NEXO STRICT MODE BLOCKED THIS EDIT:"
         )
     lines = [header]
+    for item in warnings:
+        message = item.get("message") or "Review this operation before continuing."
+        debt_id = item.get("debt_id")
+        suffix = f" (debt_id={debt_id})" if debt_id else ""
+        lines.append(f"- WARN {item.get('reason_code') or item.get('debt_type')}: {message}{suffix}")
     for item in blocks:
         file_note = item["file"] or "(unknown target)"
         if item.get("reason_code") == "missing_startup":

package/src/plugins/protocol.py

@@ -25,6 +25,7 @@ from db import (
     get_db,
     get_followups,
     get_protocol_task,
+    list_session_correction_requirements,
     set_protocol_task_guard_acknowledged,
     list_workflow_goals,
     list_workflow_runs,
@@ -1370,6 +1371,38 @@ def handle_task_close(
         high_stakes=bool(task.get("response_high_stakes")),
     )
 
+    pending_corrections = list_session_correction_requirements(
+        session_id=task["session_id"],
+        status="open",
+        limit=3,
+    )
+    if pending_corrections:
+        debt = _ensure_open_debt(
+            task["session_id"],
+            task_id,
+            "missing_learning_after_correction",
+            severity="error",
+            evidence=(
+                "User correction was detected for this session and has not "
+                "been resolved by nexo_learning_add. task_close is blocked "
+                "until a durable learning is persisted."
+            ),
+            debts=debts_created,
+        )
+        return json.dumps(
+            {
+                "ok": False,
+                "error": "Cannot close task while a detected user correction has no durable nexo_learning_add.",
+                "hint": "Call nexo_learning_add with the reusable rule learned from the correction, then retry nexo_task_close.",
+                "task_id": task_id,
+                "blocked_by": "d5_correction_learning_required",
+                "debt_id": debt.get("id"),
+                "pending_corrections": len(pending_corrections),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+
     # ── Evidence enforcement: reject 'done' without proof ──
     # G1 hardening: "done" is no longer allowed to degrade into a debt-only
     # close when verify evidence is missing. Keep the task open, open/dedupe

package/src/scripts/nexo-daily-self-audit.py

@@ -1807,6 +1807,59 @@ def check_codex_conditioned_file_discipline():
     finding(severity, "codex-discipline", message)
 
 
+def check_correction_learning_requirements():
+    if not NEXO_DB.exists():
+        return
+    conn = sqlite3.connect(str(NEXO_DB))
+    conn.row_factory = sqlite3.Row
+    try:
+        if not _table_exists(conn, "session_correction_requirements"):
+            return
+        rows = conn.execute(
+            """SELECT id, session_id, correction_text, detected_at, followup_id
+               FROM session_correction_requirements
+               WHERE status = 'open'
+               ORDER BY detected_at ASC
+               LIMIT 25"""
+        ).fetchall()
+        if not rows:
+            return
+        refreshed = 0
+        for row in rows:
+            snippet = " ".join(str(row["correction_text"] or "").split())[:240]
+            description = (
+                "Persist learning for detected user correction "
+                f"in session {row['session_id']}: {snippet or '(no snippet)'}"
+            )
+            followup_id = _ensure_followup(
+                conn,
+                prefix="D5-CORRECTION",
+                description=description,
+                verification="Run nexo_learning_add, then confirm session_correction_requirements.status='resolved'.",
+                reasoning=(
+                    "Deep Sleep/self-audit found a correction detection with no durable learning_add. "
+                    "D.5 requires a reusable learning before session closure."
+                ),
+                priority="high",
+            )
+            if followup_id:
+                conn.execute(
+                    """UPDATE session_correction_requirements
+                       SET followup_id = ?
+                       WHERE id = ? AND COALESCE(followup_id, '') = ''""",
+                    (followup_id, int(row["id"])),
+                )
+                refreshed += 1
+        conn.commit()
+        finding(
+            "ERROR",
+            "correction-learning",
+            f"{len(rows)} correction(s) detected without learning_add; opened/refreshed {refreshed} followup(s)",
+        )
+    finally:
+        conn.close()
+
+
 def check_codex_startup_discipline():
     try:
         from doctor.providers.runtime import _recent_codex_session_parity_status
@@ -2155,6 +2208,7 @@ def main():
     check_automation_opportunities()
     check_state_watchers()
     check_memory_quality_scores()
+    check_correction_learning_requirements()
     check_codex_startup_discipline()
     check_codex_conditioned_file_discipline()
     check_watchdog_registry()

package/src/tools_learnings.py

@@ -4,7 +4,8 @@ import re
 from datetime import datetime
 
 from db import (create_learning, update_learning, delete_learning, search_learnings,
-                list_learnings, find_similar_learnings, get_db, now_epoch, supersede_learning, extract_keywords)
+                list_learnings, find_similar_learnings, get_db, now_epoch, supersede_learning, extract_keywords,
+                resolve_session_correction_requirements)
 
 NEGATION_PATTERNS = (
     "do not", "don't", "never", "avoid", "skip", "without", "forbid", "forbidden",
@@ -137,6 +138,14 @@ def find_conflicting_active_learning(*, category: str, title: str, content: str,
     )
 
 
+def _resolve_pending_correction_learning(learning_id: int) -> int:
+    """Best-effort D.5 bridge: a real learning_add resolves one open correction window."""
+    try:
+        return resolve_session_correction_requirements(learning_id=int(learning_id))
+    except Exception:
+        return 0
+
+
 def _priority_score(priority: str) -> float:
     return {
         "critical": 1.0,
@@ -286,6 +295,7 @@ def handle_learning_add(category: str, title: str, content: str, reasoning: str
         (title.strip(), category)
     ).fetchone()
     if existing:
+        _resolve_pending_correction_learning(int(existing["id"]))
         return f"Learning #{existing['id']} already exists with same title in {category}: {existing['title']}. Use nexo_learning_update to modify it."
 
     # ── R05 (Fase 2 Protocol Enforcer): auto-merge on high Jaccard similarity ──
@@ -322,6 +332,7 @@ def handle_learning_add(category: str, title: str, content: str, reasoning: str
                     (new_weight, now_epoch(), existing_id),
                 )
                 conn.commit()
+                _resolve_pending_correction_learning(int(existing_id))
                 return (
                     f"Learning #{existing_id} matched new content at Jaccard {similarity:.2f} "
                     f">= R05 merge threshold ({R05_MERGE_THRESHOLD:.2f}). No duplicate created. "
@@ -465,6 +476,7 @@ def handle_learning_add(category: str, title: str, content: str, reasoning: str
             pass  # Best-effort surfacing only
 
     meta = []
+    resolved_corrections = _resolve_pending_correction_learning(int(result["id"]))
     if prevention:
         meta.append("with prevention")
     if applies_to:
@@ -472,7 +484,11 @@ def handle_learning_add(category: str, title: str, content: str, reasoning: str
     if supersedes_id:
         meta.append(f"supersedes={int(supersedes_id)}")
     meta_str = f" ({', '.join(meta)})" if meta else ""
-    return f"Learning #{result['id']} added in {category}: {title}{meta_str} ✓verified{repetition_msg}{retro_meta_msg}"
+    correction_msg = (
+        f"\nD.5: resolved {resolved_corrections} pending correction learning requirement(s)."
+        if resolved_corrections else ""
+    )
+    return f"Learning #{result['id']} added in {category}: {title}{meta_str} ✓verified{repetition_msg}{retro_meta_msg}{correction_msg}"
 
 
 def handle_learning_search(query: str, category: str = '') -> str:

package/src/tools_sessions.py

@@ -829,9 +829,40 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
 
     if context_hint and _hint_suggests_correction(context_hint):
         try:
+            from db import (
+                create_protocol_debt,
+                list_protocol_debts,
+                record_session_correction_requirement,
+            )
+
+            record_session_correction_requirement(
+                sid,
+                context_hint,
+                source="heartbeat",
+            )
             if not _recent_learning_capture_exists(conn, sid, window_seconds=300):
+                existing_debt = list_protocol_debts(
+                    status="open",
+                    session_id=sid,
+                    debt_type="missing_learning_after_correction",
+                    limit=1,
+                )
+                if not existing_debt:
+                    create_protocol_debt(
+                        sid,
+                        "missing_learning_after_correction",
+                        severity="error",
+                        evidence=(
+                            "Detected user correction in heartbeat context. "
+                            "A durable nexo_learning_add is required before "
+                            "nexo_task_close or nexo_stop may close this session."
+                        ),
+                    )
                 parts.append("")
                 parts.append(render_core_prompt("heartbeat-learning-reminder"))
+                parts.append(
+                    "LEARNING REQUIRED: call nexo_learning_add for this correction before nexo_task_close or nexo_stop."
+                )
         except Exception:
             pass  # Best-effort reminder only
 
@@ -1288,6 +1319,18 @@ def _toolbox_summary(conn) -> str:
 
 def handle_stop(sid: str) -> str:
     """Cleanly close a session, removing it from active sessions immediately."""
+    try:
+        from db import list_session_correction_requirements
+
+        pending = list_session_correction_requirements(session_id=sid, status="open", limit=3)
+        if pending:
+            return (
+                "ERROR: session has user correction(s) without durable learning_add. "
+                "Call nexo_learning_add for the correction before nexo_stop. "
+                f"pending={len(pending)}"
+            )
+    except Exception:
+        pass
     _stop_keepalive(sid)
     complete_session(sid)
     return f"Session {sid} closed."