nexo-brain 6.0.5 → 6.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "6.0.5",
+  "version": "6.1.0",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,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 `6.0.5` is the current packaged-runtime line: the strict pre-tool guardrail no longer blocks `Edit`/`Write` with *"unknown target"* when Claude Code's `PreToolUse` payload omits `session_id`. `process_pre_tool_event` now falls back to `$NEXO_HOME/coordination/.claude-session-id` (written by the SessionStart hook) before giving up, so a user who already called `nexo_startup` + `nexo_task_open` + `nexo_guard_check` + `nexo_track` stops seeing the block storm that several Claude Code versions triggered in 6.0.2–6.0.4. Fail-closed semantics are preserved: if neither the payload nor the coordination file yields a session id the guardrail still blocks with `missing_startup`. Release also lands a new `.github/workflows/tests.yml` that runs the full `pytest` suite on every PR — the hook-guardrail regressions that shipped unnoticed in 6.0.2+ would have been caught by CI had this job existed then.
+Version `6.1.0` is the current packaged-runtime line: the Protocol Enforcer Fase 2 ships — a Capa 2 runtime guardian with 25 rules (R13–R25 + R23b–R23m) that keep Claude Code / Codex / Desktop aligned to NEXO protocol. Rule coverage: pre-Edit guard (R13), post-correction learning window (R14), declared-done without close (R16), Nora/María read-only destructive block (R25), plus 21 more across stream wrapper layers (Fase C + D + D2). Also lands migration v43 `session_claude_aliases` — a 1-to-N map from NEXO sid to every Claude session UUID, fixing the NEXO Desktop multi-conversation block where every second conversation's PreToolUse hook failed with "unknown target". External-LLM audit + Opus 4.7 self-audit cycle applied (log redaction with modern token formats, R23f heredoc multiline, R23h native PATH resolution, R14 awaited, hermetic map lookup, cross-engine parity harness strict). Suite: 291 pass + 2 skip documented.
 
 Previously in `6.0.2`: adds the reserved caller prefix `personal/*` so scripts living in `~/.nexo/scripts/` can invoke the automation backend with their own caller id without editing `src/resonance_map.py`. New kwarg `tier` (`"maximo"` / `"alto"` / `"medio"` / `"bajo"`) on `run_automation_prompt`, `run_automation_interactive`, `nexo_helper.run_automation_text`, `nexo_helper.run_automation_json`, and `nexo-agent-run.py --tier`. Precedence for `personal/*` callers: explicit `tier=` → explicit `reasoning_effort=` → `calibration.preferences.default_resonance` → `DEFAULT_RESONANCE` (`alto`). Registered callers keep their behaviour unchanged. New guide: [`docs/personal-scripts-guide.md`](docs/personal-scripts-guide.md).
 

package/bin/nexo-brain.js

@@ -21,6 +21,27 @@ const path = require("path");
 const readline = require("readline");
 
 let NEXO_HOME = process.env.NEXO_HOME || path.join(require("os").homedir(), ".nexo");
+
+function shouldSkipShellProfileBackfill() {
+  // Mirror of _should_skip_shell_profile_backfill() in src/auto_update.py.
+  // Prevent the installer from leaking ``export PATH`` / operator alias lines
+  // into the developer's real shell profile whenever NEXO_HOME is not the
+  // canonical $HOME/.nexo path (pytest tmp dirs, CI sandboxes, containers).
+  const flag = String(process.env.NEXO_SKIP_SHELL_PROFILE || "").trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(flag)) {
+    return { skip: true, reason: `NEXO_SKIP_SHELL_PROFILE=${flag}` };
+  }
+  const canonical = path.join(require("os").homedir(), ".nexo");
+  let actual = NEXO_HOME;
+  try {
+    actual = path.resolve(NEXO_HOME);
+  } catch {}
+  if (actual !== canonical) {
+    return { skip: true, reason: `NEXO_HOME=${actual} is not the canonical ${canonical}` };
+  }
+  return { skip: false, reason: "" };
+}
+
 const CLAUDE_SETTINGS = path.join(
   require("os").homedir(),
   ".claude",
@@ -1856,6 +1877,10 @@ async function main() {
         const migOperatorName = installed.operator_name || "NEXO";
         const migAliasName = migOperatorName.toLowerCase();
         if (migAliasName !== "nexo") {
+          const migSkip = shouldSkipShellProfileBackfill();
+          if (migSkip.skip) {
+            log(`  Skipping shell profile alias restore — ${migSkip.reason}`);
+          } else {
           const migAliasLine = `alias ${migAliasName}='nexo chat .'`;
           const migAliasComment = `# ${migOperatorName} — open the configured NEXO terminal client`;
           const migNexoPathLine = `export PATH="${path.join(NEXO_HOME, "bin")}:$PATH"`;
@@ -1884,6 +1909,7 @@ async function main() {
               log(`  Restored '${migAliasName}' alias in ${path.basename(rcFile)}`);
             }
           }
+          }
         }
 
         console.log("");
@@ -3390,6 +3416,12 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
 
   // Step 8: Create shell alias and add runtime CLI to PATH
   const aliasName = operatorName.toLowerCase();
+  const installSkipShell = shouldSkipShellProfileBackfill();
+  if (installSkipShell.skip) {
+    log(`Skipping shell profile setup — ${installSkipShell.reason}`);
+    log(`(Runtime CLI wrapper still installed at ${path.join(NEXO_HOME, "bin", "nexo")}; add it to PATH manually if needed.)`);
+    console.log("");
+  } else {
   const nexoPathLine = `export PATH="${path.join(NEXO_HOME, "bin")}:$PATH"`;
   const nexoPathComment = "# NEXO runtime CLI";
 
@@ -3442,6 +3474,7 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
     log(`After setup, open a new terminal and type: ${aliasName} or nexo`);
   }
   console.log("");
+  }
 
   // Step 9: Generate CLAUDE.md template
   log("Generating operator instructions...");

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nexo-brain",
-  "version": "6.0.5",
+  "version": "6.1.0",
   "mcpName": "io.github.wazionapps/nexo",
-  "description": "NEXO Brain \u2014 Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
+  "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/auto_update.py

@@ -383,7 +383,38 @@ def _shell_rc_files() -> list[Path]:
     return [home_dir / ".bash_profile", home_dir / ".bashrc"]
 
 
+def _should_skip_shell_profile_backfill() -> tuple[bool, str]:
+    """Decide whether to skip writing ``export PATH`` into the user's shell rc.
+
+    The backfill must only touch the real user shell profile when the runtime
+    is installed at the canonical ``$HOME/.nexo`` location. When ``NEXO_HOME``
+    points elsewhere (pytest ``tmp_path``, CI sandbox, containerised test
+    harness) writing to ``~/.bash_profile`` / ``~/.bashrc`` / ``~/.zshrc``
+    leaks a non-canonical ``export PATH`` line into the developer's real
+    shell, which is exactly the bug reported for v6.0.x. Users can force-skip
+    via ``NEXO_SKIP_SHELL_PROFILE=1``.
+    """
+    flag = os.environ.get("NEXO_SKIP_SHELL_PROFILE", "").strip().lower()
+    if flag in {"1", "true", "yes", "on"}:
+        return True, f"NEXO_SKIP_SHELL_PROFILE={flag}"
+    try:
+        canonical = managed_nexo_home()
+    except Exception:
+        canonical = Path.home() / ".nexo"
+    try:
+        same = NEXO_HOME.resolve(strict=False) == canonical.resolve(strict=False)
+    except Exception:
+        same = NEXO_HOME == canonical
+    if not same:
+        return True, f"NEXO_HOME={NEXO_HOME} is not the canonical {canonical}"
+    return False, ""
+
+
 def _ensure_runtime_cli_in_shell():
+    skip, reason = _should_skip_shell_profile_backfill()
+    if skip:
+        _log(f"Skipping shell profile backfill — {reason}")
+        return
     path_line = f'export PATH="{NEXO_HOME / "bin"}:$PATH"'
     comment = "# NEXO runtime CLI"
     for rc_file in _shell_rc_files():

package/src/call_model_raw.py

@@ -0,0 +1,342 @@
+"""call_model_raw — Plain LLM invocation for the Protocol Enforcer classifier.
+
+Fase 2 spec item 0.1 + 0.20. Provides a DIRECT SDK call that bypasses the
+Claude Code CLI, the NEXO MCP server and the enforcement wrapper. Designed
+for short yes/no classification (R13 pre-edit, R14 correction, R16
+declared-done, R17 promise, R20 constant-change, etc.) where starting the
+full automation stack would dwarf the actual cost of the model call.
+
+Design contract (from plan doc 1 "Refactor de keywords/regex hardcoded —
+Mecanismo C"):
+
+  - Resolve (model, effort) via resonance_map.resolve_model_and_effort on
+    caller "enforcer_classifier" (tier "muy_bajo"). Respects user's backend
+    preference via resolve_automation_backend.
+  - Direct SDK call to the resolved backend (anthropic or openai).
+  - Triple reinforcement for yes/no parsing is implemented in the caller
+    (enforcement_classifier.py): system prompt strict + max_tokens<=3 +
+    regex parser with one retry.
+  - Fail-closed: every transient error (timeout, rate limit, 5xx,
+    connection) raises ClassifierUnavailableError. Upstream catches and
+    degrades the rule to shadow or injects a generic reminder. Never
+    fail-open. Rule #249, #294.
+  - No MCP tools, no hook side-effects, no subprocess. This function is
+    safe to call inside enforcement hot paths.
+
+This module deliberately does NOT live inside agent_runner.py so that:
+
+  1. agent_runner.py stays focused on automation subprocess orchestration.
+  2. enforcement_engine.py (headless) and tools that run outside an
+     automation subprocess can import call_model_raw without pulling in
+     the rest of agent_runner.py.
+  3. Tests for call_model_raw (test_call_model_raw.py) can mock the SDK
+     entry points precisely without monkey-patching agent_runner.
+
+Historical note: pre-Fase 2, callers sometimes reached for
+run_automation_prompt() when they needed a one-shot model call. That
+starts a full Claude Code session and a full NEXO MCP handshake — a
+disaster for per-turn classification cost. call_model_raw closes that
+gap.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+class ClassifierUnavailableError(RuntimeError):
+    """Signal that the enforcer classifier backend is unavailable.
+
+    Fase 2 spec 0.20: callers MUST catch this and fall back to a safer
+    default (inject generic reminder, degrade rule to shadow for the
+    session, etc.). Never fail-open. Learning #249: structured protocol
+    inputs must fail explicitly, never coerce silently.
+    """
+
+
+_ANTHROPIC_KEY_PATHS = (
+    Path.home() / ".claude" / "anthropic-api-key.txt",
+    Path.home() / ".nexo" / "config" / "anthropic-api-key.txt",
+)
+
+_OPENAI_KEY_PATHS = (
+    Path.home() / ".nexo" / "config" / "openai-api-key.txt",
+    Path.home() / ".codex" / "auth.json",
+)
+
+
+def _resolve_anthropic_key() -> str:
+    env_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    if env_key:
+        return env_key
+    for path in _ANTHROPIC_KEY_PATHS:
+        try:
+            if path.is_file():
+                key = path.read_text().strip()
+                if key:
+                    return key
+        except OSError:
+            continue
+    return ""
+
+
+def _resolve_openai_key() -> str:
+    env_key = os.environ.get("OPENAI_API_KEY", "").strip()
+    if env_key:
+        return env_key
+    for path in _OPENAI_KEY_PATHS:
+        try:
+            if not path.is_file():
+                continue
+            text = path.read_text().strip()
+            if not text:
+                continue
+            try:
+                data = json.loads(text)
+                if isinstance(data, dict):
+                    for candidate in ("OPENAI_API_KEY", "api_key", "openai_api_key"):
+                        value = str(data.get(candidate, "") or "").strip()
+                        if value:
+                            return value
+            except json.JSONDecodeError:
+                return text
+        except OSError:
+            continue
+    return ""
+
+
+def _extract_anthropic_text(response) -> str:
+    try:
+        blocks = list(getattr(response, "content", None) or [])
+    except Exception as _exc:  # noqa: BLE001
+        # Audit-MEDIUM: log SDK drift so operators see when the Anthropic
+        # response shape changes between minor versions.
+        import logging as _log
+        _log.getLogger("nexo.enforcer").warning(
+            "anthropic extract_text failed (%s); returning empty", _exc
+        )
+        return ""
+    for block in blocks:
+        text = getattr(block, "text", None)
+        if text:
+            return str(text).strip()
+    return ""
+
+
+def _extract_openai_text(response) -> str:
+    try:
+        choices = getattr(response, "choices", None) or []
+        if not choices:
+            return ""
+        message = getattr(choices[0], "message", None)
+        content = getattr(message, "content", None)
+        if content is None and isinstance(message, dict):
+            content = message.get("content")
+        return str(content or "").strip()
+    except Exception:
+        return ""
+
+
+def _call_anthropic_raw(
+    *,
+    prompt: str,
+    system: str | None,
+    model: str,
+    max_tokens: int,
+    temperature: float,
+    stop_sequences: list[str],
+    timeout: float,
+) -> str:
+    try:
+        import anthropic  # type: ignore
+    except ImportError as exc:
+        raise ClassifierUnavailableError(f"anthropic SDK missing: {exc}") from exc
+
+    api_key = _resolve_anthropic_key()
+    if not api_key:
+        raise ClassifierUnavailableError("anthropic: no ANTHROPIC_API_KEY found")
+
+    client = anthropic.Anthropic(api_key=api_key, timeout=timeout)
+    kwargs: dict = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+        "stop_sequences": stop_sequences,
+        "messages": [{"role": "user", "content": prompt}],
+    }
+    if system:
+        kwargs["system"] = system
+
+    try:
+        response = client.messages.create(**kwargs)
+    except anthropic.APITimeoutError as exc:
+        raise ClassifierUnavailableError(f"anthropic timeout: {exc}") from exc
+    except anthropic.RateLimitError as exc:
+        raise ClassifierUnavailableError(f"anthropic rate_limit: {exc}") from exc
+    except anthropic.APIConnectionError as exc:
+        raise ClassifierUnavailableError(f"anthropic connection: {exc}") from exc
+    except anthropic.APIStatusError as exc:
+        status = getattr(exc, "status_code", 0)
+        if 500 <= status < 600:
+            raise ClassifierUnavailableError(f"anthropic 5xx: {status} {exc}") from exc
+        raise ClassifierUnavailableError(f"anthropic {status}: {exc}") from exc
+    except Exception as exc:  # noqa: BLE001  — fail-closed wrapper
+        raise ClassifierUnavailableError(f"anthropic unexpected: {exc}") from exc
+
+    return _extract_anthropic_text(response)
+
+
+def _call_openai_raw(
+    *,
+    prompt: str,
+    system: str | None,
+    model: str,
+    max_tokens: int,
+    temperature: float,
+    stop_sequences: list[str],
+    timeout: float,
+) -> str:
+    try:
+        import openai  # type: ignore
+    except ImportError as exc:
+        raise ClassifierUnavailableError(f"openai SDK missing: {exc}") from exc
+
+    api_key = _resolve_openai_key()
+    if not api_key:
+        raise ClassifierUnavailableError("openai: no OPENAI_API_KEY found")
+
+    client = openai.OpenAI(api_key=api_key, timeout=timeout)
+    messages: list[dict] = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt})
+
+    try:
+        response = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stop=stop_sequences,
+        )
+    except openai.APITimeoutError as exc:
+        raise ClassifierUnavailableError(f"openai timeout: {exc}") from exc
+    except openai.RateLimitError as exc:
+        raise ClassifierUnavailableError(f"openai rate_limit: {exc}") from exc
+    except openai.APIConnectionError as exc:
+        raise ClassifierUnavailableError(f"openai connection: {exc}") from exc
+    except openai.APIStatusError as exc:
+        status = getattr(exc, "status_code", 0)
+        if 500 <= status < 600:
+            raise ClassifierUnavailableError(f"openai 5xx: {status} {exc}") from exc
+        raise ClassifierUnavailableError(f"openai {status}: {exc}") from exc
+    except Exception as exc:  # noqa: BLE001  — fail-closed wrapper
+        raise ClassifierUnavailableError(f"openai unexpected: {exc}") from exc
+
+    return _extract_openai_text(response)
+
+
+def call_model_raw(
+    prompt: str,
+    *,
+    tier: str = "muy_bajo",
+    caller: str = "enforcer_classifier",
+    max_tokens: int = 3,
+    temperature: float = 0.0,
+    stop_sequences: list[str] | None = None,
+    timeout: float = 10.0,
+    system: str | None = None,
+) -> str:
+    """Run a single short LLM completion for enforcement-class classification.
+
+    Parameters follow the Fase 2 plan doc 1 spec:
+
+        prompt         — the user-role text (English or the model's default).
+        tier           — resonance tier; default "muy_bajo" → Haiku / gpt-5.4-mini.
+        caller         — resonance caller label. Must be registered in
+                         resonance_map.SYSTEM_OWNED_CALLERS. Default
+                         "enforcer_classifier".
+        max_tokens     — hard cap on output tokens. Default 3 (yes/no only).
+        temperature    — sampling temperature. Default 0.0 (deterministic).
+        stop_sequences — early-stop strings. Default ["\\n", ".", " "].
+        timeout        — per-request timeout in seconds. Default 10.0.
+        system         — optional system prompt. Default None (provider default).
+
+    Returns the raw text response, trimmed. The CALLER is responsible for
+    parsing yes/no — the "triple reinforcement" (prompt strict, max_tokens
+    tiny, regex parser with retry, fallback conservative) is implemented in
+    enforcement_classifier.py on top of this function.
+
+    Raises ClassifierUnavailableError on any of:
+
+        - automation_backend == none (user disabled automation)
+        - tier not present in resonance_tiers.json for the resolved backend
+        - SDK package missing
+        - API key missing
+        - Timeout / rate limit / 5xx / ConnectionError / any unexpected exception
+
+    Callers MUST catch this and fall back to a safer default. Fase 2 spec
+    0.20 is explicit: silence is not obedience. Never fail-open.
+    """
+    if stop_sequences is None:
+        stop_sequences = ["\n", ".", " "]
+
+    # Local imports to avoid circulars and keep agent_runner.py decoupled.
+    from client_preferences import (  # type: ignore
+        BACKEND_NONE,
+        CLIENT_CLAUDE_CODE,
+        CLIENT_CODEX,
+        load_client_preferences,
+        resolve_automation_backend,
+    )
+    from resonance_map import (  # type: ignore
+        UnregisteredCallerError,
+        resolve_model_and_effort,
+    )
+
+    prefs = load_client_preferences()
+    backend = resolve_automation_backend(preferences=prefs)
+    if backend == BACKEND_NONE:
+        raise ClassifierUnavailableError("automation_backend=none")
+
+    try:
+        model, _effort = resolve_model_and_effort(
+            caller=caller,
+            backend=backend,
+            explicit_tier=tier,
+        )
+    except UnregisteredCallerError as exc:
+        raise ClassifierUnavailableError(f"caller not registered: {exc}") from exc
+
+    if not model:
+        raise ClassifierUnavailableError(
+            f"no (model, effort) for tier={tier!r} backend={backend!r}; "
+            f"check resonance_tiers.json"
+        )
+
+    if backend == CLIENT_CLAUDE_CODE:
+        return _call_anthropic_raw(
+            prompt=prompt,
+            system=system,
+            model=model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stop_sequences=stop_sequences,
+            timeout=timeout,
+        )
+    if backend == CLIENT_CODEX:
+        return _call_openai_raw(
+            prompt=prompt,
+            system=system,
+            model=model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stop_sequences=stop_sequences,
+            timeout=timeout,
+        )
+
+    raise ClassifierUnavailableError(f"unsupported backend: {backend}")
+
+
+__all__ = ["call_model_raw", "ClassifierUnavailableError"]

package/src/cli.py

@@ -2277,6 +2277,25 @@ def main():
     dashboard_parser.add_argument("action", choices=["on", "off", "status"], help="Start, stop, or check dashboard")
 
     # -- desktop bridge (read-only, for NEXO Desktop and any external UI) --
+    # Fase E.5 — quarantine ops surfaced via Desktop Guardian Proposals panel.
+    quarantine_parser = sub.add_parser("quarantine", help="Quarantine proposals (Fase E.5 Desktop UI)")
+    quarantine_sub = quarantine_parser.add_subparsers(dest="quarantine_command")
+
+    qlist_p = quarantine_sub.add_parser("list", help="List quarantine items")
+    qlist_p.add_argument("--status", default="pending",
+                         choices=["pending", "promoted", "rejected", "expired", "all"])
+    qlist_p.add_argument("--limit", type=int, default=20)
+    qlist_p.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    qpromote_p = quarantine_sub.add_parser("promote", help="Promote a quarantine item to STM")
+    qpromote_p.add_argument("id", help="Quarantine item id")
+    qpromote_p.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    qreject_p = quarantine_sub.add_parser("reject", help="Reject a quarantine item")
+    qreject_p.add_argument("id", help="Quarantine item id")
+    qreject_p.add_argument("--reason", default="", help="Optional rejection reason")
+    qreject_p.add_argument("--json", action="store_true", help="JSON output (default)")
+
     schema_parser = sub.add_parser("schema", help="Editable-field schema for Preferences UI")
     schema_parser.add_argument("--json", action="store_true", help="JSON output (default)")
 
@@ -2410,6 +2429,17 @@ def main():
         return _uninstall(args)
     elif args.command == "dashboard":
         return _dashboard(args)
+    elif args.command == "quarantine":
+        from desktop_bridge import cmd_quarantine_list, cmd_quarantine_promote, cmd_quarantine_reject
+        if args.quarantine_command == "list":
+            return cmd_quarantine_list(args)
+        if args.quarantine_command == "promote":
+            return cmd_quarantine_promote(args)
+        if args.quarantine_command == "reject":
+            return cmd_quarantine_reject(args)
+        # No subcommand — show help.
+        quarantine_parser.print_help()
+        return 1
     elif args.command in ("schema", "identity", "onboard", "scan-profile"):
         from desktop_bridge import cmd_schema, cmd_identity, cmd_onboard, cmd_scan_profile
         return {

package/src/client_preferences.py

@@ -98,6 +98,10 @@ def default_client_preferences() -> dict:
         "last_terminal_client": "",
         "automation_enabled": True,
         "automation_backend": CLIENT_CLAUDE_CODE,
+        # True iff the user has EXPLICITLY changed automation_backend from its
+        # installer-chosen value. Installer/update flows (Fase E) only rewrite
+        # automation_backend if this flag is False — respects user opt-out.
+        "automation_user_override": False,
         "client_runtime_profiles": default_client_runtime_profiles(),
         "automation_task_profiles": default_automation_task_profiles(),
         "client_install_preferences": {
@@ -233,6 +237,21 @@ def normalize_automation_enabled(value) -> bool:
     return _coerce_bool(value, True)
 
 
+def normalize_automation_user_override(value) -> bool:
+    """Normalize automation_user_override flag.
+
+    Coerces any truthy value to True, falsy to False. Use when loading
+    user preferences or when accepting apply_client_preferences input.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    if isinstance(value, (int, float)):
+        return bool(value)
+    return False
+
+
 def normalize_automation_backend(value, *, automation_enabled: bool = True) -> str:
     if not automation_enabled:
         return BACKEND_NONE
@@ -380,6 +399,9 @@ def normalize_client_preferences(
         schedule.get("automation_backend"),
         automation_enabled=automation_enabled,
     )
+    automation_user_override = normalize_automation_user_override(
+        schedule.get("automation_user_override")
+    )
     install_preferences = normalize_client_install_preferences(
         schedule.get("client_install_preferences")
     )
@@ -392,6 +414,7 @@ def normalize_client_preferences(
         "last_terminal_client": last_terminal_client,
         "automation_enabled": automation_enabled,
         "automation_backend": automation_backend,
+        "automation_user_override": automation_user_override,
         "client_runtime_profiles": runtime_profiles,
         "automation_task_profiles": normalize_automation_task_profiles(
             schedule.get("automation_task_profiles")
@@ -429,6 +452,7 @@ def apply_client_preferences(
     last_terminal_client: str | None = None,
     automation_enabled=None,
     automation_backend: str | None = None,
+    automation_user_override: bool | None = None,
     client_runtime_profiles: dict | None = None,
     automation_task_profiles: dict | None = None,
     client_install_preferences: dict | None = None,
@@ -454,6 +478,11 @@ def apply_client_preferences(
         automation_backend if automation_backend is not None else current["automation_backend"],
         automation_enabled=merged["automation_enabled"],
     )
+    merged["automation_user_override"] = normalize_automation_user_override(
+        automation_user_override
+        if automation_user_override is not None
+        else current.get("automation_user_override", False)
+    )
     merged["client_runtime_profiles"] = normalize_client_runtime_profiles(
         client_runtime_profiles
         if client_runtime_profiles is not None
@@ -490,6 +519,7 @@ def save_client_preferences(
     last_terminal_client: str | None = None,
     automation_enabled=None,
     automation_backend: str | None = None,
+    automation_user_override: bool | None = None,
     client_runtime_profiles: dict | None = None,
     automation_task_profiles: dict | None = None,
     client_install_preferences: dict | None = None,
@@ -503,6 +533,7 @@ def save_client_preferences(
         last_terminal_client=last_terminal_client,
         automation_enabled=automation_enabled,
         automation_backend=automation_backend,
+        automation_user_override=automation_user_override,
         client_runtime_profiles=client_runtime_profiles,
         automation_task_profiles=automation_task_profiles,
         client_install_preferences=client_install_preferences,