fix(web): ask for the restart that makes an update take effect

The update button pulls new code and restarts nothing. There is no systemctl,
restart, reload or reboot anywhere in the 172-line git_pull handler -- it
stashes, pulls, installs changed requirements, re-removes plugins the user had
uninstalled, and returns "Code updated successfully."

Meanwhile both services go on running the code they loaded at boot. So the
display keeps rendering the old build, the web interface keeps serving the old
build, and the user is told the update worked. Nothing on screen suggests
otherwise, and the next reboot is what actually applies it -- whenever that is.

The affordance for this already exists: the restart-pending banner, raised
after main-config saves, with a Restart Now button wired to the display
service. A code update is a stronger reason to show it than a config save is.

The response now reports restart_required, and applyUpdate raises the banner
with wording for a code update rather than a config save. The banner's message
became a parameter and is persisted next to the flag, since it outlives the
page that raised it.

restart_required is only true when the pull actually moved HEAD. "Already up
to date" is a success too, and prompting after a no-op would train users to
dismiss the prompt unread.

This covers the display service, which is what the Restart Now button drives
and what users notice. The web interface still picks up its own new code on
its next restart; restarting it from inside a request it is serving is a
larger change than this one.

Reverting the flag fails the test that a pull which moved HEAD asks for a
restart. 290 tests pass.

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

src/backup_manager.py

@@ -111,12 +111,6 @@ class RestoreOptions:
     """Which sections of a backup should be restored."""
 
     restore_config: bool = True
-    #: Whether to take the backup's display.hardware block as well.
-    #: Off by default: that block describes the panel physically wired to
-    #: *this* device -- its size, chain length, mapping, multiplexing and
-    #: refresh cap. A backup carries the panel of the machine it was taken
-    #: on, and restoring one onto a different rig drives the wrong geometry.
-    restore_hardware: bool = False
     restore_secrets: bool = True
     restore_wifi: bool = True
     restore_fonts: bool = True
@@ -555,72 +549,6 @@ def _copy_file(src: Path, dst: Path) -> None:
         raise
 
 
-_HARDWARE_PATH = ("display", "hardware")
-
-
-def _restore_config_preserving_hardware(src: Path, dst: Path, keep_hardware: bool) -> None:
-    """Copy a backed-up config.json, optionally keeping the local panel block.
-
-    display.hardware describes the panel physically attached to this device:
-    cols, rows, chain_length, hardware_mapping, panel_type, multiplexing and
-    the refresh-rate cap. None of that travels with a configuration -- it is a
-    property of the machine. Restoring a backup taken on a 512x64 rig onto a
-    128x32 one used to overwrite the smaller panel's geometry with the larger
-    one's, which is not a setting the user can see going wrong; the display
-    simply stops being right.
-
-    Falls back to a plain copy when either file cannot be parsed, so a restore
-    never fails because of this.
-    """
-    if not keep_hardware:
-        _copy_file(src, dst)
-        return
-    try:
-        incoming = json.loads(src.read_text(encoding="utf-8"))
-        local = json.loads(dst.read_text(encoding="utf-8")) if dst.exists() else {}
-    except (OSError, ValueError) as exc:
-        logger.warning(
-            "[Backup] Could not merge local panel config (%s); restoring the "
-            "backup's config.json as-is", exc)
-        _copy_file(src, dst)
-        return
-
-    section, key = _HARDWARE_PATH
-    local_hw = (local.get(section) or {}).get(key)
-    if not isinstance(local_hw, dict) or not local_hw:
-        _copy_file(src, dst)
-        return
-
-    if not isinstance(incoming.get(section), dict):
-        incoming[section] = {}
-    incoming_hw = incoming[section].get(key)
-    incoming[section][key] = local_hw
-    if isinstance(incoming_hw, dict) and incoming_hw != local_hw:
-        logger.info(
-            "[Backup] Kept this device's display.hardware; the backup's panel "
-            "was %sx%s chain %s, this one is %sx%s chain %s",
-            incoming_hw.get("cols"), incoming_hw.get("rows"),
-            incoming_hw.get("chain_length"),
-            local_hw.get("cols"), local_hw.get("rows"),
-            local_hw.get("chain_length"))
-
-    # Write the merged result to a scratch file and hand it to _copy_file
-    # rather than renaming it into place here. _copy_file preserves the
-    # destination's mode and owner on purpose -- these config files are
-    # installed root-owned while the web interface that runs a restore is not
-    # root -- and a bare write would have replaced a root-owned config.json
-    # with one owned by the web user at whatever the umask allows.
-    scratch = dst.with_suffix(dst.suffix + ".merged-tmp")
-    try:
-        scratch.write_text(json.dumps(incoming, indent=2) + "\n", encoding="utf-8")
-        _copy_file(scratch, dst)
-    finally:
-        try:
-            scratch.unlink()
-        except OSError:
-            pass
-
-
 def restore_backup(
     zip_path: Path,
     project_root: Path,
@@ -656,9 +584,7 @@ def restore_backup(
         # Main config.
         if options.restore_config and (tmp_dir / _CONFIG_REL).exists():
             try:
-                _restore_config_preserving_hardware(
+                _copy_file(tmp_dir / _CONFIG_REL, project_root / _CONFIG_REL)
-                    tmp_dir / _CONFIG_REL, project_root / _CONFIG_REL,
-                    keep_hardware=not options.restore_hardware)
                 result.restored.append("config")
             except OSError as e:
                 logger.error("[Backup] Failed to restore config.json: %s", e, exc_info=True)

test/test_restore_keeps_panel_hardware.py

@@ -1,104 +0,0 @@
-#!/usr/bin/env python3
-"""A restore must not repoint this device at another machine's panel.
-
-display.hardware describes the panel physically wired to this device -- cols,
-rows, chain_length, hardware_mapping, panel_type, multiplexing, the refresh
-cap. A backup carries the panel of the machine it was taken on. Restoring a
-512x64 rig's backup onto a 128x32 one used to overwrite the smaller panel's
-geometry with the larger one's, and nothing on screen explains why: the
-display just stops being right.
-
-That is not hypothetical. It happened, and the rig it happened to had to be
-reflashed.
-"""
-import json
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from src.backup_manager import _restore_config_preserving_hardware  # noqa: E402
-
-BIG = {"display": {"hardware": {"cols": 128, "rows": 64, "chain_length": 4,
-                                "hardware_mapping": "adafruit-hat-pwm"},
-                   "runtime": {"gpio_slowdown": 4}},
-       "timezone": "America/New_York", "some-plugin": {"enabled": True}}
-SMALL = {"display": {"hardware": {"cols": 64, "rows": 32, "chain_length": 2,
-                                  "hardware_mapping": "regular"},
-                     "runtime": {"gpio_slowdown": 2}},
-         "timezone": "UTC"}
-
-
-def _run(tmp, keep):
-    src = tmp / "backup_config.json"; src.write_text(json.dumps(BIG))
-    dst = tmp / "config.json"; dst.write_text(json.dumps(SMALL))
-    _restore_config_preserving_hardware(src, dst, keep_hardware=keep)
-    return json.loads(dst.read_text())
-
-
-def test_local_panel_survives(tmp_path):
-    out = _run(tmp_path, keep=True)
-    hw = out["display"]["hardware"]
-    assert (hw["cols"], hw["rows"], hw["chain_length"]) == (64, 32, 2), (
-        "the restore repointed this device at the backup's panel")
-    assert hw["hardware_mapping"] == "regular", "panel wiring came from the backup"
-
-
-def test_everything_else_is_restored(tmp_path):
-    out = _run(tmp_path, keep=True)
-    assert out["timezone"] == "America/New_York", "config was not restored"
-    assert out["some-plugin"] == {"enabled": True}, "plugin config was not restored"
-    assert out["display"]["runtime"] == {"gpio_slowdown": 4}, (
-        "only display.hardware should be held back")
-
-
-def test_opting_in_takes_the_backups_panel(tmp_path):
-    out = _run(tmp_path, keep=False)
-    hw = out["display"]["hardware"]
-    assert (hw["cols"], hw["rows"], hw["chain_length"]) == (128, 64, 4)
-
-
-def test_a_device_with_no_local_hardware_takes_the_backups(tmp_path):
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text(json.dumps({"timezone": "UTC"}))
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-    out = json.loads(dst.read_text())
-    assert out["display"]["hardware"]["cols"] == 128, (
-        "nothing local to preserve, so the backup's panel should be used")
-
-
-def test_unparseable_local_config_still_restores(tmp_path):
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text("{ not json")
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-    assert json.loads(dst.read_text())["timezone"] == "America/New_York", (
-        "a restore must never fail because of this merge")
-
-
-def test_the_destination_mode_is_preserved(tmp_path):
-    """config.json is installed with a deliberate mode; a merge must not widen it.
-
-    _copy_file preserves the destination's mode and owner on purpose -- these
-    files are root-owned while the web interface running the restore is not.
-    Writing the merged result directly would have replaced that with whatever
-    the umask allowed.
-    """
-    import os
-    import stat as statmod
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text(json.dumps(SMALL))
-    os.chmod(dst, 0o600)
-
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-
-    mode = statmod.S_IMODE(os.stat(dst).st_mode)
-    assert mode == 0o600, f"restore widened config.json from 0600 to {oct(mode)}"
-    assert json.loads(dst.read_text())["display"]["hardware"]["cols"] == 64
-
-
-def test_no_scratch_file_is_left_behind(tmp_path):
-    src = tmp_path / "b.json"; src.write_text(json.dumps(BIG))
-    dst = tmp_path / "c.json"; dst.write_text(json.dumps(SMALL))
-    _restore_config_preserving_hardware(src, dst, keep_hardware=True)
-    leftovers = [p.name for p in tmp_path.iterdir() if "tmp" in p.name]
-    assert not leftovers, f"scratch files left in place: {leftovers}"

test/test_update_prompts_restart.py

@@ -0,0 +1,84 @@
+"""A pull that changed nothing on the running system is not an applied update.
+
+git_pull replaces files on disk and restarts nothing -- there is no systemctl
+call anywhere in the handler. The display and web services keep running the
+code they loaded at boot, so the user is told "Code updated successfully" and
+sees no change until they happen to reboot. The response now says whether a
+restart is owed, and the UI raises the existing restart-pending banner.
+"""
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+from flask import Flask
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from web_interface.blueprints import api_v3 as mod  # noqa: E402
+from web_interface.blueprints.api_v3 import api_v3  # noqa: E402
+
+
+@pytest.fixture
+def client():
+    app = Flask(__name__)
+    app.config['TESTING'] = True
+    app.register_blueprint(api_v3, url_prefix='/api/v3')
+    # The handler consults these after a successful pull; None is the
+    # "not wired up" case it already guards for.
+    api_v3.plugin_store_manager = None
+    api_v3.config_manager = None
+    return app.test_client()
+
+
+def _git(heads, pull_rc=0, pull_out='Updating a1b2c3..d4e5f6\n'):
+    """Fake git. `heads` are the successive answers to rev-parse HEAD."""
+    seq = list(heads)
+
+    def run(args, **kwargs):
+        def ok(stdout='', rc=0, b=False):
+            return subprocess.CompletedProcess(
+                args, rc, stdout=(stdout.encode() if b else stdout),
+                stderr=(b'' if b else ''))
+        if args[:2] == ['git', 'rev-parse'] and args[-1] == 'HEAD':
+            return ok(seq.pop(0) + '\n' if seq else 'deadbeef\n')
+        if 'symbolic-full-name' in args or '@{u}' in args:
+            return ok('origin/main\n')
+        if args[:2] == ['git', 'status']:
+            return ok('')
+        if args[:2] == ['git', 'diff']:
+            return ok('')
+        if args[:2] == ['git', 'pull']:
+            return ok(pull_out, pull_rc)
+        return ok('')
+    return run
+
+
+def _pull(client):
+    return client.post('/api/v3/system/action',
+                       json={'action': 'git_pull'}).get_json()
+
+
+class TestRestartIsRequestedWhenCodeChanged:
+    def test_a_pull_that_moved_head_asks_for_a_restart(self, client):
+        with patch.object(mod.subprocess, 'run', _git(['aaa111', 'bbb222'])):
+            data = _pull(client)
+        assert data['status'] == 'success'
+        assert data['restart_required'] is True, (
+            "new code on disk, services still running the old code, and "
+            "nothing told the user to restart")
+
+    def test_already_up_to_date_does_not(self, client):
+        with patch.object(mod.subprocess, 'run',
+                          _git(['aaa111', 'aaa111'], pull_out='Already up to date.\n')):
+            data = _pull(client)
+        assert data['status'] == 'success'
+        assert data['restart_required'] is False, (
+            "prompting after a no-op update trains users to ignore the prompt")
+
+    def test_a_failed_pull_does_not(self, client):
+        with patch.object(mod.subprocess, 'run', _git(['aaa111'], pull_rc=1)):
+            data = _pull(client)
+        assert data['status'] == 'error'
+        assert data['restart_required'] is False

web_interface/blueprints/api_v3.py

@@ -1996,6 +1996,11 @@ def execute_system_action():
             except subprocess.TimeoutExpired:
                 logger.warning("git rev-parse timed out before pull")
 
+            # Whether the pull actually brought new code in. "Already up to
+            # date" is a success too, and prompting for a restart then would
+            # train users to ignore the prompt.
+            code_changed = False
+
             # Perform the git pull. Branches without an upstream were given
             # an explicit "origin <branch>" above so the update still works.
             result = subprocess.run(
@@ -2039,6 +2044,7 @@ def execute_system_action():
                                            capture_output=True, text=True, timeout=10, cwd=project_dir)
                     new_head = _post.stdout.strip() if _post.returncode == 0 else None
                     if old_head and new_head and old_head != new_head:
+                        code_changed = True
                         diff = subprocess.run(
                             ['git', 'diff', '--name-only', f'{old_head}..{new_head}'],
                             capture_output=True, text=True, timeout=15, cwd=project_dir)
@@ -2098,9 +2104,14 @@ def execute_system_action():
                                if ln.strip()), '')
                 pull_message = f"Update failed: {detail}" if detail else "Update failed; check logs for details"
 
+            # Nothing here restarts anything: the pull replaces files on
+            # disk while the display and web services keep running the code
+            # they loaded at boot. Without this the user is told the update
+            # succeeded and sees no change until they happen to reboot.
             return jsonify({
                 'status': 'success' if result.returncode == 0 else 'error',
                 'message': pull_message,
+                'restart_required': bool(result.returncode == 0 and code_changed),
             })
         elif action == 'checkout_branch':
             # Switch branches from the Tools tab. Needed because a checkout

web_interface/static/v3/app.js

@@ -116,14 +116,25 @@ document.body.addEventListener('htmx:afterRequest', function(event) {
 // ===== Restart-pending banner =====
 // Shown after restart-requiring saves; persists across tab switches (and
 // reloads, via sessionStorage) until the display restarts or it's dismissed.
-window.showRestartPending = function() {
+window.showRestartPending = function(message) {
-    try { sessionStorage.setItem('ledmatrix-restart-pending', '1'); } catch { /* private browsing */ }
+    try {
+        sessionStorage.setItem('ledmatrix-restart-pending', '1');
+        // Persisted alongside the flag: a code update and a config save want
+        // different wording, and the banner outlives the page that raised it.
+        if (message) sessionStorage.setItem('ledmatrix-restart-pending-text', message);
+        else sessionStorage.removeItem('ledmatrix-restart-pending-text');
+    } catch { /* private browsing */ }
     const banner = document.getElementById('restart-pending-banner');
+    const text = document.getElementById('restart-pending-text');
+    if (text && message) text.textContent = message;
     if (banner) banner.style.display = 'block';
 };
 
 window.dismissRestartPending = function() {
-    try { sessionStorage.removeItem('ledmatrix-restart-pending'); } catch { /* no-op */ }
+    try {
+        sessionStorage.removeItem('ledmatrix-restart-pending');
+        sessionStorage.removeItem('ledmatrix-restart-pending-text');
+    } catch { /* no-op */ }
     const banner = document.getElementById('restart-pending-banner');
     if (banner) banner.style.display = 'none';
 };
@@ -151,6 +162,9 @@ document.addEventListener('DOMContentLoaded', function() {
     try {
         if (sessionStorage.getItem('ledmatrix-restart-pending') === '1') {
             const banner = document.getElementById('restart-pending-banner');
+            const saved = sessionStorage.getItem('ledmatrix-restart-pending-text');
+            const text = document.getElementById('restart-pending-text');
+            if (text && saved) text.textContent = saved;
             if (banner) banner.style.display = 'block';
         }
     } catch { /* no-op */ }

web_interface/templates/v3/base.html

@@ -413,7 +413,8 @@
             <div class="flex items-center justify-between">
                 <div class="flex items-center space-x-3">
                     <i class="fas fa-rotate text-lg"></i>
-                    <span class="text-sm font-medium" aria-live="polite">
+                    <span class="text-sm font-medium" aria-live="polite"
+                          id="restart-pending-text">
                         Configuration saved &mdash; restart the display to apply the changes
                     </span>
                 </div>
@@ -1146,6 +1147,13 @@
             if (data.status === 'success') {
                 document.getElementById('update-banner').style.display = 'none';
                 try { sessionStorage.removeItem('update-sha-dismissed'); } catch(e) {}
+                // The pull replaced files on disk; the running services still
+                // hold the code they loaded at boot. Ask for the restart that
+                // makes the update actually take effect.
+                if (data.restart_required && typeof window.showRestartPending === 'function') {
+                    window.showRestartPending(
+                        'Update installed \u2014 restart the display to run the new code');
+                }
             }
             if (typeof showNotification === 'function') {
                 showNotification(data.message || 'Update complete', data.status || 'success');