test(harness): flag a mode that draws nothing without reporting it

The controller skips a mode whose display() returns False and treats
anything else -- including None -- as "content was shown". A mode that
draws nothing and does not return False is therefore never skipped, and
because a mode switch clears the panel first, it sits on a blank screen
for its whole display duration. Two sports plugins shipped exactly that.

The harness rendered those modes and passed them, because it called
display() and discarded the result. Capture it, and warn when a render
produced no lit pixels while claiming content.

Warn-only by default, and deliberately so: a scroll mode's first frame
is legitimately its blank scroll-in buffer, which is 42 of these on the
F1 scoreboard alone. Plugins whose modes are known to draw on their
fixture data can opt into failing via harness.json {"empty_check":
"strict"}, matching how the fill check is staged.

Worth being clear about the limit: this only sees what the fixtures
render. It would not have caught the sports bug, whose fixture seeds
games so the empty path never renders -- that needs the source-level
gate in the plugins repo. What it does catch is the same mistake in any
plugin whose empty state the harness does happen to reach, which is
coverage there was none of before.

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

docs/widget-guide.md

@@ -206,6 +206,47 @@ To use an existing widget in your plugin's `config_schema.json`, simply add the
 
 The widget will be automatically rendered when the plugin configuration form is loaded.
 
+## Labelling Enum Options (`x-options.labels`)
+
+A plain `enum` renders as a dropdown whose option text is the value with
+underscores replaced and title case applied — `day_first` becomes "Day First".
+That is fine for values that read as their own label, and wrong for values that
+do not: `vs` becomes "Vs", and `abbrev` says nothing about the `Sep 19` it
+actually produces.
+
+Supply `x-options.labels` to set the visible text. This is the same convention
+the `checkbox-group` widget uses:
+
+```json
+{
+  "date_format": {
+    "type": "string",
+    "enum": ["abbrev", "numeric", "day_first"],
+    "default": "abbrev",
+    "x-options": {
+      "labels": {
+        "abbrev": "Sep 19",
+        "numeric": "9/19",
+        "day_first": "19 Sep"
+      }
+    }
+  }
+}
+```
+
+Labels are **display only** — the stored value is still the enum value, so
+adding them never changes a saved config. The map may be partial: any value
+without a label keeps the humanised fallback. Older cores that predate this
+support ignore `x-options` and render the fallback for every option, so a
+plugin can ship labels without requiring a core upgrade.
+
+Array-table columns (`x-widget: array-table`) accept the same
+`x-options.labels` on a column definition, but their fallback is the **raw
+value** rather than the humanised one, because those columns hold values such
+as ticker symbols where `aapl` → "Aapl" would be wrong. Rows added in the
+browser use the labels too (`array-table.js`), so a column reads the same
+before and after a page reload.
+
 ## Marking Fields as Advanced (`x-advanced`)
 
 Add `"x-advanced": true` to any top-level, non-object property to move it out

scripts/check_plugin.py

@@ -41,6 +41,7 @@ from src.plugin_system.testing.loading import (  # noqa: E402
 )
 from src.plugin_system.testing.harness import (  # noqa: E402
     RenderResult, render_plugin_matrix, compare_to_goldens, write_goldens,
+    check_empty_claimed,
     check_scale_up,
 )
 from src.plugin_system.testing.sizes import (  # noqa: E402
@@ -115,6 +116,11 @@ def check_one(plugin_id: str, search_dirs: List[str], sizes, mock_data: Dict,
     declared = load_manifest(plugin_dir).get("display", {}).get("design_size", {})
     design_size = (int(declared.get("width", 128)), int(declared.get("height", 32)))
     fill_strict = spec.get("fill_check") == "strict"
+    # A mode that renders nothing without returning False is never skipped by
+    # the display controller, so it holds a blank panel for its whole duration.
+    # Warn-only by default: a scroll mode's first frame is legitimately its
+    # blank scroll-in buffer.
+    empty_strict = spec.get("empty_check") == "strict"
 
     # Every run: the base config, plus one per harness.json "variant" —
     # a config overlay with its own golden dir (e.g. adaptive layout mode
@@ -142,6 +148,7 @@ def check_one(plugin_id: str, search_dirs: List[str], sizes, mock_data: Dict,
             compare_to_goldens(results, golden_dir)
 
         check_scale_up(results, design_size=design_size, strict=fill_strict)
+        check_empty_claimed(results, strict=empty_strict)
 
         # Tag variant runs so the report and PNG dumps stay distinguishable.
         if variant_name:
@@ -178,6 +185,9 @@ def print_report(all_results: Dict[str, List[RenderResult]]) -> bool:
                     # warn-only underfill: big panel left mostly empty
                     ex, ey = r.fill_extent
                     detail += f" (fill warn: extent {ex:.0%}x{ey:.0%})"
+                if r.empty_claimed and r.empty_ok is None:
+                    detail += (f" (empty warn: drew nothing but display() returned"
+                               f" {r.display_returned!r}, so the mode is not skipped)")
             else:
                 everything_ok = False
                 if r.error is not None:
@@ -191,6 +201,11 @@ def print_report(all_results: Dict[str, List[RenderResult]]) -> bool:
                     ex, ey = r.fill_extent or (0.0, 0.0)
                     status = "FAIL"
                     detail = f" fill: extent {ex:.0%}x{ey:.0%} below required coverage"
+                elif r.empty_ok is False:
+                    status = "FAIL"
+                    detail = (f" drew nothing but display() returned"
+                              f" {r.display_returned!r}; return False so the"
+                              f" controller skips the mode")
                 else:
                     status, detail = "FAIL", ""
             print(f"  [{status}] {r.size_label:>7}  {r.mode}{detail}")

src/plugin_system/testing/harness.py

@@ -73,6 +73,11 @@ class RenderResult:
     golden_ok: Optional[bool] = None
     golden_diff_pixels: int = 0
     golden_max_delta: int = 0
+    # what display() handed back; the controller skips a mode only on False
+    display_returned: Any = None
+    # empty-frame check: rendered nothing while not reporting "no content"
+    empty_claimed: Optional[bool] = None   # True when that happened
+    empty_ok: Optional[bool] = None        # False only in strict mode
     # fill / scale-up check (populated only for sizes >= 2x the design size)
     fill_checked: bool = False
     fill_ok: Optional[bool] = None       # False only in strict mode
@@ -92,6 +97,8 @@ class RenderResult:
             return False
         if self.fill_ok is False:
             return False
+        if self.empty_ok is False:
+            return False
         return True
 
 
@@ -132,21 +139,25 @@ def _instantiate(plugin_id: str, manifest: Dict[str, Any], plugin_dir: Path,
     return plugin_instance
 
 
-def _render_mode(plugin_instance: Any, mode: str) -> None:
+def _render_mode(plugin_instance: Any, mode: str) -> Any:
     """Render a specific screen. Prefer an explicit display_mode kwarg; otherwise
     drive the plugin's internal mode state machine (first display() call renders
-    modes[current_mode_index] when current_display_mode is None)."""
+    modes[current_mode_index] when current_display_mode is None).
+
+    Returns whatever display() returned. The display controller skips a mode
+    whose display() returns False, so that value decides whether an empty mode
+    is rotated past or sat on -- which makes it worth reporting rather than
+    discarding."""
     sig = inspect.signature(plugin_instance.display)
     if "display_mode" in sig.parameters:
-        plugin_instance.display(force_clear=True, display_mode=mode)
-        return
+        return plugin_instance.display(force_clear=True, display_mode=mode)
 
     modes = getattr(plugin_instance, "modes", None)
     if modes and mode in modes:
         plugin_instance.current_mode_index = list(modes).index(mode)
     if hasattr(plugin_instance, "current_display_mode"):
         plugin_instance.current_display_mode = None
-    plugin_instance.display(force_clear=False)
+    return plugin_instance.display(force_clear=False)
 
 
 def _freeze(freeze_time: Optional[str]):
@@ -234,7 +245,7 @@ def _render_size(plugin_id, manifest, plugin_dir, config, mock_data,
                     logger.warning("update() raised a non-connectivity error for %s [%s]: %s",
                                    plugin_id, mode, e)
             if result.error is None:
-                _render_mode(inst, mode)
+                result.display_returned = _render_mode(inst, mode)
                 result.image = dm.get_image()
                 result.overflow = dm.check_overflow()
         except Exception as e:  # noqa: BLE001 — a display crash is a real failure
@@ -341,6 +352,44 @@ def fill_metrics(image: Image.Image) -> Tuple[float, float, float]:
     return (extent_x, extent_y, ink)
 
 
+def check_empty_claimed(results: List[RenderResult],
+                        strict: bool = False) -> List[RenderResult]:
+    """Flag a mode that rendered nothing without reporting "no content".
+
+    The display controller skips a mode whose ``display()`` returns False, and
+    treats anything else -- including None -- as "content was shown". A mode
+    that draws nothing and does not return False therefore holds whatever is on
+    the panel for its whole display duration. Since a mode switch clears first,
+    that is a blank screen. Two sports plugins shipped exactly this: their
+    ``display()`` returned None on every path, so an out-of-season league sat
+    blank for its full duration rather than being rotated past.
+
+    Warn-only by default, because a blank frame is not automatically wrong: a
+    scroll mode whose first frame is its blank scroll-in buffer renders empty
+    and is behaving correctly. ``strict=True`` sets ``empty_claimed`` such that
+    ``RenderResult.ok`` fails -- opt in per plugin via harness.json
+    ``{"empty_check": "strict"}`` once its modes are known to draw on the
+    fixture data.
+
+    Note this can only catch what the fixtures actually render. A plugin whose
+    harness fixture seeds content never exercises its empty path here; the
+    source-level gate in the plugins repo covers that case.
+    """
+    for r in results:
+        if r.image is None or r.error is not None:
+            continue
+        # An explicit False is the plugin correctly saying "nothing to show".
+        if r.display_returned is False:
+            continue
+        if r.image.convert("L").point(
+                lambda p: 255 if p > _LIT_THRESHOLD else 0).getbbox() is not None:
+            continue
+        r.empty_claimed = True
+        if strict:
+            r.empty_ok = False
+    return results
+
+
 def check_scale_up(results: List[RenderResult],
                    design_size: Tuple[int, int] = (128, 32),
                    min_extent: float = _MIN_FILL_EXTENT,

test/test_enum_option_labels.py

@@ -0,0 +1,134 @@
+"""Guard: enum dropdowns in the plugin config form honour x-options.labels.
+
+The form derives an option's visible text from its value — underscores
+replaced, title case applied ("day_first" -> "Day First"). That cannot
+express every label a schema needs: "vs" reads as "Vs", and "abbrev" says
+nothing about the "Sep 19" it produces. Schemas can supply x-options.labels
+instead, the same convention the checkbox-group widget already uses.
+
+These tests extract the enum <select> block *out of the shipped template*
+and render that, so they exercise the production expression rather than a
+copy of it. If the fallback or the lookup changes, these tests render the
+changed code and fail — a duplicated fragment here would silently keep
+passing.
+"""
+import re
+from pathlib import Path
+
+import pytest
+from jinja2 import DictLoader, Environment
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+CONFIG_FORM = (PROJECT_ROOT / 'web_interface' / 'templates' / 'v3' / 'partials'
+               / 'plugin_config.html')
+ARRAY_TABLE_JS = (PROJECT_ROOT / 'web_interface' / 'static' / 'v3' / 'js'
+                  / 'widgets' / 'array-table.js')
+
+# The enum branch: from the `{% set enum_labels %}` line through `</select>`.
+ENUM_BLOCK_RE = re.compile(
+    r"(\{%\s*set enum_labels\s*=.*?</select>)", re.S
+)
+
+
+def _shipped_enum_block() -> str:
+    """Return the live enum <select> block lifted from plugin_config.html."""
+    source = CONFIG_FORM.read_text(encoding='utf-8')
+    match = ENUM_BLOCK_RE.search(source)
+    assert match, (
+        'could not find the enum <select> block in plugin_config.html — the '
+        'template changed shape and this guard needs updating'
+    )
+    return match.group(1)
+
+
+def _render(prop: dict, value=None) -> str:
+    """Render the shipped enum block with a minimal fixture."""
+    env = Environment(loader=DictLoader({'f': _shipped_enum_block()}),
+                      autoescape=True)
+    return env.get_template('f').render(
+        prop=prop, value=value, field_id='fid', full_key='k'
+    )
+
+
+def _option_labels(html: str) -> dict:
+    """Map each rendered option's value to its visible text."""
+    return {
+        value: text.strip()
+        for value, text in re.findall(
+            r'<option value="([^"]*)"[^>]*>(.*?)</option>', html, re.S
+        )
+    }
+
+
+def test_labels_are_used_when_supplied() -> None:
+    html = _render({
+        'enum': ['vs', 'date_time'],
+        'x-options': {'labels': {'vs': 'VS', 'date_time': 'Date and time'}},
+    })
+    assert _option_labels(html) == {'vs': 'VS', 'date_time': 'Date and time'}
+
+
+def test_unlabelled_values_keep_the_humanised_fallback() -> None:
+    """Schemas without labels must render exactly as they did before."""
+    html = _render({'enum': ['day_first', 'weekday']})
+    assert _option_labels(html) == {'day_first': 'Day First', 'weekday': 'Weekday'}
+
+
+def test_partial_labels_fall_back_per_value() -> None:
+    """A labels map covering some values leaves the rest humanised."""
+    html = _render({'enum': ['vs', 'day_first'],
+                    'x-options': {'labels': {'vs': 'VS'}}})
+    assert _option_labels(html) == {'vs': 'VS', 'day_first': 'Day First'}
+
+
+def test_option_values_are_unchanged_by_labelling() -> None:
+    """Labels are display-only: the submitted value stays the enum value."""
+    html = _render({'enum': ['abbrev'],
+                    'x-options': {'labels': {'abbrev': 'Sep 19'}}})
+    assert _option_labels(html) == {'abbrev': 'Sep 19'}
+
+
+def test_selected_option_still_tracks_the_current_value() -> None:
+    """Labelling must not disturb which option is marked selected."""
+    html = _render({'enum': ['abbrev', 'numeric'],
+                    'x-options': {'labels': {'abbrev': 'Sep 19'}}},
+                   value='numeric')
+    selected = re.search(r'<option value="([^"]+)"[^>]*selected', html)
+    assert selected and selected.group(1) == 'numeric'
+
+
+@pytest.mark.parametrize('key', ['x-options', 'x_options'])
+def test_both_option_key_spellings_work(key: str) -> None:
+    """The template accepts either spelling, as its other widgets do."""
+    html = _render({'enum': ['vs'], key: {'labels': {'vs': 'VS'}}})
+    assert _option_labels(html) == {'vs': 'VS'}
+
+
+def test_table_column_enum_falls_back_to_the_raw_value() -> None:
+    """Array-table columns must not title-case values that were never labelled.
+
+    Those columns hold values such as ticker symbols, where "aapl" -> "Aapl"
+    would be wrong, so their fallback stays the raw value.
+    """
+    source = CONFIG_FORM.read_text(encoding='utf-8')
+    assert 'col_labels.get(opt, opt)' in source, (
+        'array-table column options must fall back to the raw value, not the '
+        'humanised one'
+    )
+
+
+def test_dynamically_added_table_rows_use_the_same_labels() -> None:
+    """Rows added client-side must label options like the server-rendered ones.
+
+    array-table.js builds new rows in the browser; if it printed the raw value
+    a column would read differently before and after a page reload.
+    """
+    js = ARRAY_TABLE_JS.read_text(encoding='utf-8')
+    assert 'function enumOptionLabel' in js, (
+        'array-table.js lost its enum label helper'
+    )
+    raw_option_text = re.findall(r'o\.textContent\s*=\s*opt\s*;', js)
+    assert not raw_option_text, (
+        'array-table.js renders an enum option as its raw value; it must go '
+        'through enumOptionLabel() so dynamic rows match server-rendered ones'
+    )

test/test_git_pull_resolution.py

@@ -0,0 +1,202 @@
+"""Guard: the update button works on branches without tracking information.
+
+`git pull --rebase` fails outright on a branch with no upstream:
+
+    There is no tracking information for the current branch.
+    Please specify which branch you want to rebase against.
+
+That is easy to land on — checking out a branch by name, restoring a
+backup, or following a guide that names one — and the Tools tab reported it
+as a bare "Update failed; check logs for details", which the user cannot act
+on. resolve_pull_command() falls back to an explicit `origin <branch>` pull
+when that remote branch exists, and returns an actionable message when it
+does not.
+
+These tests build real git repositories in a temp dir, so they exercise git's
+actual behaviour rather than a mock of it.
+"""
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from web_interface.blueprints.api_v3 import (
+    checkout_branch,
+    is_valid_branch_name,
+    resolve_pull_command,
+)
+
+pytestmark = pytest.mark.skipif(
+    subprocess.run(['git', '--version'], capture_output=True).returncode != 0,
+    reason='git not available',
+)
+
+
+def _git(*args, cwd):
+    return subprocess.run(['git', *args], cwd=str(cwd),
+                          capture_output=True, text=True, check=True)
+
+
+@pytest.fixture()
+def repos(tmp_path):
+    """An 'origin' repo with a main branch, and a clone of it."""
+    origin = tmp_path / 'origin'
+    origin.mkdir()
+    _git('init', '--initial-branch=main', '--bare', cwd=origin)
+
+    work = tmp_path / 'work'
+    _git('clone', str(origin), str(work), cwd=tmp_path)
+    _git('config', 'user.email', 'test@example.com', cwd=work)
+    _git('config', 'user.name', 'Test', cwd=work)
+    (work / 'README.md').write_text('hello\n')
+    _git('add', 'README.md', cwd=work)
+    _git('commit', '-m', 'initial', cwd=work)
+    _git('push', '-u', 'origin', 'main', cwd=work)
+    return work
+
+
+def test_branch_with_upstream_uses_a_plain_pull(repos):
+    args, note, error = resolve_pull_command(str(repos))
+    assert error is None
+    assert args == ['git', 'pull', '--rebase']
+    assert note == ''
+
+
+def test_branch_without_upstream_falls_back_to_origin_branch(repos):
+    """The reported bug: a local branch that also exists on origin."""
+    _git('push', 'origin', 'main:audit', cwd=repos)
+    _git('fetch', 'origin', cwd=repos)
+    # A branch created this way has no tracking information.
+    _git('checkout', '-b', 'audit', cwd=repos)
+    assert subprocess.run(['git', 'rev-parse', '--abbrev-ref', '@{u}'],
+                          cwd=str(repos), capture_output=True).returncode != 0
+
+    args, note, error = resolve_pull_command(str(repos))
+    assert error is None
+    assert args == ['git', 'pull', '--rebase', 'origin', 'audit']
+    assert 'audit' in note
+
+
+def test_pull_fallback_actually_succeeds(repos):
+    """The fallback command must work, not merely look right."""
+    _git('push', 'origin', 'main:audit', cwd=repos)
+    _git('fetch', 'origin', cwd=repos)
+    _git('checkout', '-b', 'audit', cwd=repos)
+
+    args, _, error = resolve_pull_command(str(repos))
+    assert error is None
+    done = subprocess.run(args, cwd=str(repos), capture_output=True, text=True)
+    assert done.returncode == 0, done.stderr
+
+
+def test_local_only_branch_reports_an_actionable_message(repos):
+    """No upstream and no origin/<branch>: say so, don't just fail."""
+    _git('checkout', '-b', 'local-experiment', cwd=repos)
+    args, _, error = resolve_pull_command(str(repos))
+    assert args is None
+    assert error and 'local-experiment' in error
+    assert 'no origin/local-experiment' in error
+
+
+def test_detached_head_reports_an_actionable_message(repos):
+    head = subprocess.run(['git', 'rev-parse', 'HEAD'], cwd=str(repos),
+                          capture_output=True, text=True).stdout.strip()
+    _git('checkout', head, cwd=repos)
+    args, _, error = resolve_pull_command(str(repos))
+    assert args is None
+    assert error and 'detached HEAD' in error
+
+
+def test_missing_directory_does_not_raise(tmp_path):
+    """A bad path must return an error, not blow up the request."""
+    args, _, error = resolve_pull_command(str(tmp_path / 'nope'))
+    assert args is None
+    assert error
+
+
+# ── branch switching ────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize('name', [
+    'main', 'audit', 'feat/thing', 'release-1.2', 'a_b.c',
+])
+def test_valid_branch_names_accepted(name):
+    assert is_valid_branch_name(name)
+
+
+@pytest.mark.parametrize('name', [
+    '', '   ', 'a b', 'a;rm -rf /', '--upload-pack=evil', '-x',
+    'a..b', 'a\nb', 'x' * 201, 'branch$(whoami)', '../escape',
+])
+def test_unsafe_branch_names_rejected(name):
+    """The value reaches a subprocess argument list, so refuse the exotic."""
+    assert not is_valid_branch_name(name)
+
+
+def test_switch_to_remote_only_branch_creates_it_with_tracking(repos):
+    _git('push', 'origin', 'main:release', cwd=repos)
+    _git('fetch', 'origin', cwd=repos)
+
+    payload, code = checkout_branch(str(repos), 'release')
+    assert code == 200 and payload['status'] == 'success', payload
+
+    assert _git('branch', '--show-current', cwd=repos).stdout.strip() == 'release'
+    upstream = subprocess.run(['git', 'rev-parse', '--abbrev-ref', '@{u}'],
+                              cwd=str(repos), capture_output=True, text=True)
+    assert upstream.stdout.strip() == 'origin/release'
+
+
+def test_switching_attaches_tracking_so_pull_needs_no_fallback(repos):
+    """The whole point: after switching, a plain `git pull` works."""
+    _git('push', 'origin', 'main:audit', cwd=repos)
+    _git('fetch', 'origin', cwd=repos)
+    payload, _ = checkout_branch(str(repos), 'audit')
+    assert payload['status'] == 'success'
+
+    args, note, error = resolve_pull_command(str(repos))
+    assert error is None
+    assert args == ['git', 'pull', '--rebase']
+    assert note == ''
+
+
+def test_unknown_branch_is_reported_not_created(repos):
+    payload, code = checkout_branch(str(repos), 'does-not-exist')
+    assert code == 404
+    assert 'does-not-exist' in payload['message']
+    assert _git('branch', '--show-current', cwd=repos).stdout.strip() == 'main'
+
+
+def test_local_edits_block_the_switch_and_name_the_files(repos):
+    _git('push', 'origin', 'main:other', cwd=repos)
+    _git('fetch', 'origin', cwd=repos)
+    _git('checkout', '-b', 'other', 'origin/other', cwd=repos)
+    (repos / 'README.md').write_text('changed on other\n')
+    _git('add', 'README.md', cwd=repos)
+    _git('commit', '-m', 'diverge', cwd=repos)
+    _git('checkout', 'main', cwd=repos)
+    (repos / 'README.md').write_text('uncommitted local edit\n')
+
+    payload, code = checkout_branch(str(repos), 'other')
+    assert code == 200 and payload['status'] == 'error'
+    assert payload['can_retry_with_stash'] is True
+    assert 'README.md' in payload['detail']
+    assert _git('branch', '--show-current', cwd=repos).stdout.strip() == 'main'
+
+
+def test_stash_option_lets_the_switch_through_and_keeps_the_work(repos):
+    """stash=True must switch *and* leave the edit recoverable."""
+    _git('push', 'origin', 'main:other', cwd=repos)
+    _git('fetch', 'origin', cwd=repos)
+    _git('checkout', '-b', 'other', 'origin/other', cwd=repos)
+    (repos / 'README.md').write_text('changed on other\n')
+    _git('add', 'README.md', cwd=repos)
+    _git('commit', '-m', 'diverge', cwd=repos)
+    _git('checkout', 'main', cwd=repos)
+    (repos / 'README.md').write_text('uncommitted local edit\n')
+
+    payload, code = checkout_branch(str(repos), 'other', stash=True)
+    assert code == 200 and payload['status'] == 'success', payload
+    assert 'stashed' in payload['message']
+    assert _git('branch', '--show-current', cwd=repos).stdout.strip() == 'other'
+    # The edit is not lost — it is on the stash.
+    assert 'switch to other' in _git('stash', 'list', cwd=repos).stdout

test/test_harness_empty_claimed.py

@@ -0,0 +1,103 @@
+"""Tests for the harness empty-frame check (src/plugin_system/testing/harness.py).
+
+The display controller skips a mode whose display() returns False and treats
+anything else -- including None -- as "content was shown". A mode that draws
+nothing without returning False is therefore never skipped, and since a mode
+switch clears the panel first, it sits on a blank screen for its whole display
+duration.
+
+Two sports plugins shipped exactly that: their display() returned None on every
+path, so an out-of-season league held a blank panel instead of being rotated
+past. The harness rendered those modes and passed them, because it discarded
+the return value entirely.
+"""
+
+from PIL import Image
+
+from src.plugin_system.testing.harness import RenderResult, check_empty_claimed
+
+
+def _blank(w=64, h=32):
+    return Image.new("RGB", (w, h), (0, 0, 0))
+
+
+def _drawn(w=64, h=32):
+    img = _blank(w, h)
+    img.paste(Image.new("RGB", (10, 10), (255, 255, 255)), (5, 5))
+    return img
+
+
+def _result(image, returned=None, **kw):
+    return RenderResult("p", 64, 32, "mode", image=image,
+                        display_returned=returned, **kw)
+
+
+class TestCheckEmptyClaimed:
+    def test_blank_frame_returning_none_is_flagged(self):
+        # The shape that shipped: nothing drawn, nothing reported.
+        r = _result(_blank(), returned=None)
+        check_empty_claimed([r])
+        assert r.empty_claimed is True
+
+    def test_blank_frame_returning_true_is_flagged(self):
+        # Just as broken, and more explicit about it.
+        r = _result(_blank(), returned=True)
+        check_empty_claimed([r])
+        assert r.empty_claimed is True
+
+    def test_blank_frame_returning_false_is_fine(self):
+        # The plugin correctly said "no content"; the controller will skip it.
+        r = _result(_blank(), returned=False)
+        check_empty_claimed([r])
+        assert r.empty_claimed is None
+
+    def test_a_drawn_frame_is_fine_whatever_it_returns(self):
+        for returned in (None, True, False):
+            r = _result(_drawn(), returned=returned)
+            check_empty_claimed([r])
+            assert r.empty_claimed is None, returned
+
+    def test_near_black_still_counts_as_drawn(self):
+        # Guard the threshold: content dim enough to look black to the eye is
+        # still content, and flagging it would train people to ignore this.
+        img = _blank()
+        img.paste(Image.new("RGB", (4, 4), (60, 60, 60)), (2, 2))
+        r = _result(img, returned=None)
+        check_empty_claimed([r])
+        assert r.empty_claimed is None
+
+
+class TestWarnVersusStrict:
+    def test_warn_only_by_default(self):
+        # A scroll mode's first frame is legitimately its blank scroll-in
+        # buffer, so this must not fail a run unless opted in.
+        r = _result(_blank(), returned=None)
+        check_empty_claimed([r])
+        assert r.empty_ok is None
+        assert r.ok is True
+
+    def test_strict_fails_the_result(self):
+        r = _result(_blank(), returned=None)
+        check_empty_claimed([r], strict=True)
+        assert r.empty_ok is False
+        assert r.ok is False
+
+    def test_strict_still_allows_an_honest_false(self):
+        r = _result(_blank(), returned=False)
+        check_empty_claimed([r], strict=True)
+        assert r.empty_ok is None
+        assert r.ok is True
+
+
+class TestSkippedResults:
+    def test_a_crashed_render_is_left_alone(self):
+        # error already fails the result; adding a second reason just muddies
+        # the report.
+        r = _result(None, returned=None, error="boom")
+        check_empty_claimed([r], strict=True)
+        assert r.empty_claimed is None
+
+    def test_a_result_with_no_image_is_left_alone(self):
+        r = _result(None, returned=None)
+        check_empty_claimed([r], strict=True)
+        assert r.empty_claimed is None

web_interface/blueprints/api_v3.py

@@ -1631,6 +1631,161 @@ def get_health():
             'data': {'status': 'unhealthy'}
         }), 500
 
+def _git_current_branch(project_dir):
+    """Current branch name, or '' when detached or git fails."""
+    try:
+        r = subprocess.run(['git', 'branch', '--show-current'],
+                           capture_output=True, text=True, timeout=10, cwd=str(project_dir))
+        return r.stdout.strip() if r.returncode == 0 else ''
+    except (subprocess.TimeoutExpired, OSError):
+        return ''
+
+
+def _git_upstream(project_dir):
+    """Configured upstream for the current branch (e.g. 'origin/main'), or ''."""
+    try:
+        r = subprocess.run(['git', 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'],
+                           capture_output=True, text=True, timeout=10, cwd=str(project_dir))
+        return r.stdout.strip() if r.returncode == 0 else ''
+    except (subprocess.TimeoutExpired, OSError):
+        return ''
+
+
+def _git_remote_branch_exists(project_dir, branch):
+    """True when origin/<branch> exists locally as a remote-tracking ref."""
+    if not branch:
+        return False
+    try:
+        r = subprocess.run(
+            ['git', 'show-ref', '--verify', '--quiet', f'refs/remotes/origin/{branch}'],
+            capture_output=True, text=True, timeout=10, cwd=str(project_dir))
+        return r.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def resolve_pull_command(project_dir):
+    """Work out how to pull, for branches with and without an upstream.
+
+    A plain ``git pull --rebase`` fails outright on a branch that has no
+    upstream ("There is no tracking information for the current branch"),
+    which is easy to end up on: checking out a branch by name, restoring a
+    backup, or following an install guide that names one. The update button
+    then reports a failure the user cannot act on.
+
+    Returns ``(args, note, error)``. When ``origin/<branch>`` exists the pull
+    is made explicit against it, so the update proceeds and the branch is
+    given tracking information afterwards.
+    """
+    upstream = _git_upstream(project_dir)
+    if upstream:
+        return ['git', 'pull', '--rebase'], '', None
+
+    branch = _git_current_branch(project_dir)
+    if not branch:
+        return None, '', (
+            "This checkout is in a detached HEAD state, so there is no branch "
+            "to update. Switch to a branch first (Tools -> Switch branch)."
+        )
+    if _git_remote_branch_exists(project_dir, branch):
+        return (
+            ['git', 'pull', '--rebase', 'origin', branch],
+            f"Branch '{branch}' had no upstream; pulled from origin/{branch} and set it as the upstream.",
+            None,
+        )
+    return None, '', (
+        f"Branch '{branch}' has no upstream and there is no origin/{branch} to "
+        f"pull from. Use Switch branch to move to a branch that exists on the "
+        f"remote, or push this one first."
+    )
+
+
+_BRANCH_NAME_RE = re.compile(r'[A-Za-z0-9._/-]{1,200}')
+
+
+def is_valid_branch_name(name):
+    """Accept only plain branch names.
+
+    This value becomes a subprocess argument, so anything exotic is refused
+    rather than escaped. '..' is excluded because it is range syntax to git.
+    """
+    if not name or not _BRANCH_NAME_RE.fullmatch(name):
+        return False
+    return '..' not in name and not name.startswith('-')
+
+
+def checkout_branch(project_dir, target, stash=False):
+    """Switch the checkout to `target`, returning (payload, http_status).
+
+    Split out of the route so it can be tested against real repositories.
+    Attaches tracking when the branch exists on origin, so the next
+    Pull Latest is a plain `git pull` rather than the no-upstream fallback.
+    """
+    target = (target or '').strip()
+    if not target:
+        return {'status': 'error', 'message': 'Branch name required'}, 400
+    if not is_valid_branch_name(target):
+        return {'status': 'error', 'message': 'Invalid branch name'}, 400
+
+    try:
+        subprocess.run(['git', 'fetch', 'origin', '--prune'],
+                       capture_output=True, text=True, timeout=60, cwd=project_dir)
+
+        local_exists = subprocess.run(
+            ['git', 'show-ref', '--verify', '--quiet', f'refs/heads/{target}'],
+            capture_output=True, text=True, timeout=10, cwd=project_dir).returncode == 0
+        remote_exists = _git_remote_branch_exists(project_dir, target)
+        if not local_exists and not remote_exists:
+            return {'status': 'error',
+                    'message': f"No branch '{target}' locally or on origin"}, 404
+
+        # Local edits block a checkout. Pull Latest already stashes for the
+        # same reason, so offer it here too -- but only when asked, never
+        # silently: putting someone's edits away unasked is worse than
+        # refusing the switch.
+        stash_note = ''
+        if stash:
+            stashed = subprocess.run(['git', 'stash', 'push', '-m', f'switch to {target}'],
+                                     capture_output=True, text=True, timeout=60, cwd=project_dir)
+            if stashed.returncode == 0 and 'No local changes' not in stashed.stdout:
+                stash_note = ' Local changes were stashed (recover them with git stash list).'
+
+        if local_exists:
+            co = subprocess.run(['git', 'checkout', target],
+                                capture_output=True, text=True, timeout=60, cwd=project_dir)
+        else:
+            # -B so a stale local ref does not block the checkout.
+            co = subprocess.run(['git', 'checkout', '-B', target, f'origin/{target}'],
+                                capture_output=True, text=True, timeout=60, cwd=project_dir)
+
+        if co.returncode != 0:
+            logger.warning("git checkout %s failed: %s", target, co.stderr)
+            return {
+                'status': 'error',
+                'message': f"Could not switch to '{target}'.",
+                # Keep git's full list of blocking files: naming them is the
+                # difference between an error the user can act on and one they
+                # cannot.
+                'detail': (co.stderr or '').strip(),
+                'can_retry_with_stash': 'would be overwritten by checkout' in (co.stderr or ''),
+            }, 200
+
+        if remote_exists:
+            subprocess.run(['git', 'branch', f'--set-upstream-to=origin/{target}', target],
+                           capture_output=True, text=True, timeout=10, cwd=project_dir)
+
+        logger.info("Switched checkout to branch %s", target)
+        return {
+            'status': 'success',
+            'message': f"Now on '{target}'.{stash_note} Use Pull Latest to fetch its newest code.",
+        }, 200
+    except subprocess.TimeoutExpired:
+        return {'status': 'error', 'message': 'Timed out talking to git'}, 504
+    except OSError as exc:
+        logger.error("checkout_branch failed: %s", exc, exc_info=True)
+        return {'status': 'error', 'message': 'Could not switch branch'}, 500
+
+
 def get_git_version(project_dir=None):
     """Get git version information from the repository"""
     if project_dir is None:
@@ -1795,6 +1950,14 @@ def execute_system_action():
             # Use PROJECT_ROOT instead of hardcoded path
             project_dir = str(PROJECT_ROOT)
 
+            # Decide how to pull BEFORE stashing. If this checkout cannot be
+            # updated at all, stashing first would put the user's local changes
+            # away for an update that was never going to run.
+            pull_args, upstream_note, pull_error = resolve_pull_command(project_dir)
+            if pull_error:
+                logger.warning("git pull not attempted: %s", pull_error)
+                return jsonify({'status': 'error', 'message': pull_error})
+
             # Check if there are local changes that need to be stashed
             # Exclude plugins directory - plugins are separate repos and shouldn't be stashed with base project
             # Use --untracked-files=no to skip untracked files check (much faster with symlinked plugins)
@@ -1849,15 +2012,28 @@ def execute_system_action():
             except subprocess.TimeoutExpired:
                 logger.warning("git rev-parse timed out before pull")
 
-            # Perform the git pull
+            # Perform the git pull. Branches without an upstream were given
+            # an explicit "origin <branch>" above so the update still works.
             result = subprocess.run(
-                ['git', 'pull', '--rebase'],
+                pull_args,
                 capture_output=True,
                 text=True,
                 timeout=60,
                 cwd=project_dir
             )
 
+            # Give the branch tracking information so the next pull is a plain
+            # `git pull` — otherwise every update repeats the fallback.
+            if result.returncode == 0 and upstream_note:
+                branch = _git_current_branch(project_dir)
+                if branch:
+                    try:
+                        subprocess.run(
+                            ['git', 'branch', f'--set-upstream-to=origin/{branch}', branch],
+                            capture_output=True, text=True, timeout=10, cwd=project_dir)
+                    except (subprocess.TimeoutExpired, OSError) as exc:
+                        logger.debug("could not set upstream for %s: %s", branch, exc)
+
             # Return custom response for git_pull
             if result.returncode == 0:
                 pull_message = "Code updated successfully."
@@ -1865,6 +2041,8 @@ def execute_system_action():
                     pull_message = f"Code updated successfully. Local changes were automatically stashed.{stash_info}"
                 if result.stdout and "Already up to date" not in result.stdout:
                     pull_message = f"Code updated successfully.{stash_info}"
+                if upstream_note:
+                    pull_message = f"{pull_message} {upstream_note}"
 
                 # Keep Python dependencies in sync automatically: if the pull
                 # changed a requirements file, install it now — users updating
@@ -1929,12 +2107,25 @@ def execute_system_action():
                         logger.warning("Post-update plugin purge failed: %s", purge_err)
             else:
                 logger.warning("git pull failed (returncode=%d): %s", result.returncode, result.stderr)
-                pull_message = "Update failed; check logs for details"
+                # Show git's own first line: "check logs" leaves the user with
+                # nothing to act on, and these failures are usually actionable
+                # (conflicting local commits, no upstream, network).
+                detail = next((ln.strip() for ln in (result.stderr or '').splitlines()
+                               if ln.strip()), '')
+                pull_message = f"Update failed: {detail}" if detail else "Update failed; check logs for details"
 
             return jsonify({
                 'status': 'success' if result.returncode == 0 else 'error',
                 'message': pull_message,
             })
+        elif action == 'checkout_branch':
+            # Switch branches from the Tools tab. Needed because a checkout
+            # that predates tracking (or a restored backup) can leave the pi
+            # on a branch the update button cannot pull.
+            result_payload, http_status = checkout_branch(
+                str(PROJECT_ROOT), data.get('branch') or '', stash=bool(data.get('stash')))
+            return jsonify(result_payload), http_status
+
         elif action == 'restart_display_service':
             result = subprocess.run(['sudo', 'systemctl', 'restart', 'ledmatrix.service'],
                                  capture_output=True, text=True, timeout=10)
@@ -2078,18 +2269,64 @@ def get_git_info():
 
         log    = subprocess.run([_GIT, 'log', '--oneline', '-5'], capture_output=True, text=True, timeout=10, cwd=d)
         remote = subprocess.run([_GIT, 'remote', 'get-url', 'origin'], capture_output=True, text=True, timeout=10, cwd=d)
+        branch_name = branch.stdout.strip()
+        upstream = _git_upstream(d)
         return jsonify({
-            'branch': branch.stdout.strip(),
+            'branch': branch_name,
             'dirty': bool(status.stdout.strip()),
             'status': status.stdout.strip(),
             'recent_commits': log.stdout.strip() if log.returncode == 0 else '',
             'remote_url': _scrub_git_remote_url(remote.stdout.strip()) if remote.returncode == 0 else '',
+            # Surfaced so the Tools tab can warn before the user clicks Pull
+            # Latest, rather than after it fails.
+            'upstream': upstream,
+            'can_pull': bool(upstream) or _git_remote_branch_exists(d, branch_name),
         })
     except Exception as e:
         logger.error("get_git_info failed: %s", e, exc_info=True)
         return jsonify({'status': 'error', 'message': 'Failed to get git info'}), 500
 
 
+@api_v3.route('/system/git-branches', methods=['GET'])
+def get_git_branches():
+    """List branches available to switch to, for the Tools tab picker."""
+    if not _GIT:
+        return jsonify({'status': 'error', 'message': 'git not found on this system'}), 503
+    d = str(PROJECT_ROOT)
+    try:
+        # Refresh remote refs so a branch created since the last fetch shows up.
+        subprocess.run([_GIT, 'fetch', 'origin', '--prune'],
+                       capture_output=True, text=True, timeout=60, cwd=d)
+
+        local = subprocess.run([_GIT, 'for-each-ref', '--format=%(refname:short)', 'refs/heads'],
+                               capture_output=True, text=True, timeout=15, cwd=d)
+        remote = subprocess.run([_GIT, 'for-each-ref', '--format=%(refname:short)', 'refs/remotes/origin'],
+                                capture_output=True, text=True, timeout=15, cwd=d)
+        if local.returncode != 0:
+            return jsonify({'status': 'error', 'message': 'Could not list branches'}), 500
+
+        local_names = [b for b in local.stdout.split() if b]
+        remote_names = []
+        for ref in remote.stdout.split() if remote.returncode == 0 else []:
+            name = ref.split('origin/', 1)[-1]
+            # origin/HEAD is a symbolic alias, not a branch a user can pick.
+            if name and name != 'HEAD' and name not in local_names:
+                remote_names.append(name)
+
+        return jsonify({
+            'status': 'success',
+            'current': _git_current_branch(d),
+            'upstream': _git_upstream(d),
+            'local': sorted(local_names),
+            'remote_only': sorted(remote_names),
+        })
+    except subprocess.TimeoutExpired:
+        return jsonify({'status': 'error', 'message': 'Timed out talking to the remote'}), 504
+    except OSError as e:
+        logger.error("get_git_branches failed: %s", e, exc_info=True)
+        return jsonify({'status': 'error', 'message': 'Failed to list branches'}), 500
+
+
 @api_v3.route('/hardware/status', methods=['GET'])
 def get_hardware_status():
     """Return LED matrix hardware initialization status written by display_manager at startup."""

web_interface/static/v3/js/widgets/array-table.js

@@ -160,6 +160,24 @@
 
     // ─── Cell rendering ─────────────────────────────────────────────────────
 
+    /**
+     * Visible text for one enum option.
+     *
+     * Mirrors the server-rendered table in plugin_config.html: a schema may
+     * supply x-options.labels, and anything unlabelled falls back to the raw
+     * value. Rows added here must match rows rendered by the template, or the
+     * same column would read differently before and after a page reload.
+     *
+     * @param {Object} colDef  column (or property) schema
+     * @param {*}      opt     the enum value
+     * @returns {string} label to display
+     */
+    function enumOptionLabel(colDef, opt) {
+        const options = (colDef && (colDef['x-options'] || colDef['x_options'])) || {};
+        const labels = options.labels || {};
+        return Object.prototype.hasOwnProperty.call(labels, opt) ? labels[opt] : opt;
+    }
+
     /**
      * Create one <td> for a display column.
      */
@@ -219,7 +237,7 @@
                 if (opt === null) return;
                 const o = document.createElement('option');
                 o.value    = opt;
-                o.textContent = opt;
+                o.textContent = enumOptionLabel(colDef, opt);
                 if (String(colValue) === String(opt)) o.selected = true;
                 sel.appendChild(o);
             });
@@ -646,7 +664,7 @@
             enumVals.forEach(opt => {
                 if (opt === null) return;
                 const o = document.createElement('option');
-                o.value = opt; o.textContent = opt;
+                o.value = opt; o.textContent = enumOptionLabel(schema, opt);
                 if (String(currentVal) === String(opt)) o.selected = true;
                 sel.appendChild(o);
             });

web_interface/templates/v3/partials/plugin_config.html

@@ -121,14 +121,21 @@
             </label>
             {% endif %}
             
-            {# Enum dropdown #}
+            {# Enum dropdown. Option text comes from x-options.labels when the
+               schema supplies it -- the same convention the checkbox-group
+               widget already uses -- because humanising the raw value cannot
+               express every label: "vs" reads as "Vs", and "abbrev" says
+               nothing about the "Sep 19" it produces. Values without a label
+               fall back to the humanised form, so existing schemas render
+               exactly as before. #}
             {% elif prop.enum %}
+            {% set enum_labels = (prop.get('x-options') or prop.get('x_options') or {}).get('labels') or {} %}
             <select id="{{ field_id }}"
                     name="{{ full_key }}"
                     class="form-select w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500 bg-white text-black">
                 {% for option in prop.enum %}
                 <option value="{{ option }}" {% if value == option %}selected{% endif %}>
-                    {{ option|replace('_', ' ')|title }}
+                    {{ enum_labels.get(option, option|replace('_', ' ')|title) }}
                 </option>
                 {% endfor %}
             </select>
@@ -569,10 +576,14 @@
                                                        class="block w-20 px-2 py-1 border border-gray-300 rounded text-sm text-center"
                                                        {% if col_def.get('description') %}title="{{ col_def.get('description') }}"{% endif %}>
                                             {% elif col_enum %}
+                                                {# Labels are opt-in here and the fallback stays the raw
+                                                   value: table columns hold things like ticker symbols,
+                                                   which must not be title-cased behind the user's back. #}
+                                                {% set col_labels = (col_def.get('x-options') or col_def.get('x_options') or {}).get('labels') or {} %}
                                                 <select name="{{ full_key }}.{{ item_index }}.{{ col_name }}"
                                                         class="block w-full px-2 py-1 border border-gray-300 rounded text-sm bg-white">
                                                     {% for opt in col_enum %}{% if opt is not none %}
-                                                    <option value="{{ opt }}" {% if col_value == opt or (col_value is none and col_def.get('default') == opt) %}selected{% endif %}>{{ opt }}</option>
+                                                    <option value="{{ opt }}" {% if col_value == opt or (col_value is none and col_def.get('default') == opt) %}selected{% endif %}>{{ col_labels.get(opt, opt) }}</option>
                                                     {% endif %}{% endfor %}
                                                 </select>
                                             {% elif col_xwidget == 'date-picker' %}

web_interface/templates/v3/partials/tools.html

@@ -31,6 +31,24 @@
         </div>
 
         <div class="space-y-4">
+            <!-- Switch branch -->
+            <div class="flex items-start justify-between gap-4">
+                <div class="min-w-0">
+                    <p class="text-sm font-medium text-gray-900">Branch</p>
+                    <p class="text-xs text-gray-500 mt-0.5">Choose which branch this pi follows. Switching attaches tracking, so Pull Latest works afterwards.</p>
+                </div>
+                <div class="shrink-0 flex items-center gap-2">
+                    <select id="branch-select" class="text-sm border border-gray-300 rounded-md px-2 py-2 bg-white max-w-[14rem]">
+                        <option value="">Loading branches…</option>
+                    </select>
+                    <button id="btn-checkout-branch" onclick="checkoutBranch(false)"
+                            class="inline-flex items-center px-3 py-2 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50">
+                        <i class="fas fa-code-branch mr-2"></i>Switch
+                    </button>
+                </div>
+            </div>
+            <div id="result-checkout-branch" class="hidden"></div>
+
             <!-- Pull latest -->
             <div class="flex items-start justify-between gap-4">
                 <div>
@@ -467,6 +485,14 @@
                     </div>`;
                 }
 
+                if (d.upstream) {
+                    html += `<p class="text-xs text-gray-500 mt-1"><i class="fas fa-link mr-1"></i>tracking <span class="font-mono">${escHtml(d.upstream)}</span></p>`;
+                } else if (d.can_pull) {
+                    html += `<p class="text-xs text-blue-700 mt-1"><i class="fas fa-info-circle mr-1"></i>No upstream set; Pull Latest will use <span class="font-mono">origin/${escHtml(d.branch || '')}</span> and set it.</p>`;
+                } else {
+                    html += `<p class="text-xs text-amber-700 mt-1"><i class="fas fa-triangle-exclamation mr-1"></i>No upstream and no matching branch on origin — Pull Latest cannot run. Switch to a branch that exists on the remote.</p>`;
+                }
+
                 if (d.remote_url) {
                     html += `<p class="text-xs text-gray-400 mt-1"><i class="fas fa-cloud mr-1"></i>${escHtml(d.remote_url)}</p>`;
                 }
@@ -479,6 +505,84 @@
             });
     }
 
+    // ── branch picker ─────────────────────────────────────────────────────
+    // A pi can end up on a branch with no tracking information (checked out by
+    // name, restored from a backup), where `git pull` refuses to run. Being
+    // able to see and change the branch from here beats needing SSH.
+
+    function loadBranches() {
+        const sel = document.getElementById('branch-select');
+        if (!sel) return;
+
+        fetch('/api/v3/system/git-branches')
+            .then(r => r.ok ? r.json() : r.json().then(d => Promise.reject(d.message || `HTTP ${r.status}`)))
+            .then(d => {
+                if (d.status === 'error') {
+                    sel.innerHTML = `<option value="">${escHtml(d.message || 'unavailable')}</option>`;
+                    sel.disabled = true;
+                    return;
+                }
+                sel.innerHTML = '';
+                const add = (name, suffix) => {
+                    const o = document.createElement('option');
+                    o.value = name;
+                    o.textContent = name + (suffix || '');
+                    if (name === d.current) o.selected = true;
+                    sel.appendChild(o);
+                };
+                (d.local || []).forEach(b => add(b, b === d.current ? '  (current)' : ''));
+                // Remote-only branches are checked out on demand.
+                (d.remote_only || []).forEach(b => add(b, '  (remote)'));
+                if (!sel.options.length) add('', 'no branches found');
+            })
+            .catch(err => {
+                sel.innerHTML = `<option value="">${escHtml(String(err))}</option>`;
+                sel.disabled = true;
+            });
+    }
+
+    window.checkoutBranch = function(stash) {
+        const sel = document.getElementById('branch-select');
+        const branch = sel && sel.value;
+        if (!branch) return;
+
+        setBusy('btn-checkout-branch', true);
+        const el = document.getElementById('result-checkout-branch');
+        if (el) el.classList.add('hidden');
+
+        fetch('/api/v3/system/action', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({action: 'checkout_branch', branch: branch, stash: !!stash})
+        })
+        .then(r => r.json().catch(() => ({status: 'error', message: `HTTP ${r.status}`})))
+        .then(d => {
+            const ok = d.status === 'success';
+            // Show git's own list of blocking files, then offer the single
+            // action that clears it. Stashing is never done unasked.
+            showResult('result-checkout-branch', ok, d.message || '', d.detail || '');
+            if (!ok && d.can_retry_with_stash && el) {
+                const retry = document.createElement('div');
+                retry.className = 'mt-2 flex items-center gap-2';
+                const label = document.createElement('span');
+                label.className = 'text-xs text-gray-700';
+                label.textContent = 'Stash these changes and switch anyway?';
+                const btn = document.createElement('button');
+                btn.className = 'inline-flex items-center px-2 py-1 border border-gray-300 text-xs font-medium rounded text-gray-700 bg-white hover:bg-gray-50';
+                btn.textContent = 'Stash and switch';
+                btn.onclick = function() { window.checkoutBranch(true); };
+                retry.appendChild(label);
+                retry.appendChild(btn);
+                el.appendChild(retry);
+            }
+            // Both panels describe the checkout, so refresh them together.
+            loadGitInfo();
+            loadBranches();
+        })
+        .catch(err => showResult('result-checkout-branch', false, String(err)))
+        .finally(() => setBusy('btn-checkout-branch', false));
+    };
+
     // ── power supply diagnostics panel ────────────────────────────────────────
     // Reuses the same SSE stream (window.statsSource, set up in base.html)
     // that already drives the header badge/banner and Overview card, instead
@@ -810,6 +914,7 @@
 
     // Load on first render; HTMX will have already swapped us in by this point.
     loadGitInfo();
+    loadBranches();
 
     // Plugin health: initial load + periodic refresh. Guard against duplicate
     // timers if this partial is re-swapped in by HTMX; the handler re-resolves