fix(store): gate the git-pull update path

docs/SPORTS_UNIFICATION.md

@@ -27,7 +27,7 @@ These are independent concerns. Conflating them is what produces god classes.
 | Plugin loads on a core that predates a module | Guarded import with a bundled fallback (`try: from src.X import Y / except ModuleNotFoundError: from y import Y`) |
 | Plugin loads on a core that predates a *method* | Capability probing — `hasattr(SportsCore, "_detect_stale_games")` — never a version comparison. The loader's compat check is advisory-only (it logs and continues), so probing is the real protection. |
 | Core changes never break a plugin's rendering | The **view-model contract**: `_extract_game_details_common` returns a dict whose `GUARANTEED_KEYS` are frozen by `test/test_skin_system.py::TestViewModelContract`. Keys may be added, never renamed or removed. |
-| A plugin can drop its bundled copy safely | The **sunset rule**: its manifest must floor `ledmatrix_min_version` at the first core release shipping the module (recorded in `CHANGELOG.md`) — *necessary but not sufficient*. Nothing enforces that floor today, so the copy also waits for the B6 gate below. |
+| A plugin can drop its bundled copy safely | The **sunset rule**: its manifest must floor `ledmatrix_min_version` at the first core release shipping the module (recorded in `CHANGELOG.md`) — *necessary but not sufficient*. The store enforces that floor on every registry-managed install and on both supported update paths (sideloading via `install_from_url` is not gated), but a floor cannot reach a user who never updates, so the copy also waits for the B6 gate below. |
 
 The core API is **additive-only**. A method the plugins call is never removed or
 given a new required parameter; new behavior arrives as new methods with
@@ -234,6 +234,20 @@ a floor can be trusted against, and today it is not:
   compares the plugin's manifest version against the registry's
   `latest_version` and nothing else.
 
+  *Fixed, in two parts.* `install_plugin` gained the gate in #431/#433, which
+  covers every registry-managed install and, through `_reinstall_with_rollback`,
+  the update path that re-downloads.
+  `update_plugin`'s git branch pulls in place and re-downloads nothing, so it
+  stayed ungated until `_gate_pulled_commit` closed it — checked after the pull
+  (the registry carries no floor field, so the incoming floor is unknowable
+  before it) and undone with `git reset --hard` to the pre-pull commit. That
+  route is rare in practice, since monorepo plugins install as archives; it was
+  closed because the sunset rule in the plugins repo's
+  `08-shared-sports-code.md` states as **condition 3** that the core enforces
+  the floor "at install/update time", and B6 rests on that being true rather
+  than merely written down. `install_from_url` — sideloading a plugin from a
+  URL — is still ungated.
+
 So B4 is: tag and release 3.2.0; make the tag, the release, and `__version__`
 agree, and keep them agreeing; reconsider the `< 2.0.0` skip; migrate manifests
 from `ledmatrix_min` to `ledmatrix_min_version`; and add the install/update

src/plugin_system/store_manager.py

@@ -2583,6 +2583,85 @@ def uninstall_plugin(self, plugin_id: str) -> bool:
             self.logger.error(f"Error uninstalling plugin {plugin_id}: {e}")
             return False
 
+    def _gate_pulled_commit(self, plugin_id: str, plugin_path: Path,
+                            previous_sha: Optional[str]) -> bool:
+        """Apply the compatibility gate to a commit that arrived via git pull.
+
+        Every other route into an installed plugin goes through
+        ``install_plugin``, which gates in ``_install_plugin_impl``. This one
+        did not: a ``git pull`` could deliver a manifest flooring above this
+        core and nothing would notice until the plugin failed to load, which
+        surfaces as one line in the journal and a scoreboard that silently
+        stopped appearing.
+
+        Checked after the pull rather than before it, for the same reason
+        ``_install_plugin_impl`` checks after the download: the registry
+        carries no compatibility field, so the incoming floor is only knowable
+        once the new commit is on disk.
+
+        Undone with ``git reset --hard`` rather than by removing the directory.
+        This is a live checkout, the previous commit is still in the object
+        store, and the reset leaves the user on the exact version they were
+        already running -- the same promise ``_reinstall_with_rollback`` makes,
+        reached by the means this path actually has. It is also the gentler
+        option: no window in which the plugin directory does not exist, and no
+        ``.standalone-backup-`` debris if the process dies mid-way.
+
+        A manifest that cannot be read is not evidence of incompatibility, so
+        it allows. ``compatibility.check`` refuses only on evidence for the
+        same reason: a wrong refusal breaks a working install, while a wrong
+        allowance degrades to exactly the behaviour this path had before the
+        gate existed.
+        """
+        manifest_path = plugin_path / "manifest.json"
+        try:
+            with open(manifest_path, 'r', encoding='utf-8') as mf:
+                manifest = json.load(mf)
+        except (OSError, ValueError) as e:
+            self.logger.warning(
+                "Could not read %s after updating %s (%s); allowing the "
+                "update, as an unreadable manifest declares no floor",
+                manifest_path, plugin_id, e)
+            return True
+
+        from src import __version__ as core_version
+        from src.plugin_system import compatibility
+
+        compatible, reason = compatibility.check(manifest, core_version)
+        if compatible:
+            return True
+
+        self.logger.error("Refusing the update to %s: %s", plugin_id, reason)
+
+        if not previous_sha:
+            self.logger.error(
+                "Cannot roll %s back: the commit it was on before the pull is "
+                "unknown. It is now on a version this core cannot run — "
+                "reinstall it from the plugin store.", plugin_id)
+            return False
+
+        # Safe by construction: update_plugin returns before pulling unless the
+        # tree was clean or successfully stashed, so there are no uncommitted
+        # tracked edits for --hard to discard. The stash is not popped on the
+        # success path either, so the reset leaves the working tree exactly
+        # where a successful pull would have. Say "commit", not "changes".
+        reset = subprocess.run(
+            ['git', '-C', str(plugin_path), 'reset', '--hard', previous_sha],
+            capture_output=True, text=True, timeout=60, check=False)
+        if reset.returncode != 0:
+            self.logger.error(
+                "CRITICAL: could not roll %s back to commit %s: %s. It is left "
+                "on a version this core cannot run; "
+                "`git -C %s reset --hard %s` restores it.",
+                plugin_id, previous_sha[:7],
+                (reset.stderr or reset.stdout or '').strip(),
+                plugin_path, previous_sha)
+        else:
+            self.logger.info(
+                "Rolled %s back to commit %s; it stays on the version it was "
+                "already running.", plugin_id, previous_sha[:7])
+        return False
+
     def _reinstall_with_rollback(self, plugin_id: str, plugin_path: Path) -> bool:
         """Replace an installed plugin with a fresh install, atomically.
 
@@ -2860,6 +2939,8 @@ def update_plugin(self, plugin_id: str) -> bool:
                         status_result = type('obj', (object,), {'stdout': '', 'stderr': 'Status check timed out'})()
 
                     stash_info = ""
+                    # Whether the pull can be undone without destroying work.
+                    tree_is_recoverable = not has_changes
                     if has_changes:
                         self.logger.info(f"Stashing local changes in {plugin_id} before update")
                         try:
@@ -2873,12 +2954,37 @@ def update_plugin(self, plugin_id: str) -> bool:
                             )
                             if stash_result.returncode == 0:
                                 stash_info = " (local changes were stashed)"
+                                tree_is_recoverable = True
                                 self.logger.info(f"Stashed local changes (including untracked files) for {plugin_id}")
                             else:
                                 self.logger.warning(f"Failed to stash local changes for {plugin_id}: {stash_result.stderr}")
                         except subprocess.TimeoutExpired:
                             self.logger.warning(f"Stash operation timed out for {plugin_id}, proceeding with pull")
 
+                    # Do not pull what cannot be un-pulled.
+                    #
+                    # The compatibility gate below can refuse the commit this
+                    # pull brings down, and its only way back is `git reset
+                    # --hard`, which discards uncommitted tracked edits. Those
+                    # edits are exactly what the stash above exists to protect,
+                    # so a stash that failed or timed out leaves the rollback
+                    # unable to run without destroying them.
+                    #
+                    # A pull does not necessarily refuse on a dirty tree -- git
+                    # merges happily as long as the incoming commit touches
+                    # different files -- so without this the update would
+                    # succeed, the gate would refuse, and the reset would take
+                    # the user's work with it. Refusing here costs an update in
+                    # a case that already went wrong; the alternative costs
+                    # data.
+                    if not tree_is_recoverable:
+                        self.logger.error(
+                            "Refusing to update %s: it has local changes that could "
+                            "not be stashed, and an incompatible update could then "
+                            "only be rolled back by discarding them. Commit or stash "
+                            "them by hand, then update.", plugin_id)
+                        return False
+
                     # Pull from the determined remote branch
                     self.logger.info(f"Pulling from origin/{remote_pull_branch} for {plugin_id}...")
                     pull_result = subprocess.run(
@@ -2901,6 +3007,14 @@ def update_plugin(self, plugin_id: str) -> bool:
                     elif updated_sha:
                         self.logger.info(f"Plugin {plugin_id} updated to commit {updated_sha[:7]}{stash_info}")
 
+                    # The install gate, at the only point on this path where
+                    # it can be answered. Every other route in goes through
+                    # install_plugin, which gates in _install_plugin_impl; this
+                    # one did not, so a pull could deliver a manifest flooring
+                    # above this core and nothing would notice.
+                    if not self._gate_pulled_commit(plugin_id, plugin_path, local_sha):
+                        return False
+
                     self._install_dependencies(plugin_path)
                     return True