Game menu: Update with a newer version… for Linux apps and PC VR games (#161)

Follow-up to "Update with a newer APK…": Linux apps take their new AppImage/archive or folder (a file or a folder
picker, like the app was added), PC VR games their new game folder. pipeline.replace_linux_app / replace_rift_game
re-run the add path (add_linux_app(replace=) / add_rift_game(replace=)): the entry keeps its package (so the Steam
shortcut), name, artwork, tags, switches and the user's recipe; a folder keeps the program chosen before if it's still
there, else FramePort picks again (and asks, for ambiguous PC VR games). A name that looks like another app's is
allowed with a heads-up.

The entry gets a new source_id, recorded in the deployment's recipe at install (no agent change):
components.source_replaced shows the Frame copy (and a PC install, pc_outdated) as outdated until then. Such an
install also re-sends same-size files changed after the last install (installer.changed_since), since uploads
otherwise skip files the Frame has with the same size. The old PC VR folder is left out of later scans
(replaced_dirs). CLI: frameport new-version <game> <path> (APKs too). Docs: INSTALL.md.

CLAUDE.md

@@ -223,6 +223,13 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     store matches and links then only update `auto_title`; a locked name gets no twin suffix); `sync_title` → Frame
     agent v77 `rename` (deployment.json title, same shortcut appid: upsert matches by Exe) + art + one Steam restart, PC
     `PcReviveTarget.rename`; an unreachable Frame → `steam_name_stale` (game page "Update name on Frame", next install).
+  - Newer versions (GitHub #161): game menu "Update with a newer APK…" (`pipeline.replace_apk`, outdated via
+    `build.source_version`) and, for Linux apps / PC VR games, "Update with a newer version…" (`replace_linux_app` /
+    `replace_rift_game` via `add_linux_app(replace=)` / `add_rift_game(replace=)`, CLI `frameport new-version`): the
+    entry keeps package, name, art, tags, switches, user recipe (a confirmed exe if the new folder has it); a new
+    `source_id` goes into the deployment's `recipe` dict at install (no agent change) → `C.source_replaced` = outdated
+    (Frame + `pc_outdated`); such an install re-sends same-size files changed after the last install (mtime/ctime,
+    `installer.changed_since`); the old Rift folder is in `replaced_dirs` (rescans skip it). Untested on the device.
   - `Recipe.as_is` = install unchanged (pre-patched libraries): `pipeline.prepare_as_is`; auto for APKs that already
     contain FrameBridge (`frame_patched`). For Rift it changes nothing (the dump is never modified; the Frame copy
     still gets launch fixes like the crash-reporter rename — `-nocrashreports` alone doesn't stop UE 4.23) — it does

docs/INSTALL.md

@@ -167,6 +167,10 @@ FramePort downloads it, checks it, restarts and keeps your games and settings. *
 - Settings → **Updates** turns the check off or turns on **Install updates automatically**.
 - **Recipes** (the tested patches and settings for each game) update by themselves. A game whose recipe changed shows
   **Update on Frame**.
+- **A newer version of a game:** right-click it (or use **…** on its page) → **Update with a newer APK…** (Quest and
+  Android games) or **Update with a newer version…** (Linux apps: the new AppImage, archive or folder; PC VR games:
+  the new game folder). Its name, artwork, tags and your settings stay. Then click **Update on Frame** (or **on this
+  PC**).
 - **Dev builds:** if you're asked to test a change before its release, use Settings → Updates → **Install the latest
   dev build…**. The next release then arrives as a normal update.
 
@@ -255,6 +259,7 @@ option. The main ones:
 |---|---|
 | `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's patches |
 | `add-linux <path> [--exe <program>]` | add a Linux app (AppImage, folder or archive) |
+| `new-version <game> <path>` | point a game at its newer version (APK, Linux app file/folder, PC VR game folder) |
 | `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
 | `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for this PC), launch test |
 | `frame discover` / `frame connect` / `frame info` | find, connect to and describe the Frame |

scripts/ui_smoke.py

@@ -150,7 +150,8 @@ def main() -> int:
         if args.fake_frame:  # GitHub #90: the Move to… dialog (drives load in the background)
             steps.append(("move-dialog", lambda a: (a.page.pop_dialog(), a.move_game(game))))
             steps.append(("uninstall-dialog", lambda a: (a.page.pop_dialog(), a.uninstall(game))))
-        # last: the right-click menu stays open over whatever comes next
+        # last: the menus stay open over whatever comes next (the page's "…" menu, then the right-click menu)
+        steps.append(("game-menu", lambda a: (a.show_activity(False), a.open_game_menu(game))))
         steps.append(("library-menu", lambda a: (a.show_activity(False), a.navigate(0), time.sleep(3),
                                                  a.library_view.open_menu(game))))
     if args.docs:
@@ -278,6 +279,7 @@ def main() -> int:
                  ("linux-change-program", lambda a: a.choose_exe(LINUX_FOLDER)),
                  ("frame", lambda a: (a.page.pop_dialog(), a.navigate(1))),
                  ("linux-move", lambda a: a.move_game(LINUX_APPIMAGE) if args.fake_frame else None),
+                 ("linux-game-menu", lambda a: (a.page.pop_dialog(), a.open_game_menu(LINUX_FOLDER))),
                  ("linux-menu", lambda a: (a.page.pop_dialog(), a.navigate(0), time.sleep(3),
                                            a.library_view.open_menu(LINUX_APPIMAGE)))]
     if args.links:

src/frameport/cli.py

@@ -398,6 +398,30 @@ def rename(package: str = typer.Argument(..., help="the game (package or part of
             pipeline.sync_title(pkg, _target(None, to="pc"), rep)
 
 
+@app.command("new-version")
+def new_version(package: str = typer.Argument(..., help="the game (package or part of its title)"),
+                path: Path = typer.Argument(..., exists=True, help="the newer version: an APK (Quest/Android games), "
+                                            "an AppImage/archive/folder (Linux apps) or the game folder (PC VR)")):
+    """Point a game at a newer version of it (GitHub #161). Its name, artwork, tags and your own recipe stay; install
+    it again (frameport install) to update it on the Frame."""
+    [pkg] = _pkgs(package, False)
+    try:
+        res = pipeline.replace_source(pkg, path, printing_reporter(verbose=False))
+    except pipeline.WrongPackage as exc:
+        raise typer.BadParameter(f"that APK is a different app: {exc}") from None
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from None
+    g = res["entry"]
+    typer.echo(f"{pkg}: now {path}" + (f" (program {g.get('exe')})" if g.get("kind") in ("rift", "linux") else ""))
+    if res.get("older"):
+        typer.echo("Heads-up: that APK is an older version than the one before.", err=True)
+    if res.get("different"):
+        typer.echo(f"Heads-up: {res.get('name')} looks like a different app than {g.get('title')}.", err=True)
+    if g.get("kind") == "rift" and g.get("exe_confirmed") is False:
+        typer.echo(f"More than one program could start it; FramePort picked {g.get('exe')}. Another one: "
+                   f"frameport recipe {pkg} --exe <program>", err=True)
+
+
 @app.command()
 def patches():
     """List every available patch."""

src/frameport/install/installer.py

@@ -220,6 +220,28 @@ class PcvrPlan:
     art_lookup: str | None = None  # package whose store art to use
     dest: str | None = None
     overlay: dict | None = None  # a SteamVR overlay app: the agent's overlay argument (analysis/vroverlay.py)
+    source_id: str | None = None  # which version of the game folder (GitHub #161: a newer one was added)
+    changed_since: float | None = None  # a newer version: game files changed after this are sent again (see below)
+
+
+def changed_since(path: Path, since: float | None) -> bool:
+    """A newer version of a Linux app / PC VR game (GitHub #161): uploads skip files the Frame has with the same
+    size, so a changed file of the same size would stay old. Files written (or unpacked: ctime) after the last
+    install are sent again; since=None (no newer version) never, 0 (last install unknown) always."""
+    if since is None:
+        return False
+    try:
+        st = path.stat()
+    except OSError:
+        return True
+    return max(st.st_mtime, st.st_ctime) > since
+
+
+def _recipe_record(recipe: dict | None, source_id: str | None) -> dict | None:
+    """The deployment's recipe record, with the source version it was installed from (ui.components.source_replaced)."""
+    if not source_id:
+        return recipe
+    return {**(recipe or {}), "source_id": source_id}
 
 
 def install_pcvr(frame: Frame, plan: PcvrPlan, reporter: Reporter) -> dict:
@@ -259,7 +281,8 @@ def install_pcvr(frame: Frame, plan: PcvrPlan, reporter: Reporter) -> dict:
         manifests["helpers"] = {p.name: p.stat().st_size for p in sorted(helpers.iterdir()) if p.is_file()}
         sources["helpers"] = helpers
     to_send = [(t, rel) for t, m in manifests.items() for rel, size in m.items()
-               if prep["existing"].get(t, {}).get(rel) != size]
+               if prep["existing"].get(t, {}).get(rel) != size
+               or t == "game" and changed_since(plan.game_dir / rel, plan.changed_since)]
     need = sum(manifests[t][rel] for t, rel in to_send)
     if need > prep["free_bytes"] - (1 << 30):
         raise RuntimeError(f"not enough space on the Frame: need {need / 2**30:.1f} GiB + 1 GiB headroom, "
@@ -290,7 +313,8 @@ def install_pcvr(frame: Frame, plan: PcvrPlan, reporter: Reporter) -> dict:
         game_args=game_args(plan.recipe), no_crash_reporter="pcvr.no_crash_reporter" in plan.recipe.patches,
         libovr_redirect="pcvr.libovr_redirect" in plan.recipe.patches,
         exe_sha256=plan.exe_sha256, revive_version=plan.revive_version, vr=not is_flat_windows(plan.package),
-        recipe={"patches": sorted(plan.recipe.patches), "source": plan.recipe.source}, overlay=plan.overlay,
+        recipe=_recipe_record({"patches": sorted(plan.recipe.patches), "source": plan.recipe.source}, plan.source_id),
+        overlay=plan.overlay,
     )
     reporter.log(f"installed at {result['base']} (Proton {result['proton']}, Steam shortcut id {result['appid']})")
     log_overlay(result.get("overlay"), reporter)
@@ -325,6 +349,8 @@ class LinuxPlan:
     desktop_entry: bool = True  # an entry in Desktop Mode's menu and on its desktop (GitHub #84)
     desktop_icon: bool = True  # with it, a copy on Desktop Mode's desktop (GitHub #212)
     overlay: dict | None = None  # a SteamVR overlay app: the agent's overlay argument (analysis/vroverlay.py)
+    source_id: str | None = None  # which version of the app (GitHub #161: a newer one was added)
+    changed_since: float | None = None  # a newer version: files changed after this are sent again
 
 
 def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
@@ -339,7 +365,8 @@ def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
     else:
         manifest = local_data_manifest(plan.root)
         manifest = {k: v for k, v in manifest.items() if not k.startswith(".unpacked")}
-    to_send = [rel for rel, size in manifest.items() if prep["existing"].get("app", {}).get(rel) != size]
+    to_send = [rel for rel, size in manifest.items() if prep["existing"].get("app", {}).get(rel) != size
+               or changed_since(plan.root / rel, plan.changed_since)]
     need = sum(manifest[rel] for rel in to_send)
     if need > prep["free_bytes"] - (1 << 30):
         raise RuntimeError(f"not enough space on the Frame: need {need / 2**30:.1f} GiB + 1 GiB headroom, "
@@ -358,7 +385,7 @@ def install_linux(frame: Frame, plan: LinuxPlan, reporter: Reporter) -> dict:
                          appimage=plan.appimage, openxr=plan.openxr, x86_64=plan.x86_64, manifests={"app": manifest},
                          executables=executables, tags=_tags(plan.package), dest=plan.dest,
                          desktop_entry=plan.desktop_entry, desktop_icon=plan.desktop_icon, overlay=plan.overlay,
-                         timeout=900)
+                         recipe=_recipe_record(None, plan.source_id), timeout=900)
     reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
     log_overlay(result.get("overlay"), reporter)
     apply_app_icon(frame, plan.package, prep.get("anchor"), result, reporter)

src/frameport/locales/template.json

@@ -664,6 +664,7 @@
  "Hardware video decoding (H.264, HEVC, VP9)": "",
  "Hardware video decoding on the Frame": "",
  "Heads-up: that APK is an older version than the one before.": "",
+ "Heads-up: {name} looks like a different app than {title}.": "",
  "headset found": "",
  "Hi there!": "",
  "Hide Android's navigation bar": "",
@@ -941,6 +942,8 @@
  "New recipe applied. Click Update on Frame to install it.": "",
  "Newer APK for {title}": "",
  "Newer APK of {title}": "",
+ "Newer version for {title}": "",
+ "Newer version of {title}": "",
  "Next": "",
  "Nice, it works! FramePort receives install links. (Demo: nothing was installed.)": "",
  "No": "",
@@ -1173,6 +1176,7 @@
  "Reading the file list from the Frame…": "",
  "Reading the install link": "",
  "Reading the new APK": "",
+ "Reading the new version": "",
  "ready": "",
  "Ready": "",
  "Ready to play": "",
@@ -1711,6 +1715,7 @@
  "Update the app only?": "",
  "Update tools": "",
  "Update with a newer APK…": "",
+ "Update with a newer version…": "",
  "Updates": "",
  "Updates every game marked \"Update ready\", one after another.": "",
  "Updates the game, frame rate and battery every 5 seconds. Turn off to save the Frame's power.": "",
@@ -1971,6 +1976,8 @@
  "{title}: name updated in Steam": "",
  "{title}: newer APK added": "",
  "{title}: newer APK added. Press Update on Frame to install it.": "",
+ "{title}: newer version added": "",
+ "{title}: newer version added. Press Update to install it.": "",
  "{title}: ready": "",
  "{title}: Steam artwork updated on the Frame": "",
  "{title}: {line}": "",

src/frameport/pipeline.py

@@ -137,18 +137,25 @@ def _existing_rift(folder: Path) -> dict | None:
 
 
 def add_rift_game(folder: Path, reporter: Reporter | None = None, tree=None, exe: str | None = None,
-                  force: bool = False, art: bool = False) -> dict | None:
+                  force: bool = False, art: bool = False, replace: dict | None = None) -> dict | None:
     """Analyze one Rift game folder and store it. Unchanged folders (same program, size, date) are not analyzed again;
     the user's exe choice, recipe and tags survive rescans. Returns None for folders without a VR runtime (unless
-    force)."""
+    force). replace: the library entry this folder is a newer version of (replace_rift_game): it keeps its package and
+    name."""
     from .analysis import rift
     from .recommend import catalog
 
     folder = Path(folder)
-    old = _existing_rift(folder)
+    if replace is None and not force and any(str(folder) in (g.get("replaced_dirs") or []) for g in library.games()
+                                             if g.get("kind") == "rift"):
+        if reporter:  # the older copy of a game updated from another folder: a rescan must not bring it back
+            reporter.log(f"skipped {folder.name}: an older version of a game that was updated from another folder")
+        return None
+    old = replace or _existing_rift(folder)
     old_extra = ((old or {}).get("analysis") or {}).get("extra") or {}
-    forced = exe is not None  # set_exe: always analyze with the user's choice
-    exe = exe or (old.get("exe") if old and old.get("exe_confirmed") else None)
+    forced = exe is not None or replace is not None  # set_exe / a newer version: always analyze
+    if replace is None:
+        exe = exe or (old.get("exe") if old and old.get("exe_confirmed") else None)
     if old and not forced and old_extra.get("fingerprint") and \
             old_extra["fingerprint"] == rift.fingerprint(folder, old.get("exe") or ""):
         if reporter:
@@ -177,7 +184,9 @@ def add_rift_game(folder: Path, reporter: Reporter | None = None, tree=None, exe
                   suggested=library.recipe_to_dict(recipe))
     if not old or (old.get("recipe") or {}).get("source") != "user":
         fields.update(recipe=library.recipe_to_dict(recipe), status=recipe.status)
-    if not old or not (old.get("title_locked") or old.get("art_source") in ("oculusdb", "meta", "steam")):
+    if replace is not None:
+        pass  # a newer version of the game: its name stays
+    elif not old or not (old.get("title_locked") or old.get("art_source") in ("oculusdb", "meta", "steam")):
         fields["title"] = recipe.title or a.label  # (store-matched titles are kept)
     elif old.get("title_locked") and old.get("art_source") not in ("oculusdb", "meta", "steam"):
         fields["auto_title"] = recipe.title or a.label  # the user's name stays; a reset brings this one
@@ -400,14 +409,20 @@ def missing_obb(entry: dict) -> bool:
     return bool(extra.get("expects_obb")) and not (entry.get("data_dir") and entry.get("data_bytes") != 0)
 
 
-def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str | None = None) -> dict:
+def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str | None = None,
+                  replace: str | None = None) -> dict:
     """Add a Linux app to the library (no conversion: it's installed as it is): arm64, or x86_64 (run through FEX on
-    the Frame). `exe` overrides the program FramePort picked (relative to the app's folder)."""
+    the Frame). `exe` overrides the program FramePort picked (relative to the app's folder). replace: the package of
+    the library entry this is a newer version of (replace_linux_app): it keeps that package, its name and its art."""
     from .analysis import linux
     from .core.models import Recipe
 
     path = Path(path)
     info = linux.inspect(path)
+    if replace and not exe and not info["files"]:  # a folder: the program the app started before, if it's still there
+        before = (library.game(replace) or {}).get("exe")
+        if before and before != info["exe"] and (Path(info["root"]) / before).is_file():
+            exe = before
     if exe:
         info["exe"] = exe
     x86 = info["machine"] == linux.EM_X86_64
@@ -417,7 +432,7 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
     if x86 and reporter:
         reporter.log(f"{path.name} is an x86_64 build: the Frame runs it through FEX (x86 translation; an arm64 "
                      "build runs faster if there is one)")
-    package = f"linux.{linux.slug(info['title'])}"
+    package = replace or f"linux.{linux.slug(info['title'])}"
     if reporter:
         reporter.log(f"{info['title']}: program {info['exe']}{' (AppImage)' if info['appimage'] else ''}"
                      f"{', OpenXR (VR)' if info['openxr'] else ''}")
@@ -439,6 +454,8 @@ def add_linux_app(path: Path | str, reporter: Reporter | None = None, exe: str |
     if not old:
         fields.update(title=info["title"], recipe=library.recipe_to_dict(recipe), status="unknown")
     library.upsert_game(package, **fields)
+    if replace:  # a newer version: the artwork stays as it is
+        return library.game(package)
     try:
         from .artwork import fetch
 
@@ -580,7 +597,7 @@ def install_linux(package: str, target: Target, reporter: Reporter, add_to_libra
                                   reporter, x86_64=bool(extra.get("x86_64")),
                                   desktop_entry=entry.get("desktop_entry", True) is not False,
                                   desktop_icon=entry.get("desktop_icon", True) is not False,
-                                  overlay=linux_overlay(entry))
+                                  overlay=linux_overlay(entry), **_source_args(entry, target.label))
     if extra.get("x86_64"):
         reporter.check("x86 translation", True, "runs through FEX on SteamOS's x86 system (its libraries come from "
                                                  "there; not checked ahead)")
@@ -591,10 +608,23 @@ def install_linux(package: str, target: Target, reporter: Reporter, add_to_libra
         reporter.check("Libraries on the Frame", True, "everything the app needs is there")
     if add_to_library:
         target.add_to_library([package], reporter)
-    _record_install(package, target.label, {"exe": entry["exe"], "result": result, "time": time.time()})
+    _record_install(package, target.label, {"exe": entry["exe"], "result": result, "time": time.time(),
+                                            "source_id": entry.get("source_id")})
     return result
 
 
+def _source_args(entry: dict, label: str) -> dict:
+    """source_id (recorded with the install) and changed_since for a Linux app / PC VR game install: after a newer
+    version was added (replace_linux_app/replace_rift_game), files changed since the last install there are sent
+    again even when the Frame has a file of the same size (0 = the last install is unknown: every file)."""
+    sid = entry.get("source_id")
+    if not sid:
+        return {}
+    rec = (entry.get("installs") or {}).get(label) or {}
+    return {"source_id": sid,
+            "changed_since": None if rec.get("source_id") == sid else float(rec.get("time") or 0)}
+
+
 def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
     if reporter:
         reporter.log(f"analyzing {src.apk.name}")
@@ -662,6 +692,85 @@ def replace_apk(package: str, apk: Path, reporter: Reporter | None = None) -> di
             "new_version": new_vc}
 
 
+def _looks_different(before: str | None, now: str | None) -> bool:
+    """A newer version whose name has little in common with the old one's (maybe another app): the caller warns."""
+    import difflib
+
+    a, b = _norm_title(before or ""), _norm_title(now or "")
+    if not a or not b or a in b or b in a:
+        return False
+    return difflib.SequenceMatcher(None, a, b).ratio() < 0.5
+
+
+def _mark_source_replaced(package: str, **fields) -> dict:
+    """A Linux app or PC VR game got a newer version: a new source id, which installs record (in the deployment's
+    recipe); an install without it shows the game as outdated (ui.components.source_replaced)."""
+    import uuid
+
+    return library.upsert_game(package, source_id=uuid.uuid4().hex[:12], source_updated=time.time(), **fields)
+
+
+def replace_linux_app(package: str, path: Path | str, reporter: Reporter | None = None) -> dict:
+    """A newer version of a Linux app already in the library (GitHub #161): an AppImage/archive or a folder, analysed
+    like "Add a Linux app…" (program, arm64/x86_64, AppImage, OpenXR). The app keeps its package (so its Steam
+    shortcut on the Frame), name, artwork, tags and switches (Desktop Mode entry, overlay app); a folder keeps the
+    program chosen before if it's still there. Returns {"entry", "different": its name looks like another app's,
+    "name": the new version's own name}."""
+    entry = library.game(package)
+    if entry is None or not is_linux(entry):
+        raise ValueError("only Linux apps can get a newer version this way")
+    before = ((entry.get("analysis") or {}).get("label")) or entry.get("title")
+    old_source = ((entry.get("analysis") or {}).get("extra") or {}).get("source")
+    if reporter:
+        reporter.log(f"reading {Path(path).name}")
+    stored = add_linux_app(path, reporter, replace=package)
+    name = (stored.get("analysis") or {}).get("label")
+    stored = _mark_source_replaced(package, replaced_source=old_source)
+    return {"entry": stored, "different": _looks_different(before, name), "name": name}
+
+
+def replace_rift_game(package: str, folder: Path | str, reporter: Reporter | None = None) -> dict:
+    """A newer version of a PC VR (Rift) game already in the library (GitHub #161): its new game folder, analysed like
+    a scanned one (programs, VR runtimes, fingerprint). The game keeps its package, name, artwork, tags and the user's
+    own recipe; a program the user confirmed stays if the new folder has it at the same place, else FramePort picks
+    one again (exe_confirmed False when that's unclear: the caller asks). The old folder is left out of later scans.
+    Returns {"entry", "different", "name", "exe_changed"}."""
+    entry = library.game(package)
+    if entry is None or not is_rift(entry):
+        raise ValueError("only PC VR games can get a newer version folder")
+    folder = Path(folder)
+    if not folder.is_dir():
+        raise ValueError(f"{folder} isn't a folder")
+    other = _existing_rift(folder)
+    if other and other["package"] != package:
+        raise ValueError(f"{folder.name} is already in the library as {other.get('title') or other['package']}")
+    before = (entry.get("analysis") or {}).get("label") or entry.get("title")
+    old_dir, old_exe = entry.get("game_dir"), entry.get("exe")
+    keep = old_exe if entry.get("exe_confirmed") and old_exe and (folder / old_exe).is_file() else None
+    stored = add_rift_game(folder, reporter, exe=keep, force=True, replace=entry)
+    if stored is None:
+        raise ValueError(f"no game program found in {folder.name}")
+    replaced = [d for d in (entry.get("replaced_dirs") or []) + [old_dir] if d and d != str(folder)]
+    # build=None: the next install checks the new folder first (prepare_rift); the exe's checksum comes from there
+    stored = _mark_source_replaced(package, build=None, replaced_dirs=list(dict.fromkeys(replaced)))
+    name = (stored.get("analysis") or {}).get("label")
+    return {"entry": stored, "different": _looks_different(before, name), "name": name,
+            "exe_changed": stored.get("exe") != old_exe}
+
+
+def replace_source(package: str, path: Path | str, reporter: Reporter | None = None) -> dict:
+    """A newer version of any game in the library: an APK (Quest/Android), an app file or folder (Linux) or a game
+    folder (PC VR). See replace_apk, replace_linux_app, replace_rift_game."""
+    entry = library.game(package)
+    if entry is None:
+        raise ValueError(f"{package} isn't in the library")
+    if is_linux(entry):
+        return replace_linux_app(package, path, reporter)
+    if is_rift(entry):
+        return replace_rift_game(package, path, reporter)
+    return replace_apk(package, Path(path), reporter)
+
+
 def _analyze_entry(entry: dict, reporter: Reporter | None = None):
     src = source_of(entry)
     if reporter:
@@ -1275,10 +1384,11 @@ def install_rift(package: str, target: Target, reporter: Reporter, add_to_librar
     result = target.install_pcvr(package, title, Path(entry["game_dir"]), entry["exe"], recipe, reporter,
                                  revive_dir=rdir, revive_version=revive.installed_version() if rdir else None,
                                  exe_sha256=entry["build"].get("sha256"), art_lookup=entry.get("quest_package"),
-                                 overlay=rift_overlay(entry, recipe))
+                                 overlay=rift_overlay(entry, recipe), **_source_args(entry, target.label))
     if add_to_library:
         target.add_to_library([package], reporter)
-    _record_install(package, target.label, {"exe": entry["exe"], "result": result, "time": time.time()})
+    _record_install(package, target.label, {"exe": entry["exe"], "result": result, "time": time.time(),
+                                            "source_id": entry.get("source_id")})
     return result
 
 

src/frameport/targets/base.py

@@ -36,7 +36,8 @@ class Target(ABC):
         raise NotImplementedError(f"{self.label} can't launch games")
 
     def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False,
-                      desktop_entry=True, overlay=None, desktop_icon=True) -> dict:
+                      desktop_entry=True, overlay=None, desktop_icon=True, source_id=None,
+                      changed_since=None) -> dict:
         """Install a Linux app (only the Frame runs them; x86_64 ones through FEX)."""
         raise NotImplementedError(f"{self.label} can't install Linux apps")
 

src/frameport/targets/frame_lepton.py

@@ -86,14 +86,15 @@ class FrameLeptonTarget(Target):
     def install_pcvr(self, package, title, game_dir, exe, recipe, reporter, **extra):
         plan = installer.PcvrPlan(package, title, Path(game_dir), exe, recipe, extra.get("revive_dir"),
                                   extra.get("exe_sha256"), extra.get("revive_version"), extra.get("art_lookup"),
-                                  dest=self.install_dest(), overlay=extra.get("overlay"))
+                                  dest=self.install_dest(), overlay=extra.get("overlay"),
+                                  source_id=extra.get("source_id"), changed_since=extra.get("changed_since"))
         return installer.install_pcvr(self.connect().frame, plan, reporter)
 
     def install_linux(self, package, title, root, exe, files, appimage, openxr, reporter, x86_64=False,
-                      desktop_entry=True, overlay=None, desktop_icon=True):
+                      desktop_entry=True, overlay=None, desktop_icon=True, source_id=None, changed_since=None):
         plan = installer.LinuxPlan(package, title, Path(root), exe, files, appimage, openxr, x86_64,
                                    dest=self.install_dest(), desktop_entry=desktop_entry, overlay=overlay,
-                                   desktop_icon=desktop_icon)
+                                   desktop_icon=desktop_icon, source_id=source_id, changed_since=changed_since)
         return installer.install_linux(self.connect().frame, plan, reporter)
 
     def drives(self) -> list[dict]:

src/frameport/targets/pc_revive.py

@@ -191,7 +191,9 @@ class PcReviveTarget(Target):
                "tuning": dict(recipe.params("pcvr.steamvr_tuning"), enabled=True)
                if "pcvr.steamvr_tuning" in recipe.patches else None,
                "sha256": extra.get("exe_sha256"), "art_lookup": extra.get("art_lookup"),
-               "recipe": {"patches": sorted(recipe.patches), "source": recipe.source}, "time": time.time()}
+               "recipe": {"patches": sorted(recipe.patches), "source": recipe.source,
+                          **({"source_id": extra["source_id"]} if extra.get("source_id") else {})},
+               "time": time.time()}
         exe_field, _, _ = shortcut_fields(dep)
         d = pc_dir() / package
         try:  # a reinstall keeps the shortcut's appid: Steam's entry is matched by its Exe, whatever its name now

src/frameport/ui/app.py

@@ -880,7 +880,7 @@ class FramePortApp:
                     self.toast(msg, error=True, action=tr("Details"),
                                on_action=lambda e: self.show_activity(True))
             self.refresh_view()
-            if job.kind == "scan" and self.exe_queue:
+            if job.kind in ("scan", "task") and self.exe_queue:  # (a task: a newer PC VR game version)
                 self.page.run_thread(self.next_exe_choice)
         elif job and job.active and job.package and self.route[:2] == ("game", job.package):
             pkg, transit = self.hero_transit or (None, None)
@@ -1152,6 +1152,7 @@ class FramePortApp:
             "move": lambda e: self.move_game(pkg),
             "update_app": lambda e: self.update_app_only(pkg),
             "new_apk": lambda e: self.page.run_task(self.update_with_apk, pkg),
+            "new_version": lambda e: self.page.run_task(self.update_with_version, pkg),
             "uninstall_frame": lambda e: self.uninstall(pkg, "frame"),
             "uninstall_pc": lambda e: self.uninstall(pkg, "pc"),
             "remove": lambda e: self.remove_from_library(pkg),
@@ -1168,7 +1169,8 @@ class FramePortApp:
             settings=self.has_game_settings(g), programs=rift or (linux and bool(self.linux_programs(g))),
             selectable=lv is not None,
             media_button=C.is_media_player(g) and not rift,
-            movable=connected and C.frame_drive(g, self.frame_info) is not None, android=not rift and not linux)
+            movable=connected and C.frame_drive(g, self.frame_info) is not None, android=not rift and not linux,
+            new_version=rift or linux)
         return menu_sections(g, st, handlers.__getitem__)
 
     def open_game_menu(self, pkg: str) -> None:
@@ -1621,6 +1623,60 @@ class FramePortApp:
             return tr("{title}: newer APK added").format(title=self._title(pkg))
         self.submit(tr("Newer APK for {title}").format(title=self._title(pkg)), run, pkg, "task")
 
+    async def update_with_version(self, pkg: str) -> None:
+        """Game menu "Update with a newer version…" for Linux apps and PC VR games (GitHub #161): pick the new app
+        file or folder (how the app was added) / the new game folder; the game keeps its name, art, tags and switches,
+        and its page then offers Update on Frame (or on this PC)."""
+        from ..analysis import linux as linux_analysis
+
+        if self.jobs.busy_with(pkg):
+            return
+        g = library.game(pkg) or {}
+        rift = g.get("kind") == "rift"
+        title = tr("Newer version of {title}").format(title=self._title(pkg))
+        if rift or self._linux_folder_app(g):
+            path = await C.pick_dir(self.page, dialog_title=title)
+            if not path:
+                return
+        else:
+            paths = await C.pick_files(self.page, dialog_title=title)
+            if not paths:
+                return
+            path = paths[0]
+            if not linux_analysis.looks_like_linux_app(Path(path)):
+                self.toast(tr("{name} isn't a Linux app (AppImage, Linux program or .zip/.tar archive)")
+                           .format(name=Path(path).name), error=True)
+                return
+        on_frame = self.frame_state == "connected" and \
+            C.install_state(g, self.frame_info) in ("installed", "outdated")
+        on_pc = rift and pkg in self.pc_installs()
+
+        def run(job: Job):
+            job.reporter.stage(tr("Reading the new version"))
+            res = pipeline.replace_source(pkg, Path(path), job.reporter)
+            if res.get("different"):
+                self.toast(tr("Heads-up: {name} looks like a different app than {title}.").format(
+                    name=res.get("name") or Path(path).name, title=self._title(pkg)))
+            if rift and res["entry"].get("exe_confirmed") is False:  # which program starts it? (asked after the job)
+                self.exe_queue.append(pkg)
+            self.open_game(pkg)
+            if on_frame or on_pc:
+                return tr("{title}: newer version added. Press Update to install it.").format(
+                    title=self._title(pkg))
+            return tr("{title}: newer version added").format(title=self._title(pkg))
+        self.submit(tr("Newer version for {title}").format(title=self._title(pkg)), run, pkg, "task")
+
+    @staticmethod
+    def _linux_folder_app(g: dict) -> bool:
+        """A Linux app added from a folder (its newer version is a folder too), not from an AppImage/archive."""
+        from ..analysis import linux as linux_analysis
+
+        extra = (g.get("analysis") or {}).get("extra") or {}
+        source = Path(extra.get("source") or g.get("game_dir") or "")
+        if source.exists():
+            return source.is_dir()
+        return not extra.get("files") and not source.name.lower().endswith(linux_analysis.ARCHIVES)
+
     def updatable(self) -> list[tuple[str, str]]:
         """[(package, "frame" | "pc")] installs with an update ready (a newer build or changed patch settings)."""
         out = []

src/frameport/ui/components.py

@@ -178,6 +178,8 @@ def install_state(game: dict, frame_info: dict | None) -> str | None:
     # still installed (GitHub #90)
     if not dep or (dep.get("apk_present") is False and not dep.get("drive_missing")):
         return "missing"
+    if source_replaced(game, dep):
+        return "outdated"  # a newer version of the Linux app / PC VR game was added since this install (GitHub #161)
     b = game.get("build") or {}
     if game.get("kind") not in ("linux", "rift") and b.get("apk_recipe_fp") and dep.get("configuration_fp"):
         from ..game_update import plan_update
@@ -194,6 +196,16 @@ def install_state(game: dict, frame_info: dict | None) -> str | None:
     return "outdated" if settings_diff(game, frame_info) else "installed"
 
 
+def source_replaced(game: dict, dep: dict | None) -> bool:
+    """A Linux app or PC VR game got a newer version ("Update with a newer version…", GitHub #161) that this install
+    (the Frame's or the PC's deployment record) doesn't have yet."""
+    sid = game.get("source_id")
+    if not sid or game.get("kind") not in ("linux", "rift"):
+        return False
+    rec = (dep or {}).get("recipe")
+    return (rec.get("source_id") if isinstance(rec, dict) else None) != sid
+
+
 def recipe_changed(game: dict) -> bool:
     from ..patches.base import recipe_fingerprint, revised_since_unrecorded
 
@@ -216,7 +228,7 @@ def pc_outdated(g: dict, dep: dict) -> bool:
         args = game_args(recipe_from_dict(g["recipe"]))
     except Exception:  # noqa: BLE001
         args = dep.get("game_args") or []
-    return installed != want or list(dep.get("game_args") or []) != args
+    return installed != want or list(dep.get("game_args") or []) != args or source_replaced(g, dep)
 
 
 def one_choice():

src/frameport/ui/menus.py

@@ -35,6 +35,7 @@ class MenuState:
     media_button: bool = False     # the game page shows "Add videos" already
     movable: bool = False          # the Frame knows which drive it's on (agent v63+, microSD): Move to…
     android: bool = False          # a Quest/Android game (not PC VR, not a Linux app): it can get a newer APK
+    new_version: bool = False      # a Linux app or PC VR game: it can get a newer version (file or folder)
 
 
 def menu_sections(g: dict, st: MenuState, act: Callable[[str], Callable]) -> list:
@@ -55,6 +56,8 @@ def menu_sections(g: dict, st: MenuState, act: Callable[[str], Callable]) -> lis
         top.append((tr("Move to…"), ft.Icons.DRIVE_FILE_MOVE_ROUNDED, act("move")))
     if st.android and not job:  # GitHub #161: the game keeps its name, art and recipe
         top.append((tr("Update with a newer APK…"), ft.Icons.UPGRADE_ROUNDED, act("new_apk")))
+    if st.new_version and not job:  # the same for Linux apps and PC VR games
+        top.append((tr("Update with a newer version…"), ft.Icons.UPGRADE_ROUNDED, act("new_version")))
     if st.on_frame and not rift and not linux and not job:
         # the new build only; the Frame's game data stays (e.g. changed OBBs a normal update would replace)
         top.append((tr("Update app only…"), ft.Icons.SYSTEM_UPDATE_ALT_ROUNDED, act("update_app")))
@@ -103,6 +106,8 @@ def quick_menu(st: MenuState, act: Callable[[str], Callable]) -> list:
     out += st.installs[:1]
     if st.android:
         out.append((tr("Update with a newer APK…"), ft.Icons.UPGRADE_ROUNDED, act("new_apk")))
+    if st.new_version:
+        out.append((tr("Update with a newer version…"), ft.Icons.UPGRADE_ROUNDED, act("new_version")))
     if st.settings:
         out.append((tr("Game settings…"), ft.Icons.TUNE_ROUNDED, act("settings")))
     out.append((tr("Rename…"), ft.Icons.DRIVE_FILE_RENAME_OUTLINE_OUTLINED, act("rename")))

tests/test_menus.py

@@ -31,9 +31,11 @@ def _states():
         ("quest not installed", QUEST, MenuState(connected=True, installs=[_install("Install on Frame")],
                                                  settings=True, selectable=True, android=True)),
         ("rift on PC", RIFT, MenuState(on_pc=True, plays=[_play("this PC")], programs=True, selectable=True,
-                                       installs=[_install("Reinstall on this PC")])),
+                                       installs=[_install("Reinstall on this PC")], new_version=True)),
         ("linux on Frame", LINUX, MenuState(connected=True, on_frame=True, plays=[_play()], installs=[_install()],
-                                            selectable=True)),
+                                            selectable=True, new_version=True)),
+        ("linux job running", LINUX, MenuState(connected=True, on_frame=True, job=True, selectable=True,
+                                               new_version=True)),
         ("job running", QUEST, MenuState(connected=True, on_frame=True, job=True, settings=True, selectable=True,
                                          android=True)),
     ]
@@ -172,3 +174,17 @@ def test_newer_apk_for_quest_games_in_both_menus():
         want = g is QUEST and not st.job
         assert ("Update with a newer APK…" in quick) == want, name
         assert ("Update with a newer APK…" in full) == want, name
+
+
+def test_newer_version_for_linux_apps_and_pc_vr_games():
+    """GitHub #161: Linux apps and PC VR games get "Update with a newer version…" (a file or folder), not the APK
+    entry, in both menus; never while a job runs."""
+    for name, g, st in _states():
+        quick = [e[0] for e in _items(menu_sections(g, st, _key))]
+        st.quick = False
+        full = [e[0] for e in _items(menu_sections(g, st, _key))]
+        want = g is not QUEST and not st.job
+        assert ("Update with a newer version…" in quick) == want, name
+        assert ("Update with a newer version…" in full) == want, name
+        if g is not QUEST:
+            assert "Update with a newer APK…" not in quick + full, name

tests/test_newer_version.py

@@ -0,0 +1,230 @@
+"""GitHub #161: a newer version of a Linux app or a PC VR game already in the library (game menu "Update with a newer
+version…", CLI `frameport new-version`)."""
+import os
+import time
+
+import pytest
+from test_install_drives import FakeFrame
+from test_linux_apps import elf
+from test_rift import unity_game
+
+from frameport import pipeline
+from frameport.analysis import linux
+from frameport.core import library
+from frameport.core.events import Reporter
+from frameport.install import installer
+from frameport.ui import components as C
+
+
+def _appimage(path, extra=b""):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(elf(linux.EM_AARCH64, appimage=True, extra=extra))
+    return path
+
+
+def _frame(package, recipe=None):
+    return {"installed": [{"package": package, "sha256": None, "recipe": recipe}]}
+
+
+# ------------------------------------------------------------------------------------------ Linux apps
+def test_newer_appimage_keeps_name_art_and_switches(tmp_path):
+    old = _appimage(tmp_path / "v1" / "Venera-Prime-2.4.2-aarch64.AppImage")
+    pkg = pipeline.add_linux_app(old)["package"]
+    library.upsert_game(pkg, title="My Venera", title_locked=True, tags=["mine"], desktop_entry=False,
+                        desktop_icon=False, vr_overlay=True)
+    assert C.install_state(library.game(pkg), _frame(pkg)) == "installed"  # never updated: no source id needed
+    new = _appimage(tmp_path / "v2" / "Venera-Prime-2.5.0-aarch64.AppImage", extra=b"newer")
+    res = pipeline.replace_linux_app(pkg, new)
+    g = library.game(pkg)
+    assert g["package"] == pkg and g["exe"] == new.name and g["game_dir"] == str(new.parent)
+    assert g["analysis"]["extra"]["source"] == str(new) and g["analysis"]["extra"]["files"] == [new.name]
+    assert g["data_bytes"] == new.stat().st_size
+    assert (g["title"], g["title_locked"], g["tags"]) == ("My Venera", True, ["mine"])
+    assert (g["desktop_entry"], g["desktop_icon"], g["vr_overlay"]) == (False, False, True)
+    assert g["replaced_source"] == str(old) and g["source_id"] and res["different"] is False
+    # the Frame's copy (installed before) is outdated until an install records this version
+    assert C.install_state(g, _frame(pkg)) == "outdated"
+    assert C.install_state(g, _frame(pkg, {"source_id": "older"})) == "outdated"
+    assert C.install_state(g, _frame(pkg, {"source_id": g["source_id"]})) == "installed"
+
+
+def test_newer_linux_folder_keeps_the_chosen_program(tmp_path):
+    def app(root, size):
+        (root / "bin").mkdir(parents=True)
+        (root / "Tool").write_bytes(elf(linux.EM_AARCH64, extra=b"\0" * size))  # bigger: FramePort's pick
+        (root / "bin" / "tool-vr").write_bytes(elf(linux.EM_AARCH64))
+        return root
+    pkg = pipeline.add_linux_app(app(tmp_path / "v1" / "Tool", 4096), exe="bin/tool-vr")["package"]
+    assert library.game(pkg)["exe"] == "bin/tool-vr"
+    pipeline.replace_linux_app(pkg, app(tmp_path / "v2" / "Tool", 8192))
+    g = library.game(pkg)
+    assert g["exe"] == "bin/tool-vr" and g["game_dir"] == str(tmp_path / "v2" / "Tool")
+    # the program isn't there any more: FramePort's pick
+    (tmp_path / "v3" / "Tool").mkdir(parents=True)
+    (tmp_path / "v3" / "Tool" / "Tool").write_bytes(elf(linux.EM_AARCH64))
+    pipeline.replace_linux_app(pkg, tmp_path / "v3" / "Tool")
+    assert library.game(pkg)["exe"] == "Tool"
+
+
+def test_another_linux_app_is_added_with_a_warning(tmp_path):
+    pkg = pipeline.add_linux_app(_appimage(tmp_path / "Venera-Prime-1.0-aarch64.AppImage"))["package"]
+    res = pipeline.replace_linux_app(pkg, _appimage(tmp_path / "Blender-4.2-aarch64.AppImage"))
+    assert res["different"] and res["name"] == "Blender" and library.game(pkg)["exe"].startswith("Blender")
+    assert not library.game("linux.blender")  # no second entry: the user's pick is the newer version
+    with pytest.raises(ValueError):
+        pipeline.replace_linux_app(pkg, tmp_path / "missing.AppImage")
+
+
+def test_only_the_right_kind(tmp_path):
+    pkg = pipeline.add_linux_app(_appimage(tmp_path / "Tool-aarch64.AppImage"))["package"]
+    with pytest.raises(ValueError):
+        pipeline.replace_rift_game(pkg, tmp_path)
+    library.upsert_game("com.x.quest", title="Quest", apk="/x.apk")
+    with pytest.raises(ValueError):
+        pipeline.replace_linux_app("com.x.quest", tmp_path / "Tool-aarch64.AppImage")
+
+
+def test_linux_update_sends_changed_files_of_the_same_size(tmp_path, monkeypatch):
+    (tmp_path / "app").mkdir()
+    for name in ("tool", "data.txt"):
+        (tmp_path / "app" / name).write_bytes(b"x" * 10)
+    old = time.time() - 3600
+    os.utime(tmp_path / "app" / "data.txt", (old, old))
+    monkeypatch.setattr(installer, "upload_steam_art", lambda *a, **k: None)
+    monkeypatch.setattr(installer, "apply_app_icon", lambda *a, **k: None)
+    monkeypatch.setattr(installer, "_tags", lambda pkg: [])
+    sent = []
+    monkeypatch.setattr(installer, "upload_files", lambda xfer, files, *a: sent.extend(f[1] for f in files))
+    monkeypatch.setattr(installer, "transfer_link", lambda *a: _Null())
+    frame = FakeFrame({"prepare_linux": {"existing": {"app": {"tool": 10, "data.txt": 10}}, "free_bytes": 1 << 40,
+                                         "incoming": "/x/incoming", "base": "/b"},
+                       "finalize_linux": {"base": "/b", "appid": 1}})
+    plan = installer.LinuxPlan("linux.tool", "Tool", tmp_path / "app", "tool")
+    installer.install_linux(frame, plan, Reporter())
+    assert sent == [] and dict(frame.calls)["finalize_linux"]["recipe"] is None  # same sizes: nothing sent
+    # (st_ctime can't be set: the file's own ctime is now) a newer version: files changed since the last install
+    plan = installer.LinuxPlan("linux.tool", "Tool", tmp_path / "app", "tool", source_id="v2",
+                               changed_since=time.time() + 60)
+    installer.install_linux(frame, plan, Reporter())
+    assert sent == []
+    plan.changed_since = time.time() - 60
+    installer.install_linux(frame, plan, Reporter())
+    assert sorted(sent) == ["app/data.txt", "app/tool"]
+    assert frame.calls[-1][1]["recipe"] == {"source_id": "v2"}
+
+
+class _Null:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, *a):
+        return False
+
+
+def test_install_records_the_version(tmp_path, monkeypatch):
+    pkg = pipeline.add_linux_app(_appimage(tmp_path / "v1" / "Tool-aarch64.AppImage"))["package"]
+    got = {}
+
+    class T:
+        label = "Frame"
+
+        def install_linux(self, *a, **k):
+            got.clear()
+            got.update(k)
+            return {}
+    monkeypatch.setattr(pipeline, "steam_title", lambda e: "Tool")
+    pipeline.install_linux(pkg, T(), Reporter(), add_to_library=False)
+    assert "source_id" not in got  # never updated: installs as before
+    pipeline.replace_linux_app(pkg, _appimage(tmp_path / "v2" / "Tool-aarch64.AppImage"))
+    sid = library.game(pkg)["source_id"]
+    pipeline.install_linux(pkg, T(), Reporter(), add_to_library=False)
+    assert got["source_id"] == sid and 0 < got["changed_since"] <= time.time()  # since the last install there
+    assert library.game(pkg)["installs"]["Frame"]["source_id"] == sid
+    pipeline.install_linux(pkg, T(), Reporter(), add_to_library=False)
+    assert got["changed_since"] is None  # this version is there already: resumes as usual
+
+
+# ------------------------------------------------------------------------------------------ PC VR (Rift) games
+def _rift(tmp_path):
+    first = unity_game(tmp_path / "v1")
+    [g] = pipeline.add_path(tmp_path / "v1")
+    pkg = g["package"]
+    r = library.recipe_from_dict(g["recipe"])
+    r.source = "user"
+    r.patches["pcvr.no_crash_reporter"] = {}
+    pipeline.set_recipe(pkg, r)
+    library.upsert_game(pkg, title="My Space", tags=["mine"], exe_confirmed=True,
+                        build={"ok": True, "sha256": "old", "kind": "rift"})
+    return pkg, first
+
+
+def test_newer_rift_folder_keeps_name_recipe_and_program(tmp_path):
+    pkg, first = _rift(tmp_path)
+    new = unity_game(tmp_path / "v2")
+    res = pipeline.replace_rift_game(pkg, new)
+    g = library.game(pkg)
+    assert g["game_dir"] == str(new) and g["exe"] == "Space Game.exe" and g["exe_confirmed"] is True
+    assert (g["title"], g["tags"]) == ("My Space", ["mine"])
+    assert "pcvr.no_crash_reporter" in g["recipe"]["patches"] and g["recipe"]["source"] == "user"
+    assert g["build"] is None and g["replaced_dirs"] == [str(first)] and not res["different"]
+    from frameport.patches.pcvr import game_args
+
+    dep = {"package": pkg, "sha256": "old", "recipe": {"patches": sorted(g["recipe"]["patches"])},
+           "game_args": game_args(library.recipe_from_dict(g["recipe"]))}
+    assert C.install_state(g, {"installed": [dep]}) == "outdated"
+    assert C.pc_outdated(g, dep)
+    dep["recipe"]["source_id"] = g["source_id"]
+    assert C.install_state(g, {"installed": [dep]}) == "installed" and not C.pc_outdated(g, dep)
+    # a rescan of the folders doesn't bring the old copy back
+    assert pipeline.add_path(tmp_path / "v1") == [] and library.game(pkg)["game_dir"] == str(new)
+
+
+def test_newer_rift_folder_without_the_program_picks_again(tmp_path):
+    pkg, _ = _rift(tmp_path)
+    new = unity_game(tmp_path / "v2", name="Space Game VR")
+    res = pipeline.replace_rift_game(pkg, new)
+    assert res["exe_changed"] and library.game(pkg)["exe"] == "Space Game VR.exe"
+    with pytest.raises(ValueError):
+        pipeline.replace_rift_game(pkg, tmp_path / "nothing")
+    other = unity_game(tmp_path / "other", name="Moon Game")
+    pipeline.add_path(tmp_path / "other")
+    with pytest.raises(ValueError, match="already in the library"):
+        pipeline.replace_rift_game(pkg, other)
+
+
+def test_rift_update_resends_changed_game_files(tmp_path, monkeypatch):
+    game = unity_game(tmp_path)
+    monkeypatch.setattr(installer, "upload_steam_art", lambda *a, **k: None)
+    monkeypatch.setattr(installer, "_tags", lambda pkg: [])
+    monkeypatch.setattr(installer, "transfer_link", lambda *a: _Null())
+    sent = []
+    monkeypatch.setattr(installer, "upload_files", lambda xfer, files, *a: sent.extend(f[1] for f in files))
+    monkeypatch.setattr("frameport.artwork.sources.has_art", lambda pkg: True)
+    manifest = installer.local_data_manifest(game)
+    frame = FakeFrame({"prepare_pcvr": {"proton": {"display_name": "Proton"}, "openxr": None,
+                                        "existing": {"game": dict(manifest)}, "free_bytes": 1 << 40,
+                                        "incoming": "/i", "base": "/b"},
+                       "finalize_pcvr": {"base": "/b", "proton": "p", "appid": 1}})
+    from frameport.core.models import Recipe
+
+    plan = installer.PcvrPlan("rift.space_game", "Space", game, "Space Game.exe", Recipe(package="rift.space_game"),
+                              None, source_id="v2", changed_since=time.time() - 60)
+    installer.install_pcvr(frame, plan, Reporter())
+    assert sorted(sent) == sorted(f"game/{rel}" for rel in manifest)
+    assert frame.calls[-1][1]["recipe"]["source_id"] == "v2"
+
+
+# ------------------------------------------------------------------------------------------ CLI
+def test_cli_new_version(tmp_path):
+    from typer.testing import CliRunner
+
+    from frameport import cli
+
+    pkg = pipeline.add_linux_app(_appimage(tmp_path / "v1" / "Tool-1.0-aarch64.AppImage"))["package"]
+    new = _appimage(tmp_path / "v2" / "Tool-1.1-aarch64.AppImage")
+    out = CliRunner().invoke(cli.app, ["new-version", pkg, str(new)])
+    assert out.exit_code == 0, out.output
+    assert library.game(pkg)["exe"] == new.name and "program Tool-1.1-aarch64.AppImage" in out.output
+    (tmp_path / "empty").mkdir()
+    bad = CliRunner().invoke(cli.app, ["new-version", pkg, str(tmp_path / "empty")])  # no program in it
+    assert bad.exit_code == 2