fix(plugins): retain state history by age, with the count as a ceiling (#502)

* fix(plugins): retain state history by age, with the count as a ceiling

Follow-up to the cap in this PR. A flat entry count answers the wrong
question: what a reader wants from this history is "the last couple of
hours", and how many transitions that is depends entirely on the plugin's
update interval. On a real board those span 2s to 3600s, so 200 entries is

    interval   200 entries covers
        2s          3.3 minutes     (flights, live)
       10s         16.7 minutes     (jellyfin)
       60s          1.7 hours       (default)
      300s          8.3 hours       (news)
     3600s          4.2 days

-- the plugin churning hardest, the one worth looking at, keeps the least.

So transitions are now trimmed by AGE first
(STATE_HISTORY_MAX_AGE_SECONDS, two hours), which makes the retained window
comparable whatever the cadence, and the count cap becomes purely a memory
ceiling for pollers fast enough to exceed it inside that window. The
ceiling rises 200 -> 2000: at ~230 bytes an entry that is ~0.5MB per plugin
worst case, and only plugins updating faster than roughly every 4s can
reach it. Steady-state memory is unchanged for everything slower, since the
age trim binds first.

Two details worth stating:

  - The trim reads time.monotonic(), stored alongside each transition,
    rather than the datetime already inside it. A DST shift or an NTP step
    would otherwise make every entry look ancient and flush the history in
    one go. The human-readable timestamp is untouched and still what
    get_state_history() returns.

  - Trimming happens on append, so a plugin that goes quiet keeps its last
    window until it writes again. That is deliberate: it is bounded either
    way, and a lazy trim costs nothing on the hot scheduling path. The
    guarantee is therefore about the SPAN of retained history, not its age
    against the current clock, and the test asserts it that way.

The public shape is unchanged: get_state_history() still returns the same
list of transition dicts, and state_history_count is still the lifetime
total.

test_plugin_state_history_retention.py adds 7 tests. Verified against this
branch with only the age trim removed: 4 fail, 3 pass -- the three that
survive are testing the count ceiling and the monotonic clock, which this
commit does not change. Full suite 3753 passed, 60 skipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STMbQE4YctTacQXfbYqKuW

* fix(plugins): build get_state_info() as one locked snapshot

Every field was read under its own lock, so an unload running concurrently
could be observed half-done: 'state' read before clear_state() removed it
and 'state_history_count' read after, handing PluginManager.get_plugin_info()
a plugin that is ENABLED with zero transitions.

The whole payload is now built in one critical section. _lock is an RLock,
so the helpers called inside it can still take it.

The regression test runs a reader against a thread that repeatedly fills and
clears the same plugin, and fails on the first torn snapshot. Verified by
removing only the lock: fails on 3 of 3 runs, passes on 3 of 3 with it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STMbQE4YctTacQXfbYqKuW

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/plugin_system/plugin_state.py

@@ -6,22 +6,38 @@ with state transitions and queries.
 """
 
 import threading
+import time
 from collections import deque
 from enum import Enum
-from typing import Optional, Dict, Any, Deque, List
+from typing import Optional, Dict, Any, Deque, List, Tuple
 from datetime import datetime
 import logging
 
 from src.logging_config import get_logger
 
 
-# Transitions retained per plugin. The history is diagnostic only -- nothing
-# reads the entries themselves, just their count -- but it is appended to on the
-# hot scheduling path: every update cycle records RUNNING on reserve and ENABLED
-# on finish. Unbounded, that is 2,880 entries per plugin per day at the default
-# 60s interval, which on a 1 GB Pi exhausts memory in weeks. Keep the recent
-# tail for debugging and let the rest age out.
-MAX_STATE_HISTORY_PER_PLUGIN = 200
+# The history is diagnostic only -- nothing reads the entries themselves, just
+# their count -- but it is appended to on the hot scheduling path: every update
+# cycle records RUNNING on reserve and ENABLED on finish. Unbounded, that is
+# 2,880 entries per plugin per day at the default 60s interval, which on a 1 GB
+# Pi exhausts memory in weeks.
+#
+# Two limits, because a single entry count answers the wrong question. What a
+# reader wants is "the last couple of hours", and how many transitions that is
+# depends entirely on the plugin's update interval -- which on a real board
+# spans 2s to 3600s. A flat 200 entries is 4.2 days for the slowest plugin and
+# 3.3 minutes for the fastest, so the plugin churning hardest, the one worth
+# looking at, keeps the least history.
+#
+# So: trim by AGE first, which makes the retained window comparable across
+# plugins whatever their cadence...
+STATE_HISTORY_MAX_AGE_SECONDS = 2 * 60 * 60
+
+# ...and cap by COUNT second, purely as a memory ceiling for the fast pollers
+# whose age window would otherwise run to thousands of entries. At ~230 bytes
+# an entry this is ~0.5 MB per plugin worst case, and only plugins updating
+# faster than roughly every 4s can reach it.
+MAX_STATE_HISTORY_PER_PLUGIN = 2000
 
 
 class PluginState(Enum):
@@ -47,7 +63,10 @@ class PluginStateManager:
         self.logger = logger or get_logger(__name__)
         self._lock = threading.RLock()
         self._states: Dict[str, PluginState] = {}
-        self._state_history: Dict[str, Deque[Dict[str, Any]]] = {}
+        # (monotonic timestamp, transition). The clock is monotonic so a DST
+        # shift or an NTP step cannot make entries look old and flush the
+        # history; the human-readable timestamp lives inside the transition.
+        self._state_history: Dict[str, Deque[Tuple[float, Dict[str, Any]]]] = {}
         # Lifetime transition totals, kept separately so the count reported by
         # get_state_info() stays truthful once the history above starts rolling.
         self._state_transition_counts: Dict[str, int] = {}
@@ -70,7 +89,13 @@ class PluginStateManager:
         if history is None:
             history = deque(maxlen=MAX_STATE_HISTORY_PER_PLUGIN)
             self._state_history[plugin_id] = history
-        history.append(transition)
+        now = time.monotonic()
+        history.append((now, transition))
+        # Age out first; the deque's maxlen is the backstop for plugins that
+        # produce more than the ceiling within the window.
+        cutoff = now - STATE_HISTORY_MAX_AGE_SECONDS
+        while history and history[0][0] < cutoff:
+            history.popleft()
         self._state_transition_counts[plugin_id] = (
             self._state_transition_counts.get(plugin_id, 0) + 1
         )
@@ -160,8 +185,10 @@ class PluginStateManager:
         """
         Get state transition history for a plugin.
 
-        Only the most recent MAX_STATE_HISTORY_PER_PLUGIN transitions are
-        retained; older ones age out.
+        Retention is by age first -- transitions older than
+        STATE_HISTORY_MAX_AGE_SECONDS are dropped -- and by count second, at
+        MAX_STATE_HISTORY_PER_PLUGIN, which only binds for plugins updating
+        fast enough to exceed it inside that window.
 
         Args:
             plugin_id: Plugin identifier
@@ -175,7 +202,7 @@ class PluginStateManager:
         with self._lock:
             return [
                 dict(transition)
-                for transition in self._state_history.get(plugin_id, ())
+                for _stamp, transition in self._state_history.get(plugin_id, ())
             ]
     
     def set_error_info(self, plugin_id: str, error_info: Dict[str, Any]) -> None:
@@ -279,19 +306,26 @@ class PluginStateManager:
         Returns:
             Dictionary with state information
         """
-        state = self.get_state(plugin_id)
-        info = {
-            'state': state.value,
-            'is_loaded': self.is_loaded(plugin_id),
-            'is_enabled': self.is_enabled(plugin_id),
-            'is_running': self.is_running(plugin_id),
-            'is_error': self.is_error(plugin_id),
-            'can_execute': self.can_execute(plugin_id),
-            'last_update': self.get_last_update(plugin_id),
-            'last_display': self.get_last_display(plugin_id),
-            'error_info': self.get_error_info(plugin_id),
-            'state_history_count': self._state_transition_counts.get(plugin_id, 0)
-        }
+        # One snapshot, one critical section. Each field was read under its own
+        # lock, so an unload running concurrently could be observed half-done:
+        # 'state' read before clear_state() removed it and
+        # 'state_history_count' read after, giving a caller a plugin that is
+        # ENABLED with zero transitions. _lock is an RLock, so the helpers
+        # below can still take it.
+        with self._lock:
+            state = self.get_state(plugin_id)
+            info = {
+                'state': state.value,
+                'is_loaded': self.is_loaded(plugin_id),
+                'is_enabled': self.is_enabled(plugin_id),
+                'is_running': self.is_running(plugin_id),
+                'is_error': self.is_error(plugin_id),
+                'can_execute': self.can_execute(plugin_id),
+                'last_update': self.get_last_update(plugin_id),
+                'last_display': self.get_last_display(plugin_id),
+                'error_info': self.get_error_info(plugin_id),
+                'state_history_count': self._state_transition_counts.get(plugin_id, 0)
+            }
         return info
     
     def clear_state(self, plugin_id: str) -> None: