docs(common): list espn_payload in the common README

#749 added src/common/espn_payload.py without a summary row or section,
so test_common_readme_lists_every_module fails on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VZNWFWprcFYGfuf1JAyrBJ

CHANGELOG.md

@@ -19,6 +19,58 @@ accepts both, but the store flags the old spelling as deprecated
 
 ## Unreleased
 
+### Tooling
+
+- `test/test_sports_helpers.py`'s parity tests pass again with
+  `LEDMATRIX_PLUGINS` set. The scoreboards deleted their copies of the
+  `sports_helpers` bodies and constants when they adopted `SportsHelpersMixin`
+  (ledmatrix-plugins #563/#564), and the 19 tests still expected them. A copy
+  that is gone now counts as adopted when the plugin imports
+  `src.common.sports_helpers`, as the stage 3/4 and game-over parity tests
+  already do; a copy that remains must still match.
+
+## 3.8.2
+
+The display hands freed memory back to the OS (#774), and sports consolidation
+family 6: `src.common.sports_favorites`, which the scoreboards adopt by
+flooring on 3.8.2 (#775).
+
+### The display hands freed memory back to the OS
+
+The display process's resident memory climbed in steps for hours while the
+data it held stayed flat: glibc keeps what Python frees in per-thread malloc
+arenas and returns little of it. `src/malloc_tuning.py` (new, standard library
+only, a no-op off Linux/glibc) does two things in-process, so it reaches
+devices without re-running the installer:
+
+- **Arena cap at start-up.** `run.py` calls `mallopt(M_ARENA_MAX, 2)` before any
+  thread exists, the same cap as the unit's `Environment=MALLOC_ARENA_MAX=2`.
+  Units installed before that line never got it (systemd runs the copy in
+  `/etc/systemd/system`); a `MALLOC_ARENA_MAX` in the environment still wins.
+- **`malloc_trim(0)` between screens**, at most every 5 minutes, from the top of
+  the render loop where no frame is being drawn. Measured on a Pi 4: 2-11 ms
+  per call.
+
+On ledpi (Pi 4, 192x48, Vegas on, nine plugins, a unit without
+`MALLOC_ARENA_MAX`), alternated main / branch / branch / main arms of 2.5 h:
+two hours in, resident memory was 551 MB on main (the second main arm was
+already at 651 MB after 1 h 44 min) against 412 and 386 MB with this change,
+and the 20-minute frame soaks came out at 0.147-0.165% late against main's
+0.151-0.188%.
+
+### New modules
+
+- `src/common/sports_favorites.py` -- sports consolidation family 6, once the
+  plugins made `_is_favorite_game` (seven bodies), `_select_games_for_display`
+  (two) and `_select_recent_games_for_display` (three) one each:
+  `SportsFavoritesMixin` (`SportsCore`: `_is_favorite_game`, `_favorite_code`),
+  `SportsUpcomingFavoritesMixin` and `SportsRecentFavoritesMixin` (the
+  favourites-only picks). Each side of a game is named by the 3.5.0
+  `_favorite_key` seam and compared with `favorite_teams` stripped and
+  upper-cased; nrl overrides the key with the ESPN team id. Only a game with an
+  id can be a duplicate. A plugin may inherit the mixins once it floors on
+  3.8.2, and deletes its copies then. (#775)
+
 ## 3.8.1
 
 Smooth scrolling at the slower speeds, and the fixes and performance work
@@ -1232,6 +1284,25 @@ policies are unchanged.
   a runtime publisher that stops still goes `stale`, and a subscription that
   goes quiet still falls back to the cache. The cache path's 120 s rule is
   unchanged.
+- A plugin that pauses the Vegas scroll gets its pause when its display
+  duration is not a plain number. Several plugins (clock-simple, calendar,
+  countdown) return `display_duration` as it is in config.json, so a value
+  saved as `"20"` or `null` (the raw config editor, a hand edit) reached the
+  pause as a string or None; comparing it with the clock raised, and the
+  plugin flashed up and the scroll went straight on, at every one of its
+  turns. `inf` held the pause until something interrupted it, and 0, a
+  negative number or NaN ended it at once. The pause now reads the duration
+  as the rotation does (`finite_seconds()` in `base_plugin`): a numeric
+  string counts, anything else that is not a finite number (or a
+  `get_display_duration()` that raises) pauses for 30 s, and a number at or
+  below zero for 15 s, with one warning per plugin.
+- Reinstalling Weather, Music, Stocks or Leaderboard from the Plugin Store
+  while it is enabled asks for a display restart, as reinstalling any other
+  enabled plugin does. `POST /api/v3/plugins/install` looked for the
+  plugin's `enabled` flag under the store id (`weather`), but its config
+  section is under the id its manifest declares (`ledmatrix-weather`), so
+  `restart_required` was always false and the display kept running the
+  copy it had loaded. The check now uses the installed id.
 
 ### Scrolling
 

docs/ARCHITECTURE.md

@@ -143,7 +143,9 @@ loaded and when. Nothing else keeps plugin state:
 `DisplayController` right after it creates the `PluginManager`, writes the
 cache key `plugin_runtime_snapshot`: per plugin `loaded`, `state`, `error`
 (type, a redacted message of at most 200 characters, when, recoverable),
-`version` and `loaded_at`, plus `published_at`, `stale_after` and `running`.
+`version`, `loaded_at` and `modes` (the display modes `DisplayController`
+registered -- `plugin.modes` when the plugin computes them, else the
+manifest's), plus `published_at`, `stale_after` and `running`.
 The cache is on disk, usually the SD card, so it writes when something a
 reader sees changes -- throttled to once per 10 s -- and otherwise once a
 minute as a heartbeat. RUNNING, which every `update()` passes through, is
@@ -159,6 +161,9 @@ truth cannot leak into a response. `/api/v3/plugins/installed` returns
 `loaded`, `state`, `error_info`, `loaded_version` and `loaded_at` per
 plugin and `data.runtime` (`status`, `published_at`, `age_seconds`);
 `/api/v3/plugins/state` returns the same beside the desired state.
+`PluginCatalog.get_plugin_display_modes` and `find_plugin_for_mode` prefer a
+live view's `modes` to the manifest's `display_modes`, so `/display/modes`
+and on-demand see modes a plugin generates from its config (#668).
 
 **Reconciliation**
 ([`state_reconciliation.py`](../src/plugin_system/state_reconciliation.py))

docs/REST_API_REFERENCE.md

@@ -363,9 +363,11 @@ it. This is the list the force-display dialog offers.
 
 Send the reported `plugin_id` alongside `mode` when starting an on-demand
 display: `/display/on-demand/start` falls back to `find_plugin_for_mode` when
-`plugin_id` is omitted, and that lookup only sees modes declared in a static
-manifest — a plugin whose modes are generated (each installed Starlark app is
-one) returns 404 there.
+`plugin_id` is omitted. While the display is running, this list and that
+lookup use the modes the display registered, including ones a plugin generates
+from its config (each installed Starlark app, each soccer `custom_leagues`
+entry). With the display stopped, or for a plugin it has not loaded, both see
+only the modes its manifest declares.
 
 Triggers plugin discovery, which is otherwise lazy — so a caller that never
 opens the dashboard still gets the full list.

docs/SPORTS_UNIFICATION.md

@@ -87,11 +87,12 @@ more. Shared sports code lives in `src/common`:
 | `sports_celebration.py` | 3.7.0 | `SportsCelebrationMixin` — draws the score/win takeover; colour helpers |
 | `sports_fetch.py` | 3.7.0 | `SportsFetchMixin` — season fetch, live lookback and live-odds decisions |
 | `sports_card_wrappers.py` | 3.7.0 | `SportsCardWrappersMixin` — the game renderer's `sports_card` delegations |
-| `sports_plugin_host.py` | next release | `SportsPluginHostMixin` — the plugin class's (`manager.py`) identical helpers: Vegas weight, off-thread switch refresh |
-| `sports_live_scroll.py` | next release | `SportsLiveScrollMixin` — rebuild a live scroll strip mid-cycle, keeping the marquee's place |
-| `sports_display_rules.py` | next release | `SportsCardOptionsMixin`, `SportsGameRulesMixin` — scorebug date options, the no-favourites filter, non-favourite live dwell |
-| `sports_font_path.py` | next release | `resolve_font_path` — what the plugins' `_resolve_font_path` copies return |
+| `sports_plugin_host.py` | 3.8.0 | `SportsPluginHostMixin` — the plugin class's (`manager.py`) identical helpers: Vegas weight, off-thread switch refresh |
+| `sports_live_scroll.py` | 3.8.0 | `SportsLiveScrollMixin` — rebuild a live scroll strip mid-cycle, keeping the marquee's place |
+| `sports_display_rules.py` | 3.8.0 | `SportsCardOptionsMixin`, `SportsGameRulesMixin` — scorebug date options, the no-favourites filter, non-favourite live dwell |
+| `sports_font_path.py` | 3.8.0 | `resolve_font_path` — what the plugins' `_resolve_font_path` copies return |
 | `sports_game_over.py` | 3.8.1 | `SportsGameOverMixin` — `_is_game_really_over`, with the `FINAL_PERIOD` seam (family 5) |
+| `sports_favorites.py` | 3.8.2 | `SportsFavoritesMixin`, `SportsUpcomingFavoritesMixin`, `SportsRecentFavoritesMixin` — `_is_favorite_game` and the favourites-only picks, on the `_favorite_key` seam (family 6) |
 
 Each is described in [src/common/README.md](../src/common/README.md).
 
@@ -103,7 +104,8 @@ modules taken from the plugin copies, each a **new module** rather than growth
 on an existing one: a plugin that deletes a method copy and relies on an older
 module having gained it fails at runtime with an `AttributeError`, while a
 missing module fails at load, where the version checks can see it.
-`sports_helpers.py` holds `_favorite_key`, the override point listed below.
+`sports_helpers.py` holds `_favorite_key`, the override point listed below;
+`sports_favorites.py` is what calls it.
 Each promoted module has a parity test that compares its bodies against the
 plugin copies when `LEDMATRIX_PLUGINS` points at a checkout
 (`test_sports_helpers.py`, `test_sports_stage3_parity.py`), and
@@ -126,7 +128,7 @@ deprecation cycle.
 | `_custom_scorebug_layout(game, draw)` | Per-sport overlay on the base layout | no-op |
 | `score_phrase(points, team_abbr)` | Celebration wording (`"GOOOOAAALLL!"` vs `"TOUCHDOWN!"`). `points` is the score delta, which sports with variable-value scores use to name the play | `"<abbr> SCORES!"` — only consulted when `CelebrationMixin` is present |
 | `win_phrase(team_abbr)` | Win-celebration wording | `"<abbr> WINS!"` — mixin only |
-| `_favorite_key(game, side)` | Which view-model field identifies a team for favorites matching | `game["<side>_abbr"]` |
+| `_favorite_key(game, side)` | Which view-model field identifies a team for favorites matching. `sports_favorites` compares it, and each `favorite_teams` entry, stripped and upper-cased; a `None` matches nothing | `game["<side>_abbr"]`. nrl returns the ESPN team id, `None` when it is missing |
 | `_config_schema_path()` | Plugin's `config_schema.json` — returning it routes `_get_layout_offset` through the `src.element_style` resolver (and gives it the defaults to compare against) | `None`, i.e. the classic inline `customization.layout` read |
 | `_font_root()` | Directory to resolve `assets/fonts` against | core install root |
 
@@ -315,6 +317,35 @@ were pixel-identical. `src/common/sports_game_over.py` holds the body;
 `test/test_sports_game_over_parity.py` compares it, and each plugin's
 `FINAL_PERIOD`, with the plugin copies.
 
+### Family 6: favourite matching (core done; adoption waits for a release)
+
+ledmatrix-plugins `scripts/test_favourite_matching.py` (#634) pinned 204 rows
+across the nine plugins first: `_is_favorite_game` on each manager role, the
+two selection methods, the real `update()` with favourites-only on and off,
+and the INFO summary; the reconcile extends it to 217 (a lower-case and a
+padded favourite through `update()`, and the live favourite boost). The reconcile (ledmatrix-plugins
+#635) made `_is_favorite_game` one body on `SportsCore`
+(afl and soccer's `SportsUpcoming` copies and five `SportsLive` copies, all
+redundant, are gone), added `_favorite_code` beside it, and gave nrl a
+`_favorite_key` override instead of its own copies. So that a lower-case
+favourite works on a favourites-only Upcoming board, the Upcoming `update()`'s
+favourites-only pre-filter and the basketball, hockey and lacrosse live boost
+now ask `_is_favorite_game` too (a one-line change each; `update()` itself is
+family 13). Of 3,897 cells only those the decisions above explain changed:
+case and spaces in eight plugins (30-40 each), the id-less duplicate fix (6-8
+each), nrl's key (6) and its "None" match (6), and the INFO line in baseball,
+football and ufc. The harness renders were byte-identical. `src/common/sports_favorites.py` holds the
+bodies, one mixin per carrying class; `test/test_sports_favorites_parity.py`
+compares them with the plugin copies and checks that only nrl overrides
+`_favorite_key`.
+
+Left for later families: the live screens' favourites-only filter
+(`_classify_live_game` and its inline copies) and favourites-first sort still
+compare abbreviations exactly, and
+`SportsCoreSharedMixin._round_robin_favorites` groups favourites by raw
+abbreviation (or by `_team_in` where a plugin has one) instead of through
+`_favorite_key`. The result-colour helpers also wait (decision above).
+
 ### Why the method changes
 
 Byte-identical promotion has nearly run dry. Measured on ledmatrix-plugins
@@ -400,7 +431,7 @@ release.
 |---|---|---|---|
 | 4 | Identical sweep | `manager.py`: `_dispatch_switch_refresh`, `_favorite_team_is_live`, `get_vegas_priority_weight`, `_game_involves`, `_favorite_scan_targets`, `_favorite_scan_games`, `_get_total_games_for_manager` (all nine, 1); the live-scroll helpers `_preserving_scroll_position`, `_refresh_live_scroll_managers`, `_live_scroll_managers`, `_note_live_scroll_built`, `_live_scroll_needs_rebuild`, `_live_scroll_fields` (eight, 1). `sports.py`: `_card_option`, `_filtered_or_all`, `_effective_live_duration`, `_recent_date_text` (eight, 1). 58 identical families in all | Nothing to decide; brings `manager.py` into core as a `SportsPluginHostMixin`. `_resolve_font_path` (identical in nine `sports.py` and eight renderers) becomes `sports_font_path.resolve_font_path`, not `font_layout.resolve_asset_path`, which skips the cwd. Core side done; see [Stage 4](#stage-4-the-identical-sweep-core-done-adoption-waits-for-a-release) |
 | 5 | Game-over check | `SportsLive._is_game_really_over` (5) | Pure logic, no pixels; one seam, `FINAL_PERIOD`. The pilot for the procedure. Reconciled to one body and promoted as `sports_game_over`; adoption waits for the release that ships it. See [Family 5](#family-5-the-game-over-check-core-done-adoption-waits-for-a-release) |
-| 6 | Favourite matching | `_is_favorite_game` (7 across three classes), `_select_games_for_display` (2: nrl), `_select_recent_games_for_display` (3) | Everything that asks "is this a favourite" goes through the 3.5.0 `_favorite_key` seam |
+| 6 | Favourite matching | `_is_favorite_game` (7 across three classes), `_select_games_for_display` (2: nrl), `_select_recent_games_for_display` (3) | Everything that asks "is this a favourite" goes through the 3.5.0 `_favorite_key` seam. Reconciled to one body each and promoted as `sports_favorites`; adoption waits for the release that ships it. See [Family 6](#family-6-favourite-matching-core-done-adoption-waits-for-a-release) |
 | 7 | Other-games rotation | `_by_importance`, `_other_games_window`, `_advance_other_games_if_due` (2 each: football), `_rotate_other_games_on_display` (2: ufc) | One outlier each; football carries two fixes the other eight lack |
 | 8 | Rankings | `_fetch_team_rankings` (3), `_choose_poll` (3), `_load_division_team_ids`, `_passes_other_filters`, `_best_rank`, `_is_ranked_game` (2 each: football) | Needs 7; the rank badge and the "ranked only" filter read it |
 | 9 | Live fetch and odds | `_fetch_todays_games` (5), `_fetch_odds` (3), `_attach_odds_to_rotated_games` (3) | The prerequisite for one shared ESPN poller across plugins |
@@ -444,10 +475,17 @@ suspected behaviour that needs a payload or a rig to confirm first.
   as `0:00`). A score level at 0:00 is not over: the game stays live through
   the break before overtime, and one that really ends tied ends on its final
   status. Baseball keeps its postponed/suspended override in `BaseballLive`.
-- **6, favourite matching.** NRL keeps matching favourites by team id
-  (abbreviations collide: NEW, CAN), through `_favorite_key` rather than its
-  own copies of the selection methods. Six plugins log the recent-games
-  selection at INFO; baseball, football and ufc do not.
+- **6, favourite matching. Decided 2026-10-05, done:** each side of a game is
+  named by `_favorite_key` (the abbreviation; NRL overrides it with the ESPN
+  team id, and `None` for a missing id, which fixes a favourite typed "None"
+  matching every game without one) and compared with `favorite_teams`
+  stripped and upper-cased, so " bos" matches BOS. NRL's ambiguous "NEW"
+  still matches nothing and is logged; routing the result-colour helpers
+  (`side_is_favorite`, which tint both NEW clubs) through `_favorite_key` is
+  left for a later family. The recent-games selection logs at INFO in all
+  nine. ufc stays on the shared body, dormant: its favourites are fighters,
+  which its MMA managers match themselves (a follow-up). Fix ported: only a
+  game with an id can be a duplicate in the selection methods.
 - **7, other-games rotation.** football advances the rotation window under
   `_games_lock` (update() and display() both advance it; interleaved, a
   window of games is skipped) and fixes a favourites-only pool that recomposed

first_time_install.sh

@@ -91,7 +91,11 @@ if [ -r "$LM_OS_RELEASE_FILE" ]; then
     DESKTOP_DETECTED=0
     # grep without -q: -q exits at the first match, dpkg then dies of SIGPIPE,
     # and pipefail turns a found desktop into "not found".
-    if dpkg -l | grep -E "^ii.*raspberrypi-ui-mods|^ii.*lxde|^ii.*xfce|^ii.*gnome|^ii.*kde" >/dev/null; then
+    # Match installed package names from their start: the unanchored ".*kde"
+    # matched mid-word (libblockdev-* = "bloc-kde-v") on Lite, and `dpkg -l`
+    # lines also carry descriptions that could match.
+    if dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' 2>/dev/null \
+            | grep -E "^ii +(raspberrypi-ui-mods|lxde|xfce|gnome|kde)" >/dev/null; then
         DESKTOP_DETECTED=1
     fi
     if systemctl list-units --type=service --state=running 2>/dev/null | grep -qE "lightdm|gdm3|sddm|lxdm"; then

mypy-clean.txt

@@ -36,6 +36,7 @@ src/common/sports_card.py
 src/common/sports_card_wrappers.py
 src/common/sports_celebration.py
 src/common/sports_display_rules.py
+src/common/sports_favorites.py
 src/common/sports_fetch.py
 src/common/sports_font_path.py
 src/common/sports_game_over.py
@@ -59,6 +60,7 @@ src/ipc/contract.py
 src/ipc/server.py
 src/logging_config.py
 src/logo_downloader.py
+src/malloc_tuning.py
 src/matrix_support.py
 src/pi5_matrix_support.py
 src/plugin_system/__init__.py

run.py

@@ -14,6 +14,12 @@ project_dir = os.path.dirname(os.path.abspath(__file__))
 if project_dir not in sys.path:
     sys.path.insert(0, project_dir)
 
+# Cap glibc's malloc arenas before any thread exists (arenas already made
+# stay): the in-process twin of the unit's MALLOC_ARENA_MAX=2, for units
+# installed before that line. A no-op off glibc. See src/malloc_tuning.py.
+from src import malloc_tuning
+malloc_tuning.cap_arenas()
+
 # Under systemd the watchdog clock is already running, and start-up (plugin
 # loads, initial updates) takes far longer than the render loop's limit. Widen
 # it before anything slow is imported; the render loop narrows it again once

src/__init__.py

@@ -4,5 +4,5 @@ LEDMatrix Display System
 Core source package for the LED Matrix Display project.
 """
 
-__version__ = "3.8.1"
+__version__ = "3.8.2"
 

src/background_data_service.py

@@ -34,6 +34,7 @@ from src.common.fetch_service import (
     plugin_scope,
     share_connection_pool,
 )
+from src.common.espn_payload import is_espn_scoreboard_url, slim_scoreboard_payload
 from src.common.espn_dates import (
     RANGE_RETRY_SECONDS,
     _note_range_rejected,
@@ -83,6 +84,10 @@ class FetchRequest:
     # the cache with the callbacks suppressed -- joiners waiting forever for a
     # fetch that did, in fact, succeed.
     commit_claimed: bool = False
+    # Trim an ESPN scoreboard response before it is cached and delivered
+    # (src/common/espn_payload.py). Set by whoever created the request; a
+    # submitter that joins the fetch gets the same payload.
+    slim_payload: bool = True
     result: Optional[Any] = None
     error: Optional[str] = None
     # The plugin that submitted the request, so the fetch service counts the
@@ -249,7 +254,8 @@ class BackgroundDataService:
                            timeout: Optional[int] = None,
                            max_retries: int = 3,
                            priority: int = 1,
-                           callback: Optional[Callable] = None) -> str:
+                           callback: Optional[Callable] = None,
+                           slim_payload: bool = True) -> str:
         """
         Submit a background fetch request.
         
@@ -265,6 +271,11 @@ class BackgroundDataService:
             priority: Accepted for compatibility and ignored; requests run in
                 submission order.
             callback: Optional callback function when request completes
+            slim_payload: Drop the parts of an ESPN scoreboard response no
+                scoreboard reads (stat leaders, athlete cards, links,
+                headlines, highlights) before caching it; see
+                src/common/espn_payload.py. Only ESPN /scoreboard URLs are
+                touched. Pass False to cache the response whole.
             
         Returns:
             Request ID for tracking the fetch operation
@@ -336,6 +347,7 @@ class BackgroundDataService:
             priority=priority,
             callback=callback,
             owner=owner,
+            slim_payload=slim_payload,
         )
         
         with self._lock:
@@ -497,6 +509,13 @@ class BackgroundDataService:
                 )
                 return result
 
+            # Most of an ESPN scoreboard response is never drawn, and the
+            # cached copy stays parsed in the memory tier while it is fresh.
+            # Trimmed before the write so the cache, request.result and the
+            # callbacks all see the same payload. See src/common/espn_payload.py.
+            if request.slim_payload and is_espn_scoreboard_url(request.url):
+                slim_scoreboard_payload(data)
+
             # Cache the data
             self.cache_manager.set(request.cache_key, data)
             

src/common/README.md

@@ -28,6 +28,7 @@ Rules for the package:
 | [`api_helper`](#api_helper) | HTTP GET/POST with caching and rate limiting | Yes | — |
 | [`bdf_font`](#bdf_font) | Load and draw BDF bitmap fonts | Yes, if drawing BDF text directly | 3.5.0 |
 | [`espn_dates`](#espn_dates) | Fetch ESPN scoreboards across a date range | Yes (scoreboards) | 3.5.0 |
+| [`espn_payload`](#espn_payload) | Drop the parts of an ESPN scoreboard payload no scoreboard reads | No, core-internal (used by `BackgroundDataService`) | n/a |
 | [`favorite_team_check`](#favorite_team_check) | Log why a favourite team code shows nothing | Yes (scoreboards) | 3.6.0 |
 | [`fetch_service`](#fetch_service) | Pooled, merged, budgeted and counted HTTP for core fetch paths | No, core-internal (reached through `api_helper` and `espn_dates`) | n/a |
 | [`font_layout`](#font_layout) | Reproducible TrueType loading, crisp sizes | Yes | 3.4.0 |
@@ -44,6 +45,7 @@ Rules for the package:
 | [`sports_card_wrappers`](#sports_card_wrappers) | The game renderer's `sports_card` delegations | Yes (scoreboards) | 3.7.0 |
 | [`sports_celebration`](#sports_celebration) | Draw a scoreboard's score/win celebration | Yes (scoreboards) | 3.7.0 |
 | [`sports_display_rules`](#sports_display_rules) | Which games a scoreboard shows, for how long, and its scorebug date line | Yes (scoreboards) | 3.8.0 |
+| [`sports_favorites`](#sports_favorites) | Which games involve a favourite team, and the favourites-only picks | Yes (scoreboards) | 3.8.2 |
 | [`sports_fetch`](#sports_fetch) | Scoreboard season fetch, lookback and live-odds decisions | Yes (scoreboards) | 3.7.0 |
 | [`sports_font_path`](#sports_font_path) | Find a scoreboard's bundled font whatever the cwd | Yes (scoreboards) | 3.8.0 |
 | [`sports_game_over`](#sports_game_over) | Whether a game ESPN still lists as live has ended | Yes (scoreboards) | 3.8.1 |
@@ -119,6 +121,18 @@ Every request goes through [`fetch_service`](#fetch_service), the chunks
 counted against the plugin that asked. Scoreboard plugins also bundle a copy
 for older cores.
 
+### espn_payload
+
+[`espn_payload.py`](espn_payload.py). Core-internal. ESPN scoreboard
+responses carry stat leaders, athlete cards, links, headlines and highlights
+that no scoreboard draws. `slim_scoreboard_payload(payload)` removes exactly
+those keys, in place, and leaves everything it does not know about alone;
+`is_espn_scoreboard_url(url)` says whether a URL is an ESPN site-API
+scoreboard. `BackgroundDataService` slims each scoreboard window before
+caching it, which cuts the five sports windows from ~40MB to ~12MB of parsed
+objects. Adding a key to the drop lists means first checking that nothing
+reads it.
+
 ### favorite_team_check
 
 [`favorite_team_check.py`](favorite_team_check.py).
@@ -280,6 +294,19 @@ list it before `SportsCoreSharedMixin`) and `SportsGameRulesMixin`
 `_effective_live_duration()`, the shorter dwell for a non-favourite live
 game).
 
+### sports_favorites
+
+[`sports_favorites.py`](sports_favorites.py). Sports family 6, one mixin per
+class that carried the methods: `SportsFavoritesMixin` (`SportsCore`:
+`_is_favorite_game(game)` and `_favorite_code(value)`),
+`SportsUpcomingFavoritesMixin` (`_select_games_for_display`) and
+`SportsRecentFavoritesMixin` (`_select_recent_games_for_display`). Each side
+of a game is named by `_favorite_key` (from `SportsHelpersMixin`; NRL
+overrides it with the team id) and compared with `favorite_teams` stripped and
+upper-cased. The selection methods give each favourite up to the per-team
+limit, count a game between two favourites for both, and treat only games
+with an id as possible duplicates.
+
 ### sports_fetch
 
 [`sports_fetch.py`](sports_fetch.py). `SportsFetchMixin`: the `SportsCore`

src/common/espn_payload.py

@@ -0,0 +1,97 @@
+"""Drop the parts of an ESPN scoreboard payload no scoreboard reads.
+
+The sports scoreboards cache their Recent/Upcoming window (14 days back, 7
+ahead) as the raw ESPN response, and that record stays parsed in the memory
+cache for as long as it is fresh. Most of it is never drawn. Measured on hdpi
+(2026-10-02) the MLB window was 3.35MB of JSON and 13.5MB of Python objects,
+and the five windows together ~40MB, mostly in:
+
+* ``competitors[].leaders`` / ``competitions[].leaders`` -- per-team and
+  per-game stat leaders (28% of the MLB window)
+* ``competitors[].team.links`` / ``event.links`` -- web and app URLs
+* ``status.featuredAthletes`` and ``competitors[].probables`` -- athlete
+  cards with headshots and season stats
+* ``competitions[].headlines`` / ``highlights`` -- article and video blurbs
+  (28% of the college-football window)
+* ``competitions[].geoBroadcasts``
+
+None of those keys is read by core or by any plugin in ledmatrix-plugins
+(checked 2026-10-02 across every scoreboard, the odds ticker and the
+leaderboard), while everything that is read -- odds, records, linescores,
+situation, statistics, notes, broadcasts, venue -- is kept. Dropping them
+takes the five windows from ~40MB to ~12MB of parsed objects and the files from
+10.6MB to 3.0MB, so the reads that parse an expired window on the render
+thread get 3-4x cheaper too.
+
+:func:`slim_scoreboard_payload` changes the payload in place, and only ever
+removes the keys listed here: anything it does not know about is left alone.
+"""
+
+from typing import Any, Dict
+from urllib.parse import urlsplit
+
+# Per level of the payload, the keys removed. Kept deliberately explicit:
+# adding a key here means checking that nothing reads it first.
+_EVENT_DROP = ("links",)
+_COMPETITION_DROP = ("leaders", "headlines", "highlights", "geoBroadcasts")
+_STATUS_DROP = ("featuredAthletes",)
+_COMPETITOR_DROP = ("leaders", "probables")
+_TEAM_DROP = ("links",)
+
+
+def is_espn_scoreboard_url(url: Any) -> bool:
+    """Whether ``url`` is an ESPN site-API scoreboard endpoint."""
+    if not isinstance(url, str):
+        return False
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return False
+    host = (parts.hostname or "").lower()
+    if host != "espn.com" and not host.endswith(".espn.com"):
+        return False
+    return parts.path.rstrip("/").endswith("/scoreboard")
+
+
+def _drop(obj: Any, keys) -> None:
+    if isinstance(obj, dict):
+        for key in keys:
+            obj.pop(key, None)
+
+
+def slim_scoreboard_payload(payload: Any) -> Any:
+    """Remove the unread parts of an ESPN scoreboard payload, in place.
+
+    Returns ``payload`` for convenience. Anything that is not shaped like a
+    scoreboard (not a dict, no ``events`` list, odd entries) is passed over
+    untouched rather than raising.
+    """
+    if not isinstance(payload, dict):
+        return payload
+    events = payload.get("events")
+    if not isinstance(events, list):
+        return payload
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        _drop(event, _EVENT_DROP)
+        competitions = event.get("competitions")
+        if not isinstance(competitions, list):
+            continue
+        for competition in competitions:
+            if not isinstance(competition, dict):
+                continue
+            _drop(competition, _COMPETITION_DROP)
+            _drop(competition.get("status"), _STATUS_DROP)
+            competitors = competition.get("competitors")
+            if not isinstance(competitors, list):
+                continue
+            for competitor in competitors:
+                if not isinstance(competitor, dict):
+                    continue
+                _drop(competitor, _COMPETITOR_DROP)
+                _drop(competitor.get("team"), _TEAM_DROP)
+    return payload
+
+
+__all__ = ["is_espn_scoreboard_url", "slim_scoreboard_payload"]

src/common/sports_favorites.py

@@ -0,0 +1,263 @@
+"""Which games involve a favourite team, and which of them to show (sports family 6).
+
+The scoreboards' favourite matching, reconciled in ledmatrix-plugins
+(family 6) from seven ``_is_favorite_game`` bodies, two
+``_select_games_for_display`` and three ``_select_recent_games_for_display``
+into one each, and copied here under their existing names:
+
+- ``SportsFavoritesMixin`` (``SportsCore``): ``_is_favorite_game(game)``,
+  asked by ``SportsCoreSharedMixin._favorites_first``, the switch-mode
+  favourite boost (``SportsHelpersMixin._next_switch_index``), the
+  non-favourite live dwell (``SportsGameRulesMixin._effective_live_duration``)
+  and the plugins' live rotation; and ``_favorite_code(value)``, the
+  normalisation both sides of every comparison go through.
+- ``SportsUpcomingFavoritesMixin`` (``SportsUpcoming``):
+  ``_select_games_for_display``, the favourites-only pick of upcoming games.
+- ``SportsRecentFavoritesMixin`` (``SportsRecent``):
+  ``_select_recent_games_for_display``, the same for finished games, most
+  recent first.
+
+Each mixin carries only what its class already had, so no manager gains a
+method it did not have.
+
+THE RULE
+--------
+Each side of a game is named by ``_favorite_key(game, side)``, the override
+point ``SportsHelpersMixin`` (``src.common.sports_helpers``) has carried since
+3.5.0: the team abbreviation by default. A sport whose abbreviations are not
+unique overrides it -- NRL returns the ESPN team id (and None when the id is
+missing), because "NEW" is both Newcastle and New Zealand. That value and every
+entry of ``favorite_teams`` are compared as ``_favorite_code`` leaves them:
+stripped and upper-cased, a blank or missing value matching nothing. So
+" bos" in the config matches BOS.
+
+The selection methods give each favourite team up to the per-team limit
+(``upcoming_games_to_show`` / ``recent_games_to_show``); a game between two
+favourites counts for both. Only a game with an id can be a duplicate: two
+games without one are two games.
+
+A new module rather than more methods on ``sports_shared`` or
+``sports_helpers``, for the reason ``sports_helpers`` gives: a missing module
+fails at load, where the version checks see it; a missing method fails
+mid-update.
+
+WHAT A HOST MUST PROVIDE
+------------------------
+Derived by walking every ``self.<attr>`` the mixins read; the host-contract
+test in ``test/test_sports_favorites.py`` fails if a read is added without
+being listed here.
+
+- ``favorite_teams`` -- the resolved favourites list (``_is_favorite_game``).
+  The selection methods are handed the list instead.
+- ``_favorite_key`` -- ``SportsHelpersMixin`` supplies the default.
+- ``_favorite_code`` -- from ``SportsFavoritesMixin``, which the Upcoming and
+  Recent classes inherit through their ``SportsCore``.
+- ``logger`` -- the selection methods log each pick at DEBUG and a summary at
+  INFO.
+- ``upcoming_games_to_show`` (Upcoming) and ``recent_games_to_show`` (Recent)
+  -- the per-team limits.
+
+The methods read the game dict's ``id`` and ``start_time_utc`` (selection),
+whatever ``_favorite_key`` reads (``home_abbr`` / ``away_abbr`` by default),
+and ``home_abbr`` / ``away_abbr`` again for the DEBUG line; any may be missing.
+
+BASE ORDER
+----------
+No other mixin defines these methods, so the position in the bases does not
+change which body runs; a method on the plugin's own class still wins. The
+mixins have no ``__init__`` and no state.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Callable, Dict, List, Optional
+
+
+class SportsFavoritesMixin:
+    """``SportsCore``'s favourite check. See module docstring."""
+
+    # The host contract, declared for type checking only.
+    favorite_teams: List[str]
+    _favorite_key: Callable[[Dict, str], Optional[str]]
+
+    @staticmethod
+    def _favorite_code(value) -> Optional[str]:
+        """``value`` as favourites are compared: stripped and upper-cased.
+
+        None for a missing or blank value, which matches nothing.
+        """
+        if value is None:
+            return None
+        return str(value).strip().upper() or None
+
+    def _is_favorite_game(self, game: Dict) -> bool:
+        """Does either side of this game belong to a favourite team?
+
+        ``_favorite_key`` names each side (the abbreviation; nrl overrides it
+        with the ESPN team id), and both it and ``favorite_teams`` are compared
+        as ``_favorite_code`` normalises them, so " bos" matches BOS.
+        """
+        favorites = {self._favorite_code(team) for team in self.favorite_teams or ()}
+        favorites.discard(None)
+        return any(
+            self._favorite_code(self._favorite_key(game, side)) in favorites
+            for side in ("home", "away")
+        )
+
+
+class SportsUpcomingFavoritesMixin:
+    """``SportsUpcoming``'s favourites-only pick. See module docstring."""
+
+    # The host contract, declared for type checking only.
+    logger: logging.Logger
+    upcoming_games_to_show: int
+    _favorite_key: Callable[[Dict, str], Optional[str]]
+    _favorite_code: Callable[[object], Optional[str]]
+
+    def _select_games_for_display(
+        self, processed_games: List[Dict], favorite_teams: List[str]
+    ) -> List[Dict]:
+        """
+        Single-pass game selection with proper deduplication and counting.
+
+        When a game involves two favorite teams, it counts toward BOTH teams' limits.
+        This prevents unexpected game counts from the multi-pass algorithm.
+        Teams are matched as _is_favorite_game matches them. Only a game with
+        an id can be a duplicate: two games without one are two games.
+        """
+        sorted_games = sorted(
+            processed_games,
+            key=lambda g: g.get("start_time_utc")
+            or datetime.max.replace(tzinfo=timezone.utc),
+        )
+
+        if not favorite_teams:
+            return sorted_games
+
+        selected_games = []
+        selected_ids = set()
+        team_counts: Dict[Optional[str], int] = {
+            code: 0 for code in map(self._favorite_code, favorite_teams) if code
+        }
+
+        for game in sorted_games:
+            game_id = game.get("id")
+            if game_id is not None and game_id in selected_ids:
+                continue
+
+            home = self._favorite_code(self._favorite_key(game, "home"))
+            away = self._favorite_code(self._favorite_key(game, "away"))
+
+            home_fav = home in team_counts
+            away_fav = away in team_counts
+
+            if not home_fav and not away_fav:
+                continue
+
+            home_needs = home_fav and team_counts[home] < self.upcoming_games_to_show
+            away_needs = away_fav and team_counts[away] < self.upcoming_games_to_show
+
+            if home_needs or away_needs:
+                selected_games.append(game)
+                if game_id is not None:
+                    selected_ids.add(game_id)
+                if home_fav:
+                    team_counts[home] += 1
+                if away_fav:
+                    team_counts[away] += 1
+
+                self.logger.debug(
+                    f"Selected game {game.get('away_abbr')}@{game.get('home_abbr')}: "
+                    f"team_counts={team_counts}"
+                )
+
+            if all(c >= self.upcoming_games_to_show for c in team_counts.values()):
+                self.logger.debug("All favorite teams satisfied, stopping selection")
+                break
+
+        self.logger.info(
+            f"Selected {len(selected_games)} games for {len(favorite_teams)} "
+            f"favorite teams: {team_counts}"
+        )
+        return selected_games
+
+
+class SportsRecentFavoritesMixin:
+    """``SportsRecent``'s favourites-only pick. See module docstring."""
+
+    # The host contract, declared for type checking only.
+    logger: logging.Logger
+    recent_games_to_show: int
+    _favorite_key: Callable[[Dict, str], Optional[str]]
+    _favorite_code: Callable[[object], Optional[str]]
+
+    def _select_recent_games_for_display(
+        self, processed_games: List[Dict], favorite_teams: List[str]
+    ) -> List[Dict]:
+        """
+        Single-pass game selection for recent games with proper deduplication.
+
+        When a game involves two favorite teams, it counts toward BOTH teams' limits.
+        Games are sorted by most recent first.
+        Teams are matched as _is_favorite_game matches them. Only a game with
+        an id can be a duplicate: two games without one are two games.
+        """
+        sorted_games = sorted(
+            processed_games,
+            key=lambda g: g.get("start_time_utc")
+            or datetime.min.replace(tzinfo=timezone.utc),
+            reverse=True,
+        )
+
+        if not favorite_teams:
+            return sorted_games
+
+        selected_games = []
+        selected_ids = set()
+        team_counts: Dict[Optional[str], int] = {
+            code: 0 for code in map(self._favorite_code, favorite_teams) if code
+        }
+
+        for game in sorted_games:
+            game_id = game.get("id")
+            if game_id is not None and game_id in selected_ids:
+                continue
+
+            home = self._favorite_code(self._favorite_key(game, "home"))
+            away = self._favorite_code(self._favorite_key(game, "away"))
+
+            home_fav = home in team_counts
+            away_fav = away in team_counts
+
+            if not home_fav and not away_fav:
+                continue
+
+            home_needs = home_fav and team_counts[home] < self.recent_games_to_show
+            away_needs = away_fav and team_counts[away] < self.recent_games_to_show
+
+            if home_needs or away_needs:
+                selected_games.append(game)
+                if game_id is not None:
+                    selected_ids.add(game_id)
+                if home_fav:
+                    team_counts[home] += 1
+                if away_fav:
+                    team_counts[away] += 1
+
+                self.logger.debug(
+                    f"Selected recent game {game.get('away_abbr')}@{game.get('home_abbr')}: "
+                    f"team_counts={team_counts}"
+                )
+
+            if all(c >= self.recent_games_to_show for c in team_counts.values()):
+                self.logger.debug("All favorite teams satisfied, stopping selection")
+                break
+
+        self.logger.info(
+            f"Selected {len(selected_games)} recent games for {len(favorite_teams)} "
+            f"favorite teams: {team_counts}"
+        )
+        return selected_games
+
+
+__all__ = ["SportsFavoritesMixin", "SportsUpcomingFavoritesMixin", "SportsRecentFavoritesMixin"]

src/common/sports_helpers.py

@@ -34,8 +34,9 @@ first core release that ships it (see ``CHANGELOG.md``).
 
 ``_favorite_key`` is the one method not taken from the plugins: it is the
 override point from the since-removed ``src/base_classes`` sports core,
-carried here so later phases (shared celebrations and game selection) have a
-hardware-free home for the seam. No plugin defines it today and nothing in this module calls it.
+carried here as the hardware-free home for the seam. ``sports_favorites``
+calls it; nrl overrides it with the ESPN team id. Nothing in this module
+calls it.
 
 WHAT A HOST MUST PROVIDE
 ------------------------
@@ -47,8 +48,8 @@ listed here.
 - ``mode_config`` (dict) and ``logger`` -- ``_setting_int``. ``league`` is
   read with ``getattr`` for the warning text only.
 - ``games_list`` and ``current_game_index`` -- ``_next_switch_index``; plus
-  ``_is_favorite_game`` (called with a game), which stays per-plugin and is
-  only called when
+  ``_is_favorite_game`` (called with a game; ``sports_favorites`` has the
+  shared body), only called when
   ``favorite_rotation_boost`` is above 1. ``favorite_rotation_boost`` itself
   defaults to 1 on the mixin.
 - ``last_game_switch`` -- ``_reset_dwell_on_reentry``, read with ``getattr``
@@ -216,15 +217,12 @@ class SportsHelpersMixin:
         rather than a branch so core never has to learn the string "nrl"::
 
             def _favorite_key(self, game, side):
-                return str(game.get(f"{side}_id"))
+                team_id = game.get(f"{side}_id")
+                return None if team_id is None else str(team_id)
 
-        An override that stringifies should note that a missing id becomes the
-        literal ``"None"``, which would spuriously match a favorites list
-        containing that string. The default returns ``None`` for a missing
-        abbreviation, which never matches.
-
-        Carried from the since-removed ``src/base_classes`` sports core for
-        later phases; nothing in this module calls it yet.
+        It returns ``None`` for a missing id rather than ``str(None)``, which
+        would match a favourite typed "None". A ``None`` never matches.
+        ``sports_favorites`` compares the value stripped and upper-cased.
         """
         return game.get(f"{side}_abbr")
 

src/display_controller.py

@@ -25,7 +25,6 @@ import os
 import inspect
 import signal
 import json
-import math
 import threading
 import types
 from collections import deque
@@ -37,6 +36,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed  # pylint: disab
 import pytz
 
 from src import display_watchdog
+from src.malloc_tuning import MallocTrimmer
 from src.display_arbiter import (
     Arbiter, ArbiterInputs, ArbiterState, FramePolicy,
     ScreenPlan, Source, WifiNotice, live_pick, live_takeover, on_demand_bound, rotation_plan,
@@ -63,6 +63,7 @@ from src.ipc.contract import (
     PluginReloadResult,
 )
 from src.ipc.server import ControlServer, QueuedCommand, StateHub, start_control_server
+from src.plugin_system.base_plugin import finite_seconds
 from src.vegas_mode.render_pipeline import SYNC_SEND_INTERVAL
 
 # Get logger with consistent configuration
@@ -100,19 +101,6 @@ _MIN_INITIAL_UPDATE_TIMEOUT_SECONDS = 2.0
 DEFAULT_DYNAMIC_DURATION_CAP = 180.0
 
 
-def _finite_seconds(value: Any) -> Optional[float]:
-    """``value`` as seconds when it is a finite number or a numeric string,
-    else None. A bool is not a number here, though it is an int: True would
-    read as a one-second screen."""
-    if isinstance(value, bool):
-        return None
-    try:
-        seconds = float(value)
-    except (TypeError, ValueError, OverflowError):
-        return None
-    return seconds if math.isfinite(seconds) else None
-
-
 class _PluginReloadJob:
     """A ``plugin.reload`` whose slow half runs off the render thread.
 
@@ -1568,7 +1556,7 @@ class DisplayController:
         except Exception as err:  # pylint: disable=broad-except
             problem = f"get_display_duration() raised {type(err).__name__}: {err}"
         else:
-            seconds = _finite_seconds(value)
+            seconds = finite_seconds(value)
             if seconds is not None:
                 return seconds
             problem = f"display duration {value!r} is not a number"
@@ -4217,6 +4205,7 @@ class DisplayController:
             logger.info(f"Initial mode set to: {self.current_display_mode} (index: {self.current_mode_index}, total modes: {len(self.available_modes)})")
             self._publish_current_mode_state()
             runner = ScreenRunner(_MODULE_CLOCK, _ScreenHost(self), logger)
+            trimmer = MallocTrimmer()
 
             while True:
                 # Arms the watchdog after the first frame -- or after the
@@ -4224,6 +4213,11 @@ class DisplayController:
                 # it from then on.
                 display_watchdog.watchdog.loop_pass()
 
+                # Between screens, nothing being drawn: every few minutes hand
+                # the memory glibc is holding for freed images back to the OS
+                # (src/malloc_tuning.py). A clock read when none is due.
+                trimmer.maybe_trim()
+
                 # Apply plugin enable/disable edits saved via the web UI. The
                 # config-watcher thread only sets the flag; loading/unloading and
                 # rebuilding available_modes happens here on the render thread so
@@ -4617,6 +4611,15 @@ class DisplayController:
             display_modes = [plugin_id]
         with self._plugin_modes_lock:
             self.plugin_display_modes[plugin_id] = list(display_modes)
+        # Into the runtime snapshot the web interface reads, so its mode
+        # lists and on-demand lookups see computed modes too (#668).
+        state_manager = getattr(self.plugin_manager, 'state_manager', None)
+        record_modes = getattr(state_manager, 'record_modes', None)
+        if callable(record_modes):
+            try:
+                record_modes(plugin_id, list(display_modes))
+            except Exception as e:  # reporting must never break registration
+                logger.debug("Could not record display modes for %s: %s", plugin_id, e)
 
         # Subscribe to config changes for per-plugin hot-reload. Bind plugin_id
         # and instance as defaults so each plugin's callback targets its own

src/malloc_tuning.py

@@ -0,0 +1,123 @@
+"""Keep glibc's malloc from holding on to memory the display has freed.
+
+The display process allocates and frees PIL images and numpy buffers all day
+from a dozen threads. glibc gives each allocating thread its own malloc arena
+(up to 8 x CPU count) and returns little of what is freed inside them to the
+OS, so resident memory climbs for hours while the live data stays flat. Two
+in-process remedies, both standard library only (ctypes) and both no-ops off
+Linux/glibc:
+
+* :func:`cap_arenas` -- ``mallopt(M_ARENA_MAX, 2)``, the in-process twin of the
+  unit's ``Environment=MALLOC_ARENA_MAX=2``. Units installed before that line
+  existed never got it (systemd runs the copy in /etc/systemd/system), so the
+  process applies it itself. Call it before any other thread starts: arenas
+  already created stay. A ``MALLOC_ARENA_MAX`` set in the environment wins.
+* :class:`MallocTrimmer` -- ``malloc_trim(0)`` at most every few minutes,
+  called from the render loop between screens, where no frame is being drawn.
+  glibc 2.8+ releases free pages from the middle of every arena, not only the
+  top of the main heap.
+
+Without glibc (macOS, Windows, musl, the dev server on any of them) nothing is
+loaded and every call returns False.
+"""
+import ctypes
+import logging
+import os
+import sys
+import time
+from typing import Any, Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+#: glibc's mallopt() parameter number for the arena cap (malloc.h).
+M_ARENA_MAX = -8
+
+#: The arena cap applied when the environment does not set one; the same value
+#: as the unit's ``MALLOC_ARENA_MAX``.
+DEFAULT_ARENA_MAX = 2
+
+#: Seconds between malloc_trim() calls. A trim takes about 1-20 ms on a Pi 4,
+#: so this keeps it far from frame timing while still returning memory long
+#: before it piles up.
+TRIM_INTERVAL_SECONDS = 300.0
+
+_UNLOADED = object()
+_libc: Any = _UNLOADED
+
+
+def _load_libc() -> Optional[Any]:
+    """The process's C library if it is glibc with malloc_trim, else None."""
+    global _libc
+    if _libc is _UNLOADED:
+        _libc = None
+        if sys.platform.startswith('linux'):
+            try:
+                libc = ctypes.CDLL(None)
+                # gnu_get_libc_version is glibc-only, so musl (which has
+                # mallopt but no malloc_trim) is left alone as a whole.
+                if all(hasattr(libc, name) for name in
+                       ('gnu_get_libc_version', 'malloc_trim', 'mallopt')):
+                    libc.malloc_trim.argtypes = [ctypes.c_size_t]
+                    libc.malloc_trim.restype = ctypes.c_int
+                    libc.mallopt.argtypes = [ctypes.c_int, ctypes.c_int]
+                    libc.mallopt.restype = ctypes.c_int
+                    _libc = libc
+            except (OSError, AttributeError, TypeError):
+                logger.debug("glibc malloc controls unavailable", exc_info=True)
+    return _libc
+
+
+def cap_arenas(max_arenas: int = DEFAULT_ARENA_MAX) -> bool:
+    """Cap glibc's malloc arenas at ``max_arenas``. True when the cap was set.
+
+    Skipped when ``MALLOC_ARENA_MAX`` is in the environment: glibc has read it
+    already, and an operator who set it chose that value.
+    """
+    if os.environ.get('MALLOC_ARENA_MAX'):
+        return False
+    libc = _load_libc()
+    if libc is None:
+        return False
+    try:
+        return bool(libc.mallopt(M_ARENA_MAX, int(max_arenas)))
+    except Exception:  # pylint: disable=broad-except
+        logger.debug("mallopt(M_ARENA_MAX) failed", exc_info=True)
+        return False
+
+
+class MallocTrimmer:
+    """Calls ``malloc_trim(0)`` at most once per ``interval`` seconds.
+
+    :meth:`maybe_trim` is meant for an idle point of the render loop; it costs
+    one clock read when no trim is due. The first trim comes one interval
+    after construction, so start-up's allocations have settled.
+    """
+
+    def __init__(self, interval: float = TRIM_INTERVAL_SECONDS,
+                 clock: Callable[[], float] = time.monotonic) -> None:
+        self._interval = interval
+        self._clock = clock
+        self._libc = _load_libc()
+        self._next = clock() + interval
+
+    @property
+    def available(self) -> bool:
+        return self._libc is not None
+
+    def maybe_trim(self) -> bool:
+        """Trim if one is due. True when malloc_trim ran and released memory."""
+        if self._libc is None:
+            return False
+        now = self._clock()
+        if now < self._next:
+            return False
+        self._next = now + self._interval
+        try:
+            released = bool(self._libc.malloc_trim(0))
+        except Exception:  # pylint: disable=broad-except
+            logger.debug("malloc_trim failed; not trying again", exc_info=True)
+            self._libc = None
+            return False
+        logger.debug("malloc_trim(0) took %.1f ms, released=%s",
+                     (self._clock() - now) * 1000.0, released)
+        return released

src/plugin_system/base_plugin.py

@@ -11,6 +11,7 @@ Stability: Stable - maintains backward compatibility
 from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Dict, Any, Optional, List
+import math
 import os
 import sys
 from src.deprecation import deprecated, warn_deprecated
@@ -240,6 +241,26 @@ def resolve_vegas_participation(plugin: Any, plugin_id: Optional[str] = None) ->
     return legacy_vegas_participation(plugin)
 
 
+def finite_seconds(value: Any) -> Optional[float]:
+    """``value`` as seconds when it is a finite number or a numeric string,
+    else None. A bool is not a number here, though it is an int: True would
+    read as a one-second screen.
+
+    How the core reads a plugin's get_display_duration() -- the rotation
+    (DisplayController._get_display_duration) and the Vegas static pause --
+    which several plugins answer straight from config.json, so a value saved
+    as "20" or null arrives as a string or None. A number at or below zero is
+    returned as it is; each caller has its own rule for that.
+    """
+    if isinstance(value, bool):
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    return seconds if math.isfinite(seconds) else None
+
+
 class BasePlugin(ABC):
     """
     Base class that all plugins must inherit from.

src/plugin_system/plugin_catalog.py

@@ -15,7 +15,8 @@ reads through a catalog unchanged. It has nothing that runs a plugin: no
 ``load_plugin``, ``get_plugin`` or ``plugins``.
 
 Runtime state -- whether the display has a plugin loaded, its health, its
-errors -- is not here either. The display process publishes what it knows to
+errors -- is not here either, with one exception: given a ``runtime_source``,
+the mode lookups prefer the modes the running display registered. The display process publishes what it knows to
 the shared cache (health and resource metrics, the current mode, the error
 aggregator snapshot), and the web routes read those publications. What the
 display does not publish (which plugins it has loaded, its plugin state
@@ -26,8 +27,9 @@ See docs/ARCHITECTURE.md ("Web and display processes").
 
 import json
 import threading
+import time
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Union, cast
+from typing import Any, Callable, Dict, List, Optional, Union, cast
 
 from src.common.permission_utils import (
     ensure_directory_permissions, get_plugin_dir_mode,
@@ -39,6 +41,10 @@ from src.plugin_system.plugin_dirs import (
 
 PathLike = Union[str, Path]
 
+#: How long one read of the display's runtime view answers mode lookups. A
+#: listing asks once per plugin; the cache copy is a file read each time.
+_RUNTIME_VIEW_TTL_SECONDS = 1.0
+
 
 class PluginCatalog:
     """Manifests, schemas, config and versions of the installed plugins.
@@ -49,10 +55,17 @@ class PluginCatalog:
     """
 
     def __init__(self, plugins_dir: PathLike, config_manager: Optional[Any] = None,
-                 schema_manager: Optional[Any] = None) -> None:
+                 schema_manager: Optional[Any] = None,
+                 runtime_source: Optional[Callable[[], Any]] = None) -> None:
         self.plugins_dir: Path = Path(plugins_dir)
         self.config_manager = config_manager
         self.schema_manager = schema_manager
+        # Returns the display's PluginRuntimeView
+        # (src/plugin_system/plugin_runtime.py). Its live view carries the
+        # modes the display registered, which the mode lookups below prefer
+        # to the manifest's. None: manifests only.
+        self.runtime_source = runtime_source
+        self._runtime_view_memo: Optional[tuple] = None
         self.logger = get_logger(__name__)
 
         # Guards plugin_manifests/plugin_directories: request threads read
@@ -172,23 +185,67 @@ class PluginCatalog:
             by_manifest=False)
         return str(plugin_dir) if plugin_dir is not None else None
 
-    def get_plugin_display_modes(self, plugin_id: str) -> List[str]:
-        """The manifest's ``display_modes``, or [].
+    def _runtime_view(self) -> Any:
+        """The display's runtime view, read at most once a second; None
+        without a source or when reading it fails."""
+        if self.runtime_source is None:
+            return None
+        now = time.monotonic()
+        memo = self._runtime_view_memo
+        if memo is not None and now - memo[0] < _RUNTIME_VIEW_TTL_SECONDS:
+            return memo[1]
+        try:
+            view = self.runtime_source()
+        except Exception as exc:  # a lookup must still answer from manifests
+            self.logger.debug("Could not read the display's runtime view: %s", exc)
+            view = None
+        self._runtime_view_memo = (now, view)
+        return view
 
-        What the display actually rotates can differ: a plugin may compute
-        its modes at run time (``plugin.modes``). This is the declared list.
+    def _live_display_modes(self, plugin_id: str) -> Optional[List[str]]:
+        """The modes the running display registered for ``plugin_id``, or None."""
+        view = self._runtime_view()
+        if view is None:
+            return None
+        try:
+            modes = view.display_modes(plugin_id)
+        except Exception as exc:  # includes a source returning something else
+            self.logger.debug("Could not read display modes for %s: %s", plugin_id, exc)
+            return None
+        return list(modes) if isinstance(modes, list) and modes else None
+
+    def get_plugin_display_modes(self, plugin_id: str) -> List[str]:
+        """The modes the display registered for the plugin, else the
+        manifest's ``display_modes``, else [].
+
+        A plugin may compute its modes at run time (``plugin.modes``): each
+        league soccer-scoreboard's ``custom_leagues`` adds is a mode no
+        manifest can list ahead of time (#668). The running display
+        publishes what it registered, and that wins while the display is
+        live and has the plugin loaded. Otherwise -- display stopped, plugin
+        disabled -- the declared list is the best answer there is.
         """
+        live = self._live_display_modes(plugin_id)
+        if live is not None:
+            return live
         with self._lock:
             manifest = self.plugin_manifests.get(plugin_id)
         modes = (manifest or {}).get('display_modes', [])
         return list(modes) if isinstance(modes, list) else []
 
     def find_plugin_for_mode(self, mode: str) -> Optional[str]:
-        """The plugin whose manifest declares ``mode`` (case-insensitive)."""
+        """The plugin that registered ``mode`` on the running display, else
+        the one whose manifest declares it (case-insensitive both ways)."""
         wanted = mode.strip().lower()
         with self._lock:
             manifests = dict(self.plugin_manifests)
+        for plugin_id in manifests:
+            live = self._live_display_modes(plugin_id)
+            if live and any(m.lower() == wanted for m in live):
+                return plugin_id
         for plugin_id, manifest in manifests.items():
+            if self._live_display_modes(plugin_id):
+                continue  # the display's list is the truth for this plugin
             modes = manifest.get('display_modes')
             if isinstance(modes, list) and any(
                     isinstance(m, str) and m.lower() == wanted for m in modes):

src/plugin_system/plugin_runtime.py

@@ -56,7 +56,7 @@ import os
 import threading
 import time
 from dataclasses import dataclass, field, replace
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from src import display_watchdog
 from src.logging_config import get_logger
@@ -100,6 +100,9 @@ _ERROR_MESSAGE_CHARS = 200
 _ERROR_TYPE_CHARS = 80
 _ID_CHARS = 100
 _VERSION_CHARS = 40
+#: Bounds on a plugin's published ``modes``: a plugin computes them, so a
+#: runaway list must not bloat a file written to the SD card.
+_MAX_MODES = 200
 
 #: Reader statuses. Only LIVE carries runtime facts.
 LIVE = "live"
@@ -154,6 +157,15 @@ def summarize_error(error_info: Optional[Dict[str, Any]]) -> Optional[Dict[str,
     }
 
 
+def _published_modes(modes: Any) -> Optional[List[str]]:
+    """The registered display modes as a snapshot carries them, or None."""
+    if not isinstance(modes, list):
+        return None
+    # A name is a key the display matches exactly: drop one too long to
+    # carry whole rather than clip it into a different name.
+    return [m for m in modes if isinstance(m, str) and len(m) <= _ID_CHARS][:_MAX_MODES]
+
+
 def build_runtime_snapshot(state_manager: Any, *, started_at: float,
                            now: Optional[float] = None,
                            running: bool = True,
@@ -173,6 +185,7 @@ def build_runtime_snapshot(state_manager: Any, *, started_at: float,
                 "error": summarize_error(record.get("error_info")),
                 "version": _clip(version, _VERSION_CHARS) if version else None,
                 "loaded_at": _epoch(record.get("loaded_at")),
+                "modes": _published_modes(record.get("modes")),
             }
     return {
         "schema": SNAPSHOT_SCHEMA,
@@ -416,6 +429,21 @@ class PluginRuntimeView:
             "loaded_at": record.get("loaded_at"),
         }
 
+    def display_modes(self, plugin_id: str) -> Optional[List[str]]:
+        """The display modes the display registered for ``plugin_id``: what
+        it rotates and accepts on-demand, including modes a plugin computes
+        from its config. None unless the view is live and the plugin is
+        loaded with its modes registered -- the caller then falls back to
+        the manifest's ``display_modes``."""
+        if not self.live:
+            return None
+        record = self.plugins.get(plugin_id)
+        modes = record.get("modes") if isinstance(record, dict) else None
+        if not isinstance(modes, list):
+            return None
+        modes = [m for m in modes if isinstance(m, str)]
+        return modes or None
+
     def describe(self) -> Dict[str, Any]:
         """The view's own status, for a response to carry beside the facts."""
         return {

src/plugin_system/plugin_state.py

@@ -10,7 +10,7 @@ snapshot ``plugin_runtime.PluginRuntimePublisher`` publishes from it.
 import threading
 import time
 from enum import Enum
-from typing import Optional, Dict, Any
+from typing import Any, Dict, List, Optional
 from datetime import datetime
 import logging
 
@@ -231,6 +231,26 @@ class PluginStateManager:
             }
             self._note_change()
 
+    def record_modes(self, plugin_id: str, modes: List[str]) -> None:
+        """Record the display modes the display registered for ``plugin_id``.
+
+        Called by the DisplayController each time it registers the plugin.
+        These are the modes it actually rotates and accepts on-demand --
+        ``plugin.modes`` when the plugin computes them (a soccer league the
+        user added under ``custom_leagues``), else the manifest's list -- and
+        the web interface has no other way to learn them (#668). Kept on the
+        loaded record, so an unload or a reload's fresh record_loaded()
+        forgets them until the plugin is registered again.
+        """
+        with self._lock:
+            loaded = self._loaded.get(plugin_id)
+            if loaded is None:
+                return
+            modes = [str(m) for m in modes]
+            if loaded.get('modes') != modes:
+                loaded['modes'] = modes
+                self._note_change()
+
     def record_unloaded(self, plugin_id: str) -> None:
         """Forget the loaded record alone, keeping state and error info: for
         an unload that failed after the instance was already dropped."""
@@ -243,7 +263,8 @@ class PluginStateManager:
         section so a concurrent load or unload is seen whole or not at all.
 
         Per plugin: ``state`` (published_state()'s value), ``loaded``,
-        ``version`` and ``loaded_at`` (None unless loaded) and ``error_info``
+        ``version``, ``loaded_at`` and ``modes`` (None unless loaded; ``modes``
+        also None until the display registers it) and ``error_info``
         (a copy, or None).
         """
         with self._lock:
@@ -257,6 +278,7 @@ class PluginStateManager:
                     'loaded': loaded is not None,
                     'version': loaded['version'] if loaded else None,
                     'loaded_at': loaded['loaded_at'] if loaded else None,
+                    'modes': list(loaded['modes']) if loaded and 'modes' in loaded else None,
                     'error_info': dict(info) if info is not None else None,
                 }
             return records

src/vegas_mode/coordinator.py

@@ -18,10 +18,11 @@ import math
 import sys
 import time
 import threading
-from typing import Optional, Dict, Any, List, Callable, TYPE_CHECKING
+from typing import Optional, Dict, Any, FrozenSet, List, Callable, TYPE_CHECKING
 
 from src import display_watchdog
 from src.common import render_gate
+from src.plugin_system.base_plugin import finite_seconds
 from src.vegas_mode.config import VegasModeConfig
 from src.vegas_mode.elements import LiveEpochs
 from src.vegas_mode.plugin_adapter import PluginAdapter
@@ -53,6 +54,14 @@ _FPS_HEARTBEAT_INTERVAL = 300.0
 #: every plugin. Game state doesn't change within a quarter second.
 _LIVE_PRIORITY_CHECK_INTERVAL = 0.25
 
+#: Seconds a static pause shows a plugin whose display duration can't be
+#: used, as long as the rotation shows it: 30 when get_display_duration()
+#: raises or answers something that is not a number
+#: (DisplayController._get_display_duration), 15 when it answers a number at
+#: or below zero (DisplayController._resolve_durations).
+_UNREADABLE_DURATION = 30.0
+_NOT_POSITIVE_DURATION = 15.0
+
 
 def _percentile(ordered: List[float], fraction: float) -> float:
     """Nearest-rank percentile of an already-sorted list.
@@ -92,6 +101,9 @@ class VegasModeCoordinator:
     _live_reason: Optional[str] = None
     # Set only while Vegas has changed the GIL switch interval; read with getattr.
     _saved_switch_interval: Optional[float]
+    #: Plugins already warned about a display duration the pause can't use,
+    #: so a bad setting logs once, not at every turn. Replaced, not mutated.
+    _duration_warned: FrozenSet[str] = frozenset()
 
     def __init__(
         self,
@@ -1010,7 +1022,7 @@ class VegasModeCoordinator:
             # Wait for the plugin's display duration. Monotonic, like the
             # iteration clock: an NTP step on an RTC-less Pi would otherwise
             # end the pause at once or stretch it by the correction.
-            duration = plugin.get_display_duration()
+            duration = self._static_pause_duration(plugin)
             start = time.monotonic()
 
             while time.monotonic() - start < duration:
@@ -1046,6 +1058,42 @@ class VegasModeCoordinator:
 
         return True
 
+    def _static_pause_duration(self, plugin: 'BasePlugin') -> float:
+        """Seconds a static pause shows ``plugin``: its display duration,
+        read the way the rotation reads it.
+
+        Several plugins return their display_duration setting straight from
+        config.json, so one saved as "20" or null came back as a string or
+        None; comparing it with the clock raised, and the pause's broad
+        except ended the pause at every one of the plugin's turns. inf
+        paused until something interrupted it, and NaN, False, 0 or a
+        negative number ended the pause at once. A numeric string counts
+        (finite_seconds); anything else, or a raise, gets
+        _UNREADABLE_DURATION, and a number at or below zero
+        _NOT_POSITIVE_DURATION, logged once per plugin.
+        """
+        try:
+            value = plugin.get_display_duration()
+        except Exception as err:  # pylint: disable=broad-except
+            problem = f"get_display_duration() raised {type(err).__name__}: {err}"
+            fallback = _UNREADABLE_DURATION
+        else:
+            seconds = finite_seconds(value)
+            if seconds is not None and seconds > 0:
+                return seconds
+            if seconds is None:
+                problem = f"display duration {value!r} is not a number"
+                fallback = _UNREADABLE_DURATION
+            else:
+                problem = f"display duration {value!r} is not above zero"
+                fallback = _NOT_POSITIVE_DURATION
+        plugin_id = plugin.plugin_id
+        if plugin_id not in self._duration_warned:
+            self._duration_warned = self._duration_warned | {plugin_id}
+            logger.warning("[%s] %s; its static pause lasts %.0fs (logged once)",
+                           plugin_id, problem, fallback)
+        return fallback
+
     def _end_static_pause(self) -> None:
         """End static pause and restore scroll state."""
         should_resume_scrolling = False

test/test_api_v3_display_modes.py

@@ -7,7 +7,7 @@ manifest.json off disk and reimplemented PluginManager's own fallbacks.
 """
 
 import json
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
 import pytest
 
@@ -155,3 +155,14 @@ class TestOneBadConfigSectionDoesNotBlankTheList:
             side_effect=RuntimeError("GET https://x/y?api_key=SEC123 failed"))
         body = api_v3_client.get('/api/v3/display/modes').get_json()
         assert 'SEC123' not in json.dumps(body)
+
+
+class TestOnDemandUsesTheRegisteredSpelling:
+    def test_a_mode_differing_in_case_is_sent_as_registered(self, client):
+        with patch('web_interface.blueprints.api_v3.display._deliver_on_demand',
+                   return_value=('socket', None)) as deliver:
+            response = client.post('/api/v3/display/on-demand/start',
+                                   json={'plugin_id': 'football-scoreboard',
+                                         'mode': 'NFL_LIVE', 'start_service': False})
+        assert response.status_code == 200, response.get_json()
+        assert deliver.call_args.args[0]['mode'] == 'nfl_live'

test/test_api_v3_install_restart_installed_id.py

@@ -0,0 +1,123 @@
+"""POST /plugins/install asks for a restart by the id the plugin installed as.
+
+A store install needs a display restart when config.json already enables the
+plugin (a reinstall, or a config carried over): the display loads a plugin
+when its ``enabled`` flag changes, and this flag did not. The route read the
+flag under the registry id it was given. An aliased entry installs under
+another id -- ``weather`` installs a directory whose manifest declares
+``ledmatrix-weather``, and its config section is ``ledmatrix-weather`` -- so
+reinstalling an enabled Weather never reported that a restart was needed,
+and the display kept running the old copy.
+"""
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401
+
+INSTALL = "/api/v3/plugins/install"
+
+
+@pytest.fixture
+def store(api_v3_module, tmp_path):
+    """The store installs registry entry ``weather`` as ``installed_id``."""
+    manager = api_v3_module.api_v3.plugin_store_manager
+    manager.install_plugin.return_value = True
+    manager.get_registry_info.return_value = None
+    manager._find_plugin_path.return_value = None
+
+    def installs_as(installed_id):
+        path = tmp_path / installed_id
+        path.mkdir()
+        (path / "manifest.json").write_text(json.dumps({"id": installed_id}),
+                                            encoding="utf-8")
+        manager._find_plugin_path.side_effect = (
+            lambda pid: path if pid == "weather" else None)
+
+    manager.installs_as = installs_as
+    return manager
+
+
+@pytest.fixture
+def config(api_v3_module):
+    """config.json with an ``enabled`` flag for each plugin id given."""
+    def sections(enabled):
+        api_v3_module.api_v3.config_manager.load_config.return_value = {
+            plugin_id: {"enabled": flag} for plugin_id, flag in enabled.items()}
+    return sections
+
+
+@pytest.fixture
+def queued(api_v3_module):
+    queue = MagicMock()
+
+    def enqueue(operation_type, plugin_id, operation_callback=None):
+        queue.callback_result = operation_callback(MagicMock())
+        return "op-1"
+
+    queue.enqueue_operation.side_effect = enqueue
+    api_v3_module.api_v3.operation_queue = queue
+    return queue
+
+
+def _direct(client):
+    return client.post(INSTALL, json={"plugin_id": "weather"}).get_json()
+
+
+def _queued(client, queue):
+    client.post(INSTALL, json={"plugin_id": "weather"})
+    return queue.callback_result
+
+
+class TestDirectInstall:
+    def test_an_aliased_install_enabled_under_its_installed_id_asks_for_a_restart(
+            self, api_v3_client, store, config):
+        store.installs_as("ledmatrix-weather")
+        config({"ledmatrix-weather": True})
+        body = _direct(api_v3_client)
+        assert body["status"] == "success"
+        assert body["restart_required"] is True
+        assert body["restart_message"]
+
+    def test_an_enabled_section_under_the_registry_id_alone_does_not(
+            self, api_v3_client, store, config):
+        """The display knows the plugin as ledmatrix-weather; nothing runs
+        under a section called weather."""
+        store.installs_as("ledmatrix-weather")
+        config({"weather": True})
+        assert _direct(api_v3_client)["restart_required"] is False
+
+    def test_an_aliased_install_that_is_not_enabled_needs_no_restart(
+            self, api_v3_client, store, config):
+        store.installs_as("ledmatrix-weather")
+        config({"ledmatrix-weather": False})
+        assert _direct(api_v3_client)["restart_required"] is False
+
+    def test_an_install_under_its_own_id_is_unchanged(self, api_v3_client, store, config):
+        store.installs_as("weather")
+        config({"weather": True})
+        assert _direct(api_v3_client)["restart_required"] is True
+
+    def test_an_install_that_cannot_be_found_uses_the_requested_id(
+            self, api_v3_client, store, config):
+        config({"weather": True})
+        assert _direct(api_v3_client)["restart_required"] is True
+
+
+class TestQueuedInstall:
+    def test_an_aliased_install_enabled_under_its_installed_id_asks_for_a_restart(
+            self, api_v3_client, store, config, queued):
+        store.installs_as("ledmatrix-weather")
+        config({"ledmatrix-weather": True})
+        result = _queued(api_v3_client, queued)
+        assert result["success"] is True
+        assert result["restart_required"] is True
+        assert result["restart_message"]
+
+    def test_an_enabled_section_under_the_registry_id_alone_does_not(
+            self, api_v3_client, store, config, queued):
+        store.installs_as("ledmatrix-weather")
+        config({"weather": True})
+        assert _queued(api_v3_client, queued)["restart_required"] is False

test/test_espn_payload.py

@@ -0,0 +1,162 @@
+"""Tests for src/common/espn_payload.py and its use by BackgroundDataService."""
+
+import copy
+import time
+from unittest.mock import MagicMock, Mock, patch
+
+import pytest
+
+from src.background_data_service import BackgroundDataService, shutdown_background_service
+from src.common.espn_payload import is_espn_scoreboard_url, slim_scoreboard_payload
+
+SCOREBOARD = "https://site.api.espn.com/apis/site/v2/sports/baseball/mlb/scoreboard"
+
+
+def _event():
+    """One event carrying every key the slimming drops and a sample of the
+    keys scoreboards read, at the depth ESPN puts them."""
+    competitor = {
+        "id": "10",
+        "homeAway": "home",
+        "score": "5",
+        "team": {"abbreviation": "NYY", "logo": "https://a/l.png",
+                 "links": [{"href": "https://espn.com/team"}]},
+        "records": [{"summary": "90-60"}],
+        "linescores": [{"value": 1}],
+        "statistics": [{"name": "hits", "displayValue": "9"}],
+        "leaders": [{"name": "avg", "leaders": [{"athlete": {"id": "1"}}]}],
+        "probables": [{"athlete": {"id": "2"}, "statistics": []}],
+    }
+    return {
+        "id": "401",
+        "date": "2026-10-01T23:05Z",
+        "links": [{"href": "https://espn.com/game"}],
+        "status": {"type": {"state": "post"}},
+        "competitions": [{
+            "status": {"type": {"state": "post", "shortDetail": "Final"},
+                       "featuredAthletes": [{"athlete": {"id": "3"}}]},
+            "competitors": [competitor, dict(copy.deepcopy(competitor), homeAway="away")],
+            "odds": [{"details": "NYY -150", "overUnder": 8.5}],
+            "situation": {"outs": 2},
+            "notes": [{"headline": "Game 1"}],
+            "broadcasts": [{"names": ["FOX"]}],
+            "venue": {"fullName": "Yankee Stadium"},
+            "leaders": [{"name": "hits"}],
+            "headlines": [{"description": "recap"}],
+            "highlights": [{"links": {"source": {}}}],
+            "geoBroadcasts": [{"media": {"shortName": "FOX"}}],
+        }],
+    }
+
+
+class TestSlimScoreboardPayload:
+    def test_drops_exactly_the_listed_keys(self):
+        payload = {"leagues": [{"id": "10"}], "events": [_event()]}
+        slim_scoreboard_payload(payload)
+        event = payload["events"][0]
+        competition = event["competitions"][0]
+        assert "links" not in event
+        for key in ("leaders", "headlines", "highlights", "geoBroadcasts"):
+            assert key not in competition
+        assert "featuredAthletes" not in competition["status"]
+        for competitor in competition["competitors"]:
+            assert "leaders" not in competitor
+            assert "probables" not in competitor
+            assert "links" not in competitor["team"]
+
+    def test_keeps_everything_else_unchanged(self):
+        """Removing the dropped keys from the original by hand gives exactly
+        the slimmed payload: nothing else moved, changed or went missing."""
+        original = {"leagues": [{"id": "10"}], "events": [_event(), _event()]}
+        expected = copy.deepcopy(original)
+        for event in expected["events"]:
+            del event["links"]
+            competition = event["competitions"][0]
+            for key in ("leaders", "headlines", "highlights", "geoBroadcasts"):
+                del competition[key]
+            del competition["status"]["featuredAthletes"]
+            for competitor in competition["competitors"]:
+                del competitor["leaders"], competitor["probables"]
+                del competitor["team"]["links"]
+        assert slim_scoreboard_payload(original) == expected
+
+    def test_in_place_and_returns_payload(self):
+        payload = {"events": [_event()]}
+        assert slim_scoreboard_payload(payload) is payload
+
+    @pytest.mark.parametrize("payload", [
+        None, [], "x", {}, {"events": None}, {"events": "x"},
+        {"events": [None, 1, "x", {"competitions": None}]},
+        {"events": [{"competitions": [None, {"status": None, "competitors": None}]}]},
+        {"events": [{"competitions": [{"competitors": [None, {"team": None}]}]}]},
+    ])
+    def test_odd_shapes_pass_through(self, payload):
+        before = copy.deepcopy(payload)
+        assert slim_scoreboard_payload(payload) == before
+
+
+class TestIsEspnScoreboardUrl:
+    @pytest.mark.parametrize("url", [
+        SCOREBOARD,
+        SCOREBOARD + "/",
+        "http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard",
+    ])
+    def test_scoreboards(self, url):
+        assert is_espn_scoreboard_url(url)
+
+    @pytest.mark.parametrize("url", [
+        None, "", 12,
+        "https://site.api.espn.com/apis/site/v2/sports/baseball/mlb/teams",
+        "https://site.api.espn.com/apis/site/v2/sports/football/nfl/summary",
+        "https://example.com/scoreboard",
+        "https://espn.com.evil.example/apis/x/scoreboard",
+        "https://notespn.com/apis/x/scoreboard",
+    ])
+    def test_not_scoreboards(self, url):
+        assert not is_espn_scoreboard_url(url)
+
+
+@pytest.fixture
+def service():
+    shutdown_background_service()
+    cache = MagicMock()
+    cache.get.return_value = None
+    svc = BackgroundDataService(cache, max_workers=1, request_timeout=5)
+    yield svc
+    svc.shutdown(wait=False)
+    shutdown_background_service()
+
+
+def _run(service, url, **kwargs):
+    response = Mock(status_code=200)
+    response.json.return_value = {"events": [_event()]}
+    response.raise_for_status.return_value = None
+    delivered = []
+    with patch.object(service.session, "get", return_value=response):
+        req_id = service.submit_fetch_request(
+            sport="mlb", year=2026, url=url, cache_key="mlb_schedule_window_14_7",
+            callback=lambda result: delivered.append(result.data), **kwargs)
+        deadline = time.time() + 5
+        while not service.is_request_complete(req_id) and time.time() < deadline:
+            time.sleep(0.02)
+    cached = service.cache_manager.set.call_args[0][1]
+    return cached, delivered
+
+
+class TestBackgroundServiceSlims:
+    def test_espn_scoreboard_is_cached_and_delivered_slimmed(self, service):
+        cached, delivered = _run(service, SCOREBOARD)
+        competition = cached["events"][0]["competitions"][0]
+        assert "leaders" not in competition
+        assert "probables" not in competition["competitors"][0]
+        assert competition["odds"] and competition["situation"]
+        # The callback sees the very payload that was cached.
+        assert delivered and delivered[0] is cached
+
+    def test_opt_out_caches_whole_response(self, service):
+        cached, _ = _run(service, SCOREBOARD, slim_payload=False)
+        assert cached == {"events": [_event()]}
+
+    def test_other_urls_untouched(self, service):
+        cached, _ = _run(service, "https://example.com/feed")
+        assert cached == {"events": [_event()]}

test/test_live_display_modes.py

@@ -0,0 +1,265 @@
+"""The web interface sees the display modes the display actually registered (#668).
+
+A plugin may compute its modes from its config: soccer-scoreboard registers
+``soccer_<league>_live/recent/upcoming`` for every league the user adds under
+``custom_leagues``, and no manifest can list those ahead of time. The display
+always rotated them -- DisplayController._register_loaded_plugin prefers
+``plugin.modes`` -- but the web process reads plugins as files, so its mode
+listing (/display/modes, the on-demand dialog) and find_plugin_for_mode
+(/display/on-demand/start with a mode and no plugin_id) saw only manifests.
+
+The display now records each plugin's registered modes in its plugin state,
+the runtime snapshot carries them, and PluginCatalog prefers them while the
+snapshot is live, falling back to the manifest when it is not.
+"""
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from src.cache_manager import CacheManager  # noqa: E402
+from src.plugin_system import plugin_runtime as rt  # noqa: E402
+from src.plugin_system.plugin_catalog import PluginCatalog  # noqa: E402
+from src.plugin_system.plugin_runtime import (  # noqa: E402
+    PluginRuntimePublisher, build_runtime_snapshot, read_plugin_runtime,
+    view_from_snapshot,
+)
+from src.plugin_system.plugin_state import PluginState, PluginStateManager  # noqa: E402
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+DECLARED = ["soccer_eng.1_live", "soccer_eng.1_recent", "soccer_eng.1_upcoming"]
+CUSTOM = ["soccer_sco.1_live", "soccer_sco.1_recent", "soccer_sco.1_upcoming"]
+REGISTERED = DECLARED + CUSTOM
+
+
+def _loaded_states(modes=None):
+    states = PluginStateManager()
+    states.set_state("soccer-scoreboard", PluginState.ENABLED)
+    states.record_loaded("soccer-scoreboard", "2.24.1")
+    if modes is not None:
+        states.record_modes("soccer-scoreboard", modes)
+    return states
+
+
+@pytest.fixture
+def shared_cache(tmp_path, monkeypatch):
+    """Two cache managers over one directory: the display's and the web's."""
+    monkeypatch.setattr(CacheManager, "_get_writable_cache_dir",
+                        lambda self: str(tmp_path / "cache"))
+    (tmp_path / "cache").mkdir()
+    display_cache, web_cache = CacheManager(), CacheManager()
+    yield display_cache, web_cache
+    display_cache.stop_cleanup_thread()
+    web_cache.stop_cleanup_thread()
+
+
+@pytest.fixture
+def plugins_dir(tmp_path):
+    root = tmp_path / "plugins"
+    for plugin_id, modes in (("soccer-scoreboard", DECLARED), ("clock-simple", ["clock"])):
+        (root / plugin_id).mkdir(parents=True)
+        (root / plugin_id / "manifest.json").write_text(json.dumps({
+            "id": plugin_id, "name": plugin_id, "version": "1.0.0",
+            "class_name": "P", "display_modes": modes}), encoding="utf-8")
+    return root
+
+
+# --- The display records what it registered ---------------------------------
+
+class TestStateManagerRecordsModes:
+    def test_runtime_records_carry_them(self):
+        assert _loaded_states(REGISTERED).runtime_records()[
+            "soccer-scoreboard"]["modes"] == REGISTERED
+
+    def test_none_until_registered(self):
+        assert _loaded_states().runtime_records()["soccer-scoreboard"]["modes"] is None
+
+    def test_a_new_list_is_a_change_the_same_one_is_not(self):
+        """change_count drives the publisher: re-registering an unchanged
+        plugin must not cost an SD-card write."""
+        states = _loaded_states(DECLARED)
+        before = states.change_count
+        states.record_modes("soccer-scoreboard", list(DECLARED))
+        assert states.change_count == before
+        states.record_modes("soccer-scoreboard", REGISTERED)
+        assert states.change_count == before + 1
+
+    def test_ignored_for_a_plugin_that_is_not_loaded(self):
+        states = PluginStateManager()
+        states.record_modes("ghost", ["ghost"])
+        assert "ghost" not in states.runtime_records()
+
+    def test_unload_forgets_them(self):
+        states = _loaded_states(REGISTERED)
+        states.clear_state("soccer-scoreboard")
+        assert "soccer-scoreboard" not in states.runtime_records()
+
+    def test_a_reload_starts_without_them_until_registered_again(self):
+        states = _loaded_states(REGISTERED)
+        states.record_loaded("soccer-scoreboard", "2.25.0")
+        assert states.runtime_records()["soccer-scoreboard"]["modes"] is None
+
+
+class TestControllerRecordsOnRegistration:
+    def test_plugin_modes_reach_the_state_manager(self, test_display_controller):
+        """_register_loaded_plugin is the one path every load, enable and
+        reload goes through."""
+        c = test_display_controller
+        states = _loaded_states()
+        plugin = MagicMock()
+        plugin.modes = list(REGISTERED)
+        c.plugin_manager.state_manager = states
+        c.plugin_manager.get_plugin = MagicMock(return_value=plugin)
+        c.plugin_manager.plugin_manifests = {"soccer-scoreboard": {"display_modes": DECLARED}}
+
+        c._register_loaded_plugin("soccer-scoreboard")
+
+        assert states.runtime_records()["soccer-scoreboard"]["modes"] == REGISTERED
+
+    def test_a_failing_state_manager_does_not_break_registration(self, test_display_controller):
+        c = test_display_controller
+        plugin = MagicMock()
+        plugin.modes = ["clock"]
+        c.plugin_manager.state_manager.record_modes = MagicMock(side_effect=RuntimeError("x"))
+        c.plugin_manager.get_plugin = MagicMock(return_value=plugin)
+        c.plugin_manager.plugin_manifests = {}
+
+        assert c._register_loaded_plugin("clock-simple") == ["clock"]
+        assert c.mode_to_plugin_id["clock"] == "clock-simple"
+
+
+# --- The snapshot carries them; only a live view reports them ---------------
+
+class TestSnapshotAndView:
+    NOW = 1_800_000_000.0
+
+    def _view(self, states, running=True, published_at=None):
+        snapshot = build_runtime_snapshot(states, started_at=1.0, now=self.NOW,
+                                          running=running)
+        if published_at is not None:
+            snapshot["published_at"] = published_at
+        return view_from_snapshot(snapshot, now=self.NOW)
+
+    def test_live_view_reports_the_registered_modes(self):
+        assert self._view(_loaded_states(REGISTERED)).display_modes(
+            "soccer-scoreboard") == REGISTERED
+
+    def test_stale_and_stopped_views_report_nothing(self):
+        states = _loaded_states(REGISTERED)
+        assert self._view(states, published_at=self.NOW - 10_000).display_modes(
+            "soccer-scoreboard") is None
+        assert self._view(states, running=False).display_modes("soccer-scoreboard") is None
+
+    def test_unregistered_or_unknown_plugins_report_nothing(self):
+        view = self._view(_loaded_states())
+        assert view.display_modes("soccer-scoreboard") is None
+        assert view.display_modes("not-loaded") is None
+
+    def test_a_runaway_list_is_bounded(self):
+        modes = [f"m{i}" for i in range(1000)] + ["x" * 500]
+        snapshot = build_runtime_snapshot(_loaded_states(modes), started_at=1.0, now=self.NOW)
+        published = snapshot["plugins"]["soccer-scoreboard"]["modes"]
+        assert len(published) == rt._MAX_MODES
+
+    def test_a_mode_name_is_kept_whole_or_dropped(self):
+        long_mode = "x" * (rt._ID_CHARS + 1)
+        snapshot = build_runtime_snapshot(_loaded_states(["ok", long_mode]),
+                                          started_at=1.0, now=self.NOW)
+        assert snapshot["plugins"]["soccer-scoreboard"]["modes"] == ["ok"]
+
+    def test_non_strings_from_a_hand_made_snapshot_are_dropped(self):
+        snapshot = {"schema": rt.SNAPSHOT_SCHEMA, "running": True,
+                    "published_at": self.NOW, "plugins": {
+                        "p": {"loaded": True, "modes": ["a", 3, None]}}}
+        assert view_from_snapshot(snapshot, now=self.NOW).display_modes("p") == ["a"]
+
+
+# --- The web's catalog prefers them -------------------------------------------
+
+class TestCatalog:
+    def _catalog(self, plugins_dir, web_cache):
+        catalog = PluginCatalog(plugins_dir,
+                                runtime_source=lambda: read_plugin_runtime(web_cache))
+        catalog.discover_plugins()
+        return catalog
+
+    def test_live_display_modes_win_over_the_manifest(self, plugins_dir, shared_cache):
+        display_cache, web_cache = shared_cache
+        PluginRuntimePublisher(display_cache, _loaded_states(REGISTERED)).tick()
+        catalog = self._catalog(plugins_dir, web_cache)
+        assert catalog.get_plugin_display_modes("soccer-scoreboard") == REGISTERED
+
+    def test_a_custom_league_mode_resolves_to_its_plugin(self, plugins_dir, shared_cache):
+        """What /display/on-demand/start does with a mode and no plugin_id."""
+        display_cache, web_cache = shared_cache
+        PluginRuntimePublisher(display_cache, _loaded_states(REGISTERED)).tick()
+        catalog = self._catalog(plugins_dir, web_cache)
+        assert catalog.find_plugin_for_mode("SOCCER_SCO.1_LIVE") == "soccer-scoreboard"
+
+    def test_a_plugin_the_display_has_not_loaded_falls_back_to_its_manifest(
+            self, plugins_dir, shared_cache):
+        display_cache, web_cache = shared_cache
+        PluginRuntimePublisher(display_cache, _loaded_states(REGISTERED)).tick()
+        catalog = self._catalog(plugins_dir, web_cache)
+        assert catalog.get_plugin_display_modes("clock-simple") == ["clock"]
+        assert catalog.find_plugin_for_mode("clock") == "clock-simple"
+
+    def test_a_mode_the_display_dropped_does_not_resolve_by_manifest(
+            self, plugins_dir, shared_cache):
+        display_cache, web_cache = shared_cache
+        PluginRuntimePublisher(display_cache, _loaded_states(CUSTOM)).tick()
+        catalog = self._catalog(plugins_dir, web_cache)
+        assert catalog.find_plugin_for_mode("soccer_eng.1_live") is None
+
+    def test_a_stopped_display_falls_back_to_manifests(self, plugins_dir, shared_cache):
+        display_cache, web_cache = shared_cache
+        publisher = PluginRuntimePublisher(display_cache, _loaded_states(REGISTERED))
+        publisher.tick()
+        publisher.stop()
+        catalog = self._catalog(plugins_dir, web_cache)
+        assert catalog.get_plugin_display_modes("soccer-scoreboard") == DECLARED
+        assert catalog.find_plugin_for_mode("soccer_sco.1_live") is None
+
+    def test_no_runtime_source_is_manifests_only(self, plugins_dir):
+        catalog = PluginCatalog(plugins_dir)
+        catalog.discover_plugins()
+        assert catalog.get_plugin_display_modes("soccer-scoreboard") == DECLARED
+
+    def test_a_failing_runtime_source_is_manifests_only(self, plugins_dir):
+        def broken():
+            raise OSError("cache gone")
+        catalog = PluginCatalog(plugins_dir, runtime_source=broken)
+        catalog.discover_plugins()
+        assert catalog.get_plugin_display_modes("soccer-scoreboard") == DECLARED
+
+    def test_one_listing_reads_the_view_once(self, plugins_dir):
+        source = MagicMock(return_value=None)
+        catalog = PluginCatalog(plugins_dir, runtime_source=source)
+        catalog.discover_plugins()
+        for _ in range(10):
+            catalog.get_plugin_display_modes("soccer-scoreboard")
+            catalog.find_plugin_for_mode("clock")
+        assert source.call_count == 1
+
+
+class TestDisplayModesRoute:
+    def test_lists_the_custom_league_modes(self, api_v3_module, api_v3_client,  # noqa: F811
+                                           plugins_dir, shared_cache):
+        display_cache, web_cache = shared_cache
+        PluginRuntimePublisher(display_cache, _loaded_states(REGISTERED)).tick()
+        api = api_v3_module.api_v3
+        api.plugin_catalog = PluginCatalog(
+            plugins_dir, runtime_source=lambda: read_plugin_runtime(web_cache))
+        api.config_manager.load_config = MagicMock(return_value={
+            "soccer-scoreboard": {"enabled": True}})
+
+        response = api_v3_client.get("/api/v3/display/modes")
+
+        assert response.status_code == 200, response.get_data(as_text=True)
+        modes = {m["mode"]: m for m in response.get_json()["data"]["modes"]}
+        assert set(modes) == set(REGISTERED)
+        assert modes["soccer_sco.1_live"]["plugin_id"] == "soccer-scoreboard"

test/test_malloc_tuning.py

@@ -0,0 +1,206 @@
+"""src/malloc_tuning.py: glibc arena cap and periodic malloc_trim, ctypes mocked."""
+import ctypes
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from src import malloc_tuning as mt
+
+
+class FakeLibc:
+    """Stands in for ctypes.CDLL(None) on glibc: records calls."""
+
+    def __init__(self, trim_result=1, glibc=True):
+        self.trims = []
+        self.mallopts = []
+        self._trim_result = trim_result
+        if glibc:
+            self.gnu_get_libc_version = lambda: b'2.41'
+        self.malloc_trim = mock.Mock(side_effect=self._trim)
+        self.mallopt = mock.Mock(side_effect=self._mallopt)
+
+    def _trim(self, pad):
+        self.trims.append(pad)
+        if isinstance(self._trim_result, Exception):
+            raise self._trim_result
+        return self._trim_result
+
+    def _mallopt(self, param, value):
+        self.mallopts.append((param, value))
+        return 1
+
+
+@pytest.fixture(autouse=True)
+def fresh_libc(monkeypatch):
+    """Each test loads the C library itself; nothing real is called."""
+    monkeypatch.setattr(mt, '_libc', mt._UNLOADED)
+    monkeypatch.delenv('MALLOC_ARENA_MAX', raising=False)
+    yield
+
+
+def _on_glibc(monkeypatch, libc):
+    monkeypatch.setattr(mt.sys, 'platform', 'linux')
+    cdll = mock.Mock(return_value=libc)
+    monkeypatch.setattr(mt.ctypes, 'CDLL', cdll)
+    return cdll
+
+
+class Clock:
+    def __init__(self, t=1000.0):
+        self.t = t
+
+    def __call__(self):
+        return self.t
+
+
+# -- loading ----------------------------------------------------------------
+
+@pytest.mark.parametrize('platform', ['win32', 'darwin', 'freebsd14'])
+def test_not_linux_loads_nothing(monkeypatch, platform):
+    monkeypatch.setattr(mt.sys, 'platform', platform)
+    cdll = mock.Mock(side_effect=AssertionError('must not load'))
+    monkeypatch.setattr(mt.ctypes, 'CDLL', cdll)
+    assert mt._load_libc() is None
+    assert mt.cap_arenas() is False
+    trimmer = mt.MallocTrimmer(interval=0)
+    assert not trimmer.available
+    assert trimmer.maybe_trim() is False
+    cdll.assert_not_called()
+
+
+def test_linux_without_glibc_is_a_noop(monkeypatch):
+    """musl: no gnu_get_libc_version (and no malloc_trim) -- nothing is called."""
+    libc = FakeLibc(glibc=False)
+    del libc.malloc_trim
+    _on_glibc(monkeypatch, libc)
+    assert mt._load_libc() is None
+    assert mt.cap_arenas() is False
+    assert mt.MallocTrimmer(interval=0).maybe_trim() is False
+    assert libc.mallopts == []
+
+
+def test_cdll_failure_is_a_noop(monkeypatch):
+    monkeypatch.setattr(mt.sys, 'platform', 'linux')
+    monkeypatch.setattr(mt.ctypes, 'CDLL', mock.Mock(side_effect=OSError('no libc')))
+    assert mt._load_libc() is None
+    assert mt.cap_arenas() is False
+
+
+def test_loads_once(monkeypatch):
+    cdll = _on_glibc(monkeypatch, FakeLibc())
+    mt._load_libc()
+    mt._load_libc()
+    mt.MallocTrimmer()
+    assert cdll.call_count == 1
+
+
+def test_declares_c_signatures(monkeypatch):
+    libc = FakeLibc()
+    _on_glibc(monkeypatch, libc)
+    mt._load_libc()
+    assert libc.malloc_trim.argtypes == [ctypes.c_size_t]
+    assert libc.mallopt.argtypes == [ctypes.c_int, ctypes.c_int]
+
+
+# -- cap_arenas ---------------------------------------------------------------
+
+def test_cap_arenas_calls_mallopt(monkeypatch):
+    libc = FakeLibc()
+    _on_glibc(monkeypatch, libc)
+    assert mt.cap_arenas() is True
+    assert libc.mallopts == [(mt.M_ARENA_MAX, 2)]
+    assert mt.M_ARENA_MAX == -8  # glibc's malloc.h
+
+
+def test_cap_arenas_defers_to_the_environment(monkeypatch):
+    libc = FakeLibc()
+    _on_glibc(monkeypatch, libc)
+    monkeypatch.setenv('MALLOC_ARENA_MAX', '4')
+    assert mt.cap_arenas() is False
+    assert libc.mallopts == []
+
+
+def test_cap_arenas_swallows_errors(monkeypatch):
+    libc = FakeLibc()
+    libc.mallopt = mock.Mock(side_effect=RuntimeError('boom'))
+    _on_glibc(monkeypatch, libc)
+    assert mt.cap_arenas() is False
+
+
+def test_cap_arenas_matches_the_unit():
+    """The in-process default is the value the unit's MALLOC_ARENA_MAX carries."""
+    unit = (Path(__file__).resolve().parent.parent / 'systemd' / 'ledmatrix.service').read_text()
+    assert f'Environment=MALLOC_ARENA_MAX={mt.DEFAULT_ARENA_MAX}\n' in unit
+
+
+# -- MallocTrimmer ------------------------------------------------------------
+
+def test_trim_waits_one_interval_then_rate_limits(monkeypatch):
+    libc = FakeLibc()
+    _on_glibc(monkeypatch, libc)
+    clock = Clock()
+    trimmer = mt.MallocTrimmer(interval=300, clock=clock)
+    assert trimmer.available
+    assert trimmer.maybe_trim() is False          # start-up: not yet
+    clock.t += 299.9
+    assert trimmer.maybe_trim() is False
+    clock.t += 0.1
+    assert trimmer.maybe_trim() is True
+    assert libc.trims == [0]
+    clock.t += 100
+    assert trimmer.maybe_trim() is False          # rate-limited
+    clock.t += 200
+    assert trimmer.maybe_trim() is True
+    assert libc.trims == [0, 0]
+
+
+def test_trim_reports_nothing_released(monkeypatch):
+    libc = FakeLibc(trim_result=0)
+    _on_glibc(monkeypatch, libc)
+    clock = Clock()
+    trimmer = mt.MallocTrimmer(interval=10, clock=clock)
+    clock.t += 10
+    assert trimmer.maybe_trim() is False
+    assert libc.trims == [0]
+
+
+def test_trim_failure_disables_trimming(monkeypatch):
+    libc = FakeLibc(trim_result=RuntimeError('boom'))
+    _on_glibc(monkeypatch, libc)
+    clock = Clock()
+    trimmer = mt.MallocTrimmer(interval=10, clock=clock)
+    clock.t += 10
+    assert trimmer.maybe_trim() is False
+    clock.t += 10
+    assert trimmer.maybe_trim() is False
+    assert libc.trims == [0]                      # not retried
+    assert not trimmer.available
+
+
+# -- wiring -------------------------------------------------------------------
+
+def test_run_py_caps_arenas_before_threads():
+    """run.py applies the cap before the watchdog or the controller import."""
+    src = (Path(__file__).resolve().parent.parent / 'run.py').read_text()
+    cap = src.index('malloc_tuning.cap_arenas()')
+    assert cap < src.index('display_watchdog.watchdog.begin_startup()')
+    assert cap < src.index('from src.display_controller import main')
+
+
+def test_render_loop_trims_between_screens():
+    src = (Path(__file__).resolve().parent.parent / 'src' / 'display_controller.py').read_text()
+    loop = src.index('display_watchdog.watchdog.loop_pass()')
+    trim = src.index('trimmer.maybe_trim()')
+    assert loop < trim < src.index('outcome = runner.run(plan, manager_to_display)')
+
+
+@pytest.mark.skipif(not mt.sys.platform.startswith('linux'), reason='glibc only')
+def test_real_libc_on_linux():
+    """On a real Linux C library the calls go through without raising."""
+    if mt._load_libc() is None:
+        pytest.skip('not glibc')
+    trimmer = mt.MallocTrimmer(interval=0)
+    assert trimmer.available
+    assert trimmer.maybe_trim() in (True, False)
+    assert trimmer.available  # did not fail and disable itself

test/test_plugin_runtime_snapshot.py

@@ -162,7 +162,7 @@ class TestPublisher:
         assert snapshot["stale_after"] == rt.STALE_AFTER
         assert snapshot["plugins"] == {"clock": {
             "loaded": True, "state": "enabled", "error": None,
-            "version": "1.0.0", "loaded_at": 10.0}}
+            "version": "1.0.0", "loaded_at": 10.0, "modes": None}}
 
     def test_changes_are_throttled_and_quiet_displays_refresh(self):
         cache = MagicMock()

test/test_sports_favorites.py

@@ -0,0 +1,280 @@
+"""src.common.sports_favorites: behaviour, the _favorite_key seam, host contract.
+
+The cases follow ledmatrix-plugins' ``scripts/test_favourite_matching.py``
+(the tables the family 6 reconcile was checked against), with the favourites
+given as each plugin's resolver hands them over: as typed for the
+abbreviation sports, as ESPN team ids for an NRL-style host that overrides
+``_favorite_key``.
+"""
+
+import ast
+import logging
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from src.common import sports_favorites
+from src.common.sports_favorites import (
+    SportsFavoritesMixin,
+    SportsRecentFavoritesMixin,
+    SportsUpcomingFavoritesMixin,
+)
+from src.common.sports_helpers import SportsHelpersMixin
+
+LOG = logging.getLogger("test_sports_favorites")
+
+
+def _id_key(self, game, side):
+    """NRL's override: the ESPN team id, None when it is missing."""
+    team_id = game.get(f"{side}_id")
+    return None if team_id is None else str(team_id)
+
+
+def host(favorites, by_id=False, limit=3):
+    """A manager stand-in: the three mixins over SportsHelpersMixin's default key."""
+    attrs = {"_favorite_key": _id_key} if by_id else {}
+    cls = type("Host", (SportsUpcomingFavoritesMixin, SportsRecentFavoritesMixin,
+                        SportsFavoritesMixin, SportsHelpersMixin), attrs)
+    h = cls()
+    h.logger = LOG
+    h.favorite_teams = favorites
+    h.upcoming_games_to_show = h.recent_games_to_show = limit
+    return h
+
+
+TEAM = {"1": "AAA", "2": "BBB", "3": "CCC", "4": "DDD", "41": "NEW", "42": "NEW"}
+
+
+def match(home, away, **extra):
+    g = {"home_id": home, "home_abbr": TEAM[home], "away_id": away, "away_abbr": TEAM[away]}
+    g.update(extra)
+    return g
+
+
+GAMES = {
+    "AAA home v BBB": match("1", "2"),
+    "BBB home v AAA": match("2", "1"),
+    "CCC v DDD": match("3", "4"),
+    "Knights (NEW 41) v CCC": match("41", "3"),
+    "Warriors (NEW 42) v CCC": match("42", "3"),
+    "AAA v BBB, no ids": {"home_abbr": "AAA", "away_abbr": "BBB"},
+    "ids 1 v 2, no abbrs": {"home_id": "1", "away_id": "2"},
+    "AAA v BBB, int ids": match("1", "2", home_id=1, away_id=2),
+    "lower-case abbrs": {"home_abbr": "aaa ", "away_abbr": "bbb"},
+    "empty game": {},
+}
+
+#: label -> favorite_teams as the resolver hands it over.
+FAVORITES = {
+    "none": [],
+    "AAA": ["AAA"],
+    "aaa": ["aaa"],
+    "' AAA '": [" AAA "],
+    "1": ["1"],
+    "int 1": [1],
+    "AAA,CCC": ["AAA", "CCC"],
+    "NEW": ["NEW"],
+    "41": ["41"],
+    "'None'": ["None"],
+    "blank": ["", "  "],
+}
+
+#: (favourites, game) -> answer with the abbreviation key, then the id key.
+EXPECTED_IS_FAVORITE = {
+    "AAA home v BBB": {"AAA": "Y.", "aaa": "Y.", "' AAA '": "Y.", "1": ".Y", "int 1": ".Y",
+                       "AAA,CCC": "Y."},
+    "BBB home v AAA": {"AAA": "Y.", "aaa": "Y.", "' AAA '": "Y.", "1": ".Y", "int 1": ".Y",
+                       "AAA,CCC": "Y."},
+    "CCC v DDD": {"AAA,CCC": "Y."},
+    "Knights (NEW 41) v CCC": {"AAA,CCC": "Y.", "NEW": "Y.", "41": ".Y"},
+    "Warriors (NEW 42) v CCC": {"AAA,CCC": "Y.", "NEW": "Y."},
+    "AAA v BBB, no ids": {"AAA": "Y.", "aaa": "Y.", "' AAA '": "Y.", "AAA,CCC": "Y."},
+    "ids 1 v 2, no abbrs": {"1": ".Y", "int 1": ".Y"},
+    "AAA v BBB, int ids": {"AAA": "Y.", "aaa": "Y.", "' AAA '": "Y.", "1": ".Y",
+                           "int 1": ".Y", "AAA,CCC": "Y."},
+    "lower-case abbrs": {"AAA": "Y.", "aaa": "Y.", "' AAA '": "Y.", "AAA,CCC": "Y."},
+    "empty game": {},
+}
+
+
+@pytest.mark.parametrize("game_label", sorted(GAMES))
+@pytest.mark.parametrize("fav_label", sorted(FAVORITES))
+def test_is_favorite_game(fav_label, game_label):
+    want = EXPECTED_IS_FAVORITE[game_label].get(fav_label, "..")
+    got = "".join("Y" if host(FAVORITES[fav_label], by_id)._is_favorite_game(dict(GAMES[game_label]))
+                  else "." for by_id in (False, True))
+    assert got == want
+
+
+class TestFavoriteCode:
+    @pytest.mark.parametrize("value, code", [
+        ("bos", "BOS"), (" BOS ", "BOS"), ("BOS", "BOS"), (41, "41"),
+        ("", None), ("   ", None), (None, None),
+    ])
+    def test_normalises(self, value, code):
+        assert SportsFavoritesMixin._favorite_code(value) == code
+
+    def test_a_missing_id_is_not_the_string_none(self):
+        """str(None) would match a favourite typed "None"; None matches nothing."""
+        h = host(["None"], by_id=True)
+        assert h._is_favorite_game({"home_abbr": "AAA", "away_abbr": "BBB"}) is False
+        assert h._is_favorite_game({}) is False
+
+    def test_a_none_favorites_list_matches_nothing(self):
+        assert host(None)._is_favorite_game(dict(GAMES["AAA home v BBB"])) is False
+
+
+# ---------------------------------------------------------------------------
+# Selection. A shuffled slate: two games share id s2, two have no id, s9 has
+# no start time. Hours from now; Recent gets the same slate in the past.
+# ---------------------------------------------------------------------------
+
+NOW = datetime(2026, 10, 5, 15, tzinfo=timezone.utc)
+SLATE = (("s5", "41", "2", 5), ("s1", "1", "2", 1), ("s3", "4", "3", 3),
+         ("s2", "3", "1", 2), ("s7", "2", "3", 7), ("s4", "1", "4", 4),
+         ("s6", "42", "4", 6), ("s2", "1", "4", 8), ("s9", "1", "3", None),
+         (None, "3", "1", 9), (None, "2", "1", 10))
+
+
+def slate(recent):
+    sign = -1 if recent else 1
+    games = []
+    for gid, home, away, hours in SLATE:
+        g = match(home, away, id=gid)
+        if hours is not None:
+            g["start_time_utc"] = NOW + timedelta(hours=sign * hours)
+        games.append(g)
+    return games
+
+
+def pick(favorites, limit, recent, by_id=False):
+    h = host(favorites, by_id, limit)
+    method = h._select_recent_games_for_display if recent else h._select_games_for_display
+    return ",".join(g["id"] or "~" for g in method(slate(recent), favorites)) or "none"
+
+
+ALL = "s1,s2,s3,s4,s5,s6,s7,s2,~,~,s9"
+
+#: (favourites, per-team limit) -> picked ids, the same for Upcoming and Recent.
+EXPECTED_SELECT = {
+    (("AAA",), 1): "s1", (("AAA",), 2): "s1,s2", (("AAA",), 5): "s1,s2,s4,~,~",
+    (("aaa",), 5): "s1,s2,s4,~,~", ((" AAA ",), 2): "s1,s2",
+    (("AAA", "CCC"), 1): "s1,s2", (("AAA", "CCC"), 2): "s1,s2,s3",
+    (("AAA", "CCC"), 5): "s1,s2,s3,s4,s7,~,~,s9",
+    (("AAA", "ZZZ"), 2): "s1,s2", (("NEW",), 2): "s5,s6",
+    (("ZZZ",), 2): "none", ((), 1): ALL,
+}
+
+
+@pytest.mark.parametrize("recent", [False, True], ids=["upcoming", "recent"])
+@pytest.mark.parametrize("favorites, limit", sorted(EXPECTED_SELECT))
+def test_select(favorites, limit, recent):
+    assert pick(list(favorites), limit, recent) == EXPECTED_SELECT[(favorites, limit)]
+
+
+class TestSelectByTeamId:
+    """The NRL-style host: the key is the team id, so NEW is two teams."""
+
+    @pytest.mark.parametrize("recent", [False, True])
+    def test_one_club_of_a_shared_abbreviation(self, recent):
+        assert pick(["41"], 2, recent, by_id=True) == "s5"
+
+    @pytest.mark.parametrize("recent", [False, True])
+    def test_an_unresolved_abbreviation_matches_nothing(self, recent):
+        assert pick(["NEW"], 2, recent, by_id=True) == "none"
+
+    def test_ids_select_like_abbreviations(self):
+        assert pick(["1"], 5, False, by_id=True) == "s1,s2,s4,~,~"
+
+
+class TestSelectionRules:
+    def test_a_game_between_two_favourites_counts_for_both(self):
+        h = host(["AAA", "BBB"], limit=1)
+        picked = h._select_games_for_display(slate(False), ["AAA", "BBB"])
+        assert [g["id"] for g in picked] == ["s1"]
+
+    def test_games_without_an_id_are_never_duplicates(self):
+        games = [match("1", "2"), match("1", "3")]
+        assert len(host(["AAA"])._select_games_for_display(games, ["AAA"])) == 2
+
+    def test_a_reused_id_is_a_duplicate(self):
+        games = [match("1", "2", id="x"), match("1", "3", id="x")]
+        assert len(host(["AAA"])._select_games_for_display(games, ["AAA"])) == 1
+
+    def test_upcoming_is_soonest_first_and_recent_newest_first(self):
+        assert pick(["CCC"], 5, False) == "s2,s3,s7,~,s9"
+        assert pick(["CCC"], 5, True) == "s2,s3,s7,~,s9"
+
+    def test_the_handed_list_is_used_not_favorite_teams(self):
+        h = host(["CCC"], limit=1)
+        assert [g["id"] for g in h._select_games_for_display(slate(False), ["AAA"])] == ["s1"]
+
+    @pytest.mark.parametrize("recent", [False, True])
+    def test_the_summary_is_logged_at_info(self, recent, caplog):
+        with caplog.at_level(logging.INFO, logger=LOG.name):
+            pick(["AAA"], 1, recent)
+        name = "_select_recent_games_for_display" if recent else "_select_games_for_display"
+        assert [r.levelno for r in caplog.records if r.funcName == name
+                and r.levelno >= logging.INFO] == [logging.INFO]
+
+
+# ---------------------------------------------------------------------------
+# Carriers and host contract
+# ---------------------------------------------------------------------------
+
+MIXINS = {
+    "SportsFavoritesMixin": ["_favorite_code", "_is_favorite_game"],
+    "SportsUpcomingFavoritesMixin": ["_select_games_for_display"],
+    "SportsRecentFavoritesMixin": ["_select_recent_games_for_display"],
+}
+
+
+def _classes():
+    tree = ast.parse(Path(sports_favorites.__file__).read_text(encoding="utf-8"))
+    return {n.name: n for n in tree.body if isinstance(n, ast.ClassDef)}
+
+
+def _self_reads(cls):
+    return {node.attr for node in ast.walk(cls)
+            if isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Load)
+            and isinstance(node.value, ast.Name) and node.value.id == "self"}
+
+
+class TestHostContract:
+    def test_each_mixin_carries_only_its_class_methods(self):
+        """So adopting one gives no manager a method it did not have."""
+        for name, methods in MIXINS.items():
+            mixin = getattr(sports_favorites, name)
+            assert sorted(n for n in vars(mixin) if not n.startswith("__")) == methods
+
+    def test_every_host_read_is_documented(self):
+        reads = set().union(*(_self_reads(c) for c in _classes().values()))
+        undocumented = sorted(n for n in reads if f"``{n}``" not in sports_favorites.__doc__)
+        assert undocumented == [], f"read but not in the host contract: {undocumented}"
+
+    def test_the_key_comes_from_sports_helpers(self):
+        """The seam stays where 3.5.0 put it; this module only calls it."""
+        assert "_favorite_key" in vars(SportsHelpersMixin)
+        assert all("_favorite_key" not in vars(getattr(sports_favorites, n)) for n in MIXINS)
+
+    def test_no_other_shared_mixin_defines_these(self):
+        from src.common import sports_display_rules, sports_shared
+        others = [sports_shared.SportsCoreSharedMixin, sports_shared.SportsRecentSharedMixin,
+                  sports_shared.SportsLiveSharedMixin, SportsHelpersMixin,
+                  sports_display_rules.SportsGameRulesMixin]
+        for methods in MIXINS.values():
+            for name in methods:
+                assert not any(name in vars(o) for o in others), name
+
+    def test_the_shared_callers_reach_it(self):
+        """_favorites_first and the live dwell ask _is_favorite_game; one body answers."""
+        from src.common.sports_display_rules import SportsGameRulesMixin
+
+        class Host(SportsGameRulesMixin, SportsFavoritesMixin, SportsHelpersMixin):
+            favorite_teams = ["aaa"]
+            game_display_duration = 15
+            non_favorite_live_game_duration = 5
+
+        assert Host()._effective_live_duration(dict(GAMES["AAA home v BBB"])) == 15
+        assert Host()._effective_live_duration(dict(GAMES["CCC v DDD"])) == 5

test/test_sports_favorites_parity.py

@@ -0,0 +1,135 @@
+"""sports_favorites still matches every plugin copy, and only nrl overrides the key.
+
+``src.common.sports_favorites`` was copied from the scoreboards once family 6
+had made each method one body in all nine: ``SportsCore._favorite_code`` and
+``_is_favorite_game``, ``SportsUpcoming._select_games_for_display`` and
+``SportsRecent._select_recent_games_for_display``. The plugins delete their
+copies once they floor on the release that ships this module. Until each has, a
+copy that changes on its own is a fix one side has and the other lacks.
+
+Point LEDMATRIX_PLUGINS at a ledmatrix-plugins checkout and each method is
+compared with every plugin copy using ``scripts/sports_drift_report.py``'s own
+normalisation (the AST with docstrings and annotations dropped), plus the
+decorators. A copy that is gone counts as adopted when the plugin's
+``sports.py`` names the module. The owner's decision that only nrl overrides
+``_favorite_key`` (with the team id) is checked too; that override stays in
+the plugin after adoption. Without the variable this skips: core CI has no
+plugins checkout.
+"""
+
+import ast
+import importlib.util
+import os
+from pathlib import Path
+
+import pytest
+
+from src.common import sports_favorites
+
+REPO = Path(__file__).resolve().parents[1]
+SPORTS = ("afl", "baseball", "basketball", "football", "hockey", "lacrosse",
+          "nrl", "soccer", "ufc")
+
+#: plugin class -> (our mixin, the methods it carries)
+CARRIERS = {
+    "SportsCore": ("SportsFavoritesMixin", ("_favorite_code", "_is_favorite_game")),
+    "SportsUpcoming": ("SportsUpcomingFavoritesMixin", ("_select_games_for_display",)),
+    "SportsRecent": ("SportsRecentFavoritesMixin", ("_select_recent_games_for_display",)),
+}
+
+#: The owner's decision (docs/SPORTS_UNIFICATION.md, family 6): the sports
+#: that name a team by something other than its abbreviation.
+OVERRIDES_FAVORITE_KEY = {"nrl"}
+
+
+def _drift_report():
+    """scripts/sports_drift_report.py, loaded by path (scripts/ is no package)."""
+    spec = importlib.util.spec_from_file_location(
+        "sports_drift_report", REPO / "scripts" / "sports_drift_report.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+DRIFT = _drift_report()
+
+
+def _plugins_root():
+    root = DRIFT.resolve_plugins_dir(os.environ.get("LEDMATRIX_PLUGINS"))
+    if root is None:
+        pytest.skip("set LEDMATRIX_PLUGINS to a ledmatrix-plugins checkout to "
+                    "compare this module against the plugin copies")
+    return root
+
+
+def _class(tree, name):
+    return next(n for n in tree.body if isinstance(n, ast.ClassDef) and n.name == name)
+
+
+def _method(cls, name):
+    return next((n for n in cls.body
+                 if isinstance(n, ast.FunctionDef) and n.name == name), None)
+
+
+def _fingerprint(node):
+    return (DRIFT._digest(node, DRIFT._Canonical()),
+            tuple(ast.unparse(d) for d in node.decorator_list))
+
+
+def _ours(mixin):
+    tree = ast.parse(Path(sports_favorites.__file__).read_text(encoding="utf-8"))
+    return _class(tree, mixin)
+
+
+def _plugin_tree(root, sport):
+    source = (root / f"{sport}-scoreboard" / "sports.py").read_text(encoding="utf-8")
+    return source, ast.parse(source)
+
+
+CASES = [(sport, cls, name) for sport in SPORTS
+         for cls, (_, names) in CARRIERS.items() for name in names]
+
+
+@pytest.mark.parametrize("sport, cls, name", CASES)
+def test_every_remaining_plugin_copy_matches(sport, cls, name):
+    source, tree = _plugin_tree(_plugins_root(), sport)
+    copy = _method(_class(tree, cls), name)
+    if copy is None:
+        assert sports_favorites.__name__ in source, (
+            f"{sport}: no {name} on {cls} and no {sports_favorites.__name__} import")
+    else:
+        ours = _method(_ours(CARRIERS[cls][0]), name)
+        assert _fingerprint(copy) == _fingerprint(ours), (
+            f"{cls}.{name} in {sport} differs from sports_favorites. "
+            f"Port the change to both, or stop treating it as shared.")
+
+
+@pytest.mark.parametrize("sport", SPORTS)
+def test_no_other_plugin_class_carries_a_copy(sport):
+    """A copy on another class (afl's old SportsUpcoming._is_favorite_game) would shadow the shared one."""
+    _, tree = _plugin_tree(_plugins_root(), sport)
+    shared = {name: cls for cls, (_, names) in CARRIERS.items() for name in names}
+    strays = [f"{node.name}.{name}" for node in tree.body if isinstance(node, ast.ClassDef)
+              for name, home in shared.items()
+              if node.name != home and _method(node, name) is not None]
+    assert strays == []
+
+
+def test_only_the_decided_sports_override_the_key():
+    root = _plugins_root()
+    overriding = {sport for sport in SPORTS
+                  if any(_method(node, "_favorite_key") is not None
+                         for node in _plugin_tree(root, sport)[1].body
+                         if isinstance(node, ast.ClassDef))}
+    assert overriding == OVERRIDES_FAVORITE_KEY
+
+
+def test_the_drift_report_still_calls_them_identical():
+    root = _plugins_root()
+    families = DRIFT.build(root, ("sports.py",))
+    rows = {(r["file"], r["family"]): r
+            for r in (DRIFT.summarise(k, v) for k, v in families.items())}
+    for _, names in CARRIERS.values():
+        for name in names:
+            row = rows.get(("sports.py", name))
+            assert row is None or row["worst_class_variants"] == 1, name

test/test_sports_helpers.py

@@ -8,7 +8,9 @@ loses those tests with it.
 The parity class is what keeps "byte-identical" true after this lands. Point
 LEDMATRIX_PLUGINS at a ledmatrix-plugins checkout and every promoted body is
 compared, as a docstring-stripped AST, against every plugin copy that carries
-it. Without the variable it skips rather than fails, since core CI has no
+it. A copy that is gone counts as adopted when the plugin imports
+src.common.sports_helpers (plugins#563/#564 did that for every scoreboard).
+Without the variable it skips rather than fails, since core CI has no
 plugins checkout; ledmatrix-plugins CI runs the same comparison against core
 (scripts/check_sports_helpers_parity.py, ledmatrix-plugins#495).
 """
@@ -572,6 +574,24 @@ def _core_definitions():
     return out
 
 
+def _sports_source(root, sport):
+    return (root / f"{sport}-scoreboard" / "sports.py").read_text(encoding="utf-8")
+
+
+def _adopted(source):
+    """Gone is fine once the plugin uses the module; otherwise the finder is
+    not seeing its copy."""
+    name = sports_helpers.__name__
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.ImportFrom):
+            if node.module == name or any(
+                    f"{node.module}.{a.name}" == name for a in node.names):
+                return True
+        elif isinstance(node, ast.Import) and any(a.name == name for a in node.names):
+            return True
+    return False
+
+
 class TestParityWithPlugins:
     @pytest.mark.parametrize("name", sorted(PROMOTED))
     def test_body_matches_every_plugin_copy(self, name):
@@ -580,10 +600,10 @@ class TestParityWithPlugins:
         ours = _dump(_core_definitions()[name])
         drifted, missing = [], []
         for sport in carriers:
-            defs = _definitions(ast.parse(
-                (root / f"{sport}-scoreboard" / "sports.py").read_text(encoding="utf-8")))
-            theirs = defs[where].get(plugin_name)
+            source = _sports_source(root, sport)
+            theirs = _definitions(ast.parse(source))[where].get(plugin_name)
             if theirs is None:
+                if not _adopted(source):
                     missing.append(sport)
             elif _dump(theirs) != ours:
                 drifted.append(sport)
@@ -594,10 +614,20 @@ class TestParityWithPlugins:
 
     @pytest.mark.parametrize("sport", SCOREBOARDS)
     def test_constants_match(self, sport):
-        root = _plugins_root()
-        defs = _definitions(ast.parse(
-            (root / f"{sport}-scoreboard" / "sports.py").read_text(encoding="utf-8")))
-        assert ast.literal_eval(defs["module"]["_MIN_WINDOW_DAYS"].value) == MIN_WINDOW_DAYS
-        assert ast.literal_eval(defs["module"]["_MAX_WINDOW_DAYS"].value) == MAX_WINDOW_DAYS
-        gap = defs["SportsCore"]["_DWELL_REENTRY_GAP_SECONDS"].value
-        assert math.isclose(ast.literal_eval(gap), SportsHelpersMixin._DWELL_REENTRY_GAP_SECONDS)
+        source = _sports_source(_plugins_root(), sport)
+        defs = _definitions(ast.parse(source))
+        expected = {
+            ("module", "_MIN_WINDOW_DAYS"): MIN_WINDOW_DAYS,
+            ("module", "_MAX_WINDOW_DAYS"): MAX_WINDOW_DAYS,
+            ("SportsCore", "_DWELL_REENTRY_GAP_SECONDS"):
+                SportsHelpersMixin._DWELL_REENTRY_GAP_SECONDS,
+        }
+        missing = []
+        for (where, name), value in expected.items():
+            node = defs[where].get(name)
+            if node is None:
+                if not _adopted(source):
+                    missing.append(name)
+            else:
+                assert math.isclose(ast.literal_eval(node.value), value), name
+        assert missing == [], f"not found in {sport}: {missing}"

test/test_vegas_static_mode.py

@@ -219,7 +219,8 @@ class TestCoordinatorStaticPause:
     def _plugin(self):
         plugin = MagicMock()
         plugin.plugin_id = 'clock'
-        plugin.get_display_duration.return_value = 0
+        # A moment: zero would pause 15 s, as the rotation shows it.
+        plugin.get_display_duration.return_value = 0.01
         return plugin
 
     def test_trigger_comes_from_the_pipeline(self):

test/test_vegas_static_pause_duration.py

@@ -0,0 +1,197 @@
+"""A Vegas static pause lasts as long as the rotation shows the plugin.
+
+The pause asked the plugin for get_display_duration() and compared the
+answer with the clock. Several plugins (clock-simple, calendar, countdown)
+return their display_duration setting as it is in config.json, so one saved
+as "20" or null -- the raw config editor, a hand edit -- reached that
+comparison as a string or None. The TypeError went to the pause's broad
+except, which ended the pause: the plugin flashed up and the scroll went on,
+at every one of its turns. inf paused until something interrupted it, and
+NaN, False, 0 or a negative number ended the pause at once.
+
+The pause now reads the answer the way the rotation does since #739, with
+the same helper (base_plugin.finite_seconds): a numeric string counts;
+anything else that is not a finite number, or a raise, gets the rotation's
+30 s; a number at or below zero gets its 15 s.
+"""
+
+import logging
+import os
+import threading
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+os.environ.setdefault("EMULATOR", "true")
+
+import pytest
+
+from src.vegas_mode import coordinator
+
+NOT_NUMBERS = [None, '', 'twenty', True, False, float('nan'), float('inf'),
+               'inf', '1e400', [20], {'seconds': 20}]
+NOT_ABOVE_ZERO = [0, -5, '-5', '0']
+NUMBERS = [('20', 20.0), (' 7.5 ', 7.5), (12, 12.0), (12.5, 12.5)]
+
+
+class FakeClock:
+    """time.monotonic/time.sleep for the pause loop: sleeping moves the clock."""
+
+    #: A pause still going after this long never ends (inf did that).
+    LIMIT = 3600.0
+
+    def __init__(self):
+        self.now = 0.0
+
+    def monotonic(self):
+        return self.now
+
+    def sleep(self, seconds):
+        self.now += seconds
+        if self.now > self.LIMIT:
+            raise RuntimeError("the static pause never ended")
+
+
+@pytest.fixture
+def clock(monkeypatch):
+    fake = FakeClock()
+    monkeypatch.setattr(coordinator, 'time', fake)
+    return fake
+
+
+def _plugin(duration, plugin_id='clock-simple'):
+    plugin = MagicMock()
+    plugin.plugin_id = plugin_id
+    plugin.get_display_duration.return_value = duration
+    return plugin
+
+
+def _coord(*plugins):
+    coord = coordinator.VegasModeCoordinator.__new__(coordinator.VegasModeCoordinator)
+    coord.render_pipeline = MagicMock()
+    coord.render_pipeline.get_scroll_position.return_value = 0
+    coord.display_manager = MagicMock()
+    locks = {plugin.plugin_id: threading.Lock() for plugin in plugins}
+    coord.plugin_manager = SimpleNamespace(get_plugin_lock=locks.__getitem__)
+    coord._state_lock = threading.Lock()
+    coord._static_pause_active = False
+    coord._saved_scroll_position = None
+    coord._should_stop = False
+    coord._live_priority_active = False
+    coord._live_priority_check = None
+    coord._interrupt_check = None
+    coord.stats = {'static_pauses': 0}
+    return coord
+
+
+def _pause(coord, plugin, clock):
+    """One static pause: (whether it completed, how long it lasted)."""
+    start = clock.now
+    completed = coord._handle_static_pause(plugin)
+    return completed, clock.now - start
+
+
+class TestPauseLength:
+    @pytest.mark.parametrize('value, seconds', NUMBERS)
+    def test_numbers_and_numeric_strings_are_used(self, clock, value, seconds):
+        plugin = _plugin(value)
+        completed, lasted = _pause(_coord(plugin), plugin, clock)
+        assert completed is True
+        assert lasted == pytest.approx(seconds, abs=0.15)
+
+    @pytest.mark.parametrize('value', NOT_NUMBERS, ids=repr)
+    def test_anything_but_a_finite_number_pauses_for_30s(self, clock, value):
+        plugin = _plugin(value)
+        completed, lasted = _pause(_coord(plugin), plugin, clock)
+        assert completed is True
+        assert lasted == pytest.approx(30.0, abs=0.15)
+        plugin.display.assert_called_once_with(force_clear=True)
+
+    @pytest.mark.parametrize('value', NOT_ABOVE_ZERO, ids=repr)
+    def test_a_number_not_above_zero_pauses_for_15s(self, clock, value):
+        plugin = _plugin(value)
+        completed, lasted = _pause(_coord(plugin), plugin, clock)
+        assert completed is True
+        assert lasted == pytest.approx(15.0, abs=0.15)
+
+    def test_a_raising_get_display_duration_pauses_for_30s(self, clock):
+        plugin = _plugin(None)
+        plugin.get_display_duration.side_effect = KeyError('display_duration')
+        completed, lasted = _pause(_coord(plugin), plugin, clock)
+        assert completed is True
+        assert lasted == pytest.approx(30.0, abs=0.15)
+
+    def test_a_good_value_after_a_bad_one_is_used(self, clock):
+        plugin = _plugin(None)
+        coord = _coord(plugin)
+        assert _pause(coord, plugin, clock)[1] == pytest.approx(30.0, abs=0.15)
+        plugin.get_display_duration.return_value = 45
+        assert _pause(coord, plugin, clock)[1] == pytest.approx(45.0, abs=0.15)
+
+    def test_the_pause_can_still_be_interrupted(self, clock):
+        plugin = _plugin('twenty')
+        coord = _coord(plugin)
+        coord._interrupt_check = lambda: clock.now >= 5
+        completed, lasted = _pause(coord, plugin, clock)
+        assert completed is False
+        assert lasted == pytest.approx(5.0, abs=0.15)
+
+
+class TestWarning:
+    def test_logged_once_per_plugin(self, clock, caplog):
+        clock_plugin = _plugin('twenty')
+        calendar = _plugin(None, plugin_id='calendar')
+        coord = _coord(clock_plugin, calendar)
+        with caplog.at_level(logging.WARNING, logger='src.vegas_mode.coordinator'):
+            for _ in range(3):
+                for plugin in (clock_plugin, calendar):
+                    coord._handle_static_pause(plugin)
+        warnings = [r.getMessage() for r in caplog.records
+                    if 'display duration' in r.getMessage()]
+        assert len(warnings) == 2
+        assert any('clock-simple' in m and "'twenty'" in m for m in warnings)
+        assert any('calendar' in m and 'None' in m for m in warnings)
+
+
+class TestFiniteSeconds:
+    """The shared rule: what counts as a number of seconds."""
+
+    @pytest.mark.parametrize('value, seconds', NUMBERS + [(0, 0.0), ('-5', -5.0)])
+    def test_numbers_and_numeric_strings(self, value, seconds):
+        from src.plugin_system.base_plugin import finite_seconds
+        result = finite_seconds(value)
+        assert result == seconds and isinstance(result, float)
+
+    @pytest.mark.parametrize('value', NOT_NUMBERS + [pytest.param(10 ** 400, id='10**400')],
+                             ids=repr)
+    def test_anything_else_is_none(self, value):
+        from src.plugin_system.base_plugin import finite_seconds
+        assert finite_seconds(value) is None
+
+
+def _rotation_seconds(plugin):
+    """How long the rotation shows ``plugin`` (no dynamic duration, no
+    Rotation & Durations override): the two calls run() makes for a screen.
+    """
+    from src.display_controller import DisplayController
+    dc = object.__new__(DisplayController)
+    dc.config = {}
+    dc.plugin_modes = {'mode': plugin}
+    return dc._resolve_durations(plugin, 'mode', dc._get_display_duration('mode'), False)[1]
+
+
+class TestSameAsTheRotation:
+    """The pause and the rotation share finite_seconds; this pins their
+    fallbacks (30 s, 15 s) to each other too."""
+
+    @pytest.mark.parametrize('value', [value for value, _ in NUMBERS]
+                             + NOT_NUMBERS + NOT_ABOVE_ZERO, ids=repr)
+    def test_the_pause_lasts_as_long_as_the_rotation_shows_it(self, clock, value):
+        plugin = _plugin(value)
+        expected = _rotation_seconds(plugin)
+        assert _pause(_coord(plugin), plugin, clock)[1] == pytest.approx(expected, abs=0.15)
+
+    def test_a_raise_too(self, clock):
+        plugin = _plugin(None)
+        plugin.get_display_duration.side_effect = KeyError('display_duration')
+        expected = _rotation_seconds(plugin)
+        assert _pause(_coord(plugin), plugin, clock)[1] == pytest.approx(expected, abs=0.15)

web_interface/app.py

@@ -159,10 +159,18 @@ schema_manager = SchemaManager(
 # saves reach the running plugins through the display's config watcher; what
 # the display knows at run time (health, metrics, errors, current mode) it
 # publishes to the shared cache. See docs/ARCHITECTURE.md.
+def _catalog_runtime_view():
+    """The display's runtime view, for the catalog's mode lookups. Imported
+    on call, as the startup reconciliation below imports it."""
+    from web_interface.blueprints.api_v3 import _plugin_runtime_view
+    return _plugin_runtime_view()
+
+
 plugin_catalog = PluginCatalog(
     plugins_dir=plugins_dir,
     config_manager=config_manager,
     schema_manager=schema_manager,
+    runtime_source=_catalog_runtime_view,
 )
 
 # Initialize operation queue for plugin operations

web_interface/blueprints/api_v3/display.py

@@ -153,10 +153,12 @@ def get_display_modes():
     same list the force-display dialog offers, from the source that owns it.
 
     Knowing each mode's plugin_id also matters because /display/on-demand/start
-    falls back to find_plugin_for_mode when plugin_id is omitted, and that
-    lookup only sees modes declared in a static manifest -- a plugin whose
-    modes are generated (each installed Starlark app is one) 404s there.
-    Sending the plugin_id from this list skips the lookup entirely.
+    falls back to find_plugin_for_mode when plugin_id is omitted. While the
+    display is running, both that lookup and this list use the modes it
+    registered, so modes a plugin generates from its config (each installed
+    Starlark app, each soccer custom league) are found (#668); with the
+    display stopped they see only what manifests declare. Sending the
+    plugin_id from this list skips the lookup entirely.
 
     Query params:
         include_disabled: '1' to list modes of disabled plugins too. They can
@@ -277,6 +279,15 @@ def start_on_demand_display():
             if not resolved_plugin:
                 return jsonify({'status': 'error', 'message': f'Mode {resolved_mode} not found'}), 404
 
+    # The display matches mode names exactly: pass the registered spelling
+    # when the caller's differs only in case.
+    if api_v3.plugin_catalog and resolved_plugin and resolved_mode:
+        wanted = resolved_mode.strip().lower()
+        for registered in api_v3.plugin_catalog.get_plugin_display_modes(resolved_plugin):
+            if isinstance(registered, str) and registered.lower() == wanted:
+                resolved_mode = registered
+                break
+
     # On-demand works with disabled plugins: the running display loads one
     # for the session and unloads it afterwards, leaving config.json alone
     # (DisplayController._load_plugin_for_on_demand). Logged for debugging.

web_interface/blueprints/api_v3/plugin_store.py

@@ -530,11 +530,13 @@ def install_plugin():
                     )
 
                 branch_msg = f" (branch: {branch})" if branch else ""
-                # plugin_id: the id to enable it by (see _installed_plugin_id).
+                # plugin_id: the id to enable it by, and the id its config
+                # section is under (see _installed_plugin_id).
+                installed_id = _installed_plugin_id(plugin_id)
                 return {'success': True,
                         'message': f'Plugin {plugin_id} installed successfully{branch_msg}',
-                        'plugin_id': _installed_plugin_id(plugin_id),
-                        **_store_restart_fields('install', _plugin_enabled_in_config(plugin_id))}
+                        'plugin_id': installed_id,
+                        **_store_restart_fields('install', _plugin_enabled_in_config(installed_id))}
             else:
                 error_msg = f'Failed to install plugin {plugin_id}'
                 if branch:
@@ -588,10 +590,11 @@ def install_plugin():
                 )
 
             branch_msg = f" (branch: {branch})" if branch else ""
+            installed_id = _installed_plugin_id(plugin_id)
             return success_response(
                 message=f'Plugin installed successfully{branch_msg}',
-                extra={'plugin_id': _installed_plugin_id(plugin_id),
-                       **_store_restart_fields('install', _plugin_enabled_in_config(plugin_id))})
+                extra={'plugin_id': installed_id,
+                       **_store_restart_fields('install', _plugin_enabled_in_config(installed_id))})
         else:
             error_msg = f'Failed to install plugin {plugin_id}'
             if branch:

web_interface/blueprints/api_v3/plugins.py

@@ -150,8 +150,9 @@ def get_installed_plugins():
         vegas_participation, vegas_participation_source = _vegas_participation(
             plugin_id, plugin_config, plugin_info)
 
-        # The modes the manifest declares, from the catalog as /display/modes
-        # and on-demand/start read them. The on-demand modal offers these;
+        # The plugin's modes, from the catalog as /display/modes and
+        # on-demand/start read them: what the running display registered,
+        # else what the manifest declares. The on-demand modal offers these;
         # without them it offered only the plugin id, which the display
         # turns into the first mode. Strings only: a manifest is hand-edited.
         declared_modes = api_v3.plugin_catalog.get_plugin_display_modes(plugin_id)