nexo-brain 7.1.7 → 7.1.8

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.1.7",
+  "version": "7.1.8",
   "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.1.7` is the current packaged-runtime line. It hardens operator-facing email automation language: `email-monitor` now carries the calibrated operator language through its prompt contract and localizes direct `needs_interactive` escalation emails, so Spanish operators stop receiving fallback English monitor mail. No coordinated Desktop release was needed for this patch; the fix lives in Brain.
+Version `7.1.8` is the current packaged-runtime line. It batches the Block K Guardian/Enforcer roadmap (auto-drain of stale `protocol_debt` rows, destructive-command pre-tool gate, `guard_check`-required gate, inline guard ack on `nexo_task_open`, Guardian Health in the morning briefing) with Block D hardcode cleanup (classifier-backed `backfill_task_owner`, migration v50 supersedes the duplicate NEXO-product learning pair, new semantic-hardcodes audit) and Block E product guards (LaunchAgent plist protection, agent-name fallbacks no longer leak the product identity, `francisco_emails` removed from the email-config dict export, `runner-health-check.py` + `nexo_personal_automation.py` promoted from personal to core). All new gates ship in shadow mode with env-flag rollout to `hard`. No coordinated Desktop release is required for this patch; Desktop consumers continue against the same CLI / MCP contract.
 
 Previously in `7.0.1`: hotfix over v7.0.0 (db._core.DB_PATH was only caller still hardcoded to legacy ~/.nexo/data/nexo.db; every shared-DB command silently returned empty results post-migration). Previously in `7.0.0`: **BREAKING — Plan Consolidado fase F0.6**: physical separation of the runtime tree into `~/.nexo/{core,personal,runtime}/`. The flat layout (`~/.nexo/scripts/`, `brain/`, `data/`, `operations/`, ...) is gone. Operators on v6.x are auto-migrated on first `nexo update`; fresh installs land directly in the new tree. New `paths.py` helpers are transition-aware.
 

package/package.json

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

package/src/auto_update.py

@@ -3007,10 +3007,11 @@ def _check_npm_version() -> str | None:
             return None
         if latest != current and not current.endswith(latest):
             try:
-                from user_context import get_context
-                _name = get_context().assistant_name
+                from user_context import get_context, DEFAULT_ASSISTANT_NAME
+                _name = get_context().assistant_name or DEFAULT_ASSISTANT_NAME
             except Exception:
-                _name = "NEXO"
+                from user_context import DEFAULT_ASSISTANT_NAME
+                _name = DEFAULT_ASSISTANT_NAME
             return f"{_name} update available: {current} -> {latest}. Run: npm update -g {pkg_name}"
     except Exception:
         pass
@@ -3385,12 +3386,17 @@ def _find_user_claude_md() -> Path | None:
 
 def _resolve_placeholders(template_text: str) -> str:
     """Fill {{NAME}} and {{NEXO_HOME}} from the user's existing CLAUDE.md or config."""
-    # Read operator name from calibration/version
+    # Read operator name from calibration/version. The fallback must never be a
+    # reserved product identity ("NEXO", "NEXO Brain", "NEXO Desktop"); those
+    # are rejected by desktop_bridge.RESERVED_ASSISTANT_NAME_VALUES and leaking
+    # them into the managed CLAUDE.md would conflate the agent (Nova/Nero/etc.)
+    # with the product itself.
     try:
-        from user_context import get_context
-        name = get_context().assistant_name
+        from user_context import get_context, DEFAULT_ASSISTANT_NAME
+        name = get_context().assistant_name or DEFAULT_ASSISTANT_NAME
     except Exception:
-        name = "NEXO"
+        from user_context import DEFAULT_ASSISTANT_NAME
+        name = DEFAULT_ASSISTANT_NAME
 
     return (
         template_text

package/src/classifier_local.py

@@ -11,7 +11,12 @@ Contract:
         "lo hemos dejado, ya estaría",
         labels=("done_claim", "status_update", "question", "noise"),
     )
-    result == {"label": "done_claim", "confidence": 0.87, "scores": {...}}
+    # result is a ``ClassificationResult`` dataclass (see below):
+    #   result.label       == "done_claim"
+    #   result.confidence  == 0.87
+    #   result.scores      == {"done_claim": 0.87, ...}
+    # The dataclass keeps attribute access + ``asdict()`` compatibility
+    # for callers that previously consumed it as a dict.
 
 When transformers is not installed or the download fails (offline),
 `classify` returns `None` and `classify_fail_closed` returns a

package/src/cli.py

@@ -1755,6 +1755,21 @@ def _terminal_client_label(client: str) -> str:
 
 
 def _ordered_available_terminal_clients(preferences: dict, detected: dict) -> list[str]:
+    """Return the terminal clients we should offer the operator, in priority order.
+
+    Policy:
+      1. Clients that are BOTH detected installed AND enabled in preferences
+         keep their priority (``last_used`` → ``default`` → TERMINAL_CLIENT_ORDER).
+      2. If that primary list ends up with ≤1 choice, we also surface every
+         other DETECTED-INSTALLED client even when it is not yet marked
+         ``enabled`` in preferences. Rationale (bug Francisco 2026-04-22):
+         operators with both Claude Code and Codex installed were being
+         dropped straight into whichever one was last used (or the only one
+         ever enabled) with no chance to pick. ``nexo chat`` must offer the
+         picker whenever more than one interactive client is available on
+         the machine; the preferences flag stays as a *priority* signal, not
+         as a hard filter that hides a legitimately installed CLI.
+    """
     enabled = preferences.get("interactive_clients", {})
     last_used = str(preferences.get("last_terminal_client", "")).strip()
     preferred = str(preferences.get("default_terminal_client", "")).strip()
@@ -1764,11 +1779,22 @@ def _ordered_available_terminal_clients(preferences: dict, detected: dict) -> li
         if client in TERMINAL_CLIENT_ORDER and client not in ordered:
             ordered.append(client)
 
-    return [
+    primary = [
         client
         for client in ordered
         if enabled.get(client, False) and detected.get(client, {}).get("installed", False)
     ]
+    if len(primary) <= 1:
+        # Surface additional installed clients so the operator gets to pick
+        # whenever there is a genuine competing install on disk. We preserve
+        # the priority order built above so the picker still highlights the
+        # last-used/default client first.
+        for client in ordered:
+            if client in primary:
+                continue
+            if detected.get(client, {}).get("installed", False):
+                primary.append(client)
+    return primary
 
 
 def _preferred_terminal_client_label(preferences: dict, clients: list[str]) -> str:

package/src/db/_email_accounts.py

@@ -78,6 +78,22 @@ def add_email_account(
         raise ValueError("label and email are required")
     if role not in VALID_ROLES:
         raise ValueError(f"role must be one of {VALID_ROLES}, got {role!r}")
+    # AUDITOR-3RDPASS §Risk 3: the SELECT (``get_email_account``) and the
+    # follow-up INSERT ... ON CONFLICT DO UPDATE below used to run as two
+    # independent statements on the shared connection. A concurrent writer
+    # (Desktop + cron overlap) could slip a metadata mutation between them
+    # and get silently overwritten by whatever ``existing.get("metadata")``
+    # we captured here. Wrap the read-modify-write in ``BEGIN IMMEDIATE``
+    # so the row is pinned against concurrent writers for the duration of
+    # the upsert. WAL mode still lets readers through, so no lock storm.
+    conn = _get_db()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        _owns_txn = True
+    except Exception:
+        # Already inside a transaction (e.g. caller wrapped the whole flow);
+        # trust the caller's boundary instead of nesting an IMMEDIATE.
+        _owns_txn = False
     existing = get_email_account(label) or {}
     clean_account_type = str(account_type or existing.get("account_type") or "agent").strip().lower()
     if clean_account_type not in VALID_ACCOUNT_TYPES:
@@ -166,7 +182,10 @@ def add_email_account(
             now,
         ),
     )
-    conn.commit()
+    # Only commit/close the transaction we opened ourselves. Callers that
+    # already wrapped the flow in their own transaction must keep control.
+    if _owns_txn:
+        conn.commit()
     return get_email_account(label) or {}
 
 

package/src/db/_schema.py

@@ -1222,6 +1222,75 @@ def _m45_personal_scripts_origin(conn):
     _migrate_add_index(conn, "idx_personal_scripts_origin", "personal_scripts", "origin")
 
 
+def _m49_protocol_guard_ack_backfill(conn):
+    """Backfill protocol guard-ack columns for installs that already marked
+    migration v22 as applied before those columns were added to the migration
+    body.
+
+    This must remain a standalone migration instead of reusing v22 because
+    real runtimes can legitimately sit at schema version 48 with an older
+    ``protocol_tasks`` shape. Re-running ``init_db()`` skips v22 once it is
+    recorded in ``schema_migrations``, so the missing columns never land
+    without a new version.
+    """
+    _migrate_add_column(conn, "protocol_tasks", "guard_acknowledged", "INTEGER NOT NULL DEFAULT 0")
+    _migrate_add_column(conn, "protocol_tasks", "guard_acknowledged_at", "TEXT DEFAULT NULL")
+
+
+def _m50_dedupe_nexo_product_learning_pair(conn):
+    """Block D.2 / G7-adjacent: dedupe the two learnings that encode the
+    "NEXO Brain producto público vs instancia personal de Francisco"
+    invariant as a physically separate pair.
+
+    Francisco's runtime has this concept stored twice (historical IDs 212
+    and 224). Guard dedup already collapses them at display time, but
+    the underlying rows stayed split, so list/search/update flows still
+    saw two rows. Physically supersede the older one by pointing its
+    ``supersedes_id`` at the newer duplicate and flipping its status to
+    ``superseded``. Anything newer than both is left untouched.
+
+    Idempotent. Fresh installs that never created either row silently
+    do nothing; installs where an operator has already set the relation
+    manually do nothing. The migration matches on a text-normalised form
+    of the title so synonymous wording on both rows is enough — we don't
+    need identical strings, and we don't need the IDs to literally be
+    212 and 224.
+    """
+    try:
+        rows = conn.execute(
+            "SELECT id, title, content, status, supersedes_id FROM learnings "
+            "WHERE status = 'active'"
+        ).fetchall()
+    except Exception:
+        return
+
+    def _norm(text: str) -> str:
+        # Collapse whitespace and strip punctuation/case so "NEXO Brain
+        # producto público vs instancia personal" matches its twin no
+        # matter how the operator rephrased it.
+        import re as _re
+        stripped = _re.sub(r"[\W_]+", " ", str(text or "")).strip().lower()
+        return _re.sub(r"\s+", " ", stripped)
+
+    marker = "nexo brain producto"
+    candidates = [r for r in rows if marker in _norm(r[1] or "")]
+    # Need at least two rows for this migration to do anything.
+    if len(candidates) < 2:
+        return
+    # Sort by id ascending; the highest id is the canonical survivor.
+    candidates.sort(key=lambda r: int(r[0] or 0))
+    survivor = candidates[-1]
+    for older in candidates[:-1]:
+        older_id = int(older[0] or 0)
+        if int(older[4] or 0) == int(survivor[0] or 0):
+            continue  # already linked
+        conn.execute(
+            "UPDATE learnings SET supersedes_id = ?, status = 'superseded', "
+            "updated_at = strftime('%s','now') WHERE id = ? AND status = 'active'",
+            (int(survivor[0] or 0), older_id),
+        )
+
+
 def _m44_entities_extended_schema(conn):
     """Plan Consolidado 0.3 — extend entities with aliases/metadata/source/confidence/access_mode.
 
@@ -1291,6 +1360,8 @@ MIGRATIONS = [
     (46, "email_accounts", _m46_email_accounts),
     (47, "email_operator_accounts", _m47_email_operator_accounts),
     (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),
 ]
 
 

package/src/email_config.py

@@ -122,9 +122,15 @@ def _account_to_legacy_shape(
         "password": runtime_account["password"],
         "operator_email": default_operator_email,
         "operator_aliases": list(extra_operator_emails or []),
-        # Transitional compatibility for older scripts that still read the
-        # pre-F2 alias key directly.
-        "francisco_emails": list(extra_operator_emails or []),
+        # Historical note: earlier versions exported the same list under the
+        # ``francisco_emails`` key for scripts that still referenced the
+        # operator's email by a personal name. The key leaked the operator
+        # identity into anything consuming the email config dict, so it has
+        # been removed. Callers must read ``operator_aliases`` instead. The
+        # legacy ``francisco_emails`` key inside ~/.nexo/nexo-email/config.json
+        # is still tolerated at ingest time (see _operator_aliases in
+        # automation_controls.py and nexo-email-monitor.py) so upgrades from
+        # old runtimes do not break; it just no longer round-trips here.
         "trusted_domains": runtime_account["trusted_domains"],
         "sender_policy": runtime_account["sender_policy"],
         "sent_folder": runtime_account["sent_folder"],

package/src/hook_guardrails.py

@@ -118,6 +118,44 @@ INLINE_WRITE_RE = re.compile(
 EMBEDDED_PATH_RE = re.compile(r"(~\/[^'\"\s,);]+|\/[^'\"\s,);]+)")
 
 
+# Block K G3: destructive commands whose blast radius warrants a cortex
+# decision before they execute. The list is deliberately tight — only
+# the patterns that historically cause irrecoverable damage. Each regex
+# is tested against the full Bash command string (post shlex split
+# rebuild) so distinct spacings and option orderings do not slip past.
+DESTRUCTIVE_COMMAND_PATTERNS: tuple[tuple[str, "re.Pattern[str]"], ...] = (
+    # Matches both combined ``rm -rf`` and split ``rm -r -f`` forms. The
+    # character class ``[rfRF]*`` after the dash tolerates any flag
+    # ordering while both ``r`` and ``f`` (case-insensitive) must be
+    # present for the match to fire.
+    ("rm_rf", re.compile(r"\brm\s+-[rfRF]*(?:[rR][rfRF]*[fF]|[fF][rfRF]*[rR])[rfRF]*\b", re.IGNORECASE)),
+    ("git_push_force", re.compile(r"\bgit\s+push\s+(?:.*\s)?(?:--force|-f)\b(?!.*-with-lease)", re.IGNORECASE)),
+    ("drop_table", re.compile(r"\bdrop\s+(?:table|database|schema)\b", re.IGNORECASE)),
+    ("truncate_table", re.compile(r"\btruncate\s+(?:table\s+)?\w+", re.IGNORECASE)),
+    ("curl_pipe_bash", re.compile(r"curl[^|]*\|\s*(?:sudo\s+)?(?:bash|sh|zsh)\b", re.IGNORECASE)),
+    ("wget_pipe_bash", re.compile(r"wget[^|]*\|\s*(?:sudo\s+)?(?:bash|sh|zsh)\b", re.IGNORECASE)),
+    # ``dd if=... of=/dev/sda`` — match any ordering of args; we flag the
+    # presence of ``of=/dev/...`` which points at a raw block/device.
+    ("dd_of_root", re.compile(r"\bdd\s+.*?\bof=/dev/\S+", re.IGNORECASE)),
+    ("chmod_777_recursive", re.compile(r"\bchmod\s+-R\s+(?:777|666|a\+rw)\b", re.IGNORECASE)),
+)
+
+
+def _classify_destructive_intent(command: str) -> str | None:
+    """Return the matching pattern name if ``command`` looks destructive.
+
+    None when none of the DESTRUCTIVE_COMMAND_PATTERNS match. Intentionally
+    strict: we would rather miss a novel attack shape and rely on the
+    existing ``strict``/``write_without_file_guard_check`` gates than
+    inject false positives on routine Bash usage.
+    """
+    cmd = str(command or "")
+    for name, pattern in DESTRUCTIVE_COMMAND_PATTERNS:
+        if pattern.search(cmd):
+            return name
+    return None
+
+
 def _operation_kind(tool_name: str) -> str:
     if tool_name in READ_LIKE_TOOLS:
         return "read"
@@ -291,6 +329,10 @@ def _extract_bash_touched_files(tool_input) -> list[str]:
         ".py", ".md", ".json", ".jsonl", ".sh", ".txt", ".toml", ".yaml", ".yml",
         ".js", ".ts", ".tsx", ".jsx", ".php", ".sql", ".rs", ".go", ".c", ".cpp",
         ".h", ".css", ".html",
+        # ``.plist`` is needed so that ``_collect_launchagent_write_blocks``
+        # can see managed LaunchAgent plists inside Bash commands such as
+        # ``chmod 755 ~/Library/LaunchAgents/com.nexo.runner-health-check.plist``.
+        ".plist",
     }
 
     def add(candidate: str) -> None:
@@ -746,6 +788,79 @@ def _collect_runtime_core_write_blocks(
     return blocks
 
 
+# ``_normalize_path_token`` lower-cases the path, so the regex and substring
+# checks here must also be lower-case. We intentionally omit the leading
+# ``/`` so that both ``/Users/.../Library/...`` and ``~/Library/...`` shapes
+# match — ``_normalize_file_path`` does not expand the user home.
+_LAUNCHAGENT_PLIST_RE = re.compile(
+    r"library/launchagents/com\.nexo\.[^/]+\.plist$"
+)
+
+
+def _is_protected_launchagent_path(filepath: str) -> bool:
+    """True when ``filepath`` resolves to a NEXO-managed LaunchAgent plist.
+
+    Matches any absolute or tilde-prefixed path that ends with
+    ``Library/LaunchAgents/com.nexo.<name>.plist``. Other plists in the same
+    directory (e.g. third-party agents) are left untouched.
+    """
+    if not filepath:
+        return False
+    normalized = _normalize_file_path(filepath)
+    if "library/launchagents/com.nexo." not in normalized:
+        return False
+    return _LAUNCHAGENT_PLIST_RE.search(normalized) is not None
+
+
+def _collect_launchagent_write_blocks(
+    conn,
+    *,
+    sid: str,
+    tool_name: str,
+    files: list[str],
+) -> list[dict]:
+    """Block agent-driven writes to NEXO-managed LaunchAgent plists.
+
+    Core flows (``auto_update.py`` re-generating plists, ``nexo_migrate``,
+    product controllers) set ``NEXO_CORE_WRITES_ALLOWED=1`` via
+    ``product_mode.core_writes_allowed()``, which bypasses this gate. Agentic
+    edits (an operator prompting Claude Code to "fix this LaunchAgent"
+    manually) go through the check and are rejected with a pointer to the
+    canonical surfaces: ``nexo scripts ensure-schedules``,
+    ``nexo core-schedules``, or the source repo release flow.
+    """
+    if core_writes_allowed():
+        return []
+    blocks: list[dict] = []
+    for filepath in files:
+        if not _is_protected_launchagent_path(filepath):
+            continue
+        debt = _ensure_protocol_debt(
+            conn,
+            session_id=sid,
+            task_id="",
+            debt_type="launchagent_plist_write_blocked",
+            severity="error",
+            evidence=(
+                f"{tool_name} attempted on managed LaunchAgent plist {filepath}. "
+                "NEXO-managed plists must be regenerated through "
+                "`nexo scripts ensure-schedules`, `nexo core-schedules`, or the "
+                "source repo release flow, not edited in place."
+            ),
+            file_token=filepath,
+        )
+        blocks.append(
+            {
+                "file": filepath,
+                "task_id": "",
+                "debt_id": debt.get("id"),
+                "debt_type": "launchagent_plist_write_blocked",
+                "reason_code": "launchagent_plist_protected",
+            }
+        )
+    return blocks
+
+
 def _read_claude_session_id_from_coordination() -> str:
     """Fallback claude_session_id when Claude Code's PreToolUse payload omits it.
 
@@ -790,6 +905,19 @@ def process_pre_tool_event(payload: dict) -> dict:
         if shell_op in {"write", "delete"}:
             op = shell_op
             shell_files = _extract_bash_touched_files(tool_input)
+    # Block K G3 prescreen: destructive Bash patterns (``git push
+    # --force``, ``drop table``, ``curl | bash``, ``rm -rf``, ``dd
+    # of=/dev/…``, ``chmod -R 777``) must go through the pre-tool gate
+    # even when ``_classify_bash_operation`` labels them ``other``.
+    # Without this prescreen the ``if op not in {'write', 'delete'}``
+    # early-return below would let them slip past — exactly the failure
+    # mode Francisco flagged in G3.
+    if tool_name == "Bash" and op not in {"write", "delete"}:
+        _g3_mode_prescreen = os.environ.get("NEXO_G3_ENFORCE_DESTRUCTIVE", "shadow").strip().lower()
+        if _g3_mode_prescreen in {"shadow", "hard"}:
+            _shell_cmd = _extract_bash_command(tool_input)
+            if _classify_destructive_intent(_shell_cmd):
+                op = "delete"  # force the main gate to keep evaluating
     if op not in {"write", "delete"}:
         return {"ok": True, "skipped": True, "reason": "operation not blocked", "strictness": get_protocol_strictness()}
 
@@ -855,6 +983,136 @@ def process_pre_tool_event(payload: dict) -> dict:
             "status": "blocked",
         }
 
+    launchagent_blocks = _collect_launchagent_write_blocks(
+        conn,
+        sid=sid,
+        tool_name=tool_name,
+        files=files,
+    )
+    if launchagent_blocks:
+        return {
+            "ok": True,
+            "session_id": sid,
+            "tool_name": tool_name,
+            "operation": op,
+            "strictness": strictness,
+            "blocks": launchagent_blocks,
+            "status": "blocked",
+        }
+
+    # Block K G3 (Francisco 2026-04-22): destructive commands require an
+    # explicit cortex decision before they execute. Gated by
+    # NEXO_G3_ENFORCE_DESTRUCTIVE (default "shadow"): shadow records a
+    # warn-severity debt for observability; hard blocks the operation
+    # with error severity; off disables the gate entirely.
+    g3_mode = os.environ.get("NEXO_G3_ENFORCE_DESTRUCTIVE", "shadow").strip().lower()
+    if g3_mode in {"shadow", "hard"} and tool_name == "Bash":
+        shell_command = _extract_bash_command(tool_input)
+        destructive_pattern = _classify_destructive_intent(shell_command)
+        if destructive_pattern:
+            severity = "error" if g3_mode == "hard" else "warn"
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id="",
+                debt_type="g3_destructive_command_requires_cortex",
+                severity=severity,
+                evidence=(
+                    f"Bash command matched destructive pattern '{destructive_pattern}'. "
+                    f"Command head: {shell_command[:120]}. "
+                    "Run nexo_cortex_decide and record evidence before retrying."
+                ),
+                file_token=destructive_pattern,
+            )
+            if g3_mode == "hard":
+                return {
+                    "ok": True,
+                    "session_id": sid,
+                    "tool_name": tool_name,
+                    "operation": op,
+                    "strictness": strictness,
+                    "blocks": [
+                        {
+                            "file": "",
+                            "task_id": "",
+                            "debt_id": debt.get("id"),
+                            "debt_type": "g3_destructive_command_requires_cortex",
+                            "reason_code": "g3_destructive_blocked",
+                            "severity": "error",
+                            "pattern": destructive_pattern,
+                            "g3_mode": g3_mode,
+                        }
+                    ],
+                    "status": "blocked",
+                    "g3_mode": g3_mode,
+                }
+
+    # Block K G4 (Francisco 2026-04-22): require nexo_guard_check to have
+    # run within the session for every file about to be written. Opt-in
+    # via NEXO_G4_ENFORCE_GUARD_CHECK (default "shadow"): ``shadow``
+    # records a protocol_debt entry of severity ``warn`` but does NOT
+    # block the write; ``hard`` blocks the write with severity ``error``
+    # so the operator must run guard_check explicitly. Skipped entirely
+    # in lenient mode or when there are no files, since the existing
+    # strict-mode path already covers those cases with its own gating.
+    g4_mode = os.environ.get("NEXO_G4_ENFORCE_GUARD_CHECK", "shadow").strip().lower()
+    if g4_mode in {"shadow", "hard"} and files and sid:
+        g4_blocks: list[dict] = []
+        g4_warnings: list[dict] = []
+        for filepath in files:
+            if _session_has_guard_for_file(conn, sid, filepath):
+                continue
+            severity = "error" if g4_mode == "hard" else "warn"
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id="",
+                debt_type="g4_guard_check_required",
+                severity=severity,
+                evidence=(
+                    f"{tool_name} attempted on {filepath} without a prior "
+                    "nexo_guard_check covering that file. "
+                    "Run nexo_guard_check(files='{path}') first."
+                ).format(path=filepath),
+                file_token=filepath,
+            )
+            entry = {
+                "file": filepath,
+                "task_id": "",
+                "debt_id": debt.get("id"),
+                "debt_type": "g4_guard_check_required",
+                "reason_code": "g4_guard_check_required",
+                "severity": severity,
+                "g4_mode": g4_mode,
+            }
+            if g4_mode == "hard":
+                g4_blocks.append(entry)
+            else:
+                g4_warnings.append(entry)
+        if g4_blocks:
+            return {
+                "ok": True,
+                "session_id": sid,
+                "tool_name": tool_name,
+                "operation": op,
+                "strictness": strictness,
+                "blocks": g4_blocks,
+                "status": "blocked",
+                "g4_mode": g4_mode,
+            }
+        # Shadow-mode warnings piggyback on the existing return path so
+        # the surface stays observable without hijacking the control flow.
+        if g4_warnings:
+            # Store on the payload so callers that care about shadow
+            # telemetry can pick it up. Do NOT return yet — continue
+            # through the existing strict/lenient gates.
+            # Stash under a well-known key for the post-tool hook.
+            _shadow_cache = getattr(process_pre_tool_event, "_g4_shadow", None)
+            if _shadow_cache is None:
+                _shadow_cache = {}
+                process_pre_tool_event._g4_shadow = _shadow_cache
+            _shadow_cache[sid] = g4_warnings
+
     if strictness == "lenient":
         return {"ok": True, "skipped": True, "reason": "lenient mode", "strictness": strictness}
 

package/src/hooks/session-start.sh

@@ -250,6 +250,64 @@ if os.path.exists(evolution_file):
     except Exception:
         pass
 
+# Guardian health (Block K G8 — Francisco 2026-04-22): surface the
+# metrics the Guardian already tracks so Francisco sees them every
+# morning without asking. Soft query: missing tables or schema drift
+# must not fail the briefing; fall back to silence.
+try:
+    _conn = sqlite3.connect(db_path)
+    _health = {}
+    # protocol_debt open count + breakdown by debt_type (top 5)
+    try:
+        row = _conn.execute(
+            \"SELECT COUNT(*) FROM protocol_debt WHERE resolved_at IS NULL\"
+        ).fetchone()
+        _health['open_debts_total'] = int(row[0] or 0) if row else 0
+        breakdown = _conn.execute(
+            \"SELECT debt_type, COUNT(*) AS n FROM protocol_debt \"
+            \"WHERE resolved_at IS NULL GROUP BY debt_type ORDER BY n DESC LIMIT 5\"
+        ).fetchall()
+        _health['open_debts_by_type'] = [(r[0] or 'unknown', int(r[1] or 0)) for r in breakdown]
+    except Exception:
+        pass
+    # Guard-check activity in the last 24h
+    try:
+        row = _conn.execute(
+            \"SELECT COUNT(*) FROM guard_checks \"
+            \"WHERE ts > (strftime('%s','now') - 24*3600)\"
+        ).fetchone()
+        _health['guard_checks_24h'] = int(row[0] or 0) if row else 0
+    except Exception:
+        pass
+    # Failing hook runs in the last 24h (non-zero exit)
+    try:
+        row = _conn.execute(
+            \"SELECT COUNT(*) FROM hook_runs \"
+            \"WHERE exit_code != 0 AND started_at > datetime('now', '-1 day')\"
+        ).fetchone()
+        _health['failing_hooks_24h'] = int(row[0] or 0) if row else 0
+    except Exception:
+        pass
+    _conn.close()
+    if _health:
+        lines.append('## Guardian Health')
+        debts_total = _health.get('open_debts_total', 0)
+        lines.append(f\"Open debts: {debts_total}\")
+        if debts_total > 10:
+            lines.append('  -> ACTION NEEDED: >10 open debts — run nexo_protocol_debt_list and resolve error-severity entries.')
+        for debt_type, count in _health.get('open_debts_by_type', []):
+            lines.append(f\"  - {debt_type}: {count}\")
+        if 'guard_checks_24h' in _health:
+            lines.append(f\"guard_checks last 24h: {_health['guard_checks_24h']}\")
+        if 'failing_hooks_24h' in _health:
+            fh = _health['failing_hooks_24h']
+            lines.append(f\"failing hooks last 24h: {fh}\")
+            if fh > 0:
+                lines.append('  -> check nexo_hook_runs for details.')
+        lines.append('')
+except Exception:
+    pass
+
 print('\n'.join(lines))
 " > "$BRIEFING_FILE" 2>/dev/null