docs: guidance for 512MB and 1GB boards

Documents the memory ceiling on small boards and, more usefully, what
running into it actually looks like: sshd accepting connections and
closing them before the banner, the web UI still responding normally,
clean ping, a dark panel, and a wrong clock after the next boot. None of
those read as "out of memory", which makes the failure hard to identify
from the symptoms.

Cross-referenced from SSH_UNAVAILABLE_AFTER_INSTALL.md, since "I can't
SSH in any more" is how most people will first meet this.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/LOW_MEMORY_BOARDS.md

@@ -57,10 +57,7 @@ grep memory /sys/fs/cgroup/cgroup.controllers
 ```
 
 If that prints nothing, add `cgroup_enable=memory cgroup_memory=1` to the
-kernel command line and reboot. Edit whichever file your image uses —
+single line in `/boot/firmware/cmdline.txt` and reboot.
-`/boot/firmware/cmdline.txt` on current Raspberry Pi OS, `/boot/cmdline.txt` on
-older layouts (the installer checks the first and falls back to the second).
-Everything must stay on a single line.
 
 This changes the failure mode from "the board becomes unreachable" to "the
 display service restarts". It is a safety net, not a fix.
@@ -79,14 +76,6 @@ plugins that poll infrequently.
 Environment=LEDMATRIX_CACHE_MAX_ENTRIES=75
 ```
 
-Writing the file does not change the running service. Reload systemd and
-restart it:
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl restart ledmatrix
-```
-
 Fewer entries means more API calls, so lower this only while you are actually
 short of memory.
 

docs/SSH_UNAVAILABLE_AFTER_INSTALL.md

@@ -26,7 +26,7 @@ On a 512MB or 1GB board, memory exhaustion stops `sshd` being able to fork a
 session process. The connection is accepted and then closed immediately, before
 any banner:
 
-```text
+```
 kex_exchange_identification: Connection closed by remote host
 ```
 
@@ -205,23 +205,11 @@ The web interface allows you to:
 
 ## Summary
 
-**SSH becomes unavailable because** — two unrelated causes, and they need
+**SSH becomes unavailable because**:
-different responses:
-
-*AP mode (most common):*
 - WiFi monitor service enables AP mode when WiFi disconnects
 - AP mode switches WiFi from client to access point mode
 - Pi loses connection to your original network
 
-*Memory exhaustion (low-memory boards):*
-- The board runs out of memory, so `sshd` cannot fork a session process
-- The connection is accepted and closed before any banner
-- Ping still answers and the web UI still responds, so it looks healthy
-- The panel is usually dark and the service cannot restart
-- **Only a power cycle clears this** — there is no remote recovery, because
-  every remote route needs a new process
-- Prevention and tuning: [LOW_MEMORY_BOARDS.md](LOW_MEMORY_BOARDS.md)
-
 **To regain SSH**:
 1. Connect to **LEDMatrix-Setup** AP network (password: `ledmatrix123`)
 2. SSH to `192.168.4.1`

first_time_install.sh

@@ -1694,24 +1694,12 @@ fi
 # a runaway takes the whole board down (sshd can no longer fork, the panel goes
 # dark) rather than just restarting the one service.
 if [ "$SKIP_PERF" != "1" ] && [ -f "$CMDLINE_FILE" ]; then
-    # Both parameters are required for the memory controller, and they can get
+    if grep -q 'cgroup_enable=memory' "$CMDLINE_FILE"; then
-    # separated -- an image, another tool or a half-applied earlier run can
+        echo "cgroup_enable=memory already present in $CMDLINE_FILE"
-    # leave one without the other. Checking only cgroup_enable=memory would
-    # report success while MemoryMax= silently does nothing, so each is checked
-    # and appended independently.
-    cgroup_missing=""
-    for cgroup_param in cgroup_enable=memory cgroup_memory=1; do
-        if ! grep -qw "$cgroup_param" "$CMDLINE_FILE"; then
-            cgroup_missing="$cgroup_missing $cgroup_param"
-        fi
-    done
-    if [ -z "$cgroup_missing" ]; then
-        echo "cgroup memory parameters already present in $CMDLINE_FILE"
     else
-        echo "Adding${cgroup_missing} to $CMDLINE_FILE..."
+        echo "Adding cgroup_enable=memory to $CMDLINE_FILE..."
         cp "$CMDLINE_FILE" "$CMDLINE_FILE.bak" 2>/dev/null || true
-        # The kernel command line must stay on one line.
+        sed -i '1 s/$/ cgroup_enable=memory cgroup_memory=1/' "$CMDLINE_FILE"
-        sed -i "1 s|\$|${cgroup_missing}|" "$CMDLINE_FILE"
         echo "  Takes effect after reboot. Verify with:"
         echo "    grep memory /sys/fs/cgroup/cgroup.controllers"
     fi
@@ -1721,59 +1709,20 @@ fi
 # These images default to volatile storage: journald keeps everything in /run
 # (tmpfs), so every reboot destroys the logs — including the ones that would
 # explain why the board rebooted. Capped so an SD card is not worn out by logs.
-# A non-empty /var/log/journal does not prove journald is configured the way
+if [ -d /var/log/journal ] && [ -n "$(ls -A /var/log/journal 2>/dev/null)" ]; then
-# this needs: the directory survives a switch back to volatile storage, and it
+    echo "Persistent journald storage already enabled"
-# says nothing about whether a size cap is set. Read the effective
-# configuration instead, and only write the keys the user has not set
-# themselves so an explicit local limit is preserved.
-journald_effective() {
-    # systemd-analyze merges journald.conf with every drop-in; grep is the
-    # fallback for images that ship without it.
-    if command -v systemd-analyze >/dev/null 2>&1 &&
-       systemd-analyze cat-config systemd/journald.conf >/dev/null 2>&1; then
-        systemd-analyze cat-config systemd/journald.conf 2>/dev/null
-    else
-        cat /etc/systemd/journald.conf /etc/systemd/journald.conf.d/*.conf 2>/dev/null
-    fi
-}
-journald_conf="$(journald_effective)"
-journald_storage="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]')"
-journald_cap="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*SystemMaxUse=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]')"
-
-if [ "$journald_storage" = "persistent" ] && [ -n "$journald_cap" ]; then
-    echo "Persistent journald storage already configured (SystemMaxUse=$journald_cap)"
 else
     echo "Enabling persistent journald storage..."
     mkdir -p /etc/systemd/journald.conf.d
-    {
+    cat > /etc/systemd/journald.conf.d/ledmatrix-persistent.conf <<'JOURNALD'
-        echo "# Installed by LEDMatrix first_time_install.sh"
+# Installed by LEDMatrix first_time_install.sh
-        echo "[Journal]"
+[Journal]
-        echo "Storage=persistent"
+Storage=persistent
-        if [ -n "$journald_cap" ]; then
+SystemMaxUse=64M
-            echo "# SystemMaxUse left to your existing setting ($journald_cap)"
+JOURNALD
-        else
-            # Capped so logs cannot wear out or fill an SD card.
-            echo "SystemMaxUse=64M"
-        fi
-    } > /etc/systemd/journald.conf.d/ledmatrix-persistent.conf
     mkdir -p /var/log/journal
     systemd-tmpfiles --create --prefix /var/log/journal >/dev/null 2>&1 || true
     systemctl restart systemd-journald >/dev/null 2>&1 || true
-
-    # Drop-ins are applied in lexical order, so a locally added file that sorts
-    # after ledmatrix-persistent.conf (zz-local.conf and friends) still wins.
-    # Writing the file is not evidence it took effect -- re-read and say so
-    # plainly rather than reporting success we cannot confirm.
-    journald_now="$(journald_effective | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]')"
-    if [ "$journald_now" = "persistent" ]; then
-        echo "  Persistent journald storage active"
-    else
-        echo "  WARNING: journald storage is still '${journald_now:-unset}' after"
-        echo "  writing /etc/systemd/journald.conf.d/ledmatrix-persistent.conf."
-        echo "  Another drop-in that sorts later is overriding it. Check:"
-        echo "    systemd-analyze cat-config systemd/journald.conf | grep -n Storage="
-        echo "  Logs will not survive a reboot until that is resolved."
-    fi
 fi
 
 # Ensure dtparam=audio=off in config.txt (idempotent)

scripts/install/configure_wifi_permissions.sh

@@ -37,10 +37,6 @@ echo "  systemctl: $SYSTEMCTL_PATH"
 echo ""
 echo "Step 1: Configuring sudo permissions for nmcli..."
 SUDOERS_FILE="/etc/sudoers.d/ledmatrix_wifi"
-SYSCTL_PATH=$(command -v sysctl || echo /usr/sbin/sysctl)
-NFT_PATH=$(command -v nft || echo /usr/sbin/nft)
-RFKILL_PATH=$(command -v rfkill || echo /usr/sbin/rfkill)
-MKDIR_PATH=$(command -v mkdir || echo /usr/bin/mkdir)
 
 # Create a temporary sudoers file using mktemp (handles permissions better)
 TEMP_SUDOERS=$(mktemp) || {
@@ -66,36 +62,6 @@ $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start dnsmasq
 $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop dnsmasq
 $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart dnsmasq
 $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart NetworkManager
-# The captive portal turns IP forwarding on while the access point is up and
-# restores the previous value when it comes down (wifi_manager._setup_iptables_
-# redirect / _teardown_iptables_redirect). Without this rule that sudo call
-# needs a password, so forwarding stays off and clients associate to the AP but
-# cannot route. It goes unnoticed on a stock Raspberry Pi image, where
-# /etc/sudoers.d/010_pi-nopasswd grants the default user blanket NOPASSWD and
-# masks every gap in this file -- it only bites once that blanket rule is
-# removed.
-$WEB_USER ALL=(ALL) NOPASSWD: $SYSCTL_PATH -w net.ipv4.ip_forward=0
-$WEB_USER ALL=(ALL) NOPASSWD: $SYSCTL_PATH -w net.ipv4.ip_forward=1
-# The portal's redirect lives in its own nftables table, created when the AP
-# comes up and deleted when it goes down, and the radio has to be unblocked
-# before the AP can start at all. Same story as the sysctl rules above: called
-# with sudo, never granted here, and invisible on a stock Pi image.
-$WEB_USER ALL=(ALL) NOPASSWD: $NFT_PATH add table ip ledmatrix
-$WEB_USER ALL=(ALL) NOPASSWD: $NFT_PATH delete table ip ledmatrix
-$WEB_USER ALL=(ALL) NOPASSWD: $RFKILL_PATH unblock wifi
-# NetworkManager's dnsmasq drop-in directory, exact path.
-$WEB_USER ALL=(ALL) NOPASSWD: $MKDIR_PATH -p /etc/NetworkManager/dnsmasq-shared.d
-#
-# iptables is deliberately NOT granted here. Its rules are built from the live
-# interface name and port, so a rule covering them needs a trailing wildcard --
-# and `iptables --modprobe=/path/to/anything` runs that path as root, so
-# `NOPASSWD: iptables *` is a root shell for the web user by another name. That
-# is a worse outcome than the gap it would close, which today is masked anyway
-# by the blanket NOPASSWD rule on stock Pi images.
-#
-# Closing it safely means a wrapper script that builds the rules itself and
-# takes only an interface and a port, granted the way safe_plugin_rm.sh already
-# is. That belongs in its own change rather than being smuggled into this one.
 
 # Allow copying hostapd and dnsmasq config files into place
 $WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/hostapd.conf /etc/hostapd/hostapd.conf

src/cache/memory_cache.py

@@ -134,32 +134,6 @@ class MemoryCache:
         with self._lock:
             self._cache[key] = value
             self._timestamps[key] = time.time()
-            # Enforce the ceiling here rather than leaving it to the periodic
-            # cleanup, which only runs every cleanup_interval seconds (300 by
-            # default). A burst of inserts between two sweeps could otherwise
-            # take the cache far past _max_size, which is the memory growth this
-            # limit exists to prevent -- and on a 1GB board that is the
-            # difference between a bounded cache and an unreachable Pi.
-            self._evict_over_limit_locked()
-
-    def _evict_over_limit_locked(self) -> int:
-        """Drop oldest entries until the cache is within _max_size.
-
-        Caller must hold self._lock. Returns the number of entries removed.
-        """
-        excess = len(self._cache) - self._max_size
-        if excess <= 0:
-            return 0
-        oldest = sorted(
-            self._timestamps.items(),
-            key=lambda item: float(item[1]) if isinstance(item[1], (int, float)) else 0.0
-        )
-        removed = 0
-        for key, _ in oldest[:excess]:
-            self._cache.pop(key, None)
-            self._timestamps.pop(key, None)
-            removed += 1
-        return removed
     
     def clear(self, key: Optional[str] = None) -> None:
         """
@@ -216,8 +190,22 @@ class MemoryCache:
                 self._timestamps.pop(key, None)
                 removed_count += 1
             
-            # Same ceiling enforcement set() uses, so the two cannot drift.
+            # Enforce size limit by removing oldest entries if cache is too large
-            removed_count += self._evict_over_limit_locked()
+            if len(self._cache) > self._max_size:
+                # Sort by timestamp (oldest first)
+                sorted_entries = sorted(
+                    self._timestamps.items(),
+                    key=lambda x: float(x[1]) if isinstance(x[1], (int, float)) else 0
+                )
+                
+                # Remove oldest entries until we're under the limit
+                excess_count = len(self._cache) - self._max_size
+                for i in range(excess_count):
+                    if i < len(sorted_entries):
+                        key = sorted_entries[i][0]
+                        self._cache.pop(key, None)
+                        self._timestamps.pop(key, None)
+                        removed_count += 1
             
             self._last_cleanup = current_time
             

src/plugin_system/plugin_health.py

@@ -7,7 +7,7 @@ and circuit breaker state. Provides automatic recovery mechanisms.
 
 import time
 import logging
-from typing import Dict, Optional, Any, Tuple
+from typing import Dict, Optional, Any
 from enum import Enum
 
 
@@ -65,47 +65,20 @@ class PluginHealthTracker:
         )
 
         if isinstance(cached, dict) and cached:
-            # Complete it rather than trusting it: a persisted record can be
+            return cached
-            # missing fields the callers index directly (a partial write, a
-            # restored backup, an older schema), and returning it verbatim makes
-            # record_success / record_failure raise KeyError, which takes the
-            # display down in a restart loop that survives reboots because the
-            # bad entry is on disk.
-            state, repaired = self._repair_health_state(cached)
-            if repaired:
-                self.logger.warning(
-                    f"Repaired health state for {plugin_id}: "
-                    f"{sorted(repaired)} missing or invalid, using defaults for those."
-                )
-            return state
 
-        # Not a dict at all: written by something other than
+        # A cache entry that is not a dict means the persisted state was written
-        # _save_health_state (a key collision, a corrupted entry). Nothing to
+        # by something other than _save_health_state (a key collision, a partial
-        # salvage.
+        # write, a restored backup). Returning it verbatim makes every caller
+        # blow up on .get(), which takes the display down in a restart loop that
+        # survives reboots because the bad entry is on disk. Discard and rebuild.
         if cached is not None and not isinstance(cached, dict):
             self.logger.warning(
                 f"Discarding malformed health state for {plugin_id}: expected "
                 f"dict, got {type(cached).__name__}. Falling back to defaults."
             )
         
-        return self._default_health_state()
+        # Default state
-    
-    def _save_health_state(self, plugin_id: str, state: Dict[str, Any]) -> None:
-        """Save health state to cache."""
-        cache_key = self._get_health_key(plugin_id)
-        self.cache_manager.set(cache_key, state)  # Persist indefinitely
-        self._health_state[plugin_id] = state
-    
-    # The fields callers index directly (state['circuit_state'] and friends).
-    # A cached dict missing any of them raises KeyError deep in record_success /
-    # record_failure, so the value is completed before it is handed out.
-    _COUNTER_FIELDS = ('consecutive_failures', 'total_failures', 'total_successes')
-    _TIMESTAMP_FIELDS = ('last_success_time', 'last_failure_time',
-                         'circuit_opened_time', 'half_open_start_time')
-
-    @staticmethod
-    def _default_health_state() -> Dict[str, Any]:
-        """A fresh state with every field the callers expect."""
         return {
             'consecutive_failures': 0,
             'total_failures': 0,
@@ -115,55 +88,14 @@ class PluginHealthTracker:
             'circuit_state': CircuitState.CLOSED.value,
             'circuit_opened_time': None,
             'half_open_start_time': None,
-            'last_error': None,
+            'last_error': None
         }
     
-    @classmethod
+    def _save_health_state(self, plugin_id: str, state: Dict[str, Any]) -> None:
-    def _repair_health_state(cls, cached: Dict[str, Any]) -> Tuple[Dict[str, Any], list]:
+        """Save health state to cache."""
-        """Return `cached` completed against the defaults, plus what was repaired.
+        cache_key = self._get_health_key(plugin_id)
-
+        self.cache_manager.set(cache_key, state)  # Persist indefinitely
-        Per-field rather than all-or-nothing: a record that has real failure
+        self._health_state[plugin_id] = state
-        counts but is missing `last_error` should keep the counts, not be reset
-        to healthy. Only values that are absent or the wrong type fall back to
-        the default, so a partial or older-schema record survives with whatever
-        it does carry, while every field the callers index is guaranteed present
-        and of a usable type.
-        """
-        state = cls._default_health_state()
-        repaired = []
-        for field, default in state.items():
-            if field not in cached:
-                repaired.append(field)
-                continue
-            value = cached[field]
-            if field in cls._COUNTER_FIELDS:
-                ok = isinstance(value, int) and not isinstance(value, bool) and value >= 0
-            elif field in cls._TIMESTAMP_FIELDS:
-                # bool is a subclass of int, so True would pass as a timestamp
-                # and then compare as 1.0 -- expiring a cooldown the instant it
-                # opens, or (False) making the elapsed check never fire.
-                ok = value is None or (
-                    isinstance(value, (int, float)) and not isinstance(value, bool)
-                )
-            elif field == 'circuit_state':
-                # Membership first requires the value to be hashable: a list or
-                # dict here would raise TypeError out of the repair itself,
-                # which is the crash this whole path exists to prevent.
-                ok = isinstance(value, str) and value in {
-                    member.value for member in CircuitState
-                }
-            else:  # last_error
-                ok = value is None or isinstance(value, str)
-            if ok:
-                state[field] = value
-            else:
-                repaired.append(field)
-        # Anything the schema has since grown (degraded, degraded_reason) is
-        # read with .get() by its callers, so carry it through untouched.
-        for field, value in cached.items():
-            if field not in state:
-                state[field] = value
-        return state, repaired
     
     def get_health_state(self, plugin_id: str, force_reload: bool = False) -> Dict[str, Any]:
         """Get current health state for a plugin.

src/plugin_system/plugin_loader.py

@@ -75,30 +75,14 @@ def _extra_dependencies(dist_name: str, extras) -> Optional[List[Requirement]]:
     return gated
 
 
-def _extras_are_satisfied(req: Requirement, _visited: Optional[set] = None) -> bool:
+def _extras_are_satisfied(req: Requirement) -> bool:
     """Check the dependencies pulled in by req's extras are installed.
 
-    Follows extras through nested extras. A gated dependency can itself request
+    One level deep, not transitive: enough to tell "the extra was installed"
-    one (`requests[socks]`), and checking only that `requests` is installed at
+    from "the extra was never installed", which is all the caller needs to
-    an acceptable version says nothing about whether the socks extra's own
+    decide whether pip has work to do. Anything unreadable returns False, so
-    dependency is there -- so the caller would skip pip and the plugin would
+    the caller still falls through to pip.
-    fail at import instead. Plain dependencies are still checked one level
-    deep, which is all that is needed to tell "the extra was installed" from
-    "the extra was never installed".
-
-    `_visited` carries the (distribution, extras) pairs already seen, so a
-    dependency cycle between extras terminates instead of recursing forever.
-    Anything unreadable returns False, so the caller still falls through to pip.
     """
-    if _visited is None:
-        _visited = set()
-    marker = (req.name.lower(), frozenset(e.lower() for e in req.extras))
-    if marker in _visited:
-        # Already accounted for higher up the chain; treating a cycle as
-        # satisfied here is safe because the outer frame still has to pass.
-        return True
-    _visited.add(marker)
-
     gated = _extra_dependencies(req.name, req.extras)
     if gated is None:
         return False
@@ -110,8 +94,6 @@ def _extras_are_satisfied(req: Requirement, _visited: Optional[set] = None) -> b
             return False
         if dep.specifier and not dep.specifier.contains(dep_version, prereleases=True):
             return False
-        if dep.extras and not _extras_are_satisfied(dep, _visited):
-            return False
     return True
 
 

src/startup_validator.py

@@ -63,9 +63,6 @@ class StartupValidator:
         if self.plugin_manager:
             self._validate_plugins()
         
-        # Warn when the running systemd unit no longer matches the repo's
-        self._validate_systemd_units()
-        
         is_valid = len(self.errors) == 0
         
         if is_valid:
@@ -77,71 +74,6 @@ class StartupValidator:
         
         return (is_valid, self.errors.copy(), self.warnings.copy())
     
-    #: Units this project installs, and where each is installed to.
-    _UNITS = (
-        ("systemd/ledmatrix.service", "/etc/systemd/system/ledmatrix.service"),
-        ("systemd/ledmatrix-web.service", "/etc/systemd/system/ledmatrix-web.service"),
-    )
-
-    def _validate_systemd_units(self) -> None:
-        """Warn when an installed unit has drifted from the repo's template.
-
-        Nothing re-applies these after the first install. `git pull` -- which is
-        what the web UI's update button runs -- brings a new template into the
-        checkout, but nothing copies it to /etc/systemd/system and nothing runs
-        `systemctl daemon-reload`, so the unit that actually runs is whatever
-        first_time_install.sh wrote on day one.
-
-        That makes every hardening added to a unit inert on existing installs.
-        Measured on one rig: the installed unit was thirteen days older than the
-        repo's and differed in content, so a MemoryMax the repo had specified
-        was not being enforced at all -- `systemctl show` reported
-        MemoryMax=infinity.
-
-        A warning rather than an error, and certainly not a silent rewrite:
-        editing files under /etc and restarting services is the installer's job,
-        not something a display process should do to a machine while it boots.
-        The remedy is to re-run scripts/install/install_service.sh.
-        """
-        try:
-            project_root = Path(__file__).resolve().parent.parent
-            for template_rel, installed_path in self._UNITS:
-                template = project_root / template_rel
-                installed = Path(installed_path)
-                if not template.is_file() or not installed.is_file():
-                    continue
-
-                # The template carries placeholders the installer substitutes,
-                # so compare the substituted form rather than the raw file.
-                expected = template.read_text(encoding="utf-8")
-                expected = expected.replace("__PROJECT_ROOT_DIR__", str(project_root))
-                expected = expected.replace("__USER__", "root")
-
-                try:
-                    actual = installed.read_text(encoding="utf-8")
-                except PermissionError:
-                    continue
-
-                if self._unit_body(expected) != self._unit_body(actual):
-                    self.warnings.append(
-                        f"{installed.name} differs from {template_rel}; the "
-                        "installed unit is not refreshed by an update, so "
-                        "settings added to the template are not in effect. "
-                        "Re-run scripts/install/install_service.sh to apply them."
-                    )
-        except OSError as e:
-            self.logger.debug("Could not compare systemd units: %s", e)
-
-    @staticmethod
-    def _unit_body(text: str) -> str:
-        """A unit's meaningful lines: no comments, no blanks, no ordering noise."""
-        lines = []
-        for line in text.splitlines():
-            line = line.strip()
-            if line and not line.startswith("#"):
-                lines.append(line)
-        return "\n".join(sorted(lines))
-
     def _validate_config(self) -> None:
         """Validate configuration files."""
         try:

systemd/ledmatrix.service

@@ -8,18 +8,6 @@ Type=simple
 User=root
 WorkingDirectory=__PROJECT_ROOT_DIR__
 Environment=PYTHONDONTWRITEBYTECODE=1
-# glibc gives each allocating thread its own malloc arena, up to 8 x CPU count,
-# and an arena that has grown is never handed back to the OS. This process runs
-# 9 threads on a 3-core Pi, so the ceiling is 24 arenas -- and a rig measured at
-# 1030 MB resident held 23 large anonymous mappings on 64 MB-aligned addresses,
-# 920 MB of them, while the live data it was actually holding (widest scroll
-# strip seen: 35,746 x 64) accounts for roughly 15 MB. That gap is arena bloat,
-# not leaked objects: RSS was flat across repeated sampling, not climbing.
-#
-# Capping the arenas trades a little allocator concurrency for a large amount of
-# resident memory on a device that has neither to spare. 2 is the usual value;
-# raise it if frame times regress.
-Environment=MALLOC_ARENA_MAX=2
 ExecStart=/usr/bin/python3 __PROJECT_ROOT_DIR__/run.py
 # Restart=always, not on-failure: run.py exiting 0 (a clean shutdown path taken
 # for a reason that no longer applies, e.g. a config reload) would otherwise leave

test/test_cache_manager.py

@@ -458,26 +458,3 @@ class TestDiskCacheWriteEconomy:
         cache = DiskCache(cache_dir=str(tmp_path))
         cache.set("k", {"when": datetime(2026, 7, 12, 10, 30)})
         assert cache.get("k") == {"when": "2026-07-12T10:30:00"}
-
-
-# --- the ceiling has to hold between cleanup sweeps ---------------------------
-
-def test_memory_cache_enforces_ceiling_on_every_write():
-    """_cleanup_memory_cache only runs every cleanup_interval seconds (300 by
-    default). If set() accepted entries without bound in between, a burst could
-    take the cache far past max_size -- which is the unbounded growth the limit
-    exists to prevent, and on a 1GB board the difference between a bounded cache
-    and a Pi that cannot fork.
-    """
-    from src.cache.memory_cache import MemoryCache
-
-    cache = MemoryCache(max_size=150, cleanup_interval=300.0)
-    for i in range(1000):
-        cache.set(f"k{i}", {"v": i})
-
-    assert len(cache._cache) <= 150
-    # The timestamp map has to be evicted alongside the values, or it becomes
-    # the leak instead.
-    assert len(cache._timestamps) <= 150
-    assert cache.get("k999") is not None, "the newest write must survive"
-    assert cache.get("k0") is None, "the oldest must be the one evicted"

test/test_checkbox_group_stale_values.py

@@ -1,113 +0,0 @@
-"""A checkbox group must not post back options it cannot show.
-
-The enum that lets the widget draw checkboxes is also what validates the
-saved value. When a league retires a team code -- OAK for the Athletics, ARI
-for the Coyotes -- or a schema drops an option, a config that still holds the
-old value has nothing to render for it. The value stayed in the hidden
-``_data`` input regardless, because that input is seeded from the stored array
-and only rebuilt by ``updateCheckboxGroupData()`` on change. Editing any other
-field on that plugin therefore posted the stale value back, the schema
-rejected it, and the save endpoint returned 400
-``CONFIG_VALIDATION_FAILED`` -- so the whole plugin became uneditable until
-the user worked out which invisible entry was at fault.
-
-Runtime was never affected: plugin loading treats schema violations as
-warn/degrade, and the stale code already matched no team. Only the web UI
-blocked.
-
-These tests render the checkbox-group block lifted *out of the shipped
-template*, following test_enum_option_labels.py, so they exercise the
-production expression rather than a copy that could drift from it.
-"""
-import json
-import re
-from pathlib import Path
-
-from jinja2 import DictLoader, Environment
-
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-CONFIG_FORM = (PROJECT_ROOT / 'web_interface' / 'templates' / 'v3' / 'partials'
-               / 'plugin_config.html')
-
-# The checkbox-group branch: from its `{% elif %}` guard through the sentinel
-# hidden input that closes it. Anchored on the guard so the match cannot run on
-# into a neighbouring widget branch.
-BLOCK_RE = re.compile(
-    r"\{%\s*elif x_widget == 'checkbox-group'\s*%\}(.*?)"
-    r"<input type=\"hidden\" name=\"\{\{ full_key \}\}\[\]\" value=\"\">",
-    re.S,
-)
-
-
-def _shipped_block() -> str:
-    """Return the live checkbox-group block lifted from plugin_config.html."""
-    source = CONFIG_FORM.read_text(encoding='utf-8')
-    match = BLOCK_RE.search(source)
-    assert match, (
-        'could not find the checkbox-group block in plugin_config.html — the '
-        'template changed shape and this guard needs updating'
-    )
-    block = match.group(1)
-    assert 'data-option-value' in block, 'extracted the wrong branch'
-    assert '{% elif' not in block, 'extraction ran past the checkbox-group branch'
-    return block
-
-
-def _render(prop: dict, value=None) -> str:
-    env = Environment(loader=DictLoader({'f': _shipped_block()}), autoescape=True)
-    return env.get_template('f').render(
-        prop=prop, value=value, field_id='fid', full_key='k'
-    )
-
-
-def _submitted(html: str) -> list:
-    """The array the form will actually post: the hidden _data input."""
-    match = re.search(r'id="fid_data"[^>]*\svalue=\'([^\']*)\'', html)
-    assert match, f'hidden _data input not found in:\n{html}'
-    return json.loads(match.group(1).replace('&#39;', "'"))
-
-
-def _checked(html: str) -> list:
-    return re.findall(r'data-option-value="([^"]+)"[^>]*checked', html)
-
-
-MLB = {'type': 'array', 'items': {'type': 'string', 'enum': ['NYY', 'BOS', 'ATH']},
-       'x-widget': 'checkbox-group'}
-
-
-def test_a_retired_code_is_not_posted_back() -> None:
-    """The regression: OAK became ATH, and OAK used to ride along on save."""
-    html = _render(MLB, ['NYY', 'OAK'])
-    assert _submitted(html) == ['NYY'], 'stale value would still be submitted'
-
-
-def test_the_dropped_value_is_named_rather_than_vanishing() -> None:
-    html = _render(MLB, ['NYY', 'OAK'])
-    assert 'OAK' in html
-    assert 'data-stale-options' in html
-
-
-def test_valid_values_are_untouched_and_still_checked() -> None:
-    html = _render(MLB, ['NYY', 'ATH'])
-    assert _submitted(html) == ['NYY', 'ATH']
-    assert sorted(_checked(html)) == ['ATH', 'NYY']
-    assert 'data-stale-options' not in html
-
-
-def test_an_all_stale_selection_clears_rather_than_blocking() -> None:
-    html = _render(MLB, ['OAK', 'SD'])
-    assert _submitted(html) == []
-
-
-def test_an_empty_enum_leaves_the_value_alone() -> None:
-    """No options means nothing to validate against — filtering would wipe it."""
-    prop = {'type': 'array', 'items': {'type': 'string'}, 'x-widget': 'checkbox-group'}
-    html = _render(prop, ['ANYTHING', 'GOES'])
-    assert _submitted(html) == ['ANYTHING', 'GOES']
-
-
-def test_unset_value_falls_back_to_the_default() -> None:
-    prop = dict(MLB, default=['BOS'])
-    html = _render(prop, None)
-    assert _submitted(html) == ['BOS']
-    assert _checked(html) == ['BOS']

test/test_onboarding_checklist.py

@@ -1,241 +0,0 @@
-"""
-Getting Started checklist: what the server decides, and what it must not.
-
-The timezone step used to tick server-side when the saved timezone differed
-from the shipped default, OR-ed with the saved city. That made the step
-unsatisfiable for anyone genuinely in the default zone (the card nagged
-forever), and let a saved city tick it off while the timezone was still wrong.
-The step is now verified in the browser against its own zone, so the server's
-only job is to hand over the configured value and stay out of the decision.
-
-These tests pin that contract: the panel-size step still reflects config, the
-timezone step never pre-ticks, it carries the configured zone, and the city
-has no influence on it.
-"""
-
-import copy
-import re
-import sys
-from pathlib import Path
-from unittest.mock import MagicMock
-
-import pytest
-from flask import Flask
-
-PROJECT_ROOT = Path(__file__).parent.parent
-sys.path.insert(0, str(PROJECT_ROOT))
-
-BASE_CONFIG = {
-    "timezone": "America/New_York",
-    "location": {"city": "Tampa", "state": "Florida", "country": "US"},
-    "display": {
-        "hardware": {"rows": 32, "cols": 64, "chain_length": 2, "parallel": 1},
-        "runtime": {},
-        "double_sided": {"enabled": False},
-        "vegas_scroll": {"plugin_order": [], "excluded_plugins": []},
-        "plugin_rotation_order": [],
-    },
-    "plugin_system": {},
-    "schedule": {},
-    "dim_schedule": {},
-    "sync": {},
-}
-
-
-def render(config):
-    """Render the overview partial against one config, as app.py would."""
-    base = PROJECT_ROOT / "web_interface"
-    app = Flask(
-        __name__,
-        template_folder=str(base / "templates"),
-        static_folder=str(base / "static"),
-    )
-    app.config["TESTING"] = True
-
-    from web_interface.blueprints import pages_v3 as pv
-
-    # pages_v3 is a module-level singleton shared across the test process;
-    # restore whatever the previous test left on it.
-    original_cm = getattr(pv.pages_v3, "config_manager", None)
-    original_pm = getattr(pv.pages_v3, "plugin_manager", None)
-
-    mock_cm = MagicMock()
-    mock_cm.load_config.return_value = config
-    mock_cm.get_raw_file_content.return_value = config
-    pv.pages_v3.config_manager = mock_cm
-
-    mock_pm = MagicMock()
-    mock_pm.plugins = {}
-    mock_pm.get_all_plugin_info.return_value = []
-    mock_pm.get_plugin_display_modes.side_effect = lambda pid: []
-    pv.pages_v3.plugin_manager = mock_pm
-
-    app.register_blueprint(pv.pages_v3, url_prefix="")
-    try:
-        resp = app.test_client().get("/partials/overview")
-        assert resp.status_code == 200, resp.status_code
-        return resp.get_data(as_text=True)
-    finally:
-        pv.pages_v3.config_manager = original_cm
-        pv.pages_v3.plugin_manager = original_pm
-
-
-def timezone_step(body):
-    """The checklist <button> for the timezone step."""
-    match = re.search(r"<button[^>]*data-check=\"timezone\"[^>]*>", body)
-    assert match, "timezone step not found in the rendered checklist"
-    return match.group(0)
-
-
-def config_with(**overrides):
-    config = copy.deepcopy(BASE_CONFIG)
-    for key, value in overrides.items():
-        config[key] = value
-    return config
-
-
-@pytest.mark.parametrize(
-    "timezone",
-    ["America/New_York", "America/Los_Angeles", "Europe/Madrid", "Asia/Kolkata"],
-)
-def test_timezone_step_never_pre_ticks_server_side(timezone):
-    """The browser owns this decision; the server must not pre-empt it.
-
-    The default zone is in the list deliberately: that is the case the old
-    default-comparison could never tick.
-    """
-    step = timezone_step(render(config_with(timezone=timezone)))
-    assert 'data-done="0"' in step, step
-
-
-@pytest.mark.parametrize(
-    "timezone",
-    ["America/New_York", "Europe/Madrid", "Pacific/Auckland"],
-)
-def test_timezone_step_carries_the_configured_zone(timezone):
-    """JS compares data-tz against the browser, so it has to be the real value."""
-    assert f'data-tz="{timezone}"' in timezone_step(render(config_with(timezone=timezone)))
-
-
-def test_city_does_not_influence_the_timezone_step():
-    """The coupling this change removes: city said nothing about the timezone,
-    and OR-ing it let a saved city tick the step off with the zone still wrong.
-
-    timezone_step() returns the opening tag only, so this compares the state
-    the step is in -- data-done and data-tz -- and not the label, which does
-    still show the configured city as context and so differs between the two.
-    """
-    tampa = timezone_step(render(config_with(
-        location={"city": "Tampa", "state": "Florida", "country": "US"})))
-    seattle = timezone_step(render(config_with(
-        location={"city": "Seattle", "state": "Washington", "country": "US"})))
-    assert tampa == seattle
-
-
-def test_missing_timezone_leaves_the_step_open():
-    """Nothing saved means nothing to verify: the step stays unticked and the
-    JS bails on the empty value rather than comparing against ''."""
-    step = timezone_step(render(config_with(timezone="")))
-    assert 'data-tz=""' in step
-    assert 'data-done="0"' in step
-
-
-def test_zone_comparison_asks_for_the_time_of_day():
-    """Guard on the Intl options, which look like a stylistic choice.
-
-    dateStyle/timeStyle are late additions (Firefox shipped them in 91). An
-    implementation that does not know them ignores them and formats the date
-    alone -- which compares New York, Chicago and Madrid as equal and ticks
-    the step for a timezone that is plainly wrong. Explicit numeric fields
-    have been in Intl since ECMA-402 v1.
-    """
-    template = (PROJECT_ROOT / "web_interface" / "templates" / "v3"
-                / "partials" / "overview.html").read_text()
-    body = template[template.index("function sameZone"):]
-    body = body[:body.index("}())")]
-    # The comment above the options names dateStyle/timeStyle to explain why
-    # they are not used, so match on code only.
-    body = "\n".join(line for line in body.splitlines()
-                     if not line.lstrip().startswith("//"))
-    assert "dateStyle" not in body and "timeStyle" not in body, (
-        "zone comparison must not depend on dateStyle/timeStyle")
-    for field in ("hour:", "minute:", "year:", "month:", "day:"):
-        assert field in body, f"zone comparison dropped {field!r}"
-
-
-def test_zone_comparison_samples_both_sides_of_dst():
-    """One instant is not enough, and the shortfall is invisible for months.
-
-    America/New_York and America/Lima hold the same offset all winter, so a
-    check against now alone ticks the step in January for a panel that runs an
-    hour off from March. The comparison has to sample instants either side of
-    DST -- mid-January and mid-July, which covers both hemispheres.
-    """
-    template = (PROJECT_ROOT / "web_interface" / "templates" / "v3"
-                / "partials" / "overview.html").read_text()
-    body = template[template.index("function sameZone"):]
-    body = body[:body.index("}())")]
-    code = "\n".join(line for line in body.splitlines()
-                     if not line.lstrip().startswith("//"))
-    assert "Date.UTC" in code, (
-        "zone comparison samples only the current instant, so zones that "
-        "coincide seasonally would read as equal")
-    assert code.count("Date.UTC") >= 2, "expected an instant either side of DST"
-
-
-def _stamp(zone, instant):
-    """The JS comparison's algorithm, for pinning what it must decide.
-
-    There is no JS runtime here (and the repo has no JS test infra), so this
-    mirrors sameZone rather than executing it: same instants, same wall-clock
-    equality. It records the verdicts the shipped code has to reach.
-    """
-    from zoneinfo import ZoneInfo
-    return instant.astimezone(ZoneInfo(zone)).strftime("%m/%d/%Y %H:%M")
-
-
-@pytest.mark.parametrize(
-    "left,right,equivalent",
-    [
-        # Aliases: one zone under two names.
-        ("Asia/Calcutta", "Asia/Kolkata", True),
-        ("Europe/Kiev", "Europe/Kyiv", True),
-        # Same rules year-round: either renders the same times, so a panel set
-        # to one and browsed from the other is correctly configured.
-        ("America/New_York", "America/Toronto", True),
-        # Coincide in winter only -- the case a single-instant check gets wrong.
-        ("America/New_York", "America/Lima", False),
-        ("America/Phoenix", "America/Los_Angeles", False),
-        ("Australia/Sydney", "Pacific/Guadalcanal", False),
-        # Plainly different.
-        ("America/New_York", "America/Chicago", False),
-        ("America/New_York", "Europe/Madrid", False),
-    ],
-)
-def test_which_zone_pairs_must_count_as_the_same(left, right, equivalent):
-    from datetime import datetime
-    from zoneinfo import ZoneInfo
-
-    year = 2026
-    instants = [datetime(year, 1, 15, 12, tzinfo=ZoneInfo("UTC")),
-                datetime(year, 7, 15, 12, tzinfo=ZoneInfo("UTC"))]
-    matched = all(_stamp(left, at) == _stamp(right, at) for at in instants)
-    assert matched is equivalent, (
-        f"{left} vs {right}: sampling both seasons gave {matched}")
-
-
-@pytest.mark.parametrize(
-    "hardware,expected",
-    [
-        ({"rows": 32, "cols": 64, "chain_length": 2, "parallel": 1}, "1"),
-        ({"rows": 0, "cols": 0, "chain_length": 0, "parallel": 1}, "0"),
-    ],
-)
-def test_panel_size_step_still_reflects_config(hardware, expected):
-    """Regression guard: the hardware step is still decided server-side."""
-    config = config_with()
-    config["display"]["hardware"] = hardware
-    body = render(config)
-    match = re.search(r"<button[^>]*data-tab=\"display\"[^>]*>", body)
-    assert match, "panel-size step not found"
-    assert f'data-done="{expected}"' in match.group(0), match.group(0)

test/test_plugin_health.py

@@ -91,101 +91,3 @@ def test_force_reload_refreshes_stale_in_memory_snapshot():
 
     # and it asked the cache to bypass the in-memory tier (memory_ttl=0).
     assert any(c.kwargs.get("memory_ttl") == 0 for c in cache.get.call_args_list)
-
-
-# --- persisted state that does not match the current schema -------------------
-#
-# A record on disk can be missing fields the callers index directly: a partial
-# write, a restored backup, or a state written by an older schema. Returning it
-# verbatim raises KeyError inside record_success / record_failure, which takes
-# the display down in a restart loop that survives reboots, because the bad
-# entry is on disk and gets read again on the way back up. Observed in the wild
-# as `plugin clock-simple operation failed: 'circuit_state'`, repeating ~50x a
-# minute with the panel frozen.
-
-_INDEXED_FIELDS = (
-    "consecutive_failures", "total_failures", "total_successes",
-    "last_success_time", "last_failure_time", "circuit_state",
-    "circuit_opened_time", "half_open_start_time", "last_error",
-)
-
-
-def _tracker_reading(persisted):
-    cache = _cache()
-    cache.get.return_value = persisted
-    return PluginHealthTracker(cache)
-
-
-def test_partial_state_is_completed_not_returned_raw():
-    """The shape seen in the wild: one field, everything else absent."""
-    state = _tracker_reading({"circuit_state": "closed"}).get_health_state("p")
-    for field in _INDEXED_FIELDS:
-        assert field in state, f"{field} missing; callers index it directly"
-
-
-def test_repair_keeps_real_failure_history():
-    """A record with genuine counts must not be reset to healthy just because
-    an optional field is absent -- that would clear a tripped breaker."""
-    state = _tracker_reading({
-        "consecutive_failures": 5,
-        "total_failures": 5,
-        "circuit_state": "open",
-    }).get_health_state("p")
-    assert state["consecutive_failures"] == 5
-    assert state["total_failures"] == 5
-    assert state["circuit_state"] == "open"
-
-
-def test_wrong_types_fall_back_per_field():
-    """A counter persisted as a string would pass a membership check and then
-    fail on the first += 1; an unknown circuit_state would take a branch the
-    breaker has no handling for."""
-    state = _tracker_reading({
-        "consecutive_failures": "3",
-        "circuit_state": "melted",
-        "total_failures": 7,
-    }).get_health_state("p")
-    assert state["consecutive_failures"] == 0
-    assert state["circuit_state"] == CircuitState.CLOSED.value
-    assert state["total_failures"] == 7, "valid neighbours must survive"
-
-
-def test_newer_fields_are_carried_through():
-    """degraded/degraded_reason are read with .get() and are not part of the
-    indexed set; repairing must not drop them."""
-    state = _tracker_reading({
-        "circuit_state": "closed", "degraded": True, "degraded_reason": "x",
-    }).get_health_state("p")
-    assert state["degraded"] is True
-    assert state["degraded_reason"] == "x"
-
-
-def test_recording_against_a_repaired_state_does_not_raise():
-    """The actual failure: record_failure indexing a field that was not there.
-
-    The seed deliberately omits circuit_state. Seeding a record that *has* it
-    would pass against the old raw-return behaviour too -- the counters are
-    read with .get(), so circuit_state is the only field whose absence used to
-    raise.
-    """
-    tracker = _tracker_reading({"total_failures": 2, "total_successes": 1})
-    tracker.record_failure("p", Exception("boom"))
-    tracker.record_success("p")
-
-
-def test_unhashable_or_boolean_values_are_repaired():
-    """Values that break the repair itself rather than a later caller.
-
-    An unhashable circuit_state raises TypeError inside a set membership test,
-    and bool is a subclass of int, so True would pass as a timestamp and then
-    compare as 1.0 -- expiring a cooldown the moment it opens.
-    """
-    for bad_state in ({"circuit_state": []}, {"circuit_state": {}}):
-        state = _tracker_reading(bad_state).get_health_state("p")
-        assert state["circuit_state"] == CircuitState.CLOSED.value
-
-    state = _tracker_reading({
-        "circuit_opened_time": True, "last_success_time": False,
-    }).get_health_state("p")
-    assert state["circuit_opened_time"] is None
-    assert state["last_success_time"] is None

test/test_sudo_allowlist_covers_calls.py

@@ -1,120 +0,0 @@
-"""The captive portal's fixed-argument sudo calls must be granted.
-
-The installers write two allow-lists, /etc/sudoers.d/ledmatrix_web and
-ledmatrix_wifi. A sudo call absent from both needs a password, which a service
-cannot supply, so it fails.
-
-Four such calls were ungranted, all of them captive-portal teardown/setup:
-
-    sysctl -w net.ipv4.ip_forward=0|1     wifi_manager.py:788, 883
-    nft add|delete table ip ledmatrix     wifi_manager.py:835, 895
-    rfkill unblock wifi                   wifi_manager.py:1811
-    mkdir -p .../dnsmasq-shared.d         wifi_manager.py:922
-
-It goes unnoticed because a stock Raspberry Pi image ships
-/etc/sudoers.d/010_pi-nopasswd granting the default user
-`ALL=(ALL) NOPASSWD: ALL`, which satisfies every gap in both files. It only
-bites once that blanket rule is removed or the service runs as another user.
-
-Scope, deliberately narrow: this pins the four commands above, each of which
-can be written out literally. The portal makes further sudo calls whose
-arguments are built at runtime -- iptables and nft rules carrying an interface
-name and a port, `ip addr`, `ip link` -- and those cannot be granted safely
-here. A rule covering them needs a trailing wildcard, and
-`iptables --modprobe=/path/to/anything` runs that path as root, so
-`NOPASSWD: iptables *` is a root shell for the web user by another name.
-Closing that half needs a privileged helper that builds the rules itself and
-takes only an interface and a port, granted the way safe_plugin_rm.sh already
-is. That is a design decision, not a one-line grant, and belongs in its own
-change.
-"""
-import re
-from pathlib import Path
-
-import pytest
-
-ROOT = Path(__file__).resolve().parent.parent
-INSTALLERS = (
-    ROOT / "first_time_install.sh",
-    ROOT / "scripts" / "install" / "configure_wifi_permissions.sh",
-)
-
-#: Commands this change grants, each fully literal in the source.
-REQUIRED = (
-    ("sysctl", "-w", "net.ipv4.ip_forward=0"),
-    ("sysctl", "-w", "net.ipv4.ip_forward=1"),
-    ("nft", "add", "table", "ip", "ledmatrix"),
-    ("nft", "delete", "table", "ip", "ledmatrix"),
-    ("rfkill", "unblock", "wifi"),
-    ("mkdir", "-p", "/etc/NetworkManager/dnsmasq-shared.d"),
-)
-
-#: Tools with an option that executes a program of the caller's choosing.
-#: A trailing wildcard on any of these is a privilege escalation.
-EXEC_CAPABLE = ("iptables", "ip6tables", "nft", "tcpdump", "find", "awk",
-                "sed", "perl", "python", "python3", "env")
-
-
-def _grant_lines():
-    lines = []
-    for installer in INSTALLERS:
-        if not installer.is_file():
-            continue
-        for line in installer.read_text(encoding="utf-8", errors="replace").splitlines():
-            if "NOPASSWD:" in line:
-                lines.append(line.split("NOPASSWD:", 1)[1])
-    return lines
-
-
-def _normalised_grants():
-    """Grants with binary-path variables reduced to tool names.
-
-    Rules are written as `$SYSCTL_PATH -w ...`, so matching the literal
-    "sysctl" finds nothing and every rule looks absent -- which is exactly how
-    an earlier version of this test reported six gaps that did not exist.
-    Only NOPASSWD lines are considered, because taking the whole script let a
-    variable definition such as NFT_PATH=$(command -v nft) satisfy the check on
-    its own while the grant itself had been deleted.
-    """
-    text = "\n".join(_grant_lines())
-    text = re.sub(r"\$\{?([A-Z][A-Z0-9_]*)_PATH\}?", lambda m: m.group(1).lower(), text)
-    return re.sub(r"/usr/(?:s?bin)/", "", text)
-
-
-def test_the_installers_are_present():
-    missing = [str(p.relative_to(ROOT)) for p in INSTALLERS if not p.is_file()]
-    assert not missing, f"installer(s) missing: {missing}"
-
-
-@pytest.mark.parametrize("command", REQUIRED, ids=lambda c: " ".join(c))
-def test_the_command_is_granted(command):
-    """Whole command, not just the binary.
-
-    Checking only the binary made this far weaker than it looked: with
-    `sysctl` present anywhere, deleting the ip_forward=0 grant still passed,
-    and the portal would then be unable to restore forwarding on teardown.
-    """
-    pattern = r"\s+".join(re.escape(word) for word in command)
-    assert re.search(pattern, _normalised_grants()), (
-        f"no installer grants `{' '.join(command)}`")
-
-
-def test_no_wildcard_on_a_tool_that_can_exec():
-    """`NOPASSWD: iptables *` hands the web user root.
-
-    iptables --modprobe=/path runs that path as root. This caught a grant added
-    in this very change, which is why it is here.
-    """
-    offenders = []
-    for rule in _grant_lines():
-        rule = rule.strip()
-        if not rule.endswith("*"):
-            continue
-        haystack = rule.replace("_PATH", "").lower()
-        for tool in EXEC_CAPABLE:
-            if re.search(rf"(^|/|\s|\$){tool}(\s|$)", haystack):
-                offenders.append(rule)
-                break
-    assert not offenders, (
-        "wildcard grant on a tool that can execute another program:\n  "
-        + "\n  ".join(offenders))

test/test_systemd_malloc_arenas.py

@@ -1,95 +0,0 @@
-"""The display unit must cap glibc's malloc arenas.
-
-glibc hands each allocating thread its own malloc arena, up to 8 x CPU count,
-and an arena that has grown is never returned to the OS. This process runs
-threads for the render loop, the update workers and the background fetchers, so
-on a 3-core Pi the ceiling is 24 arenas.
-
-Measured on a live rig, 2.5 hours in:
-
-    RSS                 1030 MB
-    Private_Dirty        988 MB
-    anonymous mappings > 10 MB     23     (ceiling is 8 x 3 = 24)
-    largest few          104, 79, 66, 63, 63 MB, on 64 MB-aligned addresses
-
-against live data that accounts for perhaps 15 MB -- the widest scroll strip
-observed was 35,746 x 64, about 7 MB as RGB and the same again for its numpy
-mirror. Repeated sampling showed RSS flat between 990 and 1030 MB rather than
-climbing, so this is arena bloat rather than a leak: memory Python has freed
-but glibc is holding per-arena.
-
-The device had 59 MB free at the time.
-
-Capping the arena count trades a little allocator concurrency for that resident
-memory. The render loop is latency-sensitive, so if p99 frame time regresses the
-right response is to raise this rather than remove it.
-"""
-import re
-from pathlib import Path
-
-import pytest
-
-UNIT = (Path(__file__).resolve().parent.parent / "systemd" / "ledmatrix.service")
-
-#: The value the unit is expected to carry. 2 is the usual choice for a
-#: threaded Python process; 1-4 all keep some of the saving, but only one of
-#: them is what this project ships.
-EXPECTED_ARENA_MAX = 2
-
-
-def _environment(unit_text):
-    return dict(
-        line.split("=", 2)[1:3] if line.count("=") >= 2 else (line.split("=", 1)[1], "")
-        for line in unit_text.splitlines()
-        if line.startswith("Environment=")
-    )
-
-
-def test_the_unit_exists():
-    assert UNIT.is_file(), f"{UNIT} is missing"
-
-
-def test_malloc_arena_max_is_capped():
-    env = _environment(UNIT.read_text(encoding="utf-8"))
-    assert "MALLOC_ARENA_MAX" in env, (
-        "the display unit does not cap glibc arenas; on a 3-core Pi the default "
-        "ceiling is 24 and a measured rig held 23 of them, 920 MB"
-    )
-    value = int(env["MALLOC_ARENA_MAX"])
-    # Pinned, not a range. A range let a change to 4 -- which hands most of the
-    # saving back -- pass unnoticed, which was the point of the finding that
-    # prompted this. Raising it is a legitimate response to a frame-time
-    # regression, but it should be a visible edit here rather than a silent
-    # drift, so the number lives in one place and changing it shows up in
-    # review.
-    assert value == EXPECTED_ARENA_MAX, (
-        f"MALLOC_ARENA_MAX={value}, expected {EXPECTED_ARENA_MAX}. If this was "
-        "raised deliberately because frame times regressed, update "
-        "EXPECTED_ARENA_MAX here and say so in the commit."
-    )
-
-
-def test_the_reason_is_recorded_next_to_it():
-    """A bare tuning knob invites removal by whoever meets it next."""
-    text = UNIT.read_text(encoding="utf-8")
-    index = text.index("Environment=MALLOC_ARENA_MAX")
-    preamble = text[:index].splitlines()[-12:]
-    comment = "\n".join(line for line in preamble if line.startswith("#"))
-    assert "arena" in comment.lower(), "no explanation precedes the setting"
-    assert re.search(r"\d", comment), (
-        "the explanation cites no measurement, so a reader cannot tell whether "
-        "it still applies to their hardware"
-    )
-
-
-@pytest.mark.parametrize("unit", ["ledmatrix.service"])
-def test_the_unit_still_parses_as_ini(unit):
-    """systemd will refuse a malformed unit, and the panel stays dark."""
-    import configparser
-
-    path = UNIT.parent / unit
-    parser = configparser.ConfigParser(strict=False)
-    # systemd allows repeated keys; ConfigParser needs them merged, not rejected.
-    parser.read_string(path.read_text(encoding="utf-8"))
-    assert parser.has_section("Service")
-    assert parser.has_option("Service", "ExecStart")

test/test_systemd_unit_drift.py

@@ -1,133 +0,0 @@
-"""An installed unit that no longer matches the repo's must be reported.
-
-Nothing re-applies systemd units after the first install. `git pull` -- what
-the web UI's update button runs -- brings a new template into the checkout, but
-no code in web_interface/ or src/ copies it to /etc/systemd/system or runs
-`systemctl daemon-reload`. The unit that actually runs is whatever
-first_time_install.sh wrote on day one.
-
-So every hardening added to a unit is inert on existing installs. Measured on a
-live rig: the installed unit was dated 2026-08-06 and the repo's 2026-08-19,
-and they differed -- with the result that a MemoryMax=85% present in the repo's
-template was not being enforced at all. `systemctl show` reported
-MemoryMax=infinity.
-
-This is a warning, not an error, and deliberately not a silent rewrite:
-editing files under /etc and restarting services is the installer's job, not
-something a display process should do to a machine while it boots.
-"""
-import logging
-from pathlib import Path
-from unittest.mock import MagicMock
-
-import pytest
-
-from src.startup_validator import StartupValidator
-
-
-@pytest.fixture
-def validator():
-    v = StartupValidator(config_manager=MagicMock())
-    v.logger = logging.getLogger("test")
-    v.warnings = []
-    v.errors = []
-    return v
-
-
-def test_a_matching_unit_produces_no_warning(validator, tmp_path):
-    """The installed unit, substituted exactly as the installer would."""
-    project_root = Path("src/startup_validator.py").resolve().parent.parent
-    template_rel = "systemd/ledmatrix.service"
-    template = project_root / template_rel
-    if not template.is_file():
-        pytest.skip("repo unit template not present")
-
-    installed = tmp_path / "ledmatrix.service"
-    installed.write_text(
-        template.read_text(encoding="utf-8")
-        .replace("__PROJECT_ROOT_DIR__", str(project_root))
-        .replace("__USER__", "root"),
-        encoding="utf-8")
-
-    validator._UNITS = ((template_rel, str(installed)),)
-    validator._validate_systemd_units()
-    assert not validator.warnings, f"a matching unit warned: {validator.warnings}"
-    assert not validator.errors
-
-
-def test_comments_and_blank_lines_are_not_drift():
-    """Otherwise every comment the repo adds would look like a changed unit."""
-    a = "[Service]\n# explains a setting\nExecStart=/x\nRestart=always\n"
-    b = "[Service]\nExecStart=/x\n\nRestart=always\n"
-    assert StartupValidator._unit_body(a) == StartupValidator._unit_body(b)
-
-
-def test_a_changed_directive_is_drift():
-    a = "[Service]\nExecStart=/x\nMemoryMax=85%\n"
-    b = "[Service]\nExecStart=/x\n"
-    assert StartupValidator._unit_body(a) != StartupValidator._unit_body(b)
-
-
-def test_reordered_directives_are_not_drift():
-    """systemd does not care about order within a section, so neither should this."""
-    a = "[Service]\nExecStart=/x\nRestart=always\n"
-    b = "[Service]\nRestart=always\nExecStart=/x\n"
-    assert StartupValidator._unit_body(a) == StartupValidator._unit_body(b)
-
-
-def test_cosmetic_differences_do_not_warn(validator, tmp_path):
-    """Through the real comparison, not the helper.
-
-    The repo's template carries explanatory comments the installed copy may not
-    have, and the installer does not preserve ordering or blank lines. If those
-    counted as drift, every boot would warn and the warning would be ignored.
-    Asserting this on _unit_body alone would not catch a comparison that stopped
-    calling it -- which is exactly what a careless edit does.
-    """
-    project_root = Path("src/startup_validator.py").resolve().parent.parent
-    template_rel = "systemd/ledmatrix.service"
-    template = project_root / template_rel
-    if not template.is_file():
-        pytest.skip("repo unit template not present")
-
-    substituted = (template.read_text(encoding="utf-8")
-                   .replace("__PROJECT_ROOT_DIR__", str(project_root))
-                   .replace("__USER__", "root"))
-    # Same directives, stripped of comments and blank lines and reordered.
-    directives = sorted(line.strip() for line in substituted.splitlines()
-                        if line.strip() and not line.strip().startswith("#"))
-    installed = tmp_path / "ledmatrix.service"
-    installed.write_text("\n".join(reversed(directives)) + "\n", encoding="utf-8")
-
-    validator._UNITS = ((template_rel, str(installed)),)
-    validator._validate_systemd_units()
-    assert not validator.warnings, (
-        f"cosmetic-only difference reported as drift: {validator.warnings}")
-
-
-def test_drift_is_reported_as_a_warning(validator, tmp_path):
-    """The whole point: a real difference must surface, and only as a warning."""
-    installed = tmp_path / "ledmatrix.service"
-    installed.write_text("[Service]\nExecStart=/usr/bin/python3 /x/run.py\n")
-
-    project_root = Path("src/startup_validator.py").resolve().parent.parent
-    template_rel = "systemd/ledmatrix.service"
-    template = project_root / template_rel
-    if not template.is_file():
-        pytest.skip("repo unit template not present")
-
-    validator._UNITS = ((template_rel, str(installed)),)
-    validator._validate_systemd_units()
-
-    assert validator.warnings, "a differing unit produced no warning"
-    assert "install_service.sh" in validator.warnings[0], (
-        "the warning does not tell the user how to fix it")
-    assert not validator.errors, "drift must not be fatal at startup"
-
-
-def test_a_missing_installed_unit_is_silent(validator, tmp_path):
-    """Development checkouts have no /etc/systemd unit; that is not drift."""
-    validator._UNITS = (("systemd/ledmatrix.service", str(tmp_path / "absent.service")),)
-    validator._validate_systemd_units()
-    assert not validator.warnings
-    assert not validator.errors

web_interface/templates/v3/partials/overview.html

@@ -63,13 +63,13 @@
 
 <!-- Getting Started checklist: non-gating, dismissible (localStorage), items
      auto-check from existing config/endpoints — no new persisted state.
-     The timezone step is verified against the browser's own zone rather than
+     Known heuristic limits (acceptable, disclosed): values left at legitimate
-     compared to the shipped default; see the data-check="timezone" block below
+     defaults (e.g. a user actually in Tampa) read as "not done". -->
-     for why. -->
 {% set _hw = main_config.display.hardware if main_config and main_config.display else {} %}
 {% set _hw_done = (_hw.rows or 0) > 0 and (_hw.cols or 0) > 0 and (_hw.chain_length or 0) > 0 %}
 {% set _loc = main_config.location if main_config and main_config.location else {} %}
-{% set _tz = (main_config.timezone if main_config else '') or '' %}
+{% set _loc_done = (main_config.timezone and main_config.timezone != 'America/New_York')
+                   or (_loc.city and _loc.city != 'Tampa') %}
 <div id="getting-started-card" class="bg-blue-50 border border-blue-200 rounded-lg p-4 mb-4" style="display:none" role="region" aria-label="Getting started checklist">
     <div class="flex items-start justify-between">
         <div class="flex-1">
@@ -78,8 +78,8 @@
             <ul class="space-y-1 text-sm" id="getting-started-items">
                 <li><button type="button" class="gs-item text-left w-full" data-done="{{ '1' if _hw_done else '0' }}" data-tab="display">
                     <i class="far fa-square mr-2"></i>Set your panel size (Display tab)</button></li>
-                <li><button type="button" class="gs-item text-left w-full" data-done="0" data-check="timezone" data-tz="{{ _tz }}" data-tab="general">
+                <li><button type="button" class="gs-item text-left w-full" data-done="{{ '1' if _loc_done else '0' }}" data-tab="general">
-                    <i class="far fa-square mr-2"></i>Set your timezone{% if _tz %} — currently {{ _tz }}{% if _loc.city %}, {{ _loc.city }}{% endif %}{% endif %} (General tab)<span data-gs-tz-note class="text-xs"></span></button></li>
+                    <i class="far fa-square mr-2"></i>Set your timezone and location (General tab)</button></li>
                 <li><button type="button" class="gs-item text-left w-full" data-done="0" data-check="installed" data-tab="plugins">
                     <i class="far fa-square mr-2"></i>Install a plugin from the Plugin Store</button></li>
                 <li><button type="button" class="gs-item text-left w-full" data-done="0" data-check="enabled" data-tab="plugins">
@@ -165,91 +165,6 @@
     });
     maybeAutoHide();
 
-    // Timezone: verified against the browser's own zone.
-    //
-    // This step used to tick when the saved timezone differed from the value
-    // config.template.json ships (America/New_York), with the saved city
-    // OR-ed in. Two things were wrong with that. "Differs from the default"
-    // answers "did somebody edit this?", but what the checklist needs to know
-    // is whether the value is RIGHT — so anyone who genuinely lives in the
-    // default zone could never satisfy it and the card nagged forever. And
-    // the city has no bearing on whether the timezone is set: because the two
-    // were OR-ed, saving a city ticked the step off with the timezone still
-    // wrong, which is the direction that actually breaks displays (event
-    // times render in the wrong zone).
-    //
-    // The browser already knows its zone, so compare against that: no new
-    // persisted state, no network, and it catches the reverse case too — a
-    // panel still set to the old zone after a move now stays unticked, where
-    // the old test ticked it the moment the value stopped being the default.
-    function sameZone(a, b) {
-        if (a === b) return true;
-        // Compare the wall-clock time each zone yields, not the identifiers:
-        // aliases (Asia/Calcutta vs Asia/Kolkata, Europe/Kiev vs Europe/Kyiv)
-        // name one zone and must not read as a mismatch.
-        //
-        // Sampled at three instants, all of which have to agree. Checking only
-        // now is not enough: America/New_York and America/Lima hold the same
-        // offset all winter, so a panel set to the wrong one of those would
-        // tick in January and then run an hour off from March. Mid-January and
-        // mid-July sit either side of DST in both hemispheres, so only zones
-        // that agree year-round match -- while Toronto still matches New York,
-        // which is right, since either renders the same times.
-        try {
-            var now = new Date();
-            var year = now.getUTCFullYear();
-            var instants = [now,
-                            new Date(Date.UTC(year, 0, 15, 12)),
-                            new Date(Date.UTC(year, 6, 15, 12))];
-            var stamp = function (tz, at) {
-                // Explicit numeric fields rather than dateStyle/timeStyle:
-                // those are late additions to Intl (Firefox shipped them in
-                // 91), and an implementation that does not know them ignores
-                // them and formats the date alone. That would compare
-                // New York, Chicago and Madrid as equal and tick the step for
-                // a timezone that is plainly wrong -- the exact failure this
-                // check exists to catch. These options have been in Intl
-                // since ECMA-402 v1.
-                return new Intl.DateTimeFormat('en-US', {
-                    timeZone: tz, year: 'numeric', month: '2-digit',
-                    day: '2-digit', hour: '2-digit', minute: '2-digit',
-                    hour12: false
-                }).format(at);
-            };
-            for (var i = 0; i < instants.length; i++) {
-                if (stamp(a, instants[i]) !== stamp(b, instants[i])) {
-                    return false;
-                }
-            }
-            return true;
-        } catch (e) {
-            // An unparseable zone in the config is worth surfacing, not hiding.
-            return false;
-        }
-    }
-
-    (function () {
-        var tzBtn = card.querySelector('[data-check="timezone"]');
-        if (!tzBtn) return;
-        var configured = tzBtn.dataset.tz || '';
-        if (!configured) return;          // nothing saved yet: leave it open
-        var local = '';
-        try {
-            local = (Intl.DateTimeFormat().resolvedOptions().timeZone) || '';
-        } catch (e) {
-            return;                        // no Intl: leave it to the manual tick
-        }
-        if (!local) return;
-        if (sameZone(configured, local)) {
-            markDone(tzBtn);
-            return;
-        }
-        // Unticked on its own says "wrong" without saying why; name the zone
-        // the browser is in so the step is actionable.
-        var note = tzBtn.querySelector('[data-gs-tz-note]');
-        if (note) note.textContent = ' — this browser is in ' + local;
-    }());
-
     // Plugin-derived states from the existing installed-plugins endpoint.
     fetch('/api/v3/plugins/installed')
         .then(function (r) { return r.json(); })

web_interface/templates/v3/partials/plugin_config.html

@@ -296,26 +296,6 @@
                 {% set enum_items = items_schema.get('enum') or [] %}
                 {% set x_options = prop.get('x-options') or {} %}
                 {% set labels = x_options.get('labels') or {} %}
-                {# A saved value that is no longer one of the options -- a team
-                   code the league retired, an option dropped from the schema --
-                   has no checkbox to render, so it would sit unseen in the
-                   hidden input below and be posted back on save. The schema
-                   rejects it and the save endpoint returns 400, which blocks
-                   editing any other field on the plugin until the stale entry
-                   is found and removed. Drop them here instead, and say which,
-                   so the value is not lost silently. Only when the widget
-                   actually has options: an empty enum means nothing to check
-                   against, and filtering on it would wipe the field. #}
-                {% set stale_values = (array_value | reject('in', enum_items) | list) if enum_items else [] %}
-                {% set array_value = (array_value | select('in', enum_items) | list) if enum_items else array_value %}
-
-                {% if stale_values %}
-                <div class="mt-1 mb-2 rounded border border-amber-300 bg-amber-50 px-3 py-2 text-sm text-amber-800"
-                     data-stale-options="{{ field_id }}">
-                    No longer offered, and will be removed when you save:
-                    <span class="font-mono">{{ stale_values | join(', ') }}</span>.
-                </div>
-                {% endif %}
                 
                 <div class="mt-1 space-y-2">
                     {% for option in enum_items %}