fix: name RETROBIOS_REF when a list is too old

install.ps1

@@ -8,7 +8,7 @@ param(
 
 $ErrorActionPreference = "Stop"
 $defaultInstallUrl = "https://raw.githubusercontent.com/Abdess/retrobios/main/install.py"
-$defaultInstallSha256 = "8c5f113a893373b7bc0be00766f52b5c1629b9d6a587291428c06fed5c5ea61f"
+$defaultInstallSha256 = "68fa53debdfbe8d16310d037fb50ab9231fa4b51f2df5c4b8984de7a61d01374"
 $maximumInstallerBytes = 2MB
 $installerExit = 0
 $installer = if ($PSScriptRoot) { Join-Path $PSScriptRoot "install.py" } else { $null }

install.py

@@ -2811,6 +2811,21 @@ def _print_choices(
         print(f"  {name:<{width}}  {_sized(held)}")
 
 
+def _older_list_advice() -> str:
+    """How to reach a file list that records what an option needs.
+
+    A list without the fields comes from an older release. Pinned with
+    RETROBIOS_REF, as the docs suggest for reproducibility, "a newer one"
+    meant unsetting the variable, and nothing said so.
+    """
+    if RELEASE_REF != DEFAULT_RELEASE_REF:
+        return (f"  RETROBIOS_REF={RELEASE_REF} selects file lists published before "
+                "this option existed: unset RETROBIOS_REF to use the current ones, "
+                "or run without the option.")
+    return ("  The file list comes from an older release: run the one-line "
+            "installer again to fetch the current one.")
+
+
 def _requested_narrowing(
     args: argparse.Namespace, plat: str, files: list[dict], omitted: list[dict]
 ) -> tuple[list[str], list[str], list[str]] | None:
@@ -2821,10 +2836,11 @@ def _requested_narrowing(
         # Without the fields, a region filter would match nothing and install
         # everything: refused rather than ignored.
         print(
-            f"Error: the {plat} file list records no systems or regions; "
-            "narrowing needs a newer one",
+            f"Error: the {plat} file list records no systems or regions, so "
+            "--system, --core and --region cannot narrow it.",
             file=sys.stderr,
         )
+        print(_older_list_advice(), file=sys.stderr)
         sys.exit(1)
     choices = available_choices(files, omitted)
     try:
@@ -3153,9 +3169,10 @@ def _install(args: argparse.Namespace, real_stdout: TextIO) -> None:
             if "system_cores" not in manifest:
                 print(
                     f"Error: the {plat_name} file list does not say which cores "
-                    "read which systems; --installed-cores needs a newer one",
+                    "read which systems, which --installed-cores needs.",
                     file=sys.stderr,
                 )
+                print(_older_list_advice(), file=sys.stderr)
                 sys.exit(1)
             before = len(files)
             files, omitted_files = narrow_to_cores(

install.sh

@@ -18,7 +18,7 @@ esac
 TEMP_INSTALLER=""
 TEMP_DIRECTORY=""
 DEFAULT_INSTALL_URL="https://raw.githubusercontent.com/Abdess/retrobios/main/install.py"
-DEFAULT_INSTALL_SHA256="8c5f113a893373b7bc0be00766f52b5c1629b9d6a587291428c06fed5c5ea61f"
+DEFAULT_INSTALL_SHA256="68fa53debdfbe8d16310d037fb50ab9231fa4b51f2df5c4b8984de7a61d01374"
 MAX_INSTALLER_BYTES=2097152
 
 cleanup() {

tests/test_install_cores.py

@@ -379,7 +379,7 @@ class TheOneLinerReadsInstalledCores(unittest.TestCase):
             (repo.root / "cores" / "mgba_libretro.so").write_bytes(b"")
             proc = repo.run("--installed-cores")
             self.assertEqual(proc.returncode, 1)
-            self.assertIn("needs a newer one", proc.stderr)
+            self.assertIn("older release", proc.stderr)
 
     def test_a_platform_that_ships_its_cores_refuses_the_flag(self):
         with _CoreRepository() as repo:

tests/test_install_selection.py

@@ -374,6 +374,20 @@ class TheOneLinerNarrows(unittest.TestCase):
             self.assertIn("records no systems or regions", proc.stderr)
             self.assertEqual(repo.installed(), [])
 
+    def test_a_pinned_ref_is_named_as_the_way_out(self):
+        """RETROBIOS_REF=<tag>, which the docs suggest for reproducibility,
+        selects lists from before narrowing existed; the error said only
+        "narrowing needs a newer one"."""
+        with FakeRepository(selection=False) as repo:
+            proc = subprocess.run(
+                repo.command("--region", "us"),
+                env={**repo.env(), "RETROBIOS_REF": "v2026.10.10"},
+                capture_output=True, text=True, timeout=60, check=False,
+                stdin=subprocess.DEVNULL,
+            )
+            self.assertEqual(proc.returncode, 1)
+            self.assertIn("unset RETROBIOS_REF", proc.stderr)
+
     def test_empty_names_are_a_usage_error(self):
         with FakeRepository() as repo:
             for option in (["--region", " , "], ["--system", ""], ["--core", ","]):