nexo-brain 5.3.10 → 5.3.12

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.10",
+  "version": "5.3.12",
   "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 `5.3.10` is the current packaged-runtime line: packaged installs and updates now refresh `~/.nexo/package.json` from the published npm package so runtime metadata stops drifting after successful updates, `nexo doctor --tier deep` no longer flags a healthy runtime as degraded just because the first daily `self-audit-summary.json` has not been produced yet, weekly Evolution once again emits explicit dimension telemetry instead of leaving `nexo_evolution_status` blank, and daily synthesis only pulls startup/update summaries into the briefing when they are operationally actionable.
+Version `5.3.11` is the current packaged-runtime line: protocol and Cortex now reject malformed `outcome`, `task_type`, and `impact_level` values explicitly instead of silently coercing them into other valid states, so task history, debt, hot context, and decision telemetry stay trustworthy even when a caller passes a bad contract payload.
 
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)
@@ -89,7 +89,7 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
-Version `5.3.10` tightens the packaged-runtime truth layer again: installs and updates now keep `~/.nexo/package.json` aligned with the published npm package so runtime metadata and doctor evidence no longer drift to an old version, `nexo doctor --tier deep` treats a missing `self-audit-summary.json` as a pending bootstrap artifact when the runtime was just installed or updated instead of reporting a false degradation, weekly Evolution now asks for explicit `dimension_scores` / `score_evidence` so telemetry can persist instead of staying blank, and daily synthesis only ingests `update-last-summary.json` when it carries actionable runtime signals. Version `5.3.9` is the packaged core-artifact manifest heal for `5.3.8`: packaged updates now rebuild `runtime-core-artifacts.json` from the canonical npm package `src/` tree instead of scanning the live `~/.nexo/scripts` directory, script classification prefers that canonical packaged source when available, and runtime doctor syncs personal scripts before LaunchAgent inventory so personal automations recover cleanly instead of being mistaken for unknown core drift. Version `5.3.8` was the immediate packaged-migration hotfix for `5.3.7`: the installer/runtime migrator now discovers all top-level runtime Python modules from `src/` dynamically instead of relying on a manual allowlist, so new product surfaces like `nexo export` / `nexo import` actually arrive in `~/.nexo` after update instead of being present only in the published npm tarball. Version `5.3.7` closed the remaining packaged-runtime happy-path gap and finally exposed portable user-data migration commands: packaged `nexo update` now self-heals cron definitions and LaunchAgents after a successful npm bump, new `nexo export` / `nexo import` commands move operator data as a safe bundle instead of leaving that flow implicit, and runtime doctor now distinguishes tracked historical Codex drift from an actually broken runtime so cleaned installs stop staying red for stale transcript debt alone. Version `5.3.6` hardened the Claude Code bootstrap path and related runtime hygiene: managed client sync now writes the NEXO MCP server where current Claude Code actually reads it (`~/.claude.json`), script classification is stricter about core-vs-personal runtime artifacts, schedule status distinguishes genuinely running jobs from broken ones, and retroactive learnings stop opening keyword-only false positives outside their declared `applies_to` scope. Version `5.3.5` already keeps CLI version visibility honest right after `nexo update`: if the cached npm version lags behind the runtime you just installed, `nexo` / `nexo chat` now clamp `Latest` to the installed version and refresh the cache instead of showing a stale older release. Version `5.3.4` already cleaned up legacy core alias leakage and added the version-status banner. Version `5.3.3` closed the remaining packaged-runtime doctor mismatch: the built-in hourly backup helper is now inventoried as a core LaunchAgent, so clean installs no longer get a false unknown-LaunchAgent warning. Version `5.3.2` already hardened the runtime boundary by persisting which runtime scripts/hooks are core product artifacts, keeping `nexo scripts` from mixing those into the personal bucket, and migrating the legacy Claude Code heartbeat wrappers into managed core hooks.
+Version `5.3.11` hardens protocol and Cortex contracts: malformed `outcome`, `task_type`, and `impact_level` values now fail explicitly instead of being coerced into other valid states, so persisted task history, debt, hot context, and decision telemetry stay faithful to what the caller actually asked for. Version `5.3.10` tightened the packaged-runtime truth layer again: installs and updates now keep `~/.nexo/package.json` aligned with the published npm package so runtime metadata and doctor evidence no longer drift to an old version, `nexo doctor --tier deep` treats a missing `self-audit-summary.json` as a pending bootstrap artifact when the runtime was just installed or updated instead of reporting a false degradation, weekly Evolution now asks for explicit `dimension_scores` / `score_evidence` so telemetry can persist instead of staying blank, and daily synthesis only ingests `update-last-summary.json` when it carries actionable runtime signals. Version `5.3.9` is the packaged core-artifact manifest heal for `5.3.8`: packaged updates now rebuild `runtime-core-artifacts.json` from the canonical npm package `src/` tree instead of scanning the live `~/.nexo/scripts` directory, script classification prefers that canonical packaged source when available, and runtime doctor syncs personal scripts before LaunchAgent inventory so personal automations recover cleanly instead of being mistaken for unknown core drift. Version `5.3.8` was the immediate packaged-migration hotfix for `5.3.7`: the installer/runtime migrator now discovers all top-level runtime Python modules from `src/` dynamically instead of relying on a manual allowlist, so new product surfaces like `nexo export` / `nexo import` actually arrive in `~/.nexo` after update instead of being present only in the published npm tarball. Version `5.3.7` closed the remaining packaged-runtime happy-path gap and finally exposed portable user-data migration commands: packaged `nexo update` now self-heals cron definitions and LaunchAgents after a successful npm bump, new `nexo export` / `nexo import` commands move operator data as a safe bundle instead of leaving that flow implicit, and runtime doctor now distinguishes tracked historical Codex drift from an actually broken runtime so cleaned installs stop staying red for stale transcript debt alone. Version `5.3.6` hardened the Claude Code bootstrap path and related runtime hygiene: managed client sync now writes the NEXO MCP server where current Claude Code actually reads it (`~/.claude.json`), script classification is stricter about core-vs-personal runtime artifacts, schedule status distinguishes genuinely running jobs from broken ones, and retroactive learnings stop opening keyword-only false positives outside their declared `applies_to` scope. Version `5.3.5` already keeps CLI version visibility honest right after `nexo update`: if the cached npm version lags behind the runtime you just installed, `nexo` / `nexo chat` now clamp `Latest` to the installed version and refresh the cache instead of showing a stale older release. Version `5.3.4` already cleaned up legacy core alias leakage and added the version-status banner. Version `5.3.3` closed the remaining packaged-runtime doctor mismatch: the built-in hourly backup helper is now inventoried as a core LaunchAgent, so clean installs no longer get a false unknown-LaunchAgent warning. Version `5.3.2` already hardened the runtime boundary by persisting which runtime scripts/hooks are core product artifacts, keeping `nexo scripts` from mixing those into the personal bucket, and migrating the legacy Claude Code heartbeat wrappers into managed core hooks.
 
 Version `5.3.1` normalizes packaged npm installs so they behave like packaged npm installs: `nexo update` now keeps the runtime anchored to `~/.nexo`, refreshes packaged bootstrap/client artifacts after upgrade, avoids repo-only release-artifact drift in installed runtimes, and keeps personal scripts on the canonical packaged path.
 
@@ -821,9 +821,7 @@ If you want the shell or Python wrappers instead of raw MCP tools:
 - [docs/reference-verticals.md](docs/reference-verticals.md)
 - [compare/README.md](compare/README.md)
 
-Recommended defaults:
-- Claude Code: `Opus 4.6 with 1M context`
-- Codex: `gpt-5.4` with `xhigh` reasoning
+The model you pick during install is used everywhere — interactive sessions, automation scripts, and all task profiles.  Change it once in your preferences and every part of the system follows.  Default: `Opus 4.6 with 1M context`.
 
 Or use the shell alias created during install (e.g. `atlas`), which now runs `nexo chat .` so it opens the terminal client you pick for that session, with the last-used option shown first.
 
@@ -904,7 +902,7 @@ The Doctor system reads existing health artifacts (immune, watchdog, self-audit)
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
 - **Node.js 18+** (for the installer)
 - **Claude Code is the primary recommended client.** It remains the most mature NEXO path: native hooks, the most battle-tested automation contract, and the clearest parity with historical production behavior.
-- **Recommended profiles:** Claude Code + `Opus 4.6 with 1M context`; Codex + `gpt-5.4` with `xhigh` reasoning if you prefer Codex as your terminal or automation backend.
+- **Model:** You pick your model during install and every component uses it.  Default is `Opus 4.6 with 1M context`.  Scripts and automation profiles read from a single preference — no hardcoded model strings.
 - Python 3, Homebrew, and the selected required client/backend can be installed automatically when NEXO has a supported installer path for that dependency.
 
 ## Architecture
@@ -1021,7 +1019,7 @@ When Claude Desktop is installed, `nexo-brain`, `nexo update`, and `nexo clients
 
 ### Codex
 
-When Codex CLI is available, `nexo-brain`, `nexo update`, and `nexo clients sync` register the same `nexo` MCP server via `codex mcp add`, so Codex uses the same local memory store as Claude Code and Claude Desktop. If selected during install, `nexo chat` can open Codex directly and background automation can also run through Codex. Interactive `nexo chat` launches use Codex's aggressive no-confirmation mode so the session does not stall on repetitive approval prompts. The current recommended Codex profile is `gpt-5.4` with `xhigh` reasoning. Runtime Doctor also audits recent Codex sessions for NEXO startup markers and conditioned-file protocol discipline so parity drift does not hide behind the lack of native Claude-style hooks.
+When Codex CLI is available, `nexo-brain`, `nexo update`, and `nexo clients sync` register the same `nexo` MCP server via `codex mcp add`, so Codex uses the same local memory store as Claude Code and Claude Desktop. If selected during install, `nexo chat` can open Codex directly and background automation can also run through Codex. Interactive `nexo chat` launches use Codex's aggressive no-confirmation mode so the session does not stall on repetitive approval prompts. Codex uses the same model you configured during install — no separate model override is needed. Runtime Doctor also audits recent Codex sessions for NEXO startup markers and conditioned-file protocol discipline so parity drift does not hide behind the lack of native Claude-style hooks.
 
 ### Cursor
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.10",
+  "version": "5.3.12",
   "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/agent_runner.py

@@ -509,6 +509,8 @@ def _build_codex_prompt(
         "If that tool is unavailable, call `nexo_guard_check(...)` and `nexo_cortex_check(...)` first.\n"
         "- For long multi-step or cross-session work, call `nexo_workflow_open(...)` and keep it updated with "
         "`nexo_workflow_update(...)` so resume/replay use durable state instead of guesswork.\n"
+        "- Before diagnosing NEXO, explicitly fix the plane first: `product_public`, `runtime_personal`, `installation_live`, `database_real`, or `cooperator`. "
+        "Do not mix planes inside the same diagnosis.\n"
         "- If a target file has conditioned learnings or blocking guard rules, review them before any read/edit/delete step, and acknowledge guard before any edit/delete step.\n"
         "- Do not claim done without explicit verification evidence. Close with `nexo_task_close(...)`; if unavailable, capture the change log and state the evidence explicitly.\n"
         "- When a correction changes the canonical rule, capture or supersede the learning instead of leaving contradictory active rules behind."

package/src/auto_update.py

@@ -36,6 +36,7 @@ TEMPLATE_FILE = REPO_DIR / "templates" / "CLAUDE.md.template"
 
 CHECK_COOLDOWN_SECONDS = 3600  # 1 hour
 GIT_TIMEOUT_SECONDS = 4  # stay well under the 5s total budget
+CRITICAL_BACKUP_TABLES = ("learnings", "session_diary", "guard_checks", "protocol_debt")
 
 
 def _log(msg: str):
@@ -43,6 +44,108 @@ def _log(msg: str):
     print(f"[NEXO auto-update] {msg}", file=sys.stderr)
 
 
+def _critical_table_count(db_path: Path, table: str) -> int | None:
+    """Return COUNT(*) for a critical table when it exists, otherwise None."""
+    import sqlite3
+
+    conn = None
+    try:
+        conn = sqlite3.connect(str(db_path))
+        exists = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name = ?",
+            (table,),
+        ).fetchone()
+        if not exists:
+            return None
+        row = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()
+        return int(row[0]) if row else 0
+    except Exception:
+        return None
+    finally:
+        if conn is not None:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+
+def _find_primary_db_path() -> Path | None:
+    """Return the main nexo.db path if present."""
+    for candidate in (DATA_DIR / "nexo.db", NEXO_HOME / "nexo.db", SRC_DIR / "nexo.db"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _validate_db_backup(source_db: Path, backup_db: Path) -> dict:
+    """Check that a backup preserves non-empty critical tables from the source DB."""
+    report = {
+        "ok": True,
+        "source_db": str(source_db),
+        "backup_db": str(backup_db),
+        "source_counts": {},
+        "backup_counts": {},
+        "regressions": [],
+        "errors": [],
+    }
+    if not source_db.is_file():
+        report["ok"] = False
+        report["errors"].append(f"source db missing: {source_db}")
+        return report
+    if not backup_db.is_file():
+        report["ok"] = False
+        report["errors"].append(f"backup db missing: {backup_db}")
+        return report
+
+    for table in CRITICAL_BACKUP_TABLES:
+        source_count = _critical_table_count(source_db, table)
+        backup_count = _critical_table_count(backup_db, table)
+        report["source_counts"][table] = source_count
+        report["backup_counts"][table] = backup_count
+
+        if source_count is None:
+            continue
+        if backup_count is None:
+            report["regressions"].append({
+                "table": table,
+                "source": source_count,
+                "backup": None,
+                "reason": "missing_in_backup",
+            })
+            continue
+        if source_count > 0 and backup_count == 0:
+            report["regressions"].append({
+                "table": table,
+                "source": source_count,
+                "backup": backup_count,
+                "reason": "critical_rows_lost",
+            })
+
+    if report["regressions"] or report["errors"]:
+        report["ok"] = False
+    return report
+
+
+def _create_validated_db_backup() -> tuple[str | None, dict | None]:
+    """Create a DB backup and validate that critical tables still contain data."""
+    backup_dir = _backup_dbs()
+    if not backup_dir:
+        return None, None
+
+    source_db = _find_primary_db_path()
+    if source_db is None:
+        return backup_dir, None
+
+    report = _validate_db_backup(source_db, Path(backup_dir) / source_db.name)
+    if not report["ok"]:
+        details = ", ".join(
+            f"{item['table']} {item['source']}->{item['backup']}"
+            for item in report["regressions"]
+        ) or "; ".join(report["errors"])
+        _log(f"DB backup validation failed: {details}")
+    return backup_dir, report
+
+
 def _read_last_check() -> dict:
     """Read last check state from disk."""
     try:
@@ -677,6 +780,11 @@ def _check_git_updates() -> str | None:
     if rc != 0:
         return None
 
+    db_backup_dir, backup_report = _create_validated_db_backup()
+    if backup_report is not None and not backup_report["ok"]:
+        _log("Skipping auto-update because the validated pre-update DB backup is not trustworthy.")
+        return None
+
     rc, pull_out, pull_err = _git("pull", "--ff-only")
     if rc != 0:
         _log(f"git pull --ff-only failed: {pull_err}")
@@ -685,9 +793,6 @@ def _check_git_updates() -> str | None:
     new_version = _read_package_version()
     new_req_hash = _requirements_hash()
 
-    # Backup databases before any changes that might run migrations
-    db_backup_dir = _backup_dbs()
-
     # Reinstall pip deps if requirements.txt content changed (not just version)
     if old_req_hash != new_req_hash:
         if not _reinstall_pip_deps():
@@ -2057,7 +2162,14 @@ def manual_sync_update(*, interactive: bool = False, allow_source_pull: bool = T
             pulled = True
 
     _emit_progress(progress_fn, "Creating runtime backups...")
-    db_backup_dir = _backup_dbs()
+    db_backup_dir, backup_report = _create_validated_db_backup()
+    if backup_report is not None and not backup_report["ok"]:
+        return {
+            "ok": False,
+            "mode": "sync",
+            "error": "DB backup validation failed before runtime sync.",
+            "backup_dir": db_backup_dir,
+        }
     tree_backup_dir = _backup_runtime_tree(NEXO_HOME)
     sync_result = {"ok": False, "mode": "sync", "pulled_source": pulled, "backup_dir": db_backup_dir, "tree_backup": tree_backup_dir}
     try:

package/src/cli.py

@@ -26,7 +26,7 @@ Entry points:
   nexo skills evolution [--json]
   nexo clients sync [--json]
   nexo contributor status|on|off [--json]
-  nexo doctor [--tier boot|runtime|deep|all] [--json] [--fix]
+  nexo doctor [--tier boot|runtime|deep|all] [--plane runtime_personal|installation_live|database_real] [--json] [--fix]
   nexo uninstall [--dry-run] [--delete-data] [--json]
 """
 from __future__ import annotations
@@ -1210,7 +1210,7 @@ def _doctor(args):
     init_db()
     tier_label = getattr(args, "tier", "boot") or "boot"
     print(f"[NEXO] Inspecting {tier_label} diagnostics... please wait.", file=sys.stderr, flush=True)
-    report = run_doctor(tier=args.tier, fix=args.fix)
+    report = run_doctor(tier=args.tier, fix=args.fix, plane=getattr(args, "plane", ""))
     output = format_report(report, fmt="json" if args.json else "text")
     print(output)
 
@@ -1749,6 +1749,12 @@ def main():
     doctor_parser = sub.add_parser("doctor", help="Unified diagnostics")
     doctor_parser.add_argument("--tier", default="boot", choices=["boot", "runtime", "deep", "all"],
                                help="Diagnostic tier (default: boot)")
+    doctor_parser.add_argument(
+        "--plane",
+        default="",
+        choices=["", "runtime_personal", "installation_live", "database_real", "product_public", "cooperator"],
+        help="Diagnostic plane. Doctor only runs on runtime_personal, installation_live, or database_real.",
+    )
     doctor_parser.add_argument("--json", action="store_true", help="JSON output")
     doctor_parser.add_argument("--fix", action="store_true", help="Apply deterministic fixes")
 

package/src/client_preferences.py

@@ -48,10 +48,13 @@ INSTALL_PREFERENCE_KEYS = {
 }
 DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
 DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
-DEFAULT_CODEX_MODEL = "gpt-5.4"
-DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
-DEFAULT_FAST_MODEL = "gpt-5.4-mini"
-DEFAULT_FAST_REASONING_EFFORT = "medium"
+# Codex/fast defaults: fall back to the user's configured model, not a hardcoded
+# third-party model.  The user picks their model once at install time; every
+# profile and backend should honour that choice.
+DEFAULT_CODEX_MODEL = DEFAULT_CLAUDE_CODE_MODEL
+DEFAULT_CODEX_REASONING_EFFORT = ""
+DEFAULT_FAST_MODEL = DEFAULT_CLAUDE_CODE_MODEL
+DEFAULT_FAST_REASONING_EFFORT = ""
 
 
 def _user_home() -> Path:
@@ -260,9 +263,9 @@ def default_automation_task_profiles() -> dict[str, dict[str, str]]:
             "reasoning_effort": "",
         },
         "fast": {
-            "backend": CLIENT_CODEX,
-            "model": DEFAULT_FAST_MODEL,
-            "reasoning_effort": DEFAULT_FAST_REASONING_EFFORT,
+            "backend": "",
+            "model": "",
+            "reasoning_effort": "",
         },
         "balanced": {
             "backend": "",
@@ -523,6 +526,22 @@ def resolve_terminal_client(requested: str | None = None, *, preferences: dict |
     )
 
 
+def resolve_user_model(preferences: dict | None = None) -> str:
+    """Return the single model the user has configured.
+
+    Scripts and automation tasks should call this instead of hardcoding a model
+    string.  The value comes from the user's ``client_runtime_profiles`` for
+    their ``default_terminal_client`` (usually ``claude_code``).
+    """
+    normalized = preferences or load_client_preferences()
+    client = normalize_default_terminal_client(
+        normalized["default_terminal_client"],
+        interactive_clients=normalized["interactive_clients"],
+    )
+    profile = resolve_client_runtime_profile(client, preferences=normalized)
+    return profile["model"]
+
+
 def resolve_automation_backend(preferences: dict | None = None) -> str:
     normalized = preferences or load_client_preferences()
     return normalize_automation_backend(

package/src/client_sync.py

@@ -61,9 +61,10 @@ except Exception:
         }
 
     def resolve_client_runtime_profile(client: str, preferences: dict | None = None) -> dict:
+        _default_model = "claude-opus-4-6[1m]"
         defaults = {
-            "claude_code": {"model": "claude-opus-4-6[1m]", "reasoning_effort": ""},
-            "codex": {"model": "gpt-5.4", "reasoning_effort": "xhigh"},
+            "claude_code": {"model": _default_model, "reasoning_effort": ""},
+            "codex": {"model": _default_model, "reasoning_effort": ""},
         }
         return dict(defaults.get(client, {}))
 

package/src/db/__init__.py

@@ -147,13 +147,16 @@ from db._cron_runs import (
 
 # Protocol discipline runtime
 from db._protocol import (
+    VALID_IMPACT_LEVELS,
+    VALID_TASK_TYPES,
+    VALID_CLOSE_OUTCOMES,
     create_protocol_task, get_protocol_task, close_protocol_task,
     create_protocol_debt, resolve_protocol_debts, list_protocol_debts,
     protocol_compliance_summary,
     create_cortex_evaluation, get_cortex_evaluation, list_cortex_evaluations,
     cortex_evaluation_summary,
     latest_cortex_evaluation_for_task, task_has_cortex_evaluation,
-    override_cortex_evaluation,
+    override_cortex_evaluation, validate_close_outcome, validate_impact_level, validate_task_type,
 )
 
 # Durable workflow runtime

package/src/db/_protocol.py

@@ -9,6 +9,7 @@ from db._core import get_db
 
 VALID_TASK_TYPES = {"answer", "analyze", "edit", "execute", "delegate"}
 VALID_OUTCOMES = {"open", "done", "partial", "blocked", "failed", "cancelled"}
+VALID_CLOSE_OUTCOMES = VALID_OUTCOMES - {"open"}
 VALID_DEBT_STATUS = {"open", "forgiven", "resolved"}
 VALID_IMPACT_LEVELS = {"medium", "high", "critical"}
 
@@ -33,6 +34,30 @@ def _row_to_dict(row):
     return dict(row) if row else None
 
 
+def validate_task_type(task_type: str) -> str:
+    clean_type = (task_type or "").strip()
+    if clean_type not in VALID_TASK_TYPES:
+        expected = ", ".join(sorted(VALID_TASK_TYPES))
+        raise ValueError(f"Invalid task_type '{clean_type or '<empty>'}'. Expected one of: {expected}.")
+    return clean_type
+
+
+def validate_impact_level(impact_level: str) -> str:
+    clean_level = (impact_level or "").strip()
+    if clean_level not in VALID_IMPACT_LEVELS:
+        expected = ", ".join(sorted(VALID_IMPACT_LEVELS))
+        raise ValueError(f"Invalid impact_level '{clean_level or '<empty>'}'. Expected one of: {expected}.")
+    return clean_level
+
+
+def validate_close_outcome(outcome: str) -> str:
+    clean_outcome = (outcome or "").strip()
+    if clean_outcome not in VALID_CLOSE_OUTCOMES:
+        expected = ", ".join(sorted(VALID_CLOSE_OUTCOMES))
+        raise ValueError(f"Invalid close outcome '{clean_outcome or '<empty>'}'. Expected one of: {expected}.")
+    return clean_outcome
+
+
 def create_protocol_task(
     session_id: str,
     goal: str,
@@ -68,7 +93,7 @@ def create_protocol_task(
 ) -> dict:
     conn = get_db()
     task_id = _task_id()
-    clean_type = task_type if task_type in VALID_TASK_TYPES else "answer"
+    clean_type = validate_task_type(task_type)
     conn.execute(
         """INSERT INTO protocol_tasks (
                task_id, session_id, goal, task_type, area, project_hint, context_hint,
@@ -144,7 +169,7 @@ def create_cortex_evaluation(
     selection_source: str = "recommended",
 ) -> dict:
     conn = get_db()
-    clean_level = impact_level if impact_level in VALID_IMPACT_LEVELS else "high"
+    clean_level = validate_impact_level(impact_level)
     cursor = conn.execute(
         """INSERT INTO cortex_evaluations (
                session_id, task_id, goal, task_type, area, impact_level, context_hint,
@@ -335,7 +360,7 @@ def close_protocol_task(
     outcome_notes: str = "",
 ) -> dict:
     conn = get_db()
-    clean_outcome = outcome if outcome in VALID_OUTCOMES else "failed"
+    clean_outcome = validate_close_outcome(outcome)
     conn.execute(
         """UPDATE protocol_tasks
            SET status = ?,

package/src/doctor/orchestrator.py

@@ -6,6 +6,7 @@ import time
 import traceback
 
 from doctor.models import DoctorCheck, DoctorReport
+from doctor.planes import diagnostic_plane_preflight
 from doctor.providers.boot import run_boot_checks
 from doctor.providers.runtime import run_runtime_checks
 from doctor.providers.deep import run_deep_checks
@@ -22,12 +23,13 @@ _TIER_ORDER = ["boot", "runtime", "deep"]
 VALID_TIERS = frozenset(_TIER_ORDER) | {"all"}
 
 
-def run_doctor(tier: str = "boot", fix: bool = False) -> DoctorReport:
+def run_doctor(tier: str = "boot", fix: bool = False, plane: str = "") -> DoctorReport:
     """Run diagnostic checks for the specified tier(s).
 
     Args:
         tier: "boot", "runtime", "deep", or "all"
         fix: If True, apply deterministic fixes where possible
+        plane: Explicit diagnostic plane — runtime_personal, installation_live, or database_real
     """
     report = DoctorReport(overall_status="healthy")
     start = time.monotonic()
@@ -44,6 +46,13 @@ def run_doctor(tier: str = "boot", fix: bool = False) -> DoctorReport:
         report.duration_ms = int((time.monotonic() - start) * 1000)
         return report
 
+    _, preflight = diagnostic_plane_preflight(plane)
+    if preflight is not None:
+        report.add(preflight)
+        report.compute_status()
+        report.duration_ms = int((time.monotonic() - start) * 1000)
+        return report
+
     tiers = _TIER_ORDER if tier == "all" else [tier]
 
     for t in tiers:

package/src/doctor/planes.py

@@ -0,0 +1,87 @@
+"""Diagnostic plane preflight for NEXO Doctor."""
+
+from __future__ import annotations
+
+from doctor.models import DoctorCheck
+
+VALID_DIAGNOSTIC_PLANES = {
+    "product_public": {
+        "label": "producto público",
+        "use": "release contracts, artefactos publicados, compare/, docs y surfaces públicas del repo",
+    },
+    "runtime_personal": {
+        "label": "runtime personal",
+        "use": "~/.nexo, scripts personales, followups, reminders y hábitos operativos del operador",
+    },
+    "installation_live": {
+        "label": "instalación viva",
+        "use": "runtime instalado, hooks activos, clientes conectados, cron sync y parity de la instalación local",
+    },
+    "database_real": {
+        "label": "BD real",
+        "use": "SQLite/MySQL reales, filas, schema, deudas, sesiones y evidencia persistida",
+    },
+    "cooperator": {
+        "label": "co-operador",
+        "use": "comportamiento del agente, protocolo, comunicación y decisiones del asistente",
+    },
+}
+
+DOCTOR_COMPATIBLE_PLANES = {"runtime_personal", "installation_live", "database_real"}
+
+
+def normalize_diagnostic_plane(plane: str = "") -> str:
+    clean = (plane or "").strip().lower().replace("-", "_").replace(" ", "_")
+    return clean if clean in VALID_DIAGNOSTIC_PLANES else ""
+
+
+def diagnostic_plane_choices() -> list[str]:
+    return sorted(VALID_DIAGNOSTIC_PLANES)
+
+
+def diagnostic_plane_preflight(plane: str = "") -> tuple[str, DoctorCheck | None]:
+    clean_plane = normalize_diagnostic_plane(plane)
+    if not clean_plane:
+        options = ", ".join(diagnostic_plane_choices())
+        return "", DoctorCheck(
+            id="orchestrator.diagnostic_plane_required",
+            tier="orchestrator",
+            status="critical",
+            severity="error",
+            summary="El diagnóstico está bloqueado hasta fijar explícitamente el plano",
+            evidence=[
+                f"planes válidos: {options}",
+                "Usa `runtime_personal` para ~/.nexo y hábitos del runtime; `installation_live` para hooks/clientes/instalación; `database_real` para filas y schema reales.",
+            ],
+            repair_plan=[
+                "Repite `nexo_doctor` o `nexo doctor` con `plane='runtime_personal'`, `plane='installation_live'` o `plane='database_real'`.",
+                "Si el problema pertenece a producto público o al co-operador, usa el surface correcto en vez de NEXO Doctor.",
+            ],
+            escalation_prompt=(
+                "NEXO mezcló planos en diagnósticos anteriores. El doctor no debe correr hasta que se elija "
+                "explícitamente si el problema está en producto público, runtime personal, instalación viva, BD real o co-operador."
+            ),
+        )
+
+    if clean_plane not in DOCTOR_COMPATIBLE_PLANES:
+        plane_info = VALID_DIAGNOSTIC_PLANES[clean_plane]
+        return clean_plane, DoctorCheck(
+            id="orchestrator.diagnostic_plane_mismatch",
+            tier="orchestrator",
+            status="degraded",
+            severity="warn",
+            summary=f"NEXO Doctor no es la superficie correcta para el plano {plane_info['label']}",
+            evidence=[
+                f"plane: {clean_plane}",
+                f"este plano se diagnostica mejor desde: {plane_info['use']}",
+            ],
+            repair_plan=[
+                "Si quieres diagnosticar runtime/instalación/BD, vuelve a lanzar el doctor con el plano correcto.",
+                "Si el problema es del producto público o del co-operador, usa release checks, repo checks o herramientas de protocolo/sesión en vez de Doctor.",
+            ],
+            escalation_prompt=(
+                "El plano elegido no corresponde al runtime doctor. Cambia de plano o de herramienta antes de seguir para no mezclar diagnóstico técnico con producto o comportamiento del agente."
+            ),
+        )
+
+    return clean_plane, None