nexo-brain 7.1.8 → 7.2.0

package/src/doctor/providers/boot.py

@@ -220,6 +220,193 @@ def check_config_parse() -> DoctorCheck:
     )
 
 
+def check_core_dev_packaged_install() -> DoctorCheck:
+    """Warn when ``~/.nexo/core-dev/`` exists on a packaged (non-dev) install.
+
+    Contract (see ``docs/f06-layout-contract.md`` §3): ``core-dev/`` is a
+    developer opt-in and MUST be absent on production installs. Its presence
+    on a packaged install is almost always a leftover from a dev environment
+    that was later repackaged, and silently keeps parallel code paths
+    discoverable through ``_classify_script_dir``. Doctor surfaces it so the
+    operator can confirm and remove.
+    """
+    import paths
+    core_dev = paths.core_dev_dir()
+    if not core_dev.exists():
+        return DoctorCheck(
+            id="boot.core_dev_absent_on_packaged",
+            tier="boot",
+            status="healthy",
+            severity="info",
+            summary="core-dev/ absent (expected on packaged installs)",
+        )
+    is_packaged = paths.core_dir().is_dir() and not (NEXO_HOME / "src").is_dir()
+    if not is_packaged:
+        return DoctorCheck(
+            id="boot.core_dev_absent_on_packaged",
+            tier="boot",
+            status="healthy",
+            severity="info",
+            summary="core-dev/ present on a dev install (contract allows this)",
+        )
+    try:
+        payload = [p.name for p in core_dev.iterdir()][:5]
+    except OSError:
+        payload = []
+    return DoctorCheck(
+        id="boot.core_dev_absent_on_packaged",
+        tier="boot",
+        status="degraded",
+        severity="warn",
+        summary="core-dev/ present on a packaged install — contract forbids this",
+        evidence=[f"Location: {core_dev}"] + [f"Entry: {n}" for n in payload],
+        repair_plan=[
+            f"Confirm with operator, then: rm -rf {core_dev}",
+        ],
+    )
+
+
+def check_dashboard_desktop_contract() -> DoctorCheck:
+    """Flag Dashboard LaunchAgent contradicting Desktop product surface.
+
+    Contract (see ``docs/f06-layout-contract.md`` §4):
+      - Terminal-only install → ``com.nexo.dashboard`` loaded.
+      - Desktop-managed install → ``com.nexo.dashboard`` unloaded.
+    Both signals disagreeing with the chosen product mode is a warn.
+    """
+    if sys.platform != "darwin":
+        return DoctorCheck(
+            id="boot.dashboard_desktop_contract",
+            tier="boot",
+            status="healthy",
+            severity="info",
+            summary="Non-darwin host — dashboard LaunchAgent contract does not apply",
+        )
+    agent_path = Path.home() / "Library" / "LaunchAgents" / "com.nexo.dashboard.plist"
+    agent_installed = agent_path.exists()
+    try:
+        from product_mode import enforce_desktop_product_contract  # type: ignore
+        desktop_contract = bool(enforce_desktop_product_contract())
+    except Exception:
+        desktop_contract = False
+
+    if desktop_contract and agent_installed:
+        return DoctorCheck(
+            id="boot.dashboard_desktop_contract",
+            tier="boot",
+            status="degraded",
+            severity="warn",
+            summary="Desktop product surface active but standalone dashboard LaunchAgent is installed",
+            evidence=[f"Plist: {agent_path}"],
+            repair_plan=[
+                f"launchctl unload {agent_path}",
+                f"rm {agent_path}",
+            ],
+        )
+    if not desktop_contract and not agent_installed:
+        return DoctorCheck(
+            id="boot.dashboard_desktop_contract",
+            tier="boot",
+            status="degraded",
+            severity="warn",
+            summary="Terminal-only install without a dashboard LaunchAgent",
+            evidence=["Expected plist missing: com.nexo.dashboard.plist"],
+            repair_plan=["nexo update  # re-materialize com.nexo.dashboard"],
+        )
+    return DoctorCheck(
+        id="boot.dashboard_desktop_contract",
+        tier="boot",
+        status="healthy",
+        severity="info",
+        summary="Dashboard LaunchAgent state matches the product surface contract",
+    )
+
+
+def check_f06_migration_consistency() -> DoctorCheck:
+    """Detect half-migrated F0.6 installs.
+
+    Contract (``docs/f06-layout-contract.md`` §6 rule 5):
+      - F0.6 marker + legacy runtime dirs populated → half-migration.
+      - No marker but canonical ``core/`` already populated → half-migration.
+      - Marker F0.6 with no legacy residue → healthy.
+      - No marker, no canonical ``core/``, pure legacy layout → healthy
+        (pre-F0.6 install waiting for ``nexo update``).
+
+    Half-migration is the scenario where ``paths.coordination_dir()`` (and
+    siblings) silently fall back to the legacy path on an install that
+    *should* be on F0.6. Doctor surfaces it so ``nexo update`` can be
+    asked to finish the job instead of the operator discovering later that
+    half their state lives in the wrong place.
+    """
+    import paths
+    marker = NEXO_HOME / ".structure-version"
+    marker_text = ""
+    if marker.is_file():
+        try:
+            marker_text = marker.read_text().strip().upper().split()[0]
+        except (OSError, IndexError):
+            marker_text = ""
+    is_f06_marked = marker_text.startswith("F0.6")
+
+    core_dir = paths.core_dir()
+    core_populated = core_dir.is_dir() and any(core_dir.iterdir()) if core_dir.exists() else False
+
+    # Legacy runtime dirs that MUST be gone (or be symlinks into canonical F0.6)
+    # once the migration has finished physically.
+    legacy_runtime_names = ("coordination", "data", "logs", "operations")
+    legacy_stragglers: list[str] = []
+    for name in legacy_runtime_names:
+        legacy_path = NEXO_HOME / name
+        if not legacy_path.exists():
+            continue
+        if legacy_path.is_symlink():
+            # A symlink pointing at the canonical runtime/<name> is the
+            # compat shim contract; that is acceptable.
+            continue
+        try:
+            has_content = any(legacy_path.iterdir())
+        except OSError:
+            has_content = False
+        if has_content:
+            legacy_stragglers.append(name)
+
+    if is_f06_marked and legacy_stragglers:
+        return DoctorCheck(
+            id="boot.f06_migration_consistency",
+            tier="boot",
+            status="critical",
+            severity="error",
+            summary="Half-migrated F0.6 install: marker present but legacy runtime dirs still populated",
+            evidence=[f"Marker: {marker_text}"] + [f"Legacy with content: {NEXO_HOME / n}" for n in legacy_stragglers],
+            repair_plan=[
+                "nexo update   # finish the F0.6 migration",
+                "# if update refuses, inspect manifest and consider: nexo rollback f06",
+            ],
+        )
+    if (not is_f06_marked) and core_populated:
+        return DoctorCheck(
+            id="boot.f06_migration_consistency",
+            tier="boot",
+            status="critical",
+            severity="error",
+            summary="Half-migrated F0.6 install: core/ populated but marker absent",
+            evidence=[f"Marker: {marker_text or '(absent)'}", f"core/ path: {core_dir}"],
+            repair_plan=[
+                "nexo update   # re-run migration to write the marker",
+            ],
+        )
+    return DoctorCheck(
+        id="boot.f06_migration_consistency",
+        tier="boot",
+        status="healthy",
+        severity="info",
+        summary=(
+            f"F0.6 marker consistent with layout (marker={marker_text or 'absent'}, "
+            f"legacy_stragglers={len(legacy_stragglers)})"
+        ),
+    )
+
+
 def run_boot_checks(fix: bool = False) -> list[DoctorCheck]:
     """Run all boot-tier checks."""
     checks = [
@@ -229,6 +416,9 @@ def run_boot_checks(fix: bool = False) -> list[DoctorCheck]:
         safe_check(check_wrapper_scripts),
         safe_check(check_python_runtime),
         safe_check(check_config_parse),
+        safe_check(check_core_dev_packaged_install),
+        safe_check(check_dashboard_desktop_contract),
+        safe_check(check_f06_migration_consistency),
     ]
 
     if fix:

package/src/evolution_cycle.py

@@ -19,6 +19,10 @@ from core_prompts import render_core_prompt
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(NEXO_HOME)))
 NEXO_DB = paths.db_path()
+# Evolution sandbox lives under the runtime root (equivalent to
+# ``paths.runtime_dir() / "sandbox"``). Kept as ``NEXO_HOME / sandbox /
+# workspace`` for backwards compatibility with existing installs that already
+# have a populated sandbox at this path. Do NOT relocate without a migration.
 SANDBOX_DIR = NEXO_HOME / "sandbox" / "workspace"
 SNAPSHOTS_DIR = paths.snapshots_dir()
 RESTORE_LOG = paths.logs_dir() / "snapshot-restores.log"

package/src/guardian_runtime_config.py

@@ -0,0 +1,98 @@
+"""Guardian runtime config resolver — single source of truth for enforcer flags.
+
+v7.2.0 introduces ``~/.nexo/personal/config/guardian-runtime-overrides.json``
+as the persistent operator-owned default for Guardian gate modes:
+
+    {
+      "G1_ENFORCER_ACTIVE": "hard",
+      "G3_ENFORCE_DESTRUCTIVE": "hard",
+      "G3_SSH_ENFORCE_REMOTE_WRITE": "hard",
+      "G4_ENFORCE_GUARD_CHECK": "hard"
+    }
+
+The JSON values match the ``NEXO_<FLAG>`` env-var semantics exactly
+(``off`` / ``shadow`` / ``hard``). Env vars always win over the file so
+an ad-hoc ``NEXO_G4_ENFORCE_GUARD_CHECK=shadow`` during debugging still
+takes effect. The file is loaded lazily and cached per-process; callers
+should not rely on edits to take effect without a restart.
+
+Public API:
+    ``resolve_guardian_flag(name, default='shadow')`` -> normalized value.
+
+``name`` is the short key (``G1_ENFORCER_ACTIVE``) without the ``NEXO_``
+prefix. Resolution order:
+    1. Environment variable ``NEXO_<name>`` if set and non-empty.
+    2. Override file entry.
+    3. ``default``.
+
+All returned values are lowercased and whitespace-stripped.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+_CACHE: dict[str, str] | None = None
+
+
+def _overrides_path() -> Path:
+    home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    return home / "personal" / "config" / "guardian-runtime-overrides.json"
+
+
+def _load_overrides() -> dict[str, str]:
+    global _CACHE
+    if _CACHE is not None:
+        return _CACHE
+    path = _overrides_path()
+    if not path.is_file():
+        _CACHE = {}
+        return _CACHE
+    try:
+        raw = json.loads(path.read_text())
+    except Exception:
+        _CACHE = {}
+        return _CACHE
+    if not isinstance(raw, dict):
+        _CACHE = {}
+        return _CACHE
+    normalized: dict[str, str] = {}
+    for key, value in raw.items():
+        if not isinstance(value, str):
+            continue
+        normalized[str(key).strip().upper()] = value.strip().lower()
+    _CACHE = normalized
+    return _CACHE
+
+
+def invalidate_cache() -> None:
+    """Drop the cached override file so the next call re-reads from disk.
+
+    Intended for tests and for the updater right after it writes a new
+    version of the file. Production code should not need to call this.
+    """
+    global _CACHE
+    _CACHE = None
+
+
+def resolve_guardian_flag(name: str, default: str = "shadow") -> str:
+    """Resolve a Guardian gate mode (``off`` / ``shadow`` / ``hard``).
+
+    Env var ``NEXO_<name>`` has priority; falls back to the overrides
+    file; falls back to ``default`` last.
+    """
+    clean = str(name or "").strip().upper()
+    if not clean:
+        return str(default or "shadow").strip().lower()
+
+    env_value = os.environ.get(f"NEXO_{clean}", "").strip()
+    if env_value:
+        return env_value.lower()
+
+    file_value = _load_overrides().get(clean, "")
+    if file_value:
+        return file_value
+
+    return str(default or "shadow").strip().lower()

package/src/hook_guardrails.py

@@ -156,6 +156,82 @@ def _classify_destructive_intent(command: str) -> str | None:
     return None
 
 
+# Block K G3 (SSH wrapper): remote-write patterns the local destructive
+# gate never sees because they run inside ``ssh host '...'`` / rsync /
+# scp / sftp. Matched against the raw Bash command string.
+# Each regex aims to catch a well-known write primitive *inside* a remote
+# invocation. ``ssh host 'ls'`` must not match — only write-verbs do.
+_SSH_REMOTE_SHELL_RE = re.compile(
+    r"\bssh\b[^'\"`]*?(?:['\"`])(?P<remote>[^'\"`]+)(?:['\"`])",
+    re.IGNORECASE,
+)
+_SSH_REMOTE_WRITE_VERBS = (
+    re.compile(r"^\s*cat\s*>\s*\S", re.IGNORECASE),                  # cat > file
+    re.compile(r"^\s*cat\s*>>\s*\S", re.IGNORECASE),                 # cat >> file
+    re.compile(r"\btee\s+(?:-\S+\s+)*[^\s|&;]+", re.IGNORECASE),      # tee [-a] file
+    re.compile(r"^\s*(?:echo|printf)\s+.*\s+>>?\s*\S", re.IGNORECASE),  # echo ... > file
+    re.compile(r"\bsed\s+-i\b", re.IGNORECASE),                      # sed -i ...
+    re.compile(r"(?:^|\s)>\s*\S", re.IGNORECASE),                    # bare > file
+    re.compile(r"(?:^|\s)>>\s*\S", re.IGNORECASE),                   # bare >> file
+    re.compile(r"\brm\s+-\S*[rRfF]", re.IGNORECASE),                 # remote rm -rf
+    re.compile(r"\bmv\s+\S+\s+\S+", re.IGNORECASE),                  # remote mv
+    re.compile(r"\bcp\s+\S+\s+\S+", re.IGNORECASE),                  # remote cp
+)
+_SCP_WRITE_RE = re.compile(
+    r"\bscp\b[^|&;]*?\s\S+\s+[^:\s]+:[^\s]+",
+    re.IGNORECASE,
+)
+_RSYNC_WRITE_RE = re.compile(
+    r"\brsync\b[^|&;]*?\s\S+\s+[^:\s]+:[^\s]+",
+    re.IGNORECASE,
+)
+_SFTP_BATCH_RE = re.compile(
+    r"\bsftp\b(?:[^|&;]*\s)?-b\s+\S+",
+    re.IGNORECASE,
+)
+
+
+def _classify_ssh_remote_write(command: str) -> str | None:
+    """Return the matching pattern name when ``command`` writes to a remote host.
+
+    Covers four shapes:
+        1. ``ssh host '<remote-shell-that-writes>'`` with or without
+           ``-o`` flags, using single/double/backtick quoting.
+        2. ``scp LOCAL_PATH host:REMOTE_PATH`` (upload direction).
+        3. ``rsync [opts] LOCAL_PATH host:REMOTE_PATH`` (upload direction).
+        4. ``sftp -b batchfile host`` (any -b invocation is considered a
+           write candidate because the batch may mutate).
+
+    Ignores read-only invocations such as ``ssh host 'ls /etc'`` or
+    ``scp host:REMOTE /local/`` (download), which is the common case.
+    """
+    cmd = str(command or "")
+
+    if _SCP_WRITE_RE.search(cmd):
+        # Disambiguate download (host:remote local) vs upload (local host:remote).
+        # Simple rule: if the FIRST ``host:path`` argument is preceded by a
+        # local-looking arg, treat as upload.
+        download = re.search(r"\bscp\b[^|&;]*?\s[^:\s]+:\S+\s+\S+", cmd)
+        if not download:
+            return "scp_remote_write"
+    if _RSYNC_WRITE_RE.search(cmd):
+        download = re.search(r"\brsync\b[^|&;]*?\s[^:\s]+:\S+\s+\S+", cmd)
+        if not download:
+            return "rsync_remote_write"
+    if _SFTP_BATCH_RE.search(cmd):
+        return "sftp_batch_remote_write"
+
+    for match in _SSH_REMOTE_SHELL_RE.finditer(cmd):
+        remote = match.group("remote") or ""
+        # Strip leading "sudo ", "env VAR=x ", "cd dir &&" — they never mean
+        # a write by themselves, and may hide real writes behind them.
+        trimmed = re.sub(r"^\s*(?:sudo\s+|env\s+\S+=\S+\s+|cd\s+\S+\s*&&\s*)+", "", remote)
+        for pattern in _SSH_REMOTE_WRITE_VERBS:
+            if pattern.search(trimmed):
+                return "ssh_remote_shell_write"
+    return None
+
+
 def _operation_kind(tool_name: str) -> str:
     if tool_name in READ_LIKE_TOOLS:
         return "read"
@@ -701,12 +777,18 @@ def _collect_protocol_warnings(conn, *, sid: str, tool_name: str) -> list[dict]:
             if task.get("must_change_log")
             else ""
         )
+        closeout_note = (
+            " If this edit wave came from a user correction or you are leaving a blocker unresolved, "
+            "include `correction_happened=true` with a reusable learning, or `followup_needed=true`, "
+            "when you call `nexo_task_close(...)`."
+        )
         _append_protocol_warning(
             warnings,
             render_core_prompt(
                 "hook-protocol-warning-task-close-evidence",
                 task_id=task_id,
                 change_note=change_note,
+                closeout_note=closeout_note,
             ),
         )
 
@@ -1005,7 +1087,11 @@ def process_pre_tool_event(payload: dict) -> dict:
     # 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()
+    try:
+        from guardian_runtime_config import resolve_guardian_flag
+        g3_mode = resolve_guardian_flag("G3_ENFORCE_DESTRUCTIVE", default="shadow")
+    except Exception:
+        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)
@@ -1047,6 +1133,62 @@ def process_pre_tool_event(payload: dict) -> dict:
                     "g3_mode": g3_mode,
                 }
 
+    # Block K G3 SSH wrapper (Francisco 2026-04-22 v7.2.0): remote-write
+    # commands routed through ssh/rsync/scp/sftp never reach the local
+    # destructive gate. Gated by NEXO_G3_SSH_ENFORCE_REMOTE_WRITE (default
+    # "shadow") mirroring the destructive-local flag shape. Shadow logs a
+    # warn debt row; hard blocks with error severity; off disables.
+    try:
+        from guardian_runtime_config import resolve_guardian_flag
+        g3_ssh_mode = resolve_guardian_flag(
+            "G3_SSH_ENFORCE_REMOTE_WRITE", default="shadow"
+        )
+    except Exception:
+        g3_ssh_mode = os.environ.get(
+            "NEXO_G3_SSH_ENFORCE_REMOTE_WRITE", "shadow"
+        ).strip().lower()
+    if g3_ssh_mode in {"shadow", "hard"} and tool_name == "Bash":
+        shell_command = _extract_bash_command(tool_input)
+        ssh_pattern = _classify_ssh_remote_write(shell_command)
+        if ssh_pattern:
+            severity = "error" if g3_ssh_mode == "hard" else "warn"
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id="",
+                debt_type="g3_ssh_remote_write_requires_cortex",
+                severity=severity,
+                evidence=(
+                    f"Bash command matched SSH remote-write pattern '{ssh_pattern}'. "
+                    f"Command head: {shell_command[:160]}. "
+                    "Run nexo_cortex_decide (or nexo_task_open for the session) "
+                    "and record evidence before retrying."
+                ),
+                file_token=ssh_pattern,
+            )
+            if g3_ssh_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_ssh_remote_write_requires_cortex",
+                            "reason_code": "g3_ssh_remote_write_blocked",
+                            "severity": "error",
+                            "pattern": ssh_pattern,
+                            "g3_ssh_mode": g3_ssh_mode,
+                        }
+                    ],
+                    "status": "blocked",
+                    "g3_ssh_mode": g3_ssh_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``
@@ -1055,7 +1197,11 @@ def process_pre_tool_event(payload: dict) -> dict:
     # 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()
+    try:
+        from guardian_runtime_config import resolve_guardian_flag
+        g4_mode = resolve_guardian_flag("G4_ENFORCE_GUARD_CHECK", default="shadow")
+    except Exception:
+        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] = []