Restore runtime state on startup (#23326)

* add class

* restore runtime state in dispatcher

* restore on startup with special case for profile

* add tests

* update docs

* mypy

docs/docs/configuration/live.md

@@ -262,7 +262,7 @@ cameras:
 Each camera has three possible states, surfaced as a status selector in **Settings → Global configuration → Camera management**:
 
 - **On** — streams are processed normally. Object detection, recording, and Live view are active.
-- **Off** — Frigate's ffmpeg processes are paused. Recording stops, object detection is paused, and the Live dashboard displays a blank image with a "Camera is off" message. The camera is still visible in the Live dashboard and its past review items, tracked objects, and historical footage remain accessible via the UI. This state does **not** persist across Frigate restarts; the camera returns to On after a restart.
+- **Off** — Frigate's ffmpeg processes are paused. Recording stops, object detection is paused, and the Live dashboard displays a blank image with a "Camera is off" message. The camera is still visible in the Live dashboard and its past review items, tracked objects, and historical footage remain accessible via the UI. The Off state persists across Frigate restarts via a `.runtime_state.json` file alongside `config.yml` (see [Runtime toggle persistence](#runtime-toggle-persistence)).
 - **Disabled** — the change is saved to your configuration file (`enabled: False`). The camera stops immediately, Frigate stops ffmpeg processes, and all live and historical UI elements for the camera are no longer visible but remains retained on disk. The camera is still listed in **Settings → Global configuration → Camera management** so it can be re-enabled. **A restart of Frigate is required to bring a disabled camera back to On.**
 
 #### Turning a camera on or off
@@ -290,6 +290,15 @@ For both Off and Disabled cameras, go2rtc remains active but does not use system
 
 If you want a camera's historical data (review items, tracked objects, footage) to stay accessible in the UI while you stop processing, set the camera to **Off**. If you want the camera fully removed from the Live dashboard, review filters, and other UI surfaces, set it to **Disabled**. The Disabled state still keeps the camera in Camera management so it can be re-enabled later; if you want to remove all traces of a camera including its configuration, delete it via Camera management instead.
 
+#### Runtime toggle persistence
+
+The Live view toggles for **camera on/off**, **detect**, **recordings**, **snapshots**, and **audio detection** — along with the equivalent MQTT `/set` topics — write the new state to `.runtime_state.json` next to your `config.yml`. The file is replayed on Frigate startup so your last-known toggle states survive a restart. Two interactions worth knowing:
+
+- **Settings UI saves win.** When you save a field through **Settings → Global configuration**, the matching entry is cleared from `.runtime_state.json` so the new value in your config file is the durable source.
+- **Switching profiles clears all runtime overrides.** Activating or deactivating a [profile](/configuration/profiles) is treated as a deliberate state change, so the file is wiped to avoid stale overrides replaying on top of the new profile.
+
+If you hand-edit `config.yml` while runtime overrides exist, the overrides will still replay on restart. Delete `.runtime_state.json` to reset to the YAML-defined defaults.
+
 ### Live player error messages
 
 When your browser runs into problems playing back your camera streams, it will log short error messages to the browser console. They indicate playback, codec, or network issues on the client/browser side, not something server side with Frigate itself. Below are the common messages you may see and simple actions you can take to try to resolve them.

docs/docs/configuration/profiles.md

@@ -130,6 +130,8 @@ Profiles can be activated and deactivated via the Frigate UI, [MQTT](/integratio
 
 In the Frigate UI, open the Settings cog and select **Profiles** from the submenu to see all defined profiles. From there you can activate any profile or deactivate the current one. The active profile is indicated in the UI so you always know which profile is in effect.
 
+Activating or deactivating a profile clears any [runtime toggle overrides](/configuration/live#runtime-toggle-persistence) so the profile's settings aren't silently undone by a stale toggle from before the switch.
+
 ## Example: Home / Away Setup
 
 A common use case is having different detection and notification settings based on whether you are home or away. This example below is for a system with two cameras, `front_door` and `indoor_cam`.

docs/docs/integrations/mqtt.md

@@ -368,7 +368,7 @@ The published value is the detected state class name (e.g., `open`, `closed`, `o
 
 ### `frigate/<camera_name>/enabled/set`
 
-Topic to turn Frigate's processing of a camera on or off at runtime. Expected values are `ON` and `OFF`. The change is **not** persisted across Frigate restarts — the camera returns to the configured state on restart. To permanently disable a camera, use **Settings → Global configuration → Camera management** in the Frigate UI. See [Camera state](/configuration/live#camera-state) for the difference between turning a camera off and disabling it.
+Topic to turn Frigate's processing of a camera on or off at runtime. Expected values are `ON` and `OFF`. The change is persisted across Frigate restarts (see [Runtime toggle persistence](/configuration/live#runtime-toggle-persistence)). To permanently change the configured value, use **Settings → Global configuration → Camera management** in the Frigate UI. See [Camera state](/configuration/live#camera-state) for the difference between turning a camera off and disabling it.
 
 ### `frigate/<camera_name>/enabled/state`
 
@@ -376,7 +376,7 @@ Topic with current runtime state of processing for a camera. Published values ar
 
 ### `frigate/<camera_name>/detect/set`
 
-Topic to turn object detection for a camera on and off. Expected values are `ON` and `OFF`.
+Topic to turn object detection for a camera on and off. Expected values are `ON` and `OFF`. The change is persisted across Frigate restarts (see [Runtime toggle persistence](/configuration/live#runtime-toggle-persistence)).
 
 ### `frigate/<camera_name>/detect/state`
 
@@ -384,7 +384,7 @@ Topic with current state of object detection for a camera. Published values are
 
 ### `frigate/<camera_name>/audio/set`
 
-Topic to turn audio detection for a camera on and off. Expected values are `ON` and `OFF`.
+Topic to turn audio detection for a camera on and off. Expected values are `ON` and `OFF`. The change is persisted across Frigate restarts (see [Runtime toggle persistence](/configuration/live#runtime-toggle-persistence)).
 
 ### `frigate/<camera_name>/audio/state`
 
@@ -392,7 +392,7 @@ Topic with current state of audio detection for a camera. Published values are `
 
 ### `frigate/<camera_name>/recordings/set`
 
-Topic to turn recordings for a camera on and off. Expected values are `ON` and `OFF`.
+Topic to turn recordings for a camera on and off. Expected values are `ON` and `OFF`. The change is persisted across Frigate restarts (see [Runtime toggle persistence](/configuration/live#runtime-toggle-persistence)).
 
 ### `frigate/<camera_name>/recordings/state`
 
@@ -400,7 +400,7 @@ Topic with current state of recordings for a camera. Published values are `ON` a
 
 ### `frigate/<camera_name>/snapshots/set`
 
-Topic to turn snapshots for a camera on and off. Expected values are `ON` and `OFF`.
+Topic to turn snapshots for a camera on and off. Expected values are `ON` and `OFF`. The change is persisted across Frigate restarts (see [Runtime toggle persistence](/configuration/live#runtime-toggle-persistence)).
 
 ### `frigate/<camera_name>/snapshots/state`
 

frigate/api/app.py

@@ -908,6 +908,11 @@ def config_set(request: Request, body: AppConfigSetBody):
                     status_code=500,
                 )
 
+            # drop runtime overrides for any fields the user just rewrote in
+            # yaml so a stale override doesn't silently win after restart
+            if request.app.dispatcher is not None:
+                request.app.dispatcher.clear_runtime_state_for_yaml_keys(updates.keys())
+
             if body.requires_restart == 0 or body.update_topic:
                 old_config: FrigateConfig = request.app.frigate_config
                 request.app.frigate_config = config

frigate/app.py

@@ -348,7 +348,11 @@ class FrigateApp:
             persisted in cam.profiles for cam in self.config.cameras.values()
         ):
             logger.info("Restoring persisted profile '%s'", persisted)
-            self.profile_manager.activate_profile(persisted)
+            # don't clear runtime overrides here, restore_runtime_state() later
+            # in startup replays it on top of the activated profile
+            self.profile_manager.activate_profile(
+                persisted, clear_runtime_overrides=False
+            )
 
     def start_detectors(self) -> None:
         for name in self.config.cameras.keys():
@@ -612,6 +616,9 @@ class FrigateApp:
         self.start_record_cleanup()
         self.start_watchdog()
 
+        # restore persisted runtime overrides on top of config
+        self.dispatcher.restore_runtime_state()
+
         self.init_auth()
 
         try:

frigate/comms/dispatcher.py

@@ -3,11 +3,13 @@
 import datetime
 import json
 import logging
+from collections.abc import Iterable
 from typing import Any, Callable, Optional, cast
 
 from frigate.camera import PTZMetrics
 from frigate.camera.activity_manager import AudioActivityManager, CameraActivityManager
 from frigate.comms.base_communicator import Communicator
+from frigate.comms.runtime_state import RuntimeStatePersistence
 from frigate.comms.webpush import WebPushClient
 from frigate.config import BirdseyeModeEnum, FrigateConfig
 from frigate.config.camera.updater import (
@@ -67,6 +69,7 @@ class Dispatcher:
         self.embeddings_reindex: dict[str, Any] = {}
         self.birdseye_layout: dict[str, Any] = {}
         self.audio_transcription_state: str = "idle"
+        self._runtime_state = RuntimeStatePersistence()
         self._camera_settings_handlers: dict[str, Callable] = {
             "audio": self._on_audio_command,
             "audio_transcription": self._on_audio_transcription_command,
@@ -397,6 +400,60 @@ class Dispatcher:
         for comm in self.comms:
             comm.stop()
 
+    def restore_runtime_state(self) -> None:
+        """Replay persisted runtime overrides through the camera settings handlers.
+
+        Called once after Frigate startup completes so processing threads can
+        receive the resulting ``config_updater`` broadcasts. Unknown cameras
+        and topics are skipped; handler exceptions are logged and replay
+        continues for remaining entries.
+        """
+        state = self._runtime_state.load()
+        for camera_name, features in state.items():
+            if camera_name not in self.config.cameras:
+                continue
+            for topic, value in features.items():
+                handler = self._camera_settings_handlers.get(topic)
+                if handler is None:
+                    continue
+                payload = "ON" if value else "OFF"
+                try:
+                    handler(camera_name, payload)
+                except Exception:
+                    logger.exception(
+                        "Failed to restore runtime state %s.%s=%s",
+                        camera_name,
+                        topic,
+                        payload,
+                    )
+                    continue
+                logger.info(
+                    "Restored runtime state: %s.%s=%s",
+                    camera_name,
+                    topic,
+                    payload,
+                )
+
+    def clear_runtime_state_for_yaml_keys(self, dotted_keys: Iterable[str]) -> None:
+        """Clear stored runtime overrides for YAML keys that were just rewritten.
+
+        Called by ``/api/config/set`` after a successful YAML save so an
+        explicit settings-UI save isn't silently overridden by an older
+        runtime toggle on the next restart.
+        """
+        self._runtime_state.clear_for_yaml_keys(dotted_keys)
+
+    def clear_runtime_state(self) -> None:
+        """Wipe every stored runtime override.
+
+        Called when a profile is activated or deactivated. A profile switch
+        changes the layer below the runtime overrides, so the stored
+        "steady state" is no longer valid and must be reset; otherwise a
+        subsequent restart would replay stale overrides on top of the new
+        profile-derived in-memory state.
+        """
+        self._runtime_state.clear_all()
+
     def _on_detect_command(self, camera_name: str, payload: str) -> None:
         """Callback for detect topic."""
         detect_settings = self.config.cameras[camera_name].detect
@@ -428,6 +485,7 @@ class Dispatcher:
             CameraConfigUpdateTopic(CameraConfigUpdateEnum.detect, camera_name),
             detect_settings,
         )
+        self._runtime_state.set(camera_name, "detect", detect_settings.enabled)
         self.publish(f"{camera_name}/detect/state", payload, retain=True)
 
     def _on_enabled_command(self, camera_name: str, payload: str) -> None:
@@ -452,6 +510,7 @@ class Dispatcher:
             CameraConfigUpdateTopic(CameraConfigUpdateEnum.enabled, camera_name),
             camera_settings.enabled,
         )
+        self._runtime_state.set(camera_name, "enabled", camera_settings.enabled)
         self.publish(f"{camera_name}/enabled/state", payload, retain=True)
 
     def _on_motion_command(self, camera_name: str, payload: str) -> None:
@@ -614,6 +673,7 @@ class Dispatcher:
             CameraConfigUpdateTopic(CameraConfigUpdateEnum.audio, camera_name),
             audio_settings,
         )
+        self._runtime_state.set(camera_name, "audio", audio_settings.enabled)
         self.publish(f"{camera_name}/audio/state", payload, retain=True)
 
     def _on_audio_transcription_command(self, camera_name: str, payload: str) -> None:
@@ -670,6 +730,7 @@ class Dispatcher:
             CameraConfigUpdateTopic(CameraConfigUpdateEnum.record, camera_name),
             record_settings,
         )
+        self._runtime_state.set(camera_name, "recordings", record_settings.enabled)
         self.publish(f"{camera_name}/recordings/state", payload, retain=True)
 
     def _on_snapshots_command(self, camera_name: str, payload: str) -> None:
@@ -689,6 +750,7 @@ class Dispatcher:
             CameraConfigUpdateTopic(CameraConfigUpdateEnum.snapshots, camera_name),
             snapshots_settings,
         )
+        self._runtime_state.set(camera_name, "snapshots", snapshots_settings.enabled)
         self.publish(f"{camera_name}/snapshots/state", payload, retain=True)
 
     def _on_ptz_command(self, camera_name: str, payload: str | bytes) -> None:

frigate/comms/runtime_state.py

@@ -0,0 +1,163 @@
+"""Persistence layer for dispatcher runtime state overrides."""
+
+import json
+import logging
+import os
+from collections.abc import Iterable
+from typing import Any
+
+from filelock import FileLock, Timeout
+
+from frigate.util.config import find_config_file
+
+logger = logging.getLogger(__name__)
+
+
+class RuntimeStatePersistence:
+    """Persist last-known runtime states for dispatcher toggles.
+
+    Stores boolean overrides applied to camera-level toggles by the dispatcher.
+    Overrides are replayed at startup on top of the YAML-derived in-memory
+    config, so changes made via MQTT or the live-view UI survive a restart.
+    """
+
+    # Maps dispatcher topic name -> YAML key suffix under cameras.<cam>
+    TRACKED_TOPICS: dict[str, str] = {
+        "enabled": "enabled",
+        "detect": "detect.enabled",
+        "snapshots": "snapshots.enabled",
+        "recordings": "record.enabled",
+        "audio": "audio.enabled",
+    }
+
+    _SUFFIX_TO_TOPIC: dict[str, str] = {v: k for k, v in TRACKED_TOPICS.items()}
+
+    def __init__(self) -> None:
+        self._path = os.path.join(
+            os.path.dirname(find_config_file()), ".runtime_state.json"
+        )
+        self._lock_path = f"{self._path}.lock"
+        self._lock_timeout = 5
+
+    def load(self) -> dict[str, dict[str, bool]]:
+        """Return {camera: {topic: bool}} or {} if missing/corrupt."""
+        try:
+            with FileLock(self._lock_path, timeout=self._lock_timeout):
+                data = self._read_locked()
+        except Timeout:
+            logger.error("Timed out acquiring runtime state lock for load")
+            return {}
+        cameras = data.get("cameras", {})
+        if not isinstance(cameras, dict):
+            return {}
+        # Filter out malformed camera entries so callers can trust the shape.
+        return {
+            name: features
+            for name, features in cameras.items()
+            if isinstance(features, dict)
+        }
+
+    def set(self, camera: str, topic: str, value: bool) -> None:
+        """Persist a single (camera, topic, value). No-op if topic untracked."""
+        if topic not in self.TRACKED_TOPICS:
+            return
+        try:
+            with FileLock(self._lock_path, timeout=self._lock_timeout):
+                data = self._read_locked()
+                cameras = data.setdefault("cameras", {})
+                if not isinstance(cameras, dict):
+                    cameras = {}
+                    data["cameras"] = cameras
+                cam = cameras.setdefault(camera, {})
+                if not isinstance(cam, dict):
+                    cam = {}
+                    cameras[camera] = cam
+                cam[topic] = bool(value)
+                self._write_locked(data)
+        except Timeout:
+            logger.error("Timed out persisting runtime state for %s/%s", camera, topic)
+        except OSError:
+            logger.exception("Failed to persist runtime state for %s/%s", camera, topic)
+
+    def clear_all(self) -> None:
+        """Wipe every stored runtime override.
+
+        Called when the "layer below" changes in a way that invalidates all
+        runtime overrides for the current session (currently: profile
+        activation or deactivation).
+        """
+        try:
+            with FileLock(self._lock_path, timeout=self._lock_timeout):
+                if not os.path.exists(self._path):
+                    return
+                self._write_locked({"cameras": {}})
+        except Timeout:
+            logger.error("Timed out clearing runtime state")
+        except OSError:
+            logger.exception("Failed to clear runtime state")
+
+    def clear_for_yaml_keys(self, dotted_keys: Iterable[str]) -> None:
+        """Remove stored entries whose YAML key was just rewritten.
+
+        Each dotted key must be of the form ``cameras.<camera>.<suffix>``.
+        Keys that don't match a tracked topic are ignored.
+        """
+        to_remove: list[tuple[str, str]] = []
+        for key in dotted_keys:
+            parts = key.split(".")
+            if len(parts) < 3 or parts[0] != "cameras":
+                continue
+            camera = parts[1]
+            suffix = ".".join(parts[2:])
+            topic = self._SUFFIX_TO_TOPIC.get(suffix)
+            if topic is not None:
+                to_remove.append((camera, topic))
+
+        if not to_remove:
+            return
+
+        try:
+            with FileLock(self._lock_path, timeout=self._lock_timeout):
+                data = self._read_locked()
+                cameras = data.get("cameras")
+                if not isinstance(cameras, dict):
+                    return
+                changed = False
+                for camera, topic in to_remove:
+                    cam = cameras.get(camera)
+                    if isinstance(cam, dict) and topic in cam:
+                        del cam[topic]
+                        changed = True
+                        if not cam:
+                            del cameras[camera]
+                if changed:
+                    self._write_locked(data)
+        except Timeout:
+            logger.error("Timed out clearing runtime state for YAML keys")
+        except OSError:
+            logger.exception("Failed to clear runtime state for YAML keys")
+
+    def _read_locked(self) -> dict[str, Any]:
+        """Read the JSON file while the FileLock is held.
+
+        Returns ``{}`` on a missing or corrupt file so the caller can write a
+        fresh structure on the next mutation.
+        """
+        if not os.path.exists(self._path):
+            return {}
+        try:
+            with open(self._path, "r") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            logger.exception(
+                "Failed to read runtime state file %s; starting fresh", self._path
+            )
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _write_locked(self, data: dict[str, Any]) -> None:
+        """Atomically write the JSON file while the FileLock is held."""
+        tmp_path = f"{self._path}.tmp"
+        with open(tmp_path, "w") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+        os.replace(tmp_path, self._path)

frigate/config/profile_manager.py

@@ -124,11 +124,24 @@ class ProfileManager:
                 self.config.active_profile = None
                 self._persist_active_profile(None)
 
-    def activate_profile(self, profile_name: Optional[str]) -> Optional[str]:
+            # drop all runtime overrides so they don't replay stale values on restart
+            if self.dispatcher is not None:
+                self.dispatcher.clear_runtime_state()
+
+    def activate_profile(
+        self,
+        profile_name: Optional[str],
+        clear_runtime_overrides: bool = True,
+    ) -> Optional[str]:
         """Activate a profile by name, or deactivate if None.
 
         Args:
             profile_name: Profile name to activate, or None to deactivate.
+            clear_runtime_overrides: When True (the default, for user-initiated
+                activations) drop the dispatcher's runtime override file because
+                the layer below changed. Startup callers that are replaying a
+                persisted profile pass False so the runtime state stays
+                available for the subsequent replay step.
 
         Returns:
             None on success, or an error message string on failure.
@@ -156,6 +169,11 @@ class ProfileManager:
 
         self.config.active_profile = profile_name
         self._persist_active_profile(profile_name)
+
+        # a profile switch invalidates the steady-state runtime overrides
+        if clear_runtime_overrides and self.dispatcher is not None:
+            self.dispatcher.clear_runtime_state()
+
         logger.info(
             "Profile %s",
             f"'{profile_name}' activated" if profile_name else "deactivated",

frigate/test/test_dispatcher_runtime_state.py

@@ -0,0 +1,217 @@
+"""Tests for Dispatcher runtime state persistence wiring."""
+
+import os
+import tempfile
+import unittest
+from unittest.mock import MagicMock, patch
+
+from frigate.comms.dispatcher import Dispatcher
+from frigate.comms.runtime_state import RuntimeStatePersistence
+
+
+def _make_camera_mock(
+    *,
+    enabled: bool = True,
+    enabled_in_config: bool = True,
+    detect_enabled: bool = True,
+    record_enabled: bool = True,
+    record_enabled_in_config: bool = True,
+    snapshots_enabled: bool = True,
+    audio_enabled: bool = True,
+    audio_enabled_in_config: bool = True,
+) -> MagicMock:
+    """Build a camera config mock with the fields the in-scope handlers read."""
+    camera = MagicMock()
+    camera.enabled = enabled
+    camera.enabled_in_config = enabled_in_config
+    camera.detect.enabled = detect_enabled
+    camera.motion.enabled = True  # avoid the detect→motion side-effect path
+    camera.record.enabled = record_enabled
+    camera.record.enabled_in_config = record_enabled_in_config
+    camera.snapshots.enabled = snapshots_enabled
+    camera.audio.enabled = audio_enabled
+    camera.audio.enabled_in_config = audio_enabled_in_config
+    return camera
+
+
+def _build_dispatcher(cameras: dict[str, MagicMock]) -> Dispatcher:
+    """Construct a Dispatcher with the bare-minimum mocks the tests need."""
+    config = MagicMock()
+    config.cameras = cameras
+    config_updater = MagicMock()
+    onvif = MagicMock()
+    ptz_metrics: dict = {}
+    communicators: list = []
+
+    with (
+        patch("frigate.comms.dispatcher.CameraActivityManager"),
+        patch("frigate.comms.dispatcher.AudioActivityManager"),
+    ):
+        return Dispatcher(config, config_updater, onvif, ptz_metrics, communicators)
+
+
+class TestRestoreRuntimeState(unittest.TestCase):
+    """Verify replay routes through handlers and tolerates missing entries."""
+
+    def setUp(self) -> None:
+        self.dispatcher = _build_dispatcher(
+            {
+                "front_door": _make_camera_mock(),
+                "back_yard": _make_camera_mock(),
+            }
+        )
+        # Swap each in-scope handler for a MagicMock so we can assert calls
+        # without exercising the handler's own logic.
+        self.handler_mocks: dict[str, MagicMock] = {}
+        for topic in ("enabled", "detect", "snapshots", "recordings", "audio"):
+            mock = MagicMock()
+            self.dispatcher._camera_settings_handlers[topic] = mock
+            self.handler_mocks[topic] = mock
+
+    def test_replays_each_stored_entry_through_its_handler(self) -> None:
+        self.dispatcher._runtime_state = MagicMock(
+            spec=RuntimeStatePersistence,
+            load=MagicMock(
+                return_value={
+                    "front_door": {"detect": False, "recordings": False},
+                    "back_yard": {"audio": False},
+                }
+            ),
+        )
+        self.dispatcher.restore_runtime_state()
+
+        self.handler_mocks["detect"].assert_called_once_with("front_door", "OFF")
+        self.handler_mocks["recordings"].assert_called_once_with("front_door", "OFF")
+        self.handler_mocks["audio"].assert_called_once_with("back_yard", "OFF")
+        self.handler_mocks["enabled"].assert_not_called()
+        self.handler_mocks["snapshots"].assert_not_called()
+
+    def test_skips_unknown_cameras(self) -> None:
+        self.dispatcher._runtime_state = MagicMock(
+            spec=RuntimeStatePersistence,
+            load=MagicMock(return_value={"removed_cam": {"detect": False}}),
+        )
+        self.dispatcher.restore_runtime_state()
+        for mock in self.handler_mocks.values():
+            mock.assert_not_called()
+
+    def test_skips_unknown_topics(self) -> None:
+        self.dispatcher._runtime_state = MagicMock(
+            spec=RuntimeStatePersistence,
+            load=MagicMock(return_value={"front_door": {"some_old_topic": True}}),
+        )
+        self.dispatcher.restore_runtime_state()
+        for mock in self.handler_mocks.values():
+            mock.assert_not_called()
+
+    def test_continues_after_handler_exception(self) -> None:
+        self.handler_mocks["detect"].side_effect = RuntimeError("boom")
+        self.dispatcher._runtime_state = MagicMock(
+            spec=RuntimeStatePersistence,
+            load=MagicMock(
+                return_value={
+                    "front_door": {"detect": False, "recordings": False},
+                }
+            ),
+        )
+        # Must not raise; the recordings handler must still run.
+        self.dispatcher.restore_runtime_state()
+        self.handler_mocks["recordings"].assert_called_once_with("front_door", "OFF")
+
+    def test_true_value_routes_as_on_payload(self) -> None:
+        self.dispatcher._runtime_state = MagicMock(
+            spec=RuntimeStatePersistence,
+            load=MagicMock(return_value={"front_door": {"detect": True}}),
+        )
+        self.dispatcher.restore_runtime_state()
+        self.handler_mocks["detect"].assert_called_once_with("front_door", "ON")
+
+
+class TestHandlersPersistViaSet(unittest.TestCase):
+    """Verify each in-scope handler writes to the runtime state on success."""
+
+    def setUp(self) -> None:
+        self.tmp_dir = tempfile.mkdtemp()
+        self.config_path = os.path.join(self.tmp_dir, "config.yml")
+        with open(self.config_path, "w") as f:
+            f.write("")
+        self._patcher = patch(
+            "frigate.comms.runtime_state.find_config_file",
+            return_value=self.config_path,
+        )
+        self._patcher.start()
+
+        # Start with everything OFF so each ON payload triggers a real change
+        self.cameras = {
+            "front_door": _make_camera_mock(
+                enabled=False,
+                detect_enabled=False,
+                record_enabled=False,
+                snapshots_enabled=False,
+                audio_enabled=False,
+            )
+        }
+        self.dispatcher = _build_dispatcher(self.cameras)
+
+    def tearDown(self) -> None:
+        self._patcher.stop()
+        for name in os.listdir(self.tmp_dir):
+            os.remove(os.path.join(self.tmp_dir, name))
+        os.rmdir(self.tmp_dir)
+
+    def _stored_state(self) -> dict:
+        return RuntimeStatePersistence().load()
+
+    def test_enabled_handler_persists(self) -> None:
+        self.dispatcher._on_enabled_command("front_door", "ON")
+        self.assertEqual(self._stored_state(), {"front_door": {"enabled": True}})
+
+    def test_detect_handler_persists(self) -> None:
+        self.dispatcher._on_detect_command("front_door", "ON")
+        self.assertEqual(self._stored_state(), {"front_door": {"detect": True}})
+
+    def test_recordings_handler_persists(self) -> None:
+        self.dispatcher._on_recordings_command("front_door", "ON")
+        self.assertEqual(self._stored_state(), {"front_door": {"recordings": True}})
+
+    def test_snapshots_handler_persists(self) -> None:
+        self.dispatcher._on_snapshots_command("front_door", "ON")
+        self.assertEqual(self._stored_state(), {"front_door": {"snapshots": True}})
+
+    def test_audio_handler_persists(self) -> None:
+        self.dispatcher._on_audio_command("front_door", "ON")
+        self.assertEqual(self._stored_state(), {"front_door": {"audio": True}})
+
+    def test_enabled_in_config_gate_blocks_persistence(self) -> None:
+        """An ON payload rejected by the gate must not be persisted."""
+        cam = self.cameras["front_door"]
+        cam.enabled_in_config = False
+        cam.record.enabled_in_config = False
+        cam.audio.enabled_in_config = False
+
+        self.dispatcher._on_enabled_command("front_door", "ON")
+        self.dispatcher._on_recordings_command("front_door", "ON")
+        self.dispatcher._on_audio_command("front_door", "ON")
+
+        self.assertEqual(self._stored_state(), {})
+
+
+class TestClearPassthrough(unittest.TestCase):
+    """The dispatcher's public clear methods delegate to the store."""
+
+    def test_clear_runtime_state_for_yaml_keys_passthrough(self) -> None:
+        dispatcher = _build_dispatcher({})
+        dispatcher._runtime_state = MagicMock(spec=RuntimeStatePersistence)
+        keys = ["cameras.front_door.detect.enabled"]
+        dispatcher.clear_runtime_state_for_yaml_keys(keys)
+        dispatcher._runtime_state.clear_for_yaml_keys.assert_called_once_with(keys)
+
+    def test_clear_runtime_state_passthrough(self) -> None:
+        dispatcher = _build_dispatcher({})
+        dispatcher._runtime_state = MagicMock(spec=RuntimeStatePersistence)
+        dispatcher.clear_runtime_state()
+        dispatcher._runtime_state.clear_all.assert_called_once_with()
+
+
+if __name__ == "__main__":
+    unittest.main()

frigate/test/test_profiles.py

@@ -727,6 +727,55 @@ class TestProfileManager(unittest.TestCase):
         # Should not raise
         json.dumps(api_base)
 
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_activate_profile_clears_dispatcher_runtime_state(self, mock_persist):
+        """User-initiated activation drops runtime overrides (steady-state rule)."""
+        dispatcher = MagicMock()
+        manager = ProfileManager(self.config, self.mock_updater, dispatcher)
+        manager.activate_profile("armed")
+        dispatcher.clear_runtime_state.assert_called_once_with()
+
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_deactivate_profile_clears_dispatcher_runtime_state(self, mock_persist):
+        """Deactivating a profile also drops runtime overrides."""
+        dispatcher = MagicMock()
+        manager = ProfileManager(self.config, self.mock_updater, dispatcher)
+        manager.activate_profile("armed")
+        dispatcher.clear_runtime_state.reset_mock()
+
+        manager.activate_profile(None)
+        dispatcher.clear_runtime_state.assert_called_once_with()
+
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_startup_replay_does_not_clear_runtime_state(self, mock_persist):
+        """Startup callers pass clear_runtime_overrides=False to preserve state."""
+        dispatcher = MagicMock()
+        manager = ProfileManager(self.config, self.mock_updater, dispatcher)
+        manager.activate_profile("armed", clear_runtime_overrides=False)
+        dispatcher.clear_runtime_state.assert_not_called()
+
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_update_config_clears_when_active_profile_reapplies(self, mock_persist):
+        """After /api/config/set, an active-profile re-application drops state."""
+        dispatcher = MagicMock()
+        manager = ProfileManager(self.config, self.mock_updater, dispatcher)
+        manager.activate_profile("armed")
+        dispatcher.clear_runtime_state.reset_mock()
+
+        new_config = FrigateConfig(**self.config_data)
+        manager.update_config(new_config)
+        dispatcher.clear_runtime_state.assert_called_once_with()
+
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_update_config_does_not_clear_when_no_active_profile(self, mock_persist):
+        """Plain /api/config/set without a profile doesn't trigger the broad clear."""
+        dispatcher = MagicMock()
+        manager = ProfileManager(self.config, self.mock_updater, dispatcher)
+        # No activate_profile call — config.active_profile is None
+        new_config = FrigateConfig(**self.config_data)
+        manager.update_config(new_config)
+        dispatcher.clear_runtime_state.assert_not_called()
+
 
 class TestProfilePersistence(unittest.TestCase):
     """Test profile persistence to disk."""

frigate/test/test_runtime_state.py

@@ -0,0 +1,136 @@
+"""Tests for RuntimeStatePersistence."""
+
+import json
+import os
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from frigate.comms.runtime_state import RuntimeStatePersistence
+
+
+class TestRuntimeStatePersistence(unittest.TestCase):
+    """Unit tests for the JSON-backed runtime state store."""
+
+    def setUp(self) -> None:
+        self.tmp_dir = tempfile.mkdtemp()
+        self.config_path = os.path.join(self.tmp_dir, "config.yml")
+        # Touch a placeholder config.yml so find_config_file returns a real path
+        with open(self.config_path, "w") as f:
+            f.write("")
+        self._patcher = patch(
+            "frigate.comms.runtime_state.find_config_file",
+            return_value=self.config_path,
+        )
+        self._patcher.start()
+        self.store = RuntimeStatePersistence()
+
+    def tearDown(self) -> None:
+        self._patcher.stop()
+        for name in os.listdir(self.tmp_dir):
+            os.remove(os.path.join(self.tmp_dir, name))
+        os.rmdir(self.tmp_dir)
+
+    def test_load_returns_empty_when_file_missing(self) -> None:
+        self.assertEqual(self.store.load(), {})
+
+    def test_set_then_load_round_trip(self) -> None:
+        self.store.set("front_door", "detect", False)
+        self.store.set("front_door", "recordings", True)
+        self.store.set("back_yard", "audio", False)
+
+        result = self.store.load()
+        self.assertEqual(
+            result,
+            {
+                "front_door": {"detect": False, "recordings": True},
+                "back_yard": {"audio": False},
+            },
+        )
+
+    def test_set_with_untracked_topic_is_noop(self) -> None:
+        self.store.set("front_door", "ptz_autotracker", True)
+        self.assertEqual(self.store.load(), {})
+        # File should not even be created if no tracked entries were written
+        runtime_path = os.path.join(self.tmp_dir, ".runtime_state.json")
+        self.assertFalse(os.path.exists(runtime_path))
+
+    def test_set_overwrites_previous_value(self) -> None:
+        self.store.set("front_door", "detect", True)
+        self.store.set("front_door", "detect", False)
+        self.assertEqual(self.store.load(), {"front_door": {"detect": False}})
+
+    def test_load_returns_empty_when_file_corrupt(self) -> None:
+        runtime_path = os.path.join(self.tmp_dir, ".runtime_state.json")
+        with open(runtime_path, "w") as f:
+            f.write("{not valid json")
+        self.assertEqual(self.store.load(), {})
+
+    def test_load_handles_unexpected_top_level_shape(self) -> None:
+        runtime_path = os.path.join(self.tmp_dir, ".runtime_state.json")
+        with open(runtime_path, "w") as f:
+            json.dump(["unexpected", "list"], f)
+        self.assertEqual(self.store.load(), {})
+
+    def test_clear_for_yaml_keys_removes_matching_entries(self) -> None:
+        self.store.set("front_door", "detect", False)
+        self.store.set("front_door", "recordings", False)
+        self.store.set("back_yard", "audio", False)
+
+        self.store.clear_for_yaml_keys(
+            [
+                "cameras.front_door.detect.enabled",
+                "cameras.back_yard.audio.enabled",
+            ]
+        )
+
+        self.assertEqual(
+            self.store.load(),
+            {"front_door": {"recordings": False}},
+        )
+
+    def test_clear_for_yaml_keys_collapses_empty_camera_dict(self) -> None:
+        self.store.set("front_door", "detect", False)
+        self.store.clear_for_yaml_keys(["cameras.front_door.detect.enabled"])
+        self.assertEqual(self.store.load(), {})
+
+    def test_clear_for_yaml_keys_ignores_unrelated_keys(self) -> None:
+        self.store.set("front_door", "detect", False)
+        self.store.clear_for_yaml_keys(
+            [
+                "ui.theme",
+                "go2rtc.streams.x",
+                "cameras.front_door.ffmpeg.inputs",
+                "not_cameras.front_door.detect.enabled",
+            ]
+        )
+        self.assertEqual(self.store.load(), {"front_door": {"detect": False}})
+
+    def test_clear_for_yaml_keys_handles_empty_iterable(self) -> None:
+        self.store.set("front_door", "detect", False)
+        self.store.clear_for_yaml_keys([])
+        self.assertEqual(self.store.load(), {"front_door": {"detect": False}})
+
+    def test_camera_level_enabled_uses_top_level_yaml_key(self) -> None:
+        """`enabled` topic maps to the camera-level `cameras.<cam>.enabled` key."""
+        self.store.set("front_door", "enabled", False)
+        self.store.clear_for_yaml_keys(["cameras.front_door.enabled"])
+        self.assertEqual(self.store.load(), {})
+
+    def test_clear_all_wipes_every_entry(self) -> None:
+        self.store.set("front_door", "detect", False)
+        self.store.set("front_door", "recordings", True)
+        self.store.set("back_yard", "audio", False)
+
+        self.store.clear_all()
+
+        self.assertEqual(self.store.load(), {})
+
+    def test_clear_all_is_safe_when_file_missing(self) -> None:
+        # No prior set() calls — file does not exist
+        self.store.clear_all()
+        self.assertEqual(self.store.load(), {})
+
+
+if __name__ == "__main__":
+    unittest.main()