ha-mcp-dev 8.6.0.dev2844__tar.gz → 8.6.0.dev2847__tar.gz

{ha_mcp_dev-8.6.0.dev2844 → ha_mcp_dev-8.6.0.dev2847}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2844
+Version: 8.6.0.dev2847
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev2844 → ha_mcp_dev-8.6.0.dev2847}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2844"
+version = "8.6.0.dev2847"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2844 → ha_mcp_dev-8.6.0.dev2847}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2844"
+version = "8.6.0.dev2847"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

ha_mcp_dev-8.6.0.dev2847/src/ha_mcp/config.py

@@ -0,0 +1,396 @@
+"""
+Configuration management for Home Assistant MCP Server.
+
+The ``Settings`` model, the runtime-editable registries and the override
+loaders live in the ``config_*`` modules and are re-exported here. This
+module holds the settings singleton and the embedded-mode connection.
+"""
+
+# isort: off
+from ha_mcp.config_backup import (
+    _apply_backup_overrides as _apply_backup_overrides,
+    get_backup_setting_origin as get_backup_setting_origin,
+)
+from ha_mcp.config_overrides import (
+    _BETA_GATE_LOGGED as _BETA_GATE_LOGGED,
+    _apply_advanced_overrides as _apply_advanced_overrides,
+    _apply_feature_flag_overrides as _apply_feature_flag_overrides,
+    _coerce_advanced_override_value as _coerce_advanced_override_value,
+    _read_feature_flag_override_file as _read_feature_flag_override_file,
+    get_feature_flag_origin as get_feature_flag_origin,
+)
+from ha_mcp.config_registry import (
+    _ADVANCED_SETTINGS_BOUNDS as _ADVANCED_SETTINGS_BOUNDS,
+    _ADVANCED_SETTINGS_CHOICES as _ADVANCED_SETTINGS_CHOICES,
+    _ADVANCED_SETTINGS_SENTINELS as _ADVANCED_SETTINGS_SENTINELS,
+    _FEATURE_FLAG_INT_BOUNDS as _FEATURE_FLAG_INT_BOUNDS,
+    _FEATURE_FLAG_OVERRIDE_FILENAME as _FEATURE_FLAG_OVERRIDE_FILENAME,
+    ADDON_SYNCED_ADVANCED_FIELDS as ADDON_SYNCED_ADVANCED_FIELDS,
+    ADVANCED_SETTINGS_FIELDS as ADVANCED_SETTINGS_FIELDS,
+    BACKUP_OVERRIDE_FIELDS as BACKUP_OVERRIDE_FIELDS,
+    BETA_FEATURE_FIELDS as BETA_FEATURE_FIELDS,
+    FEATURE_FLAG_FIELDS as FEATURE_FLAG_FIELDS,
+    AdvancedField as AdvancedField,
+    BackupOverrideField as BackupOverrideField,
+    FeatureFlagField as FeatureFlagField,
+)
+from ha_mcp.config_settings import (
+    _PACKAGE_VERSION as _PACKAGE_VERSION,
+    OAUTH_MODE_TOKEN as OAUTH_MODE_TOKEN,
+    OAUTH_MODE_URL as OAUTH_MODE_URL,
+    Settings as Settings,
+    get_settings as get_settings,
+)
+# isort: on
+
+__all__ = [
+    "ADDON_SYNCED_ADVANCED_FIELDS",
+    "ADVANCED_SETTINGS_FIELDS",
+    "BACKUP_OVERRIDE_FIELDS",
+    "BETA_FEATURE_FIELDS",
+    "FEATURE_FLAG_FIELDS",
+    "OAUTH_MODE_TOKEN",
+    "OAUTH_MODE_URL",
+    "_ADVANCED_SETTINGS_BOUNDS",
+    "_ADVANCED_SETTINGS_CHOICES",
+    "_ADVANCED_SETTINGS_SENTINELS",
+    "_FEATURE_FLAG_INT_BOUNDS",
+    "_FEATURE_FLAG_OVERRIDE_FILENAME",
+    "_PACKAGE_VERSION",
+    "BackupOverrideField",
+    "FeatureFlagField",
+    "Settings",
+    "_coerce_advanced_override_value",
+    "_read_feature_flag_override_file",
+    "_reset_global_settings",
+    "_settings",
+    "get_backup_setting_origin",
+    "get_embedded_config_dir",
+    "get_feature_flag_origin",
+    "get_global_settings",
+    "get_settings",
+    "parse_extra_yaml_write_keys",
+    "reset_global_settings",
+    "set_embedded_connection",
+    "should_emit_llm_api_metadata",
+]
+
+
+def parse_extra_yaml_write_keys(settings: "Settings") -> list[str]:
+    """Parse ``extra_yaml_write_keys`` into a clean key list (#1887).
+
+    Whitespace and empty entries are dropped and the result is deduplicated
+    and sorted, so the service payload is deterministic and unaffected by how
+    the operator spaced the setting.
+
+    The component's ``YAML_KEY_DENYLIST`` is NOT applied here: that floor
+    lives component-side, in the layer that authorizes the write. Mirroring it
+    would mean a second copy to keep in lockstep for no gain: a denied key sent
+    on the wire is dropped there anyway.
+
+    Lives in this module rather than next to the YAML tool because the backup
+    restore path needs it too, and ``backup_manager`` importing a ``tools_*``
+    module would add an import edge that binds ``tools_yaml_config``'s
+    module-level names at restore time.
+    """
+    # Direct attribute access, matching ``_disabled_packages_keys``: a future
+    # rename must raise loudly rather than silently return an empty list,
+    # which would read as "the operator configured nothing".
+    raw = settings.extra_yaml_write_keys or ""
+    return sorted({segment.strip() for segment in raw.split(",") if segment.strip()})
+
+
+# Global settings instance
+_settings: Settings | None = None
+
+# In-process (embedded) HA connection, set only when ha-mcp runs inside Home
+# Assistant core via the ha_mcp_tools custom component's in-process server entry.
+# The component hands the loopback URL + a provisioned admin token to ha-mcp
+# THROUGH THIS DICT — never
+# via os.environ — so the admin token can't be read from the shared HA process
+# environment. Applied onto the Settings singleton in ``get_global_settings``.
+_EMBEDDED_CONNECTION: dict[str, str | bool] = {}
+
+
+def set_embedded_connection(
+    url: str,
+    token: str,
+    verify_ssl: bool | None = None,
+    config_dir: str | None = None,
+    llm_api_enabled: bool | None = None,
+) -> None:
+    """Register the in-process HA connection for embedded mode.
+
+    Embedded-mode only: called by the ha_mcp_tools custom component's in-process
+    server entry inside its server worker thread, before the server is
+    constructed, so the loopback URL
+    and admin token reach ``Settings`` in memory instead of through ``os.environ``.
+    The values survive ``_reset_global_settings()``: the settings-UI reset+rebuild
+    path re-applies them on the next ``get_global_settings()`` call.
+
+    Also applies to an ALREADY-BUILT singleton: importing ``ha_mcp`` runs the
+    package's eager import chain, and ``tools/smart_search/_config.py`` builds
+    the settings singleton at import time (its documented read-once budgets).
+    Registration therefore cannot assume it runs before the first build — the
+    integration imports this function from the very package whose import
+    creates the singleton.
+
+    ``verify_ssl`` lets the component disable certificate verification when it
+    derives an ``https://127.0.0.1`` loopback URL from Home Assistant's SSL
+    config (issue #1890): HA's certificate is issued for its hostname, never
+    for 127.0.0.1, so verification on the loopback connection can only fail.
+    ``None`` (the default, and what pre-#1890 components pass implicitly)
+    leaves ``Settings.verify_ssl`` alone.
+
+    ``config_dir`` is Home Assistant's own configuration directory (#2329).
+    Embedded mode is its only writer and it is read back through
+    :func:`get_embedded_config_dir` alone — deliberately NOT a ``Settings``
+    field, so no env var or override file can point it anywhere. It lets an
+    in-process server read a blueprint's on-disk YAML directly instead of
+    routing the read through the component, and grants nothing an external
+    server could not already reach.
+    """
+    _EMBEDDED_CONNECTION["url"] = url
+    _EMBEDDED_CONNECTION["token"] = token
+    if verify_ssl is None:
+        _EMBEDDED_CONNECTION.pop("verify_ssl", None)
+    else:
+        _EMBEDDED_CONNECTION["verify_ssl"] = verify_ssl
+    if config_dir is None:
+        _EMBEDDED_CONNECTION.pop("config_dir", None)
+    else:
+        _EMBEDDED_CONNECTION["config_dir"] = config_dir
+    if llm_api_enabled is None:
+        _EMBEDDED_CONNECTION.pop("llm_api_enabled", None)
+    else:
+        _EMBEDDED_CONNECTION["llm_api_enabled"] = llm_api_enabled
+    if _settings is not None:
+        _apply_embedded_connection(_settings)
+
+
+def get_embedded_config_dir() -> str | None:
+    """Home Assistant's configuration directory, when running embedded.
+
+    ``None`` outside embedded mode, and on an embedded install whose component
+    predates the ``config_dir`` keyword. Consumers must treat it as an optional
+    capability and fall back to their component / service path.
+    """
+    config_dir = _EMBEDDED_CONNECTION.get("config_dir")
+    return config_dir if isinstance(config_dir, str) and config_dir else None
+
+
+def should_emit_llm_api_metadata() -> bool:
+    """Return whether ``tools/list`` needs the component's private metadata.
+
+    Standalone and add-on clients have no consumer for ``_meta.ha_mcp``. An
+    embedded server needs it only when the custom component exposes its LLM
+    API. A missing flag means an older component, so preserve the historical
+    embedded behavior until that component is upgraded.
+    """
+    if not _EMBEDDED_CONNECTION:
+        return False
+    enabled = _EMBEDDED_CONNECTION.get("llm_api_enabled")
+    return enabled if isinstance(enabled, bool) else True
+
+
+def _reset_embedded_connection() -> None:
+    """Drop the registered embedded connection (test seam).
+
+    Sibling to :func:`_reset_global_settings`; lets suites that exercise the
+    in-process token channel isolate state between tests. Not used in production —
+    the connection is registered once per worker thread and is meant to persist.
+    """
+    _EMBEDDED_CONNECTION.clear()
+
+
+def _apply_embedded_connection(settings: "Settings") -> None:
+    """Apply the in-process embedded HA connection (url/token/verify_ssl) if registered.
+
+    No-op outside embedded mode. Plain ``setattr`` (``validate_assignment`` is off
+    on ``Settings``, mirroring ``_apply_backup_overrides``), so the loopback URL
+    and admin token are set in memory without ever passing through ``os.environ``.
+    Applied last so it wins over any env/override-file connection values.
+    """
+    url = _EMBEDDED_CONNECTION.get("url")
+    token = _EMBEDDED_CONNECTION.get("token")
+    if isinstance(url, str) and url:
+        settings.homeassistant_url = url.rstrip("/")
+    if isinstance(token, str) and token:
+        settings.homeassistant_token = token
+    verify_ssl = _EMBEDDED_CONNECTION.get("verify_ssl")
+    if isinstance(verify_ssl, bool):
+        settings.verify_ssl = verify_ssl
+
+
+def get_global_settings() -> Settings:
+    """Get global settings instance (singleton pattern).
+
+    Applies override files at first read so web-UI edits take effect
+    on the next ``get_global_settings()`` call after
+    ``_reset_global_settings()`` is called by the POST handler:
+
+    - Feature flags persisted to ``<data_dir>/feature_flags.json``
+    - Auto-backup settings persisted to ``<data_dir>/backup_settings.json``
+
+    In embedded mode, the in-process HA connection registered via
+    ``set_embedded_connection`` is applied last (so a settings-UI reset+rebuild
+    re-picks it up).
+    """
+    global _settings
+    if _settings is None:
+        _settings = get_settings()
+        _apply_feature_flag_overrides(_settings)
+        _apply_backup_overrides(_settings)
+        _apply_advanced_overrides(_settings)
+        _apply_embedded_connection(_settings)
+    return _settings
+
+
+def reset_global_settings() -> None:
+    """Public seam to drop the cached settings singleton.
+
+    The in-process (embedded) server calls this at every start: a config-entry
+    reload reuses the same Python process, so without an explicit reset the
+    singleton built on the FIRST start would keep serving stale feature-flag /
+    override values forever (the add-on gets fresh settings for free from its
+    process restart).
+    """
+    _reset_global_settings()
+
+
+def _reset_global_settings() -> None:
+    """Drop the cached settings singleton.
+
+    Test seam so suites that mutate env vars can force a re-read
+    without reaching into module-private state. Also used by the
+    feature-flag and auto-backup settings POST handlers to publish a
+    freshly edited override file value to runtime consumers
+    (``get_global_settings`` is the only documented read path; the
+    ``@with_auto_backup`` decorator reads it per tool call).
+    """
+    global _settings
+    _settings = None
+    # Drop the gate-log dedup set too — once Settings has been
+    # rebuilt, an operator who's re-investigating "why is my beta
+    # tool off?" should see the next gate fire logged. This keeps
+    # the dedup tight to the lifetime of one cached Settings.
+    _BETA_GATE_LOGGED.clear()
+
+
+# Import-time validator for cross-registry invariants.
+#
+# Catches a class of silent runtime bugs at module load:
+#  - registry rows referencing fields that don't exist on ``Settings``
+#    (rename / removal drift)
+#  - registries overlapping by name (same field applied by two
+#    ``_apply_*_overrides`` functions with potentially divergent
+#    coercion policies)
+#  - bounds entries pointing at non-numeric fields (would silently
+#    no-op in the apply loop)
+#  - choices entries pointing at non-str fields (same)
+#  - ``BETA_FEATURE_FIELDS`` referencing names not in
+#    ``FEATURE_FLAG_FIELDS`` (master gate would write to phantom
+#    Settings attributes)
+def _validate_registry_fields_exist(
+    settings_fields: set[str],
+    advanced_names: set[str],
+    flag_names: set[str],
+    backup_names: set[str],
+) -> None:
+    """Every registry row must reference a real Settings field."""
+    for registry_name, names in (
+        ("ADVANCED_SETTINGS_FIELDS", advanced_names),
+        ("FEATURE_FLAG_FIELDS", flag_names),
+        ("BACKUP_OVERRIDE_FIELDS", backup_names),
+    ):
+        missing = names - settings_fields
+        if missing:
+            raise RuntimeError(
+                f"{registry_name} references fields not on Settings: {sorted(missing)}"
+            )
+
+
+def _validate_registries_disjoint(
+    advanced_names: set[str], flag_names: set[str], backup_names: set[str]
+) -> None:
+    """Registries must be name-disjoint to avoid double-apply with divergent policies."""
+    overlaps = {
+        ("advanced", "flags"): advanced_names & flag_names,
+        ("advanced", "backup"): advanced_names & backup_names,
+        ("flags", "backup"): flag_names & backup_names,
+    }
+    for (a, b), shared in overlaps.items():
+        if shared:
+            raise RuntimeError(
+                f"Registry overlap between {a} and {b}: {sorted(shared)}. "
+                "Each field must be applied by exactly one of "
+                "_apply_feature_flag_overrides / _apply_advanced_overrides "
+                "/ _apply_backup_overrides."
+            )
+
+
+def _validate_advanced_bounds(advanced_by_name: dict[str, AdvancedField]) -> None:
+    """_ADVANCED_SETTINGS_BOUNDS keys must be advanced fields AND numeric."""
+    for name in _ADVANCED_SETTINGS_BOUNDS:
+        if name not in advanced_by_name:
+            raise RuntimeError(
+                f"_ADVANCED_SETTINGS_BOUNDS[{name!r}] is not in "
+                "ADVANCED_SETTINGS_FIELDS"
+            )
+        if advanced_by_name[name].ftype not in (int, float):
+            raise RuntimeError(
+                f"_ADVANCED_SETTINGS_BOUNDS[{name!r}] is on a non-numeric "
+                f"field (type={advanced_by_name[name].ftype.__name__})"
+            )
+
+
+def _validate_advanced_choices(advanced_by_name: dict[str, AdvancedField]) -> None:
+    """_ADVANCED_SETTINGS_CHOICES keys must be advanced fields AND str."""
+    for name in _ADVANCED_SETTINGS_CHOICES:
+        if name not in advanced_by_name:
+            raise RuntimeError(
+                f"_ADVANCED_SETTINGS_CHOICES[{name!r}] is not in "
+                "ADVANCED_SETTINGS_FIELDS"
+            )
+        if advanced_by_name[name].ftype is not str:
+            raise RuntimeError(
+                f"_ADVANCED_SETTINGS_CHOICES[{name!r}] is on a non-str "
+                f"field (type={advanced_by_name[name].ftype.__name__})"
+            )
+
+
+def _validate_beta_subset(flag_names: set[str]) -> None:
+    """BETA_FEATURE_FIELDS must be a subset of FEATURE_FLAG_FIELDS.
+
+    The master gate writes to them via setattr; phantom names would
+    silently land on extras with no effect on the runtime gate.
+    """
+    beta_set = set(BETA_FEATURE_FIELDS)
+    not_in_flags = beta_set - flag_names
+    if not_in_flags:
+        raise RuntimeError(
+            f"BETA_FEATURE_FIELDS contains names not in FEATURE_FLAG_FIELDS: "
+            f"{sorted(not_in_flags)}"
+        )
+
+
+def _validate_registries() -> None:
+    settings_fields = set(Settings.model_fields.keys())
+
+    advanced_names = {f.field for f in ADVANCED_SETTINGS_FIELDS}
+    flag_names = {f.field for f in FEATURE_FLAG_FIELDS}
+    backup_names = {f.field for f in BACKUP_OVERRIDE_FIELDS}
+
+    _validate_registry_fields_exist(
+        settings_fields, advanced_names, flag_names, backup_names
+    )
+    _validate_registries_disjoint(advanced_names, flag_names, backup_names)
+
+    advanced_by_name = {f.field: f for f in ADVANCED_SETTINGS_FIELDS}
+    _validate_advanced_bounds(advanced_by_name)
+    _validate_advanced_choices(advanced_by_name)
+
+    _validate_beta_subset(flag_names)
+
+
+_validate_registries()

ha_mcp_dev-8.6.0.dev2847/src/ha_mcp/config_backup.py

@@ -0,0 +1,258 @@
+"""Auto-backup settings overrides read from ``backup_settings.json``."""
+
+import logging
+import os
+from typing import Any
+
+from ha_mcp._version import is_running_in_addon
+from ha_mcp.config_registry import (
+    _BACKUP_OVERRIDE_FILENAME,
+    BACKUP_OVERRIDE_FIELDS,
+    RegistryFieldType,
+)
+from ha_mcp.config_settings import Settings
+
+# All config modules log under the ``ha_mcp.config`` logger name.
+logger = logging.getLogger("ha_mcp.config")
+
+
+def get_backup_setting_origin(env_name: str) -> str:
+    """Return where the live value for ``env_name`` is sourced from.
+
+    Used by the web UI to label each auto-backup field with its source
+    and decide whether the field is editable from the web UI:
+
+    - ``"addon"``: running inside the HA add-on. ``start.py`` always
+      writes these env vars from ``config.yaml`` on every addon start;
+      the override file is ignored. Web UI edits are routed through
+      Supervisor ``/addons/self/options`` so ``config.yaml`` stays
+      authoritative.
+    - ``"env"``: env var explicitly set in the process environment
+      (includes values loaded from ``.env`` via ``load_dotenv`` at
+      module import — those land in ``os.environ`` and are
+      indistinguishable from ``docker -e`` / shell-set values, which is
+      intentional per the deployment design). Web UI shows the field
+      read-only; user must unset / remove the env var to edit.
+    - ``"file"``: standalone deployment with a value persisted in
+      ``<data_dir>/backup_settings.json``. Web UI edits update the
+      file in place.
+    - ``"default"``: no env var and no override file entry; the
+      pydantic field default applies. Web UI edits create the file.
+    """
+    # is_running_in_addon() rather than a raw SUPERVISOR_TOKEN read so the
+    # embedded in-process server (SUPERVISOR_TOKEN present on HAOS, but not an
+    # add-on) is labeled a standalone deployment and its backup settings persist
+    # to the override file instead of a non-existent Supervisor add-on.
+    if is_running_in_addon():
+        return "addon"
+    if os.environ.get(env_name) is not None:
+        return "env"
+    field_name = next(
+        (fname for fname, ename, _ in BACKUP_OVERRIDE_FIELDS if ename == env_name),
+        None,
+    )
+    if field_name is None:
+        return "default"
+    overrides = _read_backup_override_file()
+    if field_name in overrides:
+        return "file"
+    return "default"
+
+
+def _read_backup_override_file() -> dict[str, object]:
+    """Return the contents of the auto-backup override file, or ``{}``.
+
+    Best-effort: a corrupt file MUST NOT break Settings loading. The
+    failure modes split into two categories that need different
+    treatment (mirrors ``_read_feature_flag_override_file``):
+
+    * **Silent**: file does not exist. The override layer is opt-in;
+      a missing file is the normal "user has never edited" state and
+      should not log.
+    * **Loud (WARNING)**: file exists but is unreadable
+      (``PermissionError``, broken filesystem) or unparseable
+      (``JSONDecodeError``). The user toggled something, the UI said
+      "Saved", and the value is silently being ignored. Without a
+      log line they have no diagnostic; with one, the sidecar/server
+      log tells them exactly what to fix.
+
+    Reads are not cached — callers (Settings construction, the GET
+    endpoint) hit disk each time, which is fine for a small JSON file
+    behind a singleton-cached Settings.
+    """
+    import json
+    from pathlib import Path
+
+    try:
+        from .utils.data_paths import get_data_dir
+
+        path: Path = get_data_dir() / _BACKUP_OVERRIDE_FILENAME
+    except (RuntimeError, OSError):
+        # Couldn't resolve the data dir at all — user has no override
+        # file by definition. Silent.
+        return {}
+    try:
+        raw = path.read_text()
+    except FileNotFoundError:
+        return {}
+    except OSError:
+        logger.warning(
+            "Auto-backup override file at %s exists but is unreadable; "
+            "falling back to defaults. Check filesystem permissions.",
+            path,
+            exc_info=True,
+        )
+        return {}
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        logger.warning(
+            "Auto-backup override file at %s is not valid JSON; "
+            "falling back to defaults. Delete or fix the file to "
+            "re-enable persisted toggles.",
+            path,
+        )
+        return {}
+    if not isinstance(data, dict):
+        logger.warning(
+            "Auto-backup override file at %s is not a JSON object "
+            "(got %s); falling back to defaults.",
+            path,
+            type(data).__name__,
+        )
+        return {}
+    return data
+
+
+def _coerce_backup_int_value(field_name: str, raw: object) -> tuple[bool, Any]:
+    """Coerce + per-field range-check one int-typed BACKUP_OVERRIDE_FIELDS value.
+
+    Split out of ``_coerce_backup_override_value`` (mccabe complexity):
+    handles the int-parse plus the three field-specific range checks.
+    """
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        logger.warning(
+            "backup_settings.json: %s expects int, got %s; ignoring",
+            field_name,
+            type(raw).__name__,
+        )
+        return False, None
+    coerced = int(raw)
+    if field_name == "auto_backup_throttle_minutes" and not 0 <= coerced <= 1440:
+        logger.warning(
+            "backup_settings.json: auto_backup_throttle_minutes=%d out of "
+            "range 0..1440; ignoring",
+            coerced,
+        )
+        return False, None
+    if field_name == "auto_backup_retain_per_entity" and not 1 <= coerced <= 10_000:
+        logger.warning(
+            "backup_settings.json: auto_backup_retain_per_entity=%d out of "
+            "range 1..10000; ignoring",
+            coerced,
+        )
+        return False, None
+    if field_name == "auto_backup_calendar_lookahead_days" and not 1 <= coerced <= 365:
+        logger.warning(
+            "backup_settings.json: auto_backup_calendar_lookahead_days=%d out of "
+            "range 1..365; ignoring",
+            coerced,
+        )
+        return False, None
+    if field_name == "snapshot_delete_min_age_days" and not 0 <= coerced <= 365:
+        logger.warning(
+            "backup_settings.json: snapshot_delete_min_age_days=%d out of "
+            "range 0..365; ignoring",
+            coerced,
+        )
+        return False, None
+    return True, coerced
+
+
+def _coerce_backup_override_value(
+    field_name: str, ftype: RegistryFieldType, raw: object
+) -> tuple[bool, Any]:
+    """Coerce + range-check one override-file value for BACKUP_OVERRIDE_FIELDS.
+
+    Returns ``(ok, coerced)``. ``ok=False`` means the value was rejected
+    (a warning has already been logged) and the caller should skip
+    applying it.
+    """
+    if ftype is bool:
+        if not isinstance(raw, bool | int):
+            logger.warning(
+                "backup_settings.json: %s expects bool, got %s; ignoring",
+                field_name,
+                type(raw).__name__,
+            )
+            return False, None
+        return True, bool(raw)
+    elif ftype is int:
+        return _coerce_backup_int_value(field_name, raw)
+    elif ftype is str:
+        if not isinstance(raw, str):
+            logger.warning(
+                "backup_settings.json: %s expects str, got %s; ignoring",
+                field_name,
+                type(raw).__name__,
+            )
+            return False, None
+        if "\x00" in raw:
+            logger.warning(
+                "backup_settings.json: %s contains null byte; ignoring",
+                field_name,
+            )
+            return False, None
+        return True, raw
+    return False, None
+
+
+def _apply_one_backup_override(
+    settings: "Settings",
+    field_name: str,
+    env_name: str,
+    ftype: RegistryFieldType,
+    overrides: dict[str, object],
+) -> None:
+    """Apply a single BACKUP_OVERRIDE_FIELDS override-file entry, if eligible."""
+    if os.environ.get(env_name) is not None:
+        return
+    if field_name not in overrides:
+        return
+    ok, coerced = _coerce_backup_override_value(
+        field_name, ftype, overrides[field_name]
+    )
+    if not ok:
+        return
+    try:
+        setattr(settings, field_name, coerced)
+    except (ValueError, TypeError) as err:
+        logger.warning(
+            "backup_settings.json: setattr(%s, %r) rejected by Settings (%s); ignoring",
+            field_name,
+            coerced,
+            err,
+        )
+
+
+def _apply_backup_overrides(settings: "Settings") -> None:
+    """Patch ``settings`` with values from the override file, in place.
+
+    Honors the "env var wins" contract: a field whose env var is set in
+    the process environment is never overwritten. Addon mode short-
+    circuits — ``start.py`` already wrote these env vars from
+    ``config.yaml`` and the override file is ignored in that mode.
+    Range / type clamping mirrors the pydantic Field bounds so a
+    corrupt override file can't push values out of range; out-of-range
+    or untypable entries are silently skipped.
+    """
+    # is_running_in_addon() (embedded-aware) so the in-process server applies
+    # its backup override file like a standalone deployment; see the matching
+    # rationale in _apply_feature_flag_overrides / get_backup_setting_origin.
+    if is_running_in_addon():
+        return
+    overrides = _read_backup_override_file()
+    if not overrides:
+        return
+    for field_name, env_name, ftype in BACKUP_OVERRIDE_FIELDS:
+        _apply_one_backup_override(settings, field_name, env_name, ftype, overrides)