Merge pull request #292 from spoopyghosty0/catalog/issue-270

catalog: com.edde746.plezy

CLAUDE.md

@@ -643,7 +643,9 @@ reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual butto
 "outside of frame bounds" warnings stay (~2/frame) and are harmless.
 Steam library (GitHub #4/#21/#27, agent v38): shortcuts go to every Steam account (signed-in first; MostRecent isn't
 always the account on the Frame); stop_steam also waits for Steam's helpers; after the restart the agent re-reads
-shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`), else reports it. 0.6.3's Play
+shortcuts.vdf and writes once more if Steam put its old copy back (`shortcuts_lost`); lost again (agent v89): Steam
+ignores FramePort's entries on that Frame, so `add_devkit_entry` adds the devkit entry instead (`added` gets `via:
+devkit`) and only reports an error if that fails too. 0.6.3's Play
 auto-repair (`_add_then_play`) crashed (its job got a Job, not a reporter). Uploads resume on a transient OSError.
 Lepton's Android 11 has no clipboard service (134 services; checked with `podman exec … service check clipboard`):
 SDL/LÖVE apps crashed at start → `frame.sdl_clipboard` (`apk/dex.py`: in-place dex edit, nops one invoke, fixes
@@ -741,6 +743,7 @@ own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless lau
 shows what the game draws. Vader: Lucasfilm logo (an OBB mp4: video works), then its loading card (portrait + segmented
 bar) that never advances; the async loader thread sleeps and OBB reads stop (~168 MB of a 2.7 GB pak).
 **SteamVR overlay apps (agent v75, 2026-10-10):** host OpenVR overlays (VRApplication_Overlay) are composited over Lepton (Quest) games on the Frame (probe checker seen over 4XVR in the headset view, `native/vroverlay_probe`); Windows ones register through Proton's vrclient too (Temporal Reality's Windows build created its overlays; fpsVR never reaches OpenVR under Proton). Detection `analysis/vroverlay.py` (bundled `.vrmanifest` with `is_dashboard_overlay`, else OpenVR + IVROverlay + self-registration markers, engine Other; Rift fingerprint `RIFT_ANALYSIS`), patch `pcvr.vr_overlay` (param autostart), Linux entry fields `vr_overlay`/`vr_overlay_autostart` (game page switch); agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay` (IVRApplications via ctypes, live; manifest `<anchor>/frameport-overlay.vrmanifest`, the app's own key, binary = launch.sh). **SteamVR on the Frame reads only `binary_path_linux_arm`** (binary_path_linux alone is skipped). Overlay apps: no launch test, no Linux Steam-parent watchdog (`FRAMEPORT_OVERLAY`), not a "running game". A Steam overlay-app shortcut and a game shortcut run together. SteamVR's SetApplicationAutoLaunch didn't persist on the dev Frame (the watch never started by itself) → **agent v76: FramePort's own autostart**: the deployment's `overlay.autostart` is the source of truth; `ensure_host_fixes` (`ensure_overlay_service`) keeps the user service `frameport-vr-overlays.service` (`_vr_overlay_watch`, 5 s polls of the known vrserver's /proc stat) only while an overlay app has autostart on (register/unregister, uninstall, purge and the kill switch `~/.local/share/frameport/vr-overlays.disabled` / `FRAMEPORT_NO_OVERLAY_AUTOSTART` update it); a new vrserver (pid + start time, kept in `~/.cache/frameport-vr-overlays.json` across agent updates) → child `_vr_overlay_round`: wait for IVRApplications, 15 s grace, `launch_vr_overlay` for apps not running (folder process or GetApplicationProcessId); log `~/.local/share/frameport/vr-overlays.log`. Dev Frame: adopted the running vrserver, skipped the already running watch; a start after a real SteamVR start/boot is not yet seen. Details: docs/FRAME_RUNTIME.md "Overlay apps".
+**Vader's leak solved / AC Nexus flips (2026-10-14):** Vader Immortal leaves GL errors pending on its context; SteamVR's GL interop (`openxr_graphics_gl_openvr.cpp`, `xrclient_<pkg>.txt` in Steam's logs: `SXR_GL_CHECK: error:0x502 ... glGenTextures`) takes the stale error as its own failure once, and from then on `CVRCompositorSharedTextures::BeginCommandBuffer` allocates a command buffer every frame (perf page-fault stacks; ~430 renderD128 mappings + 22 MB/s). Adapter `gl_error_clear` (GLES, catalog on for Vader ep1-3) clears them before xrCreateSwapchain/xrBeginFrame/xrEndFrame: flat memory, no SXR_GL_CHECK (headless). The per-game `xrclient_<pkg>.txt` logs are worth reading for runtime errors. The Frame's runtime caps swapchains per session (XR_ERROR_LIMIT_REACHED from ~15; AC Nexus asks for more): flip emulation now turns quads upright in place (scratch VkImage, once per acquire; transfer usage added to single-layer colour swapchains) instead of a shadow swapchain per quad, which ran into the cap (#138). Headless sessions don't draw AC Nexus's panels (adapter `flip_dump` saves before/after images of flipped quads, for headset runs).
 **Lepton's logcat mirror dies (agent v67, 2026-10-09):** occasionally launch.log ends with `logcat: Unexpected EOF!` right after the game starts (about 1 launch in 50, Lepton 2.8.14 and 3.0.5): no dashboard auto-hide, no launch-test result. launch.sh's `_logcat_keeper` then reads `podman exec lepton-steamlaunch-<appid> logcat` itself into launch.log (up to 5 restarts while the game runs).
 **Double launch (agent v57, 2026-10-06):** a second Play while Lepton still boots (~10 s with nothing to see) made
 the second Lepton stop the first one's container ("Waiting for steamlaunch-<appid> (PID …) to exit", exit 137

agent/frameport_agent.py

@@ -44,7 +44,7 @@ try:
 except ImportError:  # Windows: pc_revive loads this file for its VDF code only (GitHub #131)
     fcntl = None
 
-AGENT_VERSION = 86
+AGENT_VERSION = 89
 HOME = os.path.expanduser("~")
 STEAM = os.path.join(HOME, ".local/share/Steam")
 ANCHORS = os.path.join(HOME, "Applications/quest-frame")
@@ -1256,7 +1256,7 @@ def _shortcuts_worker(payload):
         if service or args.get("restart", True):
             start_steam(service)
             lost = shortcuts_lost(users, args["packages"])
-            if lost:  # Steam wrote its old copy back over ours (it was still saving): once more, then report
+            if lost:  # Steam wrote its old copy back over ours (it was still saving): once more, then the devkit entry
                 result["retried"] = lost
                 service = stop_steam()
                 for user in users:
@@ -1264,7 +1264,7 @@ def _shortcuts_worker(payload):
                 start_steam(service)
                 for pkg in shortcuts_lost(users, lost):
                     result["added"] = [a for a in result["added"] if a["package"] != pkg]
-                    result["errors"].append(f"{pkg}: Steam removed the new library entry again after restarting")
+                    add_devkit_entry(pkg, result)
     except Exception as exc:  # noqa: BLE001
         result["state"] = "failed"
         result["errors"].append(str(exc))
@@ -1274,6 +1274,19 @@ def _shortcuts_worker(payload):
         json.dump(result, f)
 
 
+def add_devkit_entry(pkg, result):
+    """Steam dropped the game's shortcuts.vdf entry twice: this Frame's Steam ignores FramePort's entries (GitHub #41),
+    so add it the way Valve's devkit tool does (Steam is running again). That entry is the one Steam keeps."""
+    try:
+        appid = devkit_register(pkg)
+    except Exception as exc:  # noqa: BLE001
+        result["errors"].append(f"{pkg}: Steam removed the new library entry again after restarting, and the devkit "
+                                f"entry failed too: {exc}")
+        return
+    result["added"].append({"package": pkg, "appid": appid, "expected": (deployment(pkg) or {}).get("appid"),
+                            "via": "devkit"})
+
+
 def remove_from_library(user, remove, result):
     """Remove uninstalled games' shortcuts + grid art from one Steam account (Steam is closed)."""
     vdf = os.path.join(STEAM, "userdata", user, "config/shortcuts.vdf")
@@ -1526,10 +1539,17 @@ def is_overlay(dep):
     return bool(isinstance(dep, dict) and dep.get("overlay"))
 
 
+def deployment_summary(dep):
+    """Keep routine connection/monitor samples small; detailed data manifests are fetched only for an update."""
+    return {key: value for key, value in dep.items()
+            if key not in ("data_manifest", "configuration", "managed_config_files")}
+
+
 def cmd_list_installed(args):
     games = []
     table = mounts()
-    for dep_path in sorted(glob.glob(os.path.join(ANCHORS, "*/deployment.json"))):
+    selected = check_pkg(args["package"]) if args.get("package") else "*"
+    for dep_path in sorted(glob.glob(os.path.join(ANCHORS, selected, "deployment.json"))):
         try:
             dep = json.load(open(dep_path))
         except (OSError, ValueError):
@@ -1566,7 +1586,7 @@ def cmd_list_installed(args):
             dep["apk_present"] = os.path.exists(apk)
             dep["apk_size"] = os.path.getsize(apk) if dep["apk_present"] else 0
         dep["last_play"] = last_play(dep["anchor"])  # agent v70: the PC triages a finished play session's log
-        games.append(dep)
+        games.append(dep if args.get("details") else deployment_summary(dep))
     return {"games": games}
 
 
@@ -3828,7 +3848,7 @@ def cmd_finalize(args):
     pkg = check_pkg(args["package"])
     title = args["title"]
     prep = cmd_prepare({"package": pkg, "title": title, "dest": args.get("dest")})
-    base, anchor, appid, incoming = prep["base"], prep["anchor"], prep["appid"], prep["incoming"]
+    base, anchor, incoming = prep["base"], prep["anchor"], prep["incoming"]
     lepton = prep["lepton"]
     if not lepton:
         raise AgentError("Lepton is not installed (Developer Mode → install/launch 'Lepton Development' once)")
@@ -3849,6 +3869,10 @@ def cmd_finalize(args):
         bad = [k for k, v in expected.items() if have.get(k) != v]
         if bad:
             raise AgentError(f"{len(bad)} data file(s) missing or incomplete, e.g. {bad[0]}")
+    if args.get("existing_only") and os.path.exists(new_apk):
+        raise AgentError("an interrupted APK upload is pending; finish that install before updating data")
+    if args.get("existing_only"):
+        verify_installed_apk(deployment(pkg), args.get("apk_sha256"))
     if os.path.exists(new_apk):
         if args.get("apk_sha256") and sha256_file(new_apk) != args["apk_sha256"]:
             raise AgentError("uploaded APK checksum mismatch (transfer corrupted?)")
@@ -3859,16 +3883,67 @@ def cmd_finalize(args):
     elif not os.path.exists(os.path.join(app, "game.apk")):
         raise AgentError("no APK uploaded and none installed")
     moved = 0
-    for root, _, files in os.walk(inc_obb):
-        for name in files:
-            if name.endswith(".part"):
-                continue
-            src = os.path.join(root, name)
-            dst = os.path.join(app, "obb", os.path.relpath(src, inc_obb))
-            os.makedirs(os.path.dirname(dst), exist_ok=True)
-            os.replace(src, dst)
-            moved += 1
-    shutil.rmtree(incoming, ignore_errors=True)
+    if not args.get("preserve_data"):
+        for root, _, files in os.walk(inc_obb):
+            for name in files:
+                if name.endswith(".part"):
+                    continue
+                src = os.path.join(root, name)
+                rel = os.path.relpath(src, inc_obb)
+                if expected is not None and rel not in expected:
+                    continue  # an older interrupted upload is not part of this install
+                dst = os.path.join(app, "obb", rel)
+                os.makedirs(os.path.dirname(dst), exist_ok=True)
+                os.replace(src, dst)
+                moved += 1
+        shutil.rmtree(incoming, ignore_errors=True)
+    return configure_install({**args, "consume_artwork": args.get("consume_artwork", True)}, prep, moved)
+
+
+def verify_installed_apk(dep, expected):
+    apk = os.path.join(dep["base"], "lepton-app", "game.apk")
+    if not expected or dep.get("sha256") != expected or not os.path.isfile(apk):
+        raise AgentError("installed APK is missing or changed; refresh and reinstall it")
+    st = os.stat(apk)
+    identity = {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
+    if identity != dep.get("apk_stat") and sha256_file(apk) != expected:
+        raise AgentError("installed APK content changed; reinstall it")
+
+
+def cmd_configure(args):
+    """Apply runtime configuration to an existing, matching APK without staging/replacing game files."""
+    pkg = check_pkg(args["package"])
+    dep = deployment(pkg)
+    if not dep or dep.get("kind", "quest") != "quest":
+        raise AgentError(f"{pkg} is not an installed Quest/Android app")
+    base, _ = new_base(args, pkg, dep)  # validates a removable drive; never silently falls back
+    verify_installed_apk(dep, args.get("apk_sha256"))
+    if container_running(dep["appid"]):
+        raise AgentError("Close the game before updating its configuration")
+    lepton, _ = lepton_path()
+    if not lepton:
+        raise AgentError("Lepton is not installed")
+    return configure_install({**args, "title": dep["title"]},
+                             {"base": base, "anchor": os.path.join(ANCHORS, pkg),
+                              "appid": dep["appid"], "lepton": lepton}, 0)
+
+
+def configure_install(args, prep, moved):
+    pkg, title = check_pkg(args["package"]), args["title"]
+    base, anchor, appid, lepton = prep["base"], prep["anchor"], prep["appid"], prep["lepton"]
+    app = os.path.join(base, "lepton-app")
+    previous = deployment(pkg) or {}
+    files_dir = data_files_dir(base, pkg)
+    for rel in set(args.get("files") or {}) | set(previous.get("managed_config_files") or {}):
+        target = os.path.realpath(os.path.join(files_dir, rel))
+        if not _inside(target, os.path.realpath(files_dir)) or target == os.path.realpath(files_dir):
+            raise AgentError(f"refusing to write outside the game's files dir: {rel}")
+        backup = os.path.join(files_dir, rel) + ".frameport-config-backup"
+        if os.path.islink(backup):
+            raise AgentError(f"refusing a linked configuration backup: {rel}")
+    for key, value in (args.get("settings") or {}).items():
+        if not re.fullmatch(r"[a-z_]+", key) or any(c in str(value) for c in "\r\n\x00"):
+            raise AgentError(f"bad setting {key}")
     if "flatscreen" in args:  # older clients don't send it: leave the marker as it is
         set_flatscreen(app, args["flatscreen"])
     # settings: settings.conf (read by the adapter via LEPTON_ENV_FRAMEBRIDGE_CONFIG) + framebridge.conf copy
@@ -3885,13 +3960,37 @@ def cmd_finalize(args):
             f.write(text)
         with open(os.path.join(files_dir, "framebridge.conf"), "w") as f:
             f.write(text)
+    managed = previous.get("managed_config_files") or {}
+    wanted = args.get("files") or {}
+    for rel, record in managed.items():
+        if rel in wanted:
+            continue
+        target = os.path.realpath(os.path.join(files_dir, rel))
+        if not _inside(target, os.path.realpath(files_dir)):
+            raise AgentError(f"invalid previously managed path: {rel}")
+        if os.path.isfile(target) and sha256_file(target) == record["sha256"]:
+            backup = target + ".frameport-config-backup"
+            if record.get("backup") and os.path.isfile(backup):
+                os.replace(backup, target)
+            else:
+                os.unlink(target)
+    new_managed = {}
     for rel, content in (args.get("files") or {}).items():
         target = os.path.normpath(os.path.join(files_dir, rel))
         if not target.startswith(files_dir + os.sep):
             raise AgentError(f"refusing to write outside the game's files dir: {rel}")
         os.makedirs(os.path.dirname(target), exist_ok=True)
+        record = managed.get(rel)
+        backup = target + ".frameport-config-backup"
+        # no record: an existing file is the user's, unless it already has exactly this content (written by
+        # FramePort before agent v86 kept records; backing it up would bring it back when the recipe drops it)
+        had_original = bool(record.get("backup")) if record else os.path.isfile(target) and \
+            open(target, "rb").read() != content.encode()
+        if not record and had_original:
+            shutil.copy2(target, backup)
         with open(target, "w") as f:
             f.write(content)
+        new_managed[rel] = {"sha256": sha256_file(target), "backup": had_original}
     models = install_controller_models(files_dir, str(settings.get("controller_models", 0)) not in ("0", "0.0"))
     recipe = args.get("recipe") if isinstance(args.get("recipe"), dict) else {}
     hw_video = HW_VIDEO_PATCH in (recipe.get("patches") or [])  # the shared codec (install_video_codec)
@@ -3901,22 +4000,40 @@ def cmd_finalize(args):
     config_sync = args.get("config_sync") if isinstance(args.get("config_sync"), dict) else {}
     write_launcher(anchor, base, pkg, title, appid, lepton, args.get("env"), hw_video, gamepad, bool(config_sync))
     art_in = os.path.join(base, "incoming-artwork")
-    if os.path.isdir(art_in):
+    art_moved = False
+    if args.get("consume_artwork") and os.path.isdir(art_in):
         shutil.rmtree(os.path.join(anchor, "artwork"), ignore_errors=True)
         shutil.move(art_in, os.path.join(anchor, "artwork"))
-    previous = deployment(pkg) or {}
-    dep = {"package": pkg, "appid": int(appid), "base": base, "title": title, "tags": args.get("tags") or [],
-           "apk": args.get("apk_name", "game.apk"),
-           "sha256": args.get("apk_sha256"), "recipe": args.get("recipe"), "installed_by": "frameport",
+        art_moved = True
+    dep = {**previous, "package": pkg, "appid": int(appid), "base": base, "title": title,
+           "tags": args.get("tags", previous.get("tags")) or [],
+           "apk": args.get("apk_name", previous.get("apk", "game.apk")),
+           "sha256": args.get("apk_sha256") or previous.get("sha256"),
+           "recipe": args.get("recipe"), "installed_by": "frameport",
            "hw_video_decode": hw_video, "steam_gamepad": gamepad, "config_sync": config_sync,
            "agent_version": AGENT_VERSION, "time": time.time()}
     if previous.get("eye_base"):  # the runtime's eye size learned from an earlier start (device.config_sync)
         dep["eye_base"] = previous["eye_base"]
-    with open(os.path.join(anchor, "deployment.json"), "w") as f:
-        json.dump(dep, f, indent=2)
+    dep["managed_config_files"] = new_managed
+    # An app before agent v86 records none of these: what it installed is unknown, so a newer PC mustn't skip work
+    # on the strength of an older record. Art the agent didn't replace keeps its record.
+    art_replaced = bool(args.get("consume_artwork")) and art_moved
+    for key in ("configuration", "configuration_fp", "apk_recipe_fp", "source_version", "artwork_manifest"):
+        if key in args:
+            dep[key] = args[key]
+        elif key != "artwork_manifest" or art_replaced:
+            dep.pop(key, None)
+    if args.get("obb_manifest") is not None:
+        dep["data_manifest"] = args["obb_manifest"]
+    if "data_manifest" in dep:
+        dep["data_fp"] = hashlib.sha256(json.dumps(dep["data_manifest"], sort_keys=True).encode()).hexdigest()[:32]
+    st = os.stat(os.path.join(app, "game.apk"))
+    dep["apk_size"] = st.st_size
+    dep["apk_stat"] = {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
     synced = sync_game_config(pkg, dep)
+    write_deployment(pkg, dep)
     return {"ok": True, "base": base, "appid": appid, "moved_data_files": moved, "controller_models": models,
-            "config_sync": synced}
+            "config_sync": synced, "deployment": deployment_summary(dep)}
 
 
 # --------------------------------------------------------------- Steam Frame controller models (XR_FB_render_model)
@@ -5175,8 +5292,8 @@ def cmd_set_settings(args):
             if k:
                 current[k] = v
     for k, v in (args.get("settings") or {}).items():
-        if not re.fullmatch(r"[a-z_]+", k) or not re.fullmatch(r"-?[0-9.]+", str(v)):
-            raise AgentError(f"bad setting {k}={v}")
+        if not re.fullmatch(r"[a-z_]+", k) or not re.fullmatch(r"-?(?:[0-9]+\.?[0-9]*|\.[0-9]+)", str(v)):
+            raise AgentError(f"bad setting {k}={v}")  # checked before anything is written
         current[k] = str(v)
     text = "".join(f"{k}={v}\n" for k, v in current.items())
     with open(conf, "w") as f:
@@ -5186,7 +5303,19 @@ def cmd_set_settings(args):
     with open(os.path.join(files_dir, "framebridge.conf"), "w") as f:
         f.write(text)
     models = install_controller_models(files_dir, current.get("controller_models", "0") not in ("0", "0.0"))
-    return {"settings": current, "controller_models": models, "config_sync": sync_game_config(pkg, dep)}
+    synced = sync_game_config(pkg, dep)
+    if isinstance(dep.get("configuration"), dict):
+        applied = dep["configuration"]
+        settings = applied.get("settings") or {}
+        for key, value in (args.get("settings") or {}).items():
+            if key in settings:
+                number = float(value)
+                # keep the recorded type (the PC's fingerprint uses it); an int setting given 1.5 stays 1.5
+                settings[key] = number if isinstance(settings[key], float) or not number.is_integer() \
+                    else int(number)
+        dep["configuration_fp"] = hashlib.sha256(json.dumps(applied, sort_keys=True).encode()).hexdigest()[:32]
+        write_deployment(pkg, dep)
+    return {"settings": current, "controller_models": models, "config_sync": synced}
 
 
 TITLE_MAX = 128
@@ -5200,6 +5329,26 @@ def clean_title(title):
     return text[:TITLE_MAX]
 
 
+def cmd_record_artwork(args):
+    """Record artwork only after verifying the files actually uploaded to the game's anchor."""
+    pkg = check_pkg(args["package"])
+    dep = deployment(pkg)
+    if not dep:
+        raise AgentError(f"{pkg} is not installed")
+    manifest = args.get("manifest") or {}
+    root = os.path.join(ANCHORS, pkg, "artwork")
+    for name, digest in manifest.items():
+        if (not re.fullmatch(r"(?:portrait|landscape|hero|logo|icon)\.[a-zA-Z0-9]+|\.icon-source", name)
+                or not re.fullmatch(r"[a-f0-9]{64}", str(digest))):
+            raise AgentError("invalid artwork manifest")
+        path = os.path.join(root, name)
+        if not os.path.isfile(path) or sha256_file(path) != digest:
+            raise AgentError(f"artwork missing or checksum mismatch: {name}")
+    dep["artwork_manifest"] = manifest
+    write_deployment(pkg, dep)
+    return {"verified": True}
+
+
 def cmd_rename(args):
     """Rename an installed game (agent v77): deployment.json's title is what its Steam shortcut shows. The shortcut
     keeps its appid (upsert_shortcut matches by Exe, deployment.json keeps the appid), so Play, its grid art, launch

artifacts/SHA256SUMS

@@ -1,6 +1,6 @@
 1a4dce5c4a6d0dfc5f20e55ac29e70c73cc2cc124c21ca6a7e1b316e6afb1c79  ./arm64-v8a/libVkLayer_fdm_darken.so
 5becb96ee86fbda0ce98c0e0fd064f8ba092314aceaa400e3dcc785705dc3c23  ./arm64-v8a/libVkLayer_fp_shaderfix.so
-e7554c6343ee2989b0a273ee6230e65c25bfe6499eefd00de19f5f0fee58754f  ./arm64-v8a/libfp_langpack.so
+d6337034fb0bdcca7ef9b7063d85b7586b8508b63b435959e8fffaba0691091c  ./arm64-v8a/libfp_langpack.so
 69102b128e00fa1809489a7308e09c1505f563bf7091bbdd3fe5a58e4cc96c2c  ./arm64-v8a/libfp_luajit.so
 321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
@@ -10,11 +10,11 @@ e8c0965c188665a4e565e4a3af983ef1866d1cf9225665cc90d8df286bc96ef3  ./arm64-v8a/li
 5432674a59d02f411cd853a5dc57e3fa547d1ac518f25bf433fc54c43677177a  ./arm64-v8a/libfpglmv.so
 8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-e44ded778758de33ad87bb31398281d7ec94c1ecd43dcf55b1dc99311f011859  ./arm64-v8a/libopenxr_loader_generic.so
+51f5e0c5b3d3556baab27ece2936257782d6b590183ae59601cc6d8158c96ee2  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 7f30861c770361a4e311e3f486dcd2e48cd99a7f907961829ce68e24af17d775  ./arm64-v8a/libvrapi.so
 7f30861c770361a4e311e3f486dcd2e48cd99a7f907961829ce68e24af17d775  ./arm64-v8a/libvrapi_foveation.so
-d2361ee8b6ff62d2ff6b3f59f7b15730b95bdbe0e9dcee469ffa1117411e7288  ./armeabi-v7a/libopenxr_loader_generic.so
+6927f100536283a8c26b784af73ee400140dd910e9294e4a9d55f855547ffaf2  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so

catalog/games/com.ILMxLAB.VaderImmortal.ep1.yaml

@@ -13,8 +13,9 @@ details: Unreal Engine 4 (GLES). Found and verified in gameplay on a Frame by Kl
   the captured modules are from Lepton 2.8.14 and stop matching if a Frame update changes the driver's output -
   the layer logs that). OVRPlugin asks for poses at its own clock (pose_time_fix). Unreal's Oculus input animates the
   thumbs from near-touch, which the Frame never reports (frame.unreal_thumb_touch reads the touches instead; binding
-  the proximity to the touch inputs in FrameBridge didn't reach the game). The Frame's SteamVR runtime
-  leaks about 20 MB a second while the game runs (reported to Valve).
+  the proximity to the touch inputs in FrameBridge didn't reach the game). The game leaves GL errors
+  pending; the runtime's GL check took one as its own failure and then allocated a command buffer every frame
+  (~20 MB a second until the frame rate collapsed). gl_error_clear clears them first (GitHub #285).
 tested_version: 1.1.1+667256.cl.387770
 engine: Unreal
 xr: VrApi
@@ -27,10 +28,11 @@ frame:
 - frame.zink_shader_fix
 adapter:
   pose_time_fix: 1
+  gl_error_clear: 1
   zink_shader_fix: 12016:b2919629761ad268e0b21c72ac8520f81b76e72c3adc26897f97eae9a3e70a66:3092:0x0003003e,166,82,0x0003003e,177,82,0x0003003e,183,82,0x0003003e,189,82,0x0003003e,256,82,0x0003003e,266,82,0x0003003e,272,82,0x0003003e,278,82,0x0003003e,318,82,0x0003003e,328,82,0x0003003e,334,82,0x0003003e,340,82;11436:6f18be49f2aaa2452f962eb16f7af744c5c22a7b25f37ce681e0d6399e35a869:2932:0x0003003e,164,80,0x0003003e,175,80,0x0003003e,181,80,0x0003003e,187,80,0x0003003e,254,80,0x0003003e,264,80,0x0003003e,270,80,0x0003003e,276,80,0x0003003e,316,80,0x0003003e,326,80,0x0003003e,332,80,0x0003003e,338,80
 verified:
   date: '2026-10-09'
   issue: 49
-updated: '2026-10-09'
+updated: '2026-10-14'
 min_app: 0.12.1
 source_hint: Vader Immortal- Episode I

catalog/games/com.ILMxLAB.VaderImmortal.ep2.yaml

@@ -18,7 +18,9 @@ frame:
 - frame.unreal_thumb_touch
 adapter:
   pose_time_fix: 1
+  gl_error_clear: 1
 verified:
   date: '2026-10-09'
+updated: '2026-10-14'
 min_app: 0.12.1
 source_hint: Vader Immortal- Episode II

catalog/games/com.ILMxLAB.VaderImmortal.ep3.yaml

@@ -18,7 +18,9 @@ frame:
 - frame.unreal_thumb_touch
 adapter:
   pose_time_fix: 1
+  gl_error_clear: 1
 verified:
   date: '2026-10-09'
+updated: '2026-10-14'
 min_app: 0.12.1
 source_hint: Vader Immortal- Episode III

catalog/games/com.Ubisoft.ACNexusVR.yaml

@@ -4,9 +4,9 @@ tested_version: MAIN.450412.207706.final
 source_hint: Assassins Creed Nexus VR
 engine: Unity
 xr: OpenXR
-status: issues
-notes: Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. Ubisoft login
-  may not work.
+status: works
+notes: FrameBridge turns its upside-down UI panels upright (flip emulation, in place since FramePort 1.1.2). Ubisoft
+  login may not work.
 details: Ubisoft online login may not work. Data folder holds raw assets (start0..2, .climb, bundles), not .obb
   files; install to obb as-is.
 overport_extra:
@@ -17,3 +17,6 @@ verified:
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 89644a12bf8df956fa3d3a9a40540ba9e1fb62f63494714a05c9f05984383ac8
   no_appsw_90: '2026-10-02, OVRPort 1.2.5 (owner: 90 Hz felt better than 72 Hz; same known issues)'
+  flip_in_place: '2026-10-14, owner in the headset: launch warnings and tutorial pop-ups upright (GitHub #138)'
+updated: '2026-10-14'
+min_app: 1.1.2

catalog/games/com.edde746.plezy.yaml

@@ -0,0 +1,20 @@
+package: com.edde746.plezy
+title: Plezy
+status: issues
+notes: Some videos play with strong artifacts and wrong colours; the cause is unknown, possibly hardware video decoding.
+    Otherwise works.
+tested_version: 2.22.0
+engine: Other
+xr: '?'
+frame:
+- frame.hw_video_decode
+as_is: true
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 893ae7c01d3d7688b27cbf4e7fc1260fb617614baeaf378fe5ca0af41febc92f
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 270
+source_hint: plezy

catalog/games/com.fulldivegames.majorasmaskvr.yaml

@@ -0,0 +1,20 @@
+package: com.fulldivegames.majorasmaskvr
+title: Majora's Mask VR
+status: issues
+notes: Audio on the file select screen sounds crunchy. Controls may need rebinding in the game. Quest build from https://github.com/fulldivegames/Majoras-Mask-VR.
+tested_version: '0.36'
+engine: Other
+xr: OpenXR
+frame:
+- frame.sdl_clipboard
+adapter:
+  refresh_rate: 144.0
+verified:
+  date: '2026-10-13'
+  known_good_sha256: 220096c70fb515ec7b8db1cc7a9075836b4d09f7df63026908af3c30e9fdb7e5
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 268
+source_hint: MMVR-Quest-0.36

catalog/games/com.nDreams.Ghostbusters.yaml

@@ -0,0 +1,26 @@
+package: com.nDreams.Ghostbusters
+title: 'Ghostbusters: Rise of the Ghost Lord'
+status: works
+notes: 'Needs the game''s offline mode: it is built for online play, and without a profile the player name is a random
+    number. The flat loading screen floats in front of you instead of following your head, so assets can be seen loading
+    in behind it.'
+tested_version: 1.325635.prod.shipping
+engine: Unreal
+xr: OpenXR
+alt_overport:
+- patch_remove_unreal_force_quit
+frame:
+- frame.unreal_ovrp_entrypoints
+- frame.hw_video_decode
+adapter:
+  haptic_fix: 1
+  scene_emul: 1
+verified:
+  date: '2026-10-14'
+  known_good_sha256: 7556a78c8772aed70c38fc4781677c0900e9dfd4be085a79c421a31323af7888
+  app: 1.1.0
+  overport_cli: 1.2.5
+  frame_build: '20261007.6125817'
+  agent: 85
+  issue: 279
+source_hint: GBRotgl

catalog/triage.yaml

@@ -6,6 +6,11 @@
 # with diagnostics. Launch tests and real play sessions (agent session_log, `frameport session`) are both matched.
 # Sources: every failure we hit porting 34 games to the Steam Frame (see docs/PLAYBOOK.md).
 signatures:
+  - id: meta-asset-status-error
+    pattern: 'Asset status error\s+\(code 100\)'
+    severity: error
+    diagnosis: A DLC manager reports a Meta asset-file status error after VR starts (e.g. PixelRipped 1995). The asset-file check failed; the log does not identify the native call or asset ID. Try the experimental asset-file bypass (empty list, installed status with no file path); this does not supply DLC and has not been verified in the game.
+    suggest: [frame.asset_files_stub]
   - id: lua-lightuserdata-pointer
     pattern: 'bad light userdata pointer'
     severity: fatal
@@ -375,10 +380,13 @@ signatures:
       The game stays on Unreal's OBB check screen (DownloaderActivity), which the Frame doesn't show, and never
       starts VR (for example Contractors, GitHub #159). Unreal checks that the data file (.obb) has the name and size
       this APK expects, and with bVerifyOBBOnStartUp it also reads the whole file to check it; a failed check waits
-      on an error screen. "Unreal - start without the OBB check" skips the content check. If the game still stops
-      here, the OBB doesn't match this APK version - copy the APK and the OBB from the same install, add the game
-      again and reinstall.
-    suggest: [frame.unreal_skip_obb_check]
+      on an error screen. "Unreal - start without the OBB check" skips the content check. Copy the APK and OBB
+      from the same install, add the game again and reinstall.
+      If the downloader still appears with bVerifyOBBOnStartUp=false (the skip patch already applied), try
+      "Unreal: skip the OBB delivery check", an experimental bypass of the separate Java name and size gate
+      (e.g. Into The Radius, GitHub #283). An external-storage path or visibility failure can reject an uploaded
+      OBB; the native engine still needs complete, matching, readable data.
+    suggest: [frame.unreal_skip_obb_check, frame.unreal_skip_obb_delivery]
   - id: tbxr-fdm-shutdown-crash
     pattern: '(?s)\A(?=.*Fatal signal 11)(?=.*fdm_injection_xrDestroySwapchain)(?=.*TBXR_LeaveVR)'
     severity: error

docs/GAMES.md

@@ -10,7 +10,9 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Accounting+ | Quest | ✅ Works |  |
 | AgeOfJoy | Quest | ✅ Works |  |
 | AllInOneSports | Quest | ✅ Works |  |
+| Arkio | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
+| Assassin's Creed Nexus | Quest | ✅ Works |  |
 | Audica | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
 | BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
@@ -28,6 +30,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Caves | Quest | ✅ Works |  |
 | Clockwork | Quest | ✅ Works |  |
+| COMPOUND | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Cosmodread | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
@@ -40,12 +43,14 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Down the Rabbit Hole | Quest | ✅ Works |  |
 | Drunkn Bar Fight | Quest | ✅ Works |  |
 | Drunkn Bar Fight 2 - Early Access | Quest | ✅ Works |  |
+| Eleven Table Tennis | Quest | ✅ Works |  |
 | Eleven: Table Tennis VR | PC VR | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
 | FrenzyVR | Quest | ✅ Works |  |
 | Fruit Ninja | Quest | ✅ Works |  |
 | Fruit Salon | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
+| Ghostbusters: Rise of the Ghost Lord | Quest | ✅ Works |  |
 | GORN2 | Quest | ✅ Works |  |
 | Gravity Lab | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
@@ -68,6 +73,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Medieval Dynasty New Settlement | Quest | ✅ Works |  |
 | Metro Awakening | Quest | ✅ Works |  |
 | Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
+| Moss: Book II | Quest | ✅ Works |  |
 | Munkr Funkr (The Legacy Days) | Quest | ✅ Works |  |
 | Nano | Quest | ✅ Works |  |
 | NEX Player | Quest | ✅ Works |  |
@@ -81,6 +87,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | PowerWash Simulator VR | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
 | Racket: Nx | Quest | ✅ Works |  |
+| RacketPinball | Quest | ✅ Works |  |
 | RC Pilot Trainer | Quest | ✅ Works |  |
 | Retronika | Quest | ✅ Works |  |
 | Retropolis | Quest | ✅ Works |  |
@@ -89,6 +96,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
 | RUINSMAGUS | Quest | ✅ Works |  |
+| Shoot The Zombirds VR | Quest | ✅ Works |  |
 | Shores of Loci | Quest | ✅ Works |  |
 | SilentSlayer | Quest | ✅ Works |  |
 | Sniper Elite VR | Quest | ✅ Works |  |
@@ -127,7 +135,6 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | ZombielandVR | Quest | ✅ Works |  |
 | Ancient_Dungeon | Quest | ⚠️ Works with issues | Multiplayer isn't available (offline). |
 | Arcsmith | Quest | ⚠️ Works with issues | Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out). |
-| Assassin's Creed Nexus | Quest | ⚠️ Works with issues | Some launch warning text is still upside down; the rest of the UI is fixed by flip emulation. |
 | Does it Stack? | Quest | ⚠️ Works with issues | Mixed reality mode does not work (works on Demeo), everything else seems to be OK |
 | Dungeons of Eternity | Quest | ⚠️ Works with issues | It can not connect to servers |
 | End Space | Quest | ⚠️ Works with issues | Controls stop responding after the first mission loads. |
@@ -135,9 +142,11 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Fisherman | Quest | ⚠️ Works with issues | Loading screens have corruption, but everything works otherwise. |
 | Freedom | Quest | ⚠️ Works with issues | Volume can't be changed in the game. |
 | MacacoVR | Quest | ⚠️ Works with issues | 2d loading screens are glitchy, otherwise main gameplay is fine |
+| Majora's Mask VR | Quest | ⚠️ Works with issues | Audio on the file select screen sounds crunchy. |
 | Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
 | Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
 | Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |
+| Plezy | Quest | ⚠️ Works with issues | Some videos play with strong artifacts and wrong colours; the cause is unknown, possibly hardware video decoding. |
 | Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
 | Swarm 2 | Quest | ⚠️ Works with issues | MSAA creates visible seams around edge geometry and also the skybox edge |
 | The Light Brigade | Quest | ⚠️ Works with issues | Judder in weapons |
@@ -145,7 +154,6 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
 | Vermillion | Quest | ⚠️ Works with issues | Runs. |
 | WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
-| Eleven Table Tennis | Quest | ❌ Doesn't run | Stops at the splash screen. |
 | Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
 | GOLF+ | Quest | ❌ Doesn't run | Black screen. |
 | HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |

docs/PATCHES.md

@@ -2,7 +2,7 @@
 
 # Patches
 
-Every patch and game setting FramePort knows: 164 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.
+Every patch and game setting FramePort knows: 168 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.
 
 Each entry says what the patch does, whether it changes the APK or only the install, when FramePort suggests it, its options, the catalog games whose recipe names it and the launch-test signatures that suggest it. Patches that are on by default are on for every game, so the catalog rarely names them.
 
@@ -11,8 +11,8 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 ## Groups
 
 - [Patches from OVRPort](#group-overport) (25)
-- [Steam Frame patches](#group-frame) (52)
-- [Game settings](#group-adapter) (66)
+- [Steam Frame patches](#group-frame) (54)
+- [Game settings](#group-adapter) (68)
 - [Files and settings on the Frame](#group-device) (8)
 - [PC VR (Proton and Revive)](#group-pcvr) (13)
 
@@ -39,7 +39,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Patch Oculus detection for Unity](#patch_oculus_unity) | `patch_oculus_unity` | Patches from OVRPort | default |
 | [Patch Oculus detection for Unreal](#patch_oculus_unreal) | `patch_oculus_unreal` | Patches from OVRPort | default |
 | [Remove localized app names](#patch_remove_localized_names) | `patch_remove_localized_names` | Patches from OVRPort | default |
-| [Remove Unreal's ForceQuit](#patch_remove_unreal_force_quit) | `patch_remove_unreal_force_quit` | Patches from OVRPort | 35 |
+| [Remove Unreal's ForceQuit](#patch_remove_unreal_force_quit) | `patch_remove_unreal_force_quit` | Patches from OVRPort | 36 |
 | [Remove uses-library](#patch_remove_uses_library) | `patch_remove_uses_library` | Patches from OVRPort | default |
 | [Remove VrApi library](#patch_remove_vrapi) | `patch_remove_vrapi` | Patches from OVRPort |  |
 | [Replace application label and icon](#patch_replace_icon_label) | `patch_replace_icon_label` | Patches from OVRPort | default |
@@ -47,6 +47,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [VrApi → OpenXR adapter (OVRPort)](#patch_vrapi_openxr) | `patch_vrapi_openxr` | Patches from OVRPort |  |
 | [FrameBridge OpenXR adapter](#frame-adapter) | `frame.adapter` | Steam Frame patches | default |
 | [Content files from the game's data](#frame-asset_files) | `frame.asset_files` | Steam Frame patches | 1 |
+| [Asset-file service bypass](#frame-asset_files_stub) | `frame.asset_files_stub` | Steam Frame patches |  |
 | [Skip Meta avatars](#frame-avatar_stub) | `frame.avatar_stub` | Steam Frame patches | 1 |
 | [bHaptics: skip the Bluetooth permission request](#frame-bhaptics_permission) | `frame.bhaptics_permission` | Steam Frame patches |  |
 | [BlazeRush: controllers without Meta avatars, own shader cache](#frame-blazerush) | `frame.blazerush` | Steam Frame patches | 1 |
@@ -54,7 +55,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [OpenGL ES: multiview shaders on flat panels (HUD, menus)](#frame-gl_multiview_fbo) | `frame.gl_multiview_fbo` | Steam Frame patches | 1 |
 | [GL shim (Mesa GLSL compatibility)](#frame-gl_shim) | `frame.gl_shim` | Steam Frame patches | 2 |
 | [Godot apps: start without a clipboard service](#frame-godot_clipboard) | `frame.godot_clipboard` | Steam Frame patches |  |
-| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 7 |
+| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 9 |
 | [Language packs from the game's files](#frame-langpacks) | `frame.langpacks` | Steam Frame patches |  |
 | [Launcher category (INFO → LAUNCHER)](#frame-launcher) | `frame.launcher` | Steam Frame patches | default |
 | [GL wrapper: OpenGL ES depth formats (Minecraft)](#frame-ltw_depth) | `frame.ltw_depth` | Steam Frame patches | default |
@@ -69,7 +70,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Platform compat (ovrMessageType_ToString)](#frame-ovrplatformcompat) | `frame.ovrplatformcompat` | Steam Frame patches | default |
 | [Stub missing Meta platform functions](#frame-ovrstubs) | `frame.ovrstubs` | Steam Frame patches | default |
 | [Unpaired pointer-authentication checks](#frame-pac_hints) | `frame.pac_hints` | Steam Frame patches | 1 |
-| [SDL apps: start without a clipboard service](#frame-sdl_clipboard) | `frame.sdl_clipboard` | Steam Frame patches | 3 |
+| [SDL apps: start without a clipboard service](#frame-sdl_clipboard) | `frame.sdl_clipboard` | Steam Frame patches | 4 |
 | [Stress Level Zero: let Unity start Vulkan itself](#frame-slz_vulkan_hooks) | `frame.slz_vulkan_hooks` | Steam Frame patches | 1 |
 | [Start straight in VR (skip the 2D launcher)](#frame-start_activity) | `frame.start_activity` | Steam Frame patches |  |
 | [Allow swapchains larger than 4096 px](#frame-swapchain_limit) | `frame.swapchain_limit` | Steam Frame patches | default |
@@ -85,10 +86,11 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Unity: headset always counts as worn](#frame-unity_user_presence) | `frame.unity_user_presence` | Steam Frame patches | 1 |
 | [GL shim for Unreal (no multisampled render-to-texture)](#frame-unreal_gl_shim) | `frame.unreal_gl_shim` | Steam Frame patches | 1 |
 | [Unreal: match multiview depth to the eye size](#frame-unreal_multiview_depth) | `frame.unreal_multiview_depth` | Steam Frame patches | 1 |
-| [Unreal: stand-ins for OVRPlugin functions OVRPort lacks](#frame-unreal_ovrp_entrypoints) | `frame.unreal_ovrp_entrypoints` | Steam Frame patches | 1 |
+| [Unreal: stand-ins for OVRPlugin functions OVRPort lacks](#frame-unreal_ovrp_entrypoints) | `frame.unreal_ovrp_entrypoints` | Steam Frame patches | 2 |
 | [Unreal: Quest controller bindings (RPOC key map)](#frame-unreal_quest_keymap) | `frame.unreal_quest_keymap` | Steam Frame patches | 3 |
 | [Unreal: don't wait for the Quest shader precompile](#frame-unreal_quest_precompile) | `frame.unreal_quest_precompile` | Steam Frame patches | 3 |
 | [Unreal: start without the OBB check](#frame-unreal_skip_obb_check) | `frame.unreal_skip_obb_check` | Steam Frame patches | 3 |
+| [Unreal: skip the OBB delivery check](#frame-unreal_skip_obb_delivery) | `frame.unreal_skip_obb_delivery` | Steam Frame patches |  |
 | [Unreal: bypass the stalled loading splash](#frame-unreal_splash_bypass) | `frame.unreal_splash_bypass` | Steam Frame patches | 1 |
 | [Unreal: thumb follows the capacitive touches](#frame-unreal_thumb_touch) | `frame.unreal_thumb_touch` | Steam Frame patches | 7 |
 | [Vermillion: paint canvases in the scene](#frame-vermillion_scene_canvas) | `frame.vermillion_scene_canvas` | Steam Frame patches | 1 |
@@ -112,17 +114,19 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [360° 3D](#adapter-equirect_stereo) | `adapter.equirect_stereo` | Game settings |  |
 | [Per-eye diagnostics (log)](#adapter-eye_debug) | `adapter.eye_debug` | Game settings |  |
 | [Draw fades over the picture](#adapter-fade_quad) | `adapter.fade_quad` | Game settings | 2 |
+| [Upside-down panel images (diagnostics)](#adapter-flip_dump) | `adapter.flip_dump` | Game settings |  |
 | [Fix upside-down menus](#adapter-flip_emul) | `adapter.flip_emul` | Game settings |  |
 | [Rotate panels 180°](#adapter-flip_quads) | `adapter.flip_quads` | Game settings |  |
 | [Don't pause on short interruptions](#adapter-focus_hold) | `adapter.focus_hold` | Game settings | 4 |
 | [Ignore focus dips up to](#adapter-focus_hold_ms) | `adapter.focus_hold_ms` | Game settings | 2 |
 | [Hide Quest foveation](#adapter-foveation_fix) | `adapter.foveation_fix` | Game settings |  |
+| [Clear the game's GL errors (GLES)](#adapter-gl_error_clear) | `adapter.gl_error_clear` | Game settings | 3 |
 | [Hide fast anti-aliasing (OpenGL ES)](#adapter-gl_hide_msrtt) | `adapter.gl_hide_msrtt` | Game settings | 1 |
 | [Draw each eye separately (OpenGL ES)](#adapter-gl_hide_multiview) | `adapter.gl_hide_multiview` | Game settings | 1 |
 | [GL shim: high-precision vertex shaders](#adapter-gl_highp_markers) | `adapter.gl_highp_markers` | Game settings | 1 |
 | [GL shim: integer vertex inputs](#adapter-gl_int_attribs) | `adapter.gl_int_attribs` | Game settings | 1 |
 | [Flat panel diagnostics (log)](#adapter-gl_mv_debug) | `adapter.gl_mv_debug` | Game settings |  |
-| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 65 |
+| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 66 |
 | [Vibration strength](#adapter-haptic_scale) | `adapter.haptic_scale` | Game settings |  |
 | [Turn off space warp](#adapter-hide_space_warp) | `adapter.hide_space_warp` | Game settings | 4 |
 | [Controller input diagnostics (log)](#adapter-input_diag) | `adapter.input_diag` | Game settings |  |
@@ -138,12 +142,12 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Treat newer Quest controllers as Touch](#adapter-profile_remap) | `adapter.profile_remap` | Game settings |  |
 | [Animate fingers from touch](#adapter-proximity_emul) | `adapter.proximity_emul` | Game settings |  |
 | [Keep pictures in bounds](#adapter-rect_clamp) | `adapter.rect_clamp` | Game settings |  |
-| [Refresh rate](#adapter-refresh_rate) | `adapter.refresh_rate` | Game settings | 2 |
+| [Refresh rate](#adapter-refresh_rate) | `adapter.refresh_rate` | Game settings | 3 |
 | [Wait for the game's GPU](#adapter-release_wait) | `adapter.release_wait` | Game settings |  |
 | [Re-create play space](#adapter-respace_kick) | `adapter.respace_kick` | Game settings |  |
 | [Sharpness](#adapter-scale) | `adapter.scale` | Game settings | 4 |
 | [Room depth](#adapter-scene_depth) | `adapter.scene_depth` | Game settings |  |
-| [Pretend room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 3 |
+| [Pretend room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 4 |
 | [Room height](#adapter-scene_height) | `adapter.scene_height` | Game settings |  |
 | [Room width](#adapter-scene_width) | `adapter.scene_width` | Game settings |  |
 | [Eye-image snapshots (diagnostics)](#adapter-snapshot) | `adapter.snapshot` | Game settings |  |
@@ -415,7 +419,7 @@ Stops some Unreal games from closing themselves right after starting.
 - `patch_remove_unreal_force_quit`
 - **Changes:** Changes the APK (during the OVRPort conversion).
 - **Offered (off):** Built as the alternate APK for Unreal games (use it if the game quits itself).
-- **Catalog games (35):** Asgard's Wrath 2, BARTENDER VR SIMULATOR, Carve Snowboarding, Creed, Dance Central, Espire 1: VR Operative (Quest Edition), Espire 2, ExploreVR and 27 more.
+- **Catalog games (36):** Asgard's Wrath 2, BARTENDER VR SIMULATOR, Carve Snowboarding, Creed, Dance Central, Espire 1: VR Operative (Quest Edition), Espire 2, ExploreVR and 28 more.
 - **Suggested by launch-test signatures:**
   - `force-quit` (error): The game quit itself right after starting.
 - **Source:** [patches/overport.py](../src/frameport/patches/overport.py)
@@ -511,6 +515,19 @@ Lets the game find extra content it keeps next to its data (for example Star War
 
 > Some games keep content in separate files next to their OBB (for example Star Wars: Tales from the Galaxy's Edge: its seasons and sound banks) and ask Meta's platform for them as asset files. OVRPort's platform loader doesn't know them, so the game waits for content that never arrives (black screen after loading). Lists the content files shipped with the game's data (*.pak) as installed and answers their download request at once with the file's path; nothing is copied or downloaded. Shares the language-pack library.
 
+### <a id="frame-asset_files_stub"></a>Asset-file service bypass
+
+Experimental bypass for a failed Meta asset-file check at startup. Reports an empty asset list and installed status without a file path; does not provide DLC. Experimental.
+
+- `frame.asset_files_stub` · experimental
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Suggested by launch-test signatures:**
+  - `meta-asset-status-error` (error): A DLC manager reports a Meta asset-file status error after VR starts (e.g.
+- **Source:** [patches/frame/langpack.py](../src/frameport/patches/frame/langpack.py)
+
+> Experimental bypass for a DLC manager blocked on Meta asset-file service errors at startup (e.g. PixelRipped 1995: Asset status error (code 100)). Returns an empty successful asset list and reports requested asset IDs as installed, with an empty file path. Does not supply DLC or change download requests. Enable only to test this startup failure; disable with FRAMEPORT_ASSET_FILES_STUB=0. Shares the language-pack library and needs no language packs.
+
 ### <a id="frame-avatar_stub"></a>Skip Meta avatars
 
 Lets games start that would stop at Meta's avatars (for example BlazeRush). No Meta avatars.
@@ -611,7 +628,7 @@ Plays the game's videos on the Frame's video hardware, so 4K and 8K video runs s
 - `frame.hw_video_decode` · also for 2D apps
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
 - **Suggested (on):** The game plays video through Android's decoders (MediaCodec, ExoPlayer or VLC): decode it on the Frame's hardware.
-- **Catalog games (7):** 4XVR Video Player, Batman: Arkham Shadow, Dance Central, Fruit Ninja, Kill It With Fire VR, MacacoVR, Moss: Book II.
+- **Catalog games (9):** 4XVR Video Player, Batman: Arkham Shadow, Dance Central, Fruit Ninja, Ghostbusters: Rise of the Ghost Lord, Kill It With Fire VR, MacacoVR, Moss: Book II and 1 more.
 - **Source:** [patches/frame/hw_video_decode.py](../src/frameport/patches/frame/hw_video_decode.py)
 
 > Decodes the game's videos on the Frame's hardware video decoder instead of Android's software decoders, which stutter or fall behind with 4K/8K video (for example video players, Batman: Arkham Shadow's cutscenes). Adds FramePort's codec plugin (OMX.frameport.avc/hevc/vp9.decoder) to this game's container only; the APK isn't changed. When the hardware is busy (for example Steam's own hardware video decoding is on) the video is decoded in software as before.
@@ -804,7 +821,7 @@ Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboar
 - `frame.sdl_clipboard` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** SDL app: it crashes at start in Lepton, which has no clipboard service.
-- **Catalog games (3):** Time Crisis II VR (Test), Time Crisis VR (Experimental), WiiCompiled VR.
+- **Catalog games (4):** Majora's Mask VR, Time Crisis II VR (Test), Time Crisis VR (Experimental), WiiCompiled VR.
 - **Suggested by launch-test signatures:**
   - `sdl-no-clipboard` (fatal): The app crashed at start because the Frame's Android has no clipboard.
 - **Source:** [patches/frame/sdl_clipboard.py](../src/frameport/patches/frame/sdl_clipboard.py)
@@ -855,7 +872,7 @@ Allows very large pictures (8K video, theaters) instead of quitting.
 
 Lets Team Beef ports (for example Lambda1VR) start on the Frame.
 
-- `frame.tbxr_vendor`
+- `frame.tbxr_vendor` · revision 2
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Team Beef port: it picks its OpenXR setup by headset maker, which the Frame reports as "valve".
 - **Catalog games (1):** Lambda1VR.
@@ -1021,7 +1038,7 @@ Lets older Unreal games start VR on the Frame (for example Star Wars Pinball VR)
 - `frame.unreal_ovrp_entrypoints`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unreal looks up OVRPlugin function(s) OVRPort's OVRPlugin lacks: ……. Without them Unreal starts no VR.
-- **Catalog games (1):** Star Wars Pinball VR.
+- **Catalog games (2):** Ghostbusters: Rise of the Ghost Lord, Star Wars Pinball VR.
 - **Source:** [patches/frame/unreal_ovrp.py](../src/frameport/patches/frame/unreal_ovrp.py)
 
 > Unreal's Oculus module looks up every OVRPlugin function it was built against and starts no VR when one is missing; OVRPort's OpenXR OVRPlugin lacks some old ones (for example ovrp_GetPTWNear, which Unreal 4.25 builds like Star Wars Pinball VR look up). The game then never starts an OpenXR session and crashes a few seconds in. Adds a generated library to libOVRPlugin.so with a stand-in for each missing function that reports failure (ovrpFailure), so Unreal's Oculus support starts. The functions OVRPort has are untouched.
@@ -1064,6 +1081,19 @@ Starts Unreal games without re-checking their data file (they'd seem to hang on
 
 > Unreal games can check their whole data file (.obb) before starting (bVerifyOBBOnStartUp). On the Frame that check's progress and error screens are invisible (Lepton runs VR games without an Android window), so the game seems to hang on its DownloaderActivity, for example Contractors. This turns the check off in the manifest; Unreal still checks that the OBB is there with the right size, so a missing or wrong-version OBB still stops the game.
 
+### <a id="frame-unreal_skip_obb_delivery"></a>Unreal: skip the OBB delivery check
+
+Skips a separate data-file check when an Unreal game still hangs at startup with the content check off. Experimental; the game still needs its data.
+
+- `frame.unreal_skip_obb_delivery` · experimental · also for 2D apps
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Suggested by launch-test signatures:**
+  - `unreal-obb-check-stuck` (fatal): The game stays on Unreal's OBB check screen (DownloaderActivity), which the Frame doesn't show, and never starts VR (for example Contractors, GitHub #159).
+- **Source:** [patches/frame/unreal_obb_check.py](../src/frameport/patches/frame/unreal_obb_check.py)
+
+> Unreal's Java OBB delivery check can leave a game on an invisible DownloaderActivity screen even with the manifest CRC check off (e.g. Into The Radius). Makes known Unreal expansionFilesDelivered methods return true, bypassing the Java name and size gate. Experimental: the native engine still needs complete, matching, readable OBB data.
+
 ### <a id="frame-unreal_splash_bypass"></a>Unreal: bypass the stalled loading splash
 
 Lets the game finish loading when its separate loading splash stalls the render thread.
@@ -1397,6 +1427,20 @@ For games whose fades to black don't show, so you see the level loading (for exa
 
 > Games that fade to black by dimming their picture with a layer color scale (XR_KHR_composition_layer_color_scale_bias, for example Batman: Arkham Shadow's loading screens) can show the level loading instead of black on the Frame. FrameBridge then draws the fade itself: a black quad in front of the eyes whose opacity follows the game's dimming. 2 also removes the game's own dimming (if both show, the fade is doubled).
 
+### <a id="adapter-flip_dump"></a>Upside-down panel images (diagnostics)
+
+Saves a few UI panels before and after FrameBridge turns them upright, for testing without the headset.
+
+- `adapter.flip_dump`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `0`.
+  - Game settings → Troubleshooting → "Upside-down panel images (diagnostics)" (advanced).
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> Saves the first N UI panels that FrameBridge turns upright (Vulkan games whose panels are stored upside down), before and after the flip, as fb_flip_&lt;n&gt;_raw.ppm / fb_flip_&lt;n&gt;_upright.ppm in the game's files folder on the Frame. Shows what the runtime gets without anyone wearing the headset.
+
 ### <a id="adapter-flip_emul"></a>Fix upside-down menus
 
 Turns menus and text the right way up.
@@ -1471,6 +1515,21 @@ Hides a Quest-only way of saving GPU power that the Frame lacks. Leave it on.
 
 > Hides Quest foveation extensions the Frame runtime lacks.
 
+### <a id="adapter-gl_error_clear"></a>Clear the game's GL errors (GLES)
+
+For OpenGL ES games whose memory use keeps growing (e.g. Vader Immortal).
+
+- `adapter.gl_error_clear`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `0`.
+  - Game settings → Troubleshooting → "Clear the game's GL errors (GLES)" (advanced).
+- **Catalog games (3):** Vader Immortal: Episode I, Vader Immortal: Episode II, Vader Immortal: Episode III.
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> Clears OpenGL errors the game left pending before FrameBridge calls the Frame's runtime. The runtime's GL code fails on any pending error; after one such failure at the start it allocated GPU memory every frame without freeing it (e.g. Vader Immortal, ~20 MB a second).
+
 ### <a id="adapter-gl_hide_msrtt"></a>Hide fast anti-aliasing (OpenGL ES)
 
 For Unity games that crash when they turn on anti-aliasing (for example The Room VR).
@@ -1555,7 +1614,7 @@ For games that freeze the Frame when a controller vibrates (for example Lucky's
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Controllers → "Fix freezes when controllers vibrate" (advanced).
-- **Catalog games (65):** AgeOfJoy, Ancient_Dungeon, Audica, BattleSisters, Beat Saber, Caves, Clockwork, COMPOUND and 57 more.
+- **Catalog games (66):** AgeOfJoy, Ancient_Dungeon, Audica, BattleSisters, Beat Saber, Caves, Clockwork, COMPOUND and 58 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the Frame when the game vibrates a controller (for example Lucky's Tale's save slots, GitHub #9). Needs a rebuild.
@@ -1790,7 +1849,7 @@ How often the picture updates. Higher is smoother if the game can keep up.
 - **Options:**
   - Value: float, default `0.0`.
   - Game settings → Picture → "Refresh rate": Game's choice (`0`), 72 Hz (`72`), 80 Hz (`80`), 90 Hz (`90`), 96 Hz (`96`), 108 Hz (`108`), 120 Hz (`120`), 144 Hz (`144`).
-- **Catalog games (2):** Does it Stack?, Vacation Simulator.
+- **Catalog games (3):** Does it Stack?, Majora's Mask VR, Vacation Simulator.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Display refresh rate for this game (72, 80, 90, 96, 108, 120 or 144; 0 = the game's choice). A video's frame rate that divides the refresh rate plays smoothest (for example 30 fps at 90 Hz, 24 fps at 72 Hz).
@@ -1863,7 +1922,7 @@ Mixed-reality games that build their level from your room get a simple room with
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Mixed reality → "Pretend room layout".
-- **Catalog games (3):** Arkio, Demeter, Vermillion.
+- **Catalog games (4):** Arkio, Demeter, Ghostbusters: Rise of the Ghost Lord, Vermillion.
 - **Suggested by launch-test signatures:**
   - `scene-missing` (warning): The game wants Meta's room data (scene API), which the Frame lacks.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -1929,7 +1988,7 @@ For games whose menus or screens jump to wherever you look.
 
 ### <a id="adapter-strip_color_bias"></a>Drop layer color fades
 
-For games whose memory use keeps growing (for example Vader Immortal). Some fades no longer show.
+Diagnostics: removes layer color fades. Some fades no longer show.
 
 - `adapter.strip_color_bias`
 - **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
@@ -1939,7 +1998,7 @@ For games whose memory use keeps growing (for example Vader Immortal). Some fade
   - Game settings → Troubleshooting → "Drop layer color fades" (advanced).
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, for example Vader Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show.
+> Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it (diagnostics). Fades done this way no longer show.
 
 ### <a id="adapter-strip_depth"></a>Strip depth layers
 

docs/PLAYBOOK.md

@@ -24,6 +24,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
 | A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
 | A Team Beef port (Lambda1VR, RTCWQuest, …) exits at once: `UnsatisfiedLinkError: dlopen failed: library "libopenxr_loader_valve.so" not found` (GitHub #59) | TBXR loads `openxr_loader_<Build.MANUFACTURER>` (Lepton: valve) and takes the Meta path only when `strstr(OPENXR_HMD, "meta")` matches, else Pico's | `frame.tbxr_vendor` (empty `libopenxr_loader_valve.so` + the "meta" literal → "alve"). Game data (`xash/`, …) goes to /sdcard: upload it with the Files tab to the game's storage. Black eyes with `TBXR: Incomplete frame buffer object: GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE`: TBXR always uses multisampled render-to-texture (even `--msaa 1`); `frame.tbxr_vendor` links the GL shim, which hands it single-sampled versions (log `GL shim: multisampled render-to-texture … drawn single-sampled`) |
+| Black screen after VR starts; `Asset status error  (code 100)` in `DLC_Manager:AssetStatusCallback` (GitHub #203, e.g. PixelRipped 1995) | Meta asset-file status fails after entitlement succeeds; the log does not identify the native call or asset ID | Try `frame.asset_files_stub` (opt-in, triage-only): native/langpack answers GetList with an empty successful list and StatusById with installed status, an empty path and the requested ID. No DLC files are supplied; download requests retain their existing behavior. Disable with `FRAMEPORT_ASSET_FILES_STUB=0`. Host-tested only; whether this fixes startup needs a game/device test |
 | Missing sound or extra content in a game whose OBB folder has separate `*.pak` files (GitHub #61, Star Wars: Tales from the Galaxy's Edge: seasons + Wwise banks) | the game asks Meta's platform for these asset files (`ovr_AssetFile_GetList` / `DownloadById`); OVRPort's loader doesn't list them | copy every content/sound-bank PAK and use `frame.asset_files` (native/langpack lists the data's `*.pak` as installed `default` assets, IAP `free`, and answers DownloadById at once with the path; off: env FRAMEPORT_ASSET_FILES=0). Tales also needs the splash and depth-size fixes below |
 | A SideQuest backup has `apk/` and a sibling `obb/` with content/sound-bank PAKs, but the Frame only has the main OBB (GitHub #61, Tales from the Galaxy's Edge) | older scans treated that layout as loose expansion files and selected only the named OBBs; the asset-file patch then found no PAKs | the scanner chooses the OBB folder by version first, then keeps the whole sibling data folder when all its expansion files are selected for this APK; app updates repair affected library entries and refresh asset/language-pack detection. Reinstall to copy the missing files, or scan the backup again first. Folders with other packages or unselected OBB versions still send only the selected OBBs |
 | Tales from the Galaxy's Edge stops during map loading (GitHub #61): game thread in `FlushRenderingCommands` / `UEngine::LoadMap`, render thread in `FSplash::RenderFrame_RenderThread` / `ovrp_WaitToBeginFrame` / SteamVR `WaitFrame` | the separate Oculus loading splash waits for an unbegun frame while map travel waits for rendering | `frame.unreal_splash_bypass`: returns from the splash renderer, with a checked symbol, size and prologue. The last image stays visible during loading; the normal renderer and menu layers continue. Headset test with the depth-size fix: gameplay, both eyes, controller input and sound work |
@@ -60,7 +61,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Oculus Rift game won't run on the Frame | Oculus/LibOVR game: needs Revive, whose hooks don't work under Proton-arm64, and FramePort won't defeat the Oculus runtime signature check | Play it on this PC (SteamVR + Revive). Only OpenVR/OpenXR-native Rift games run on the Frame |
 | Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
 | PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
-| Uploads to the Frame are slow (~15 MB/s) | PC and Frame both on Wi-Fi through the home router | Connect the PC to the Frame's own hotspot (or a USB cable): FramePort uses the direct link automatically (~80-100 MB/s); job log line "Transfer link" |
+| Uploads to the Frame are slow | The link, storage or transfer backend can limit throughput | Check the job's "Transfer link"; try the Frame's hotspot or USB cable. Large install files prefer system OpenSSH SFTP, retaining paired-host checks and `.part` resume; unavailable or failed native uploads fall back to Paramiko. The log names the backend. Settings → Installing → Parallel uploads accepts 1–8 (default 3; saved preferences are preserved). More is not always faster. Measure the production path with `scripts/upload_bench.py --methods app-files-3 --check-resume` (three repetitions, checksum verification) |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
 | Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`, agent v67): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (for example SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
@@ -72,6 +73,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | The Climb 666.0: audio with no headset picture, `OVRPortVrApi: Unsupported frame flags or swap interval`; then SIGSEGV in `vulkan.freedreno.so` during `vkCmdEndRenderPass` once frames are accepted (GitHub #238) | The game submits the obsolete Quest texture-density debug flag (`0x100`), which the bridge rejected. It also binds the bridge's full-rate texture as a fragment-density attachment even though foveation support is reported off; Turnip reads density maps on the CPU, but an ordinary sampled image has no mapped backing memory | Updated `frame.vrapi_bridge` accepts the compositor debug/volume flags and creates the compatibility texture with `VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT`. Do not gate that usage on the advertised format features (the Frame reports R8G8_UNORM without the density bit). `device.files` selects `r_vr_foveated = 0` when the engine contains that cvar; The Climb 2 keeps `r_variable_rate_shading = 0`. Triage `vrapi-frame-rejected` marks rejected frames as fatal despite pacing logs. Picture confirmed on the headset. With the corrected config, an uncapped launch stayed running for over four minutes at a median 72 fps with no native crash or GPU fault. The user confirmed working menus and gameplay on 2026-10-12 |
 | Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
 | Unreal game: launch.log ends with `ActivityTaskManager: START u0 {… cmp=<pkg>/.DownloaderActivity}` and `Displayed <pkg>/.DownloaderActivity`, then nothing: no OpenXR instance, no crash (GitHub #159 Contractors; triage `unreal-obb-check-stuck`, also when the OBB is on the Frame) | Epic's DownloaderActivity (started by GameActivity.onResume before the engine's main init) checks every OBB's name + size compiled into the APK (OBBData); with manifest meta-data `com.epicgames.ue4.GameActivity.bVerifyOBBOnStartUp=true` it then reads the whole OBB and compares each entry's CRC32 (cached in `files/cacheFile.txt` by the OBB's mtime). Its progress and error screens are invisible in Lepton (headless VR); a CRC mismatch waits for a button forever. A missing / wrong-size OBB starts Google Play's downloader (or a "No Google Play Store Key" dialog) and also waits | `frame.unreal_skip_obb_check` (suggested by analysis `unreal_verify_obb`): sets that meta-data to false (one boolean in the manifest, `axml.set_meta_data_bool`), which skips only the CRC pass. Still stuck: the OBB doesn't match the APK version (name `main.<versionCode>.<pkg>.obb` and its size) - copy APK + OBB from the same install |
+| Unreal game still stays on `DownloaderActivity` with CRC checking off (`bVerifyOBBOnStartUp=false`) and a fully uploaded matching OBB (GitHub #283, Into The Radius) | The separate Java `expansionFilesDelivered()` name and size gate can reject an OBB through Android external storage in Lepton; disabling CRC does not bypass it | Try `frame.unreal_skip_obb_delivery` (opt-in, experimental, triage-only). It returns true from known Unreal/package delivery predicates in every dex, preserving normal downloader success and main init. Analysis `unreal_obb_delivery` (version 16) controls applicability. The native engine still needs complete, matching, readable OBB data; unverified on a device |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK; Frame has no AArch32 | None. PC/Rift version via Revive |
 | Crash at start: `NoClassDefFoundError: … Landroid/window/OnBackInvokedCallback;` or `NoSuchMethodError: No static method storeStoreFence()V in class Ljava/lang/invoke/VarHandle;` (GitHub #71/#72, triage `android-too-new`) | The APK needs Android 13+ (minSdk 33 or more; those were 34) and calls its classes at start; Lepton's Android is 11 (API 30). OVRPort lowers minSdk to 29, so it installs anyway. minSdk ≤ 32 (Quest's Android 12L) is fine: 16 working catalog games declare 32 | None (analysis `extra.min_sdk` > 32 → a warning on the game page/CLI and in the recipe notes; never unsupported from the manifest alone, the launch test's triage decides). Waits for Valve to update Lepton's Android |
 | Nothing opens; `TWALauncherActivity: Using URL from Manifest (https://…)`, `Creating TwaLauncher for com.oculus.browser`, `NameNotFoundException: com.oculus.browser` (GitHub #86 Mahjong Table VR, triage `web-wrapper`) | The APK is a Trusted Web Activity (Bubblewrap / Meta's PWA packaging): a website that opens in Meta's browser, which Lepton doesn't have | None: open the URL in a browser. Analysis `extra.web_wrapper` (manifest meta-data `android.support.customtabs.trusted.DEFAULT_URL`, resolved through resources.arsc, or androidbrowserhelper's LauncherActivity) → a warning with the URL (not unsupported: the manifest alone never decides) |
@@ -146,6 +148,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Unreal game (ILMxLAB, for example Vader Immortal): controllers track but grip/trigger do nothing, grabbing never works (Unreal's own input values move, the game's stay 0) | `URPOCKeyMapManagerComponent` picks the Quest or the Gear VR key set by `IsRunningOnSantaCruz()`; on the Frame it takes Gear VR, empty in a Quest build | `frame.unreal_quest_keymap` (the Oculus case keeps the Quest set, for action and axis mappings; found by Klownicle, GitHub #49) |
 | The hands' thumbs never move when you touch the thumbstick or buttons (Unreal `ThumbUp` stays 1, for example Vader Immortal) | OVRPlugin reports thumb proximity from XR_FB_touch_controller_proximity, which the Frame's runtime lacks; OVRPort's loader offers it anyway and the proximity actions never get a binding | adapter `proximity_emul=1` (thumb proximity from the touch inputs: thumbstick, face buttons, thumb rest; 2 = also the index finger from trigger touch); log `proximity_emul: finger proximity bound to touch`. **For UE4 Oculus games this didn't animate the thumbs** (Vader, GitHub #49): use `frame.unreal_thumb_touch` (found by Klownicle): `OculusInput::FOculusInput::SendControllerEvents` computes ThumbUp from NearTouches (masks 0x2/0x8); the patch makes it read Touches (the slot 4 bytes before) with masks 0x0f00 (X/Y/stick/thumb rest) / 0x000f (A/B/stick/thumb rest), keeping the inversion; three instructions, matched exactly (build note `OculusInput ThumbUp: from the capacitive touches`). Matches Vader Immortal Ep. I, Robo Recall, Phantom: Covert Ops, Time Stall, Star Wars: Tales from the Galaxy's Edge; newer UE4 builds (for example Asgard's Wrath 2, RE4, In Death) compile it differently (shared mask registers) and aren't matched |
 | Vulkan game (Unreal / own engine with the Vulkan shim): the GPU hangs at one effect or cutscene (kernel `hangcheck detected gpu lockup`, freeze/exit; for example a VR4 cutscene, GitHub #140) | a SPIR-V shader reads a loop counter/accumulator before setting it (VR4's campaign shader, GitHub #10) | adapter `vk_shader_dump=1` (`frame.vk_sanitize`'s shim; log `vk shim: dumping SPIR-V modules to …`) writes every distinct module once to `files/fp_vk_shaders/<size>_<sha256>.spv` + `index.txt` (`<seq> <ms> <unix ms> <name> new\|known\|again`); play to the hang, collect diagnostics (`target/shaders/fp_vk_shaders/`, newest 4 MB) and take the modules first created (`new`) shortly before the kernel's hangcheck time; disassemble (`spirv-dis`), find the variable read before its first store, write a `vk_shader_fix` (`<size>:<sha256>:<byte offset>:<words>` = inserted OpStores; log `vk shim: fixed shader module`); switch the dump off again |
+| OpenGL ES game: memory and GPU mappings grow every frame (~20 MB/s, `/dev/dri/renderD128` mappings ~6 per frame) until the frame rate collapses; the game's `xrclient_<package>.txt` (Steam logs) has one `SXR_GL_CHECK: error:0x502 ... glGenTextures` before the session starts (GitHub #285, Vader Immortal) | The game leaves GL errors pending on its context; the runtime's GL interop reads glGetError after its own calls and takes the stale error as its own failure. From then on `CVRCompositorSharedTextures::BeginCommandBuffer` allocates a new command buffer every frame instead of reusing one (perf page-fault stacks) | Adapter `gl_error_clear=1` (GLES only) clears pending GL errors before xrCreateSwapchain/xrBeginFrame/xrEndFrame; Vader's catalog recipes set it. Verified headless 2026-10-14: 191 GPU mappings and ~1.07 GB flat over 100 s (before: +430 mappings/s, +22 MB/s), no SXR_GL_CHECK |
 | OpenGL ES game: the GPU hangs at one effect (freeze/exit, compositor watchdog, for example Vader Immortal's lightspeed jump) | a shader (as Zink compiles it) reads loop counters/accumulators before setting them | capture the SPIR-V (adapter `zink_shader_dump=1` writes every module to `files/fp_spirv/`, or a GPU capture), then a `zink_shader_fix` entry (same format as `vk_shader_fix`) + `frame.zink_shader_fix` (Vulkan layer under Zink, activated through GraphicsEnv's debug layer list); log `shader fix layer: fixed shader module N`; triage `zink-shader-fix-mismatch` when a Frame update changed the driver's output |
 | 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
 | A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |

docs/TRANSFER_BENCHMARK.md

@@ -0,0 +1,195 @@
+# Transfer measurements and incremental installs
+
+## Production OpenSSH follow-up
+
+OpenSSH is now the preferred installer backend for files >=8 MiB. The new default is three workers (range 1–8),
+with saved preferences preserved. Fresh files use `put`; existing partial files use `reput`. Each worker keeps
+one SFTP batch session. Progress is polled through a separate bounded SFTP channel. Native failures resume via
+Paramiko; cancellation stops the owned SFTP/SSH process trees and does not trigger fallback.
+
+Windows matched production comparison: eight 64 MiB files, 512 MiB total, three shuffled repetitions per backend,
+three workers, same home Wi-Fi/internal storage. OpenSSH median **15.51 MB/s**, Paramiko median **11.08 MB/s**
+(about 40% faster). All six checksums passed. OpenSSH trials ranged 9.5–16.8 MB/s, so link variability still
+matters; it was slower than Paramiko in one pass. Native credential/progress setup took 0.12–0.13 seconds.
+
+The separate Windows 128 MiB production test also passed every checksum. Native cancellation left a partial file
+of 74,752,000 bytes; resuming with OpenSSH produced the expected SHA-256. The log confirmed no fallback for the
+resumed production upload. Reports:
+`/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-production-comparison-windows.json` and
+`/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-production-windows.json`.
+
+The earlier sections below preserve measurements made before the production backend switch.
+
+The WSL production validation (128 MiB, three workers, three repetitions) measured 14.1 / 19.1 / 15.0 MB/s,
+with every checksum passing and native backend logs recorded. Production cancellation left a 72,330,240-byte
+partial file; OpenSSH resumed it in 4.23 seconds with the expected SHA-256 and no Paramiko fallback. Report:
+`/tmp/frameport-upload-native-production-wsl.json`.
+
+## Measurements (2026-10-14)
+
+Both runs used the same paired Frame, the home-router connection and internal ext4 storage under the paired user's
+home. Each large-file trial sent the same 128 MiB random payload; each small-file trial sent 512 files of 64 KiB
+(32 MiB total). Methods were shuffled for each of three repetitions. Windows and WSL runs were sequential, not
+concurrent. Every completed transfer passed SHA-256 verification. Rates below include connection/setup and transfer
+completion, but exclude checksum verification and cleanup; MB/s uses decimal bytes.
+
+| Method | WSL2 median MB/s | Windows 11 native median MB/s |
+|---|---:|---:|
+| FramePort pipelined SFTP | 10.4 | 6.1 |
+| Paramiko SFTP, 64 MiB window | 17.1 | 4.5 |
+| OpenSSH SFTP | 16.8 | 15.4 |
+| OpenSSH SCP (default protocol) | 11.1 | 10.1 |
+| OpenSSH `ssh` + streamed file | 9.9 | 8.1 |
+| FramePort tar stream | 14.9 | 6.8 |
+| OpenSSH tar stream | 15.0 | 7.2 |
+
+The network varied considerably: WSL's application trials ranged from 9.6–12.8 MB/s, native SFTP from
+16.2–17.3 MB/s, and some other methods dropped below 5 MB/s. Windows application trials ranged from 5.6–6.4 MB/s;
+native SFTP ranged from 9.1–16.5 MB/s. These are useful end-to-end comparisons on this setup, not a measurement of
+the maximum throughput each transport can achieve. Window tuning did not help the Windows run.
+
+Cancellation/resume checks interrupted the application upload at 64 MiB, then independently resumed that partial
+file with the application and with OpenSSH SFTP `reput`. All four resumed files passed SHA-256 verification. This
+checks application cancellation and both resume paths; native SFTP cancellation itself remains unmeasured.
+
+The Frame's USB and hotspot interfaces were up, but neither direct endpoint was reachable from the PC. No removable
+storage was mounted. USB, hotspot and microSD performance remain **unmeasured** in this round. The Frame's router
+connection used 5 GHz / 80 MHz Wi-Fi, with roughly -56 dBm signal during a read-only probe. This does not reproduce
+the 6 GHz direct-hotspot setup in [discussion #242](https://github.com/spoopyghosty0/frameport/discussions/242), where
+the reporter measured about 114 MB/s with OpenSSH versus 23 MB/s with Paramiko.
+
+**Recommendation:** prototype an optional OpenSSH SFTP backend for large files, retaining `.part`/`reput`,
+cancellation, retries, strict paired-host verification and Paramiko fallback. Validate it on a fast direct link
+before making it the default. On this Windows run SFTP was about 2.5 times faster than the current application,
+and it beat SCP. The small-file tar measurements do not justify selecting a new tar transport yet. Production
+transport selection remains Paramiko pending that decision. The bounded parallel-file setting described below
+uses independent Paramiko connections.
+
+## Parallel-file uploads
+
+### Matched native OpenSSH comparison
+
+The later comparison tested both backends sequentially on Windows and WSL, with three shuffled repetitions of
+the same eight 16 MiB files per worker count. Native `sftp-files-N` balances files across N persistent OpenSSH
+SFTP batch processes. Setup and completion are included; checksum verification is excluded. All 60 transfers
+passed SHA-256 checks. This is benchmark code; the production uploader still uses Paramiko.
+
+| Workers | Windows Paramiko MB/s | Windows OpenSSH MB/s | WSL Paramiko MB/s | WSL OpenSSH MB/s |
+|---|---:|---:|---:|---:|
+| 1 | 6.22 | 14.96 | 6.17 | 14.64 |
+| 2 | 10.61 | 17.73 | 14.41 | 14.45 |
+| 3 | 8.90 | 18.89 | 13.65 | 17.75 |
+| 4 | 14.90 | 16.80 | 15.67 | 16.63 |
+| 8 | 13.50 | 20.16 | 17.03 | 16.82 |
+
+Three is a reasonable default candidate for a future OpenSSH backend: versus two it improved median throughput
+by 6.5% on Windows and 22.8% on WSL. Eight was faster on Windows but slower on WSL. The production Paramiko
+default remains two because three regressed by 16.1% on Windows and 5.3% on WSL in this matched comparison.
+Link variability remains substantial, and no fast hotspot/USB result is claimed.
+
+Reports: `/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-parallel-windows.json` and
+`/tmp/frameport-upload-native-parallel-wsl.json`.
+
+Settings → Installing → **Parallel uploads** accepts **1–8**, default **2**. It controls large files within one
+install; the FIFO still runs one install job at a time. A single APK is not split into chunks. Large files are
+scheduled largest first, with at most one authenticated SSH connection per active worker and never more workers
+than files. Small files still use tar batches after the large-file uploads. Choose 1 on a busy network; a higher
+count can consume all available bandwidth and is not automatically faster.
+
+The parallel comparison uses the same eight 16 MiB OBB-shaped files (128 MiB total) for every worker count, with
+three shuffled repetitions. The production uploader is used by `app-files-N`, including its aggregate progress,
+resume baselines, cancellation checks and connection cleanup. A failed or cancelled cohort stops queued work and
+closes only its worker transports; completed files and interrupted `.part` files remain resumable.
+
+| Workers | WSL2 production median MB/s | Windows 11 production median MB/s |
+|---|---:|---:|
+| 1 | 9.6 | 5.6 |
+| 2 (default) | 9.1 | 10.9 |
+| 3 | 6.5 | Not measured in the final production run |
+| 4 | 12.4 | 14.8 |
+| 8 | 11.2 | 17.3 |
+
+On Windows, the production uploader improved from 5.6 to 10.9 MB/s with 2 workers (**1.95 times faster**), and
+17.3 MB/s with 8 (**3.08 times faster**). All twelve Windows production transfers passed SHA-256 verification.
+The preceding Windows prototype also tested 3 workers (12.2 MB/s median), before aggregate progress/cancellation
+were integrated; that is not included as a production measurement in the table.
+
+WSL was noisy: four workers improved its median by about 29%, but 2 did not improve its median, and 3 was slower.
+There is no evidence that a particular worker count is universally fastest. The option is retained because it
+produced a repeatable benefit on Windows and higher counts improved the WSL median. Default 2 limits competing
+transfers while retaining a measured Windows benefit; users can measure higher counts or select 1 in their own
+environment. Production code, including cleanup and progress checks, was used for both final comparisons.
+
+```sh
+uv run python scripts/upload_bench.py --mib 128 --repeat 3 --methods app-files-1,app-files-2,app-files-3,app-files-4,app-files-8 --json parallel.json
+```
+
+`install.upload_threads` persists the setting. Malformed values use 2 and numeric values are clamped to 1–8.
+The serial setting reuses the existing control connection; parallel workers verify that the new transport reaches
+the same paired headset before sending any files.
+
+## Reproducing the measurements
+
+Run from the checkout using the Python environment for the platform being measured:
+
+```sh
+uv run python scripts/upload_bench.py --mib 512 --repeat 3 --check-resume --json uploads.json
+uv run python scripts/upload_bench.py --fast-link --probe
+uv run python scripts/upload_bench.py --fast-link --remote-dir /path/on/card --mib 512 --repeat 3 --json card.json
+```
+
+`--host` selects a specific paired endpoint; `--fast-link` uses the same authenticated direct-link discovery as an
+install. Inspect the reported endpoint and link before comparing methods. Join the Frame's hotspot or connect its
+USB cable before testing those paths; the benchmark does not change PC networking. Keep the headset awake and avoid
+other network traffic. A 512 MiB payload is preferred for follow-up tests on fast links; the available-link runs
+above used 128 MiB.
+
+The script creates a unique scratch directory on the selected filesystem, checks content outside the timed upload,
+and removes its own temporary remote files and temporary key copy. It never modifies the pairing key's ACL. Windows
+OpenSSH rejects an `OWNER RIGHTS` ACL entry; the temporary copy grants only the current user, without Python's
+Windows `chmod` behaviour that can introduce that entry. Native clients use the application's key and known-hosts
+file with strict host verification.
+
+JSON rows contain bytes, total seconds, separately measured setup seconds where available, payload and total rates,
+verification duration and checksums. SCP/SFTP's setup is included in total time because their command-line clients
+do not expose its completion separately. On POSIX, CPU includes the Python parent and child processes; on Windows,
+`os.times()` measures only the parent, so native subprocess CPU numbers must not be compared with Paramiko's CPU.
+An error is recorded rather than counted as a successful trial. `--methods` can restrict the run; `--small-files`
+controls the tar corpus. Cipher comparisons are available as `ssh-gcm` and `ssh-chacha`.
+
+## Incremental install behaviour
+
+`game_update.plan_update` is the shared, I/O-free Quest/Android classifier used by badges and installation. Recipe
+source, notes and catalog revision do not affect it. A newer tested catalog recipe remains a separate suggestion
+when the user customized their recipe.
+
+- Build records keep an APK recipe fingerprint, source hash/stat, selected native-asset identities, converter
+  identity and the existing validated APK hashes. Reusable local APKs are checksum-checked before installation.
+- Deployment records keep applied runtime configuration and its fingerprint, APK stat/hash, source version,
+  data manifest/digest and artwork hashes. Routine device samples carry only the digest, and updates fetch a
+  detailed manifest only when necessary. Live numeric settings writes update only the applied runtime configuration,
+  leaving APK build identity intact. Desired data manifests are cached locally for badges, without render-path I/O.
+- Runtime-only updates use agent v87 `configure`: no conversion, signing, APK transfer, artwork, Steam restart or
+  automatic launch test. They still require the installed APK identity and an available destination, and refuse
+  changes while the game is running. Defaults explicitly reset overrides embedded in an older APK. Generated
+  configuration files are restored or removed only when they still match FramePort's last write; user edits survive.
+- Build support dependencies remain conservative: controller models/native surfaces/haptic support, Zink-layer
+  selection, mixed foveation patches and revised adapter support can require a new APK. A recorded alternate
+  variant can be reused when switching variants.
+- Data-only updates transfer missing/different-size data using the resumable uploader. Recipe/APK updates skip
+  data synchronization when the source data manifest is unchanged, preserving Frame-side mods; explicit forced
+  reinstalls still check/repair data. Artwork-only
+  updates send changed slots; unchanged artwork avoids a Steam refresh. APK/data changes retain the configured
+  automatic launch test. Settings/artwork changes skip it.
+- APK-only updates preserve installed OBBs, including mods, and do not apply old staged OBBs or artwork from an
+  interrupted upload. Ordinary data comparison still uses sizes, matching existing behaviour; equal-size content
+  replacement is not detected automatically. Explicit rebuild/reinstall remains available (`install --force`).
+- Legacy build identities take the full path once because their original build inputs cannot be established
+  safely. Converted-copy cleanup and `build.keep_copies` remain in effect; a configuration/data update does not
+  require the deleted converted APK.
+
+Install results record `stage_seconds` in the library's install history. This includes planning, conversion,
+validation, transfer and finalization stages reached by that operation; the GUI's subsequent optional launch test
+is separate. Use these timings to distinguish build cost, network transfer and device/Steam work when reviewing a
+slow install. Configuration success is recorded after writing the configuration and completing its sync; a failed
+operation leaves the prior applied fingerprint so it remains retryable.

native/adapter/flip_vk.c

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Included by frame_adapter.c. Emulates XR_FB_composition_layer_image_layout's VERTICAL_FLIP for quad
-// layers of Vulkan apps when the runtime lacks the extension (Frame): the app's image is blitted
-// upside-down into a runtime-owned shadow swapchain, which is submitted instead.
+// layers of Vulkan apps when the runtime lacks the extension (Frame): the quad's rectangle is turned upside down in
+// the app's own image (through a scratch image of ours), once per acquired image. An extra runtime swapchain per
+// flipped quad (the first version) ran into the Frame's swapchain limit: AC Nexus has more UI panels than it allows,
+// so some stayed upside down and the game's own later panels failed with XR_ERROR_LIMIT_REACHED (GitHub #138).
 #define VK_NO_PROTOTYPES
 #include <vulkan/vulkan.h>
 #define XR_USE_GRAPHICS_API_VULKAN
@@ -40,6 +42,25 @@ static struct {
     PFN_vkCreateFence CreateFence;
     PFN_vkWaitForFences WaitForFences;
     PFN_vkResetFences ResetFences;
+    PFN_vkCreateImage CreateImage;
+    PFN_vkDestroyImage DestroyImage;
+    PFN_vkGetImageMemoryRequirements GetImageMemoryRequirements;
+    PFN_vkAllocateMemory AllocateMemory;
+    PFN_vkFreeMemory FreeMemory;
+    PFN_vkBindImageMemory BindImageMemory;
+    PFN_vkCreateBuffer CreateBuffer;  // flip_dump
+    PFN_vkDestroyBuffer DestroyBuffer;
+    PFN_vkGetBufferMemoryRequirements GetBufferMemoryRequirements;
+    PFN_vkBindBufferMemory BindBufferMemory;
+    PFN_vkMapMemory MapMemory;
+    PFN_vkUnmapMemory UnmapMemory;
+    PFN_vkCmdCopyImageToBuffer CmdCopyImageToBuffer;
+    VkPhysicalDeviceMemoryProperties memory;
+    // scratch image for in-place flips: grown to the largest rectangle, one format at a time
+    VkImage scratch;
+    VkDeviceMemory scratch_memory;
+    VkFormat scratch_format;
+    uint32_t scratch_w, scratch_h;
 } vk;
 
 typedef struct {
@@ -49,10 +70,12 @@ typedef struct {
     uint32_t image_count;
     uint32_t last_acquired;
     uint32_t acquired[MAX_IMAGES], acquired_count, waited_count;
-    XrSwapchain shadow;
-    XrRect2Di shadow_rect;
-    VkImage shadow_images[MAX_IMAGES];
-    uint32_t shadow_count;
+    // rectangles already turned upside down in each image since the app last acquired it (static quads are
+    // submitted again without a new acquire: flipping them again would undo it)
+    struct { XrRect2Di rect; uint32_t layer; } flipped[MAX_IMAGES][4];
+    uint32_t flipped_count[MAX_IMAGES];
+    int dumped;  // flip_dump saved this swapchain's quad
+    int logged;  // its first in-place flip was logged
 } tracked_swapchain;
 
 static pthread_mutex_t flip_lock = PTHREAD_MUTEX_INITIALIZER;
@@ -81,6 +104,9 @@ static void flip_on_create_session(const XrSessionCreateInfo *info) {
             vk.family = b->queueFamilyIndex;
             vk.index = b->queueIndex;
             vk.state = 0;
+            vk.scratch = VK_NULL_HANDLE;  // belonged to the previous session's device
+            vk.scratch_memory = VK_NULL_HANDLE;
+            vk.scratch_w = vk.scratch_h = 0;
             LOG("flip: Vulkan session (queue family %u index %u)", vk.family, vk.index);
         }
 }
@@ -109,22 +135,26 @@ static void flip_on_acquire(XrSwapchain handle, uint32_t index) {
     tracked_swapchain *t = find_tracked(handle, 0);
     if (t) {
         t->last_acquired = index;
+        if (index < MAX_IMAGES) t->flipped_count[index] = 0;  // new content: upside down again
         if(t->acquired_count<MAX_IMAGES)t->acquired[t->acquired_count++]=index;
     }
     pthread_mutex_unlock(&flip_lock);
 }
 
 static void flip_on_destroy(XrSwapchain handle) {
-    PFN_xrDestroySwapchain destroy = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
     pthread_mutex_lock(&flip_lock);
     tracked_swapchain *t = find_tracked(handle, 0);
-    if (t) {
-        if (t->shadow && destroy) destroy(t->shadow);
-        memset(t, 0, sizeof(*t));
-    }
+    if (t) memset(t, 0, sizeof(*t));
     pthread_mutex_unlock(&flip_lock);
 }
 
+// xrCreateSwapchain: single-image colour swapchains of a Vulkan session (quad candidates) also get transfer usage,
+// so the in-place flip may blit from and back into them.
+static int flip_wants_transfer(const XrSwapchainCreateInfo *info) {
+    return flip_emul && vk.device && !runtime_has_image_layout && info->arraySize == 1 && info->faceCount == 1 &&
+           info->sampleCount == 1 && (info->usageFlags & XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT);
+}
+
 static int vk_ready(void) {
     if (vk.state) return vk.state > 0;
     vk.state = -1;
@@ -137,8 +167,15 @@ static int vk_ready(void) {
 #define DEV(name) vk.name = (PFN_vk##name)vk.GetDeviceProcAddr(vk.device, "vk" #name); if (!vk.name) return 0;
     DEV(GetDeviceQueue) DEV(CreateCommandPool) DEV(AllocateCommandBuffers) DEV(BeginCommandBuffer)
     DEV(EndCommandBuffer) DEV(ResetCommandBuffer) DEV(CmdPipelineBarrier) DEV(CmdBlitImage) DEV(CmdClearColorImage) DEV(QueueSubmit)
-    DEV(CreateFence) DEV(WaitForFences) DEV(ResetFences)
+    DEV(CreateFence) DEV(WaitForFences) DEV(ResetFences) DEV(CreateImage) DEV(DestroyImage)
+    DEV(GetImageMemoryRequirements) DEV(AllocateMemory) DEV(FreeMemory) DEV(BindImageMemory)
+    DEV(CreateBuffer) DEV(DestroyBuffer) DEV(GetBufferMemoryRequirements) DEV(BindBufferMemory) DEV(MapMemory)
+    DEV(UnmapMemory) DEV(CmdCopyImageToBuffer)
 #undef DEV
+    PFN_vkGetPhysicalDeviceMemoryProperties memory_properties =
+        (PFN_vkGetPhysicalDeviceMemoryProperties)gipa(vk.instance, "vkGetPhysicalDeviceMemoryProperties");
+    if (!memory_properties) return 0;
+    memory_properties(vk.physical, &vk.memory);
     vk.GetDeviceQueue(vk.device, vk.family, vk.index, &vk.queue);
     VkCommandPoolCreateInfo pool = {VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO, NULL,
                                     VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT, vk.family};
@@ -169,103 +206,195 @@ static int wants_vertical_flip(const XrCompositionLayerQuad *q) {
     return 0;
 }
 
-// Returns a replacement quad referencing a flipped copy, or NULL to keep the original.
-static const XrCompositionLayerQuad *flip_quad(XrSession session, const XrCompositionLayerQuad *q,
-                                               XrCompositionLayerQuad *out) {
-    if (!flip_emul || runtime_has_image_layout || !wants_vertical_flip(q)) return NULL;
-    if (!vk_ready()) { static int warned; if (!warned++) LOG("flip: needed but Vulkan blitter unavailable (GLES app?)"); return NULL; }
-    PFN_xrCreateSwapchain create = (PFN_xrCreateSwapchain)lookup(active_instance, "xrCreateSwapchain");
-    PFN_xrEnumerateSwapchainImages enumerate =
-        (PFN_xrEnumerateSwapchainImages)lookup(active_instance, "xrEnumerateSwapchainImages");
-    PFN_xrAcquireSwapchainImage acquire = (PFN_xrAcquireSwapchainImage)lookup(active_instance, "xrAcquireSwapchainImage");
-    PFN_xrWaitSwapchainImage wait = (PFN_xrWaitSwapchainImage)lookup(active_instance, "xrWaitSwapchainImage");
-    PFN_xrReleaseSwapchainImage release = (PFN_xrReleaseSwapchainImage)lookup(active_instance, "xrReleaseSwapchainImage");
-    if (!create || !enumerate || !acquire || !wait || !release) return NULL;
-
-    pthread_mutex_lock(&flip_lock);
-    tracked_swapchain *t = find_tracked(q->subImage.swapchain, 0);
-    const XrCompositionLayerQuad *result = NULL;
-    const XrRect2Di rect = q->subImage.imageRect;
-    if (!t || !t->image_count || t->last_acquired >= t->image_count || rect.extent.width <= 0 || rect.extent.height <= 0) {
-        static int skipped;
-        if (skipped++ < 10)
-            LOG("flip: skipped quad swapchain=%p tracked=%d images=%u last=%u rect=%dx%d", (void *)(uintptr_t)q->subImage.swapchain,
-                t != NULL, t ? t->image_count : 0, t ? t->last_acquired : 0, rect.extent.width, rect.extent.height);
-        goto done;
+// A scratch image at least w x h in this format (device-local, transfer source + destination).
+static int scratch_fit(VkFormat format, uint32_t w, uint32_t h) {
+    if (vk.scratch && vk.scratch_format == format && vk.scratch_w >= w && vk.scratch_h >= h) return 1;
+    if (vk.scratch) {
+        vk.DestroyImage(vk.device, vk.scratch, NULL);
+        vk.FreeMemory(vk.device, vk.scratch_memory, NULL);
+        vk.scratch = VK_NULL_HANDLE;
+        vk.scratch_memory = VK_NULL_HANDLE;
     }
-    if (t->shadow && (t->shadow_rect.extent.width != rect.extent.width || t->shadow_rect.extent.height != rect.extent.height)) {
-        // The app changed the sub-rectangle it shows: rebuild the shadow at the new size.
-        PFN_xrDestroySwapchain destroy = (PFN_xrDestroySwapchain)lookup(active_instance, "xrDestroySwapchain");
-        forget_swapchain(t->shadow);
-        if (destroy) destroy(t->shadow);
-        t->shadow = XR_NULL_HANDLE;
+    if (vk.scratch_format == format) {  // grow, don't shrink: panels of one game come in several sizes
+        if (vk.scratch_w > w) w = vk.scratch_w;
+        if (vk.scratch_h > h) h = vk.scratch_h;
     }
-
-    if (!t->shadow) {
-        XrSwapchainCreateInfo ci = t->info;
-        ci.createFlags = 0;
-        ci.usageFlags |= XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT | XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT;
-        ci.width = (uint32_t)rect.extent.width;
-        ci.height = (uint32_t)rect.extent.height;
-        ci.arraySize = 1;
-        ci.mipCount = 1;
-        ci.faceCount = 1;
-        if (XR_FAILED(create(session, &ci, &t->shadow))) { t->shadow = XR_NULL_HANDLE; goto done; }
-        remember_swapchain(t->shadow);
-        XrSwapchainImageVulkanKHR images[MAX_IMAGES];
-        for (int i = 0; i < MAX_IMAGES; ++i) images[i] = (XrSwapchainImageVulkanKHR){XR_TYPE_SWAPCHAIN_IMAGE_VULKAN_KHR, NULL, VK_NULL_HANDLE};
-        uint32_t n = 0;
-        if (XR_FAILED(enumerate(t->shadow, MAX_IMAGES, &n, (XrSwapchainImageBaseHeader *)images))) goto done;
-        t->shadow_count = n;
-        for (uint32_t i = 0; i < n; ++i) t->shadow_images[i] = images[i].image;
-        t->shadow_rect = rect;
-        LOG("flip: created %dx%d shadow swapchain for upside-down quad", rect.extent.width, rect.extent.height);
+    VkImageCreateInfo ci = {VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, NULL, 0, VK_IMAGE_TYPE_2D, format, {w, h, 1}, 1, 1,
+                            VK_SAMPLE_COUNT_1_BIT, VK_IMAGE_TILING_OPTIMAL,
+                            VK_IMAGE_USAGE_TRANSFER_SRC_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT,
+                            VK_SHARING_MODE_EXCLUSIVE, 0, NULL, VK_IMAGE_LAYOUT_UNDEFINED};
+    if (vk.CreateImage(vk.device, &ci, NULL, &vk.scratch) != VK_SUCCESS) { vk.scratch = VK_NULL_HANDLE; return 0; }
+    VkMemoryRequirements req;
+    vk.GetImageMemoryRequirements(vk.device, vk.scratch, &req);
+    uint32_t type = UINT32_MAX;
+    for (uint32_t i = 0; i < vk.memory.memoryTypeCount && type == UINT32_MAX; ++i)
+        if ((req.memoryTypeBits & (1u << i)) &&
+            (vk.memory.memoryTypes[i].propertyFlags & VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT)) type = i;
+    for (uint32_t i = 0; i < vk.memory.memoryTypeCount && type == UINT32_MAX; ++i)
+        if (req.memoryTypeBits & (1u << i)) type = i;
+    VkMemoryAllocateInfo ai = {VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, NULL, req.size, type};
+    if (type == UINT32_MAX || vk.AllocateMemory(vk.device, &ai, NULL, &vk.scratch_memory) != VK_SUCCESS ||
+        vk.BindImageMemory(vk.device, vk.scratch, vk.scratch_memory, 0) != VK_SUCCESS) {
+        if (vk.scratch_memory) vk.FreeMemory(vk.device, vk.scratch_memory, NULL);
+        vk.DestroyImage(vk.device, vk.scratch, NULL);
+        vk.scratch = VK_NULL_HANDLE;
+        vk.scratch_memory = VK_NULL_HANDLE;
+        return 0;
     }
+    vk.scratch_format = format;
+    vk.scratch_w = w;
+    vk.scratch_h = h;
+    LOG("flip: scratch image %ux%u format %d", w, h, (int)format);
+    return 1;
+}
 
-    uint32_t index = 0;
-    XrSwapchainImageAcquireInfo ai = {XR_TYPE_SWAPCHAIN_IMAGE_ACQUIRE_INFO, NULL};
-    XrSwapchainImageWaitInfo wi = {XR_TYPE_SWAPCHAIN_IMAGE_WAIT_INFO, NULL, 100000000};
-    XrSwapchainImageReleaseInfo ri = {XR_TYPE_SWAPCHAIN_IMAGE_RELEASE_INFO, NULL};
-    if (XR_FAILED(acquire(t->shadow, &ai, &index)) || index >= t->shadow_count) goto done;
-    if (XR_FAILED(wait(t->shadow, &wi))) { release(t->shadow, &ri); goto done; }
-
-    VkImage src = t->images[t->last_acquired], dst = t->shadow_images[index];
-    uint32_t layer = q->subImage.imageArrayIndex;
+// flip_dump=N (diagnostics): the quad's rectangle as the app drew it ("raw") and as submitted after the flip
+// ("upright"), saved as files/fb_flip_<n>_<raw|upright>.ppm (8-bit RGBA formats only).
+static int dump_rect(VkImage app, uint32_t layer, XrRect2Di rect, int64_t format, int n, const char *what) {
+    int written = 0;
+    if (!*snap_dir || (format != VK_FORMAT_R8G8B8A8_SRGB && format != VK_FORMAT_R8G8B8A8_UNORM &&
+                       format != VK_FORMAT_B8G8R8A8_SRGB && format != VK_FORMAT_B8G8R8A8_UNORM)) return 0;
+    uint32_t w = (uint32_t)rect.extent.width, h = (uint32_t)rect.extent.height;
+    VkDeviceSize size = (VkDeviceSize)w * h * 4;
+    VkBufferCreateInfo bi = {VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, NULL, 0, size, VK_BUFFER_USAGE_TRANSFER_DST_BIT,
+                             VK_SHARING_MODE_EXCLUSIVE, 0, NULL};
+    VkBuffer buf = VK_NULL_HANDLE;
+    VkDeviceMemory mem = VK_NULL_HANDLE;
+    if (vk.CreateBuffer(vk.device, &bi, NULL, &buf) != VK_SUCCESS) return 0;
+    VkMemoryRequirements req;
+    vk.GetBufferMemoryRequirements(vk.device, buf, &req);
+    uint32_t type = UINT32_MAX;
+    for (uint32_t i = 0; i < vk.memory.memoryTypeCount && type == UINT32_MAX; ++i)
+        if ((req.memoryTypeBits & (1u << i)) && (vk.memory.memoryTypes[i].propertyFlags &
+            (VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT)) ==
+            (VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT)) type = i;
+    VkMemoryAllocateInfo ai = {VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, NULL, req.size, type};
+    if (type == UINT32_MAX || vk.AllocateMemory(vk.device, &ai, NULL, &mem) != VK_SUCCESS ||
+        vk.BindBufferMemory(vk.device, buf, mem, 0) != VK_SUCCESS) goto out;
     VkCommandBufferBeginInfo begin = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO, NULL,
                                       VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, NULL};
     vk.ResetCommandBuffer(vk.cmd, 0);
     vk.BeginCommandBuffer(vk.cmd, &begin);
-    barrier(src, layer, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
+    barrier(app, layer, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
+            VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT | VK_ACCESS_TRANSFER_WRITE_BIT, VK_ACCESS_TRANSFER_READ_BIT);
+    VkBufferImageCopy region = {0, 0, 0, {VK_IMAGE_ASPECT_COLOR_BIT, 0, layer, 1},
+                                {rect.offset.x, rect.offset.y, 0}, {w, h, 1}};
+    vk.CmdCopyImageToBuffer(vk.cmd, app, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, buf, 1, &region);
+    barrier(app, layer, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
+            VK_ACCESS_TRANSFER_READ_BIT, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT);
+    vk.EndCommandBuffer(vk.cmd);
+    VkSubmitInfo submit = {VK_STRUCTURE_TYPE_SUBMIT_INFO, NULL, 0, NULL, NULL, 1, &vk.cmd, 0, NULL};
+    int ok = vk.QueueSubmit(vk.queue, 1, &submit, vk.fence) == VK_SUCCESS &&
+             vk.WaitForFences(vk.device, 1, &vk.fence, VK_TRUE, 1000000000ull) == VK_SUCCESS;
+    vk.ResetFences(vk.device, 1, &vk.fence);
+    void *mapped = NULL;
+    if (!ok || vk.MapMemory(vk.device, mem, 0, size, 0, &mapped) != VK_SUCCESS) goto out;
+    const unsigned char *bytes = mapped;
+    VkDeviceSize nonzero = 0;
+    for (VkDeviceSize i = 0; i < size && !nonzero; ++i) nonzero = bytes[i];
+    char path[320];
+    snprintf(path, sizeof(path), "%s/fb_flip_%d_%s.ppm", snap_dir, n, what);
+    FILE *f = nonzero ? fopen(path, "wb") : NULL;  // (an empty panel, e.g. before its first content: not counted)
+    if (f) {
+        int bgra = format == VK_FORMAT_B8G8R8A8_SRGB || format == VK_FORMAT_B8G8R8A8_UNORM;
+        fprintf(f, "P6\n%u %u\n255\n", w, h);
+        const unsigned char *px = mapped;
+        for (VkDeviceSize i = 0; i < (VkDeviceSize)w * h; ++i) {
+            unsigned char rgb[3] = {px[i * 4 + (bgra ? 2 : 0)], px[i * 4 + 1], px[i * 4 + (bgra ? 0 : 2)]};
+            fwrite(rgb, 1, 3, f);
+        }
+        fclose(f);
+        written = 1;
+        LOG("flip_dump: wrote %s (%ux%u)", path, w, h);
+    }
+    vk.UnmapMemory(vk.device, mem);
+out:
+    if (mem) vk.FreeMemory(vk.device, mem, NULL);
+    vk.DestroyBuffer(vk.device, buf, NULL);
+    return written;
+}
+
+// Turns the quad's rectangle upside down in the app's own image, once per acquire of that image. Always returns
+// NULL: the original quad (same swapchain, same rectangle) is submitted and now shows upright.
+static const XrCompositionLayerQuad *flip_quad(XrSession session, const XrCompositionLayerQuad *q,
+                                               XrCompositionLayerQuad *out) {
+    (void)session; (void)out;
+    if (!flip_emul || runtime_has_image_layout || !wants_vertical_flip(q)) return NULL;
+    if (!vk_ready()) { static int warned; if (!warned++) LOG("flip: needed but Vulkan blitter unavailable (GLES app?)"); return NULL; }
+
+    pthread_mutex_lock(&flip_lock);
+    tracked_swapchain *t = find_tracked(q->subImage.swapchain, 0);
+    const XrRect2Di rect = q->subImage.imageRect;
+    uint32_t layer = q->subImage.imageArrayIndex, index = t ? t->last_acquired : 0;
+    if (!t || !t->image_count || index >= t->image_count || rect.extent.width <= 0 || rect.extent.height <= 0) {
+        static int skipped;
+        if (skipped++ < 10)
+            LOG("flip: skipped quad swapchain=%p tracked=%d images=%u last=%u rect=%dx%d", (void *)(uintptr_t)q->subImage.swapchain,
+                t != NULL, t ? t->image_count : 0, index, rect.extent.width, rect.extent.height);
+        goto done;
+    }
+    for (uint32_t i = 0; i < t->flipped_count[index]; ++i)
+        if (t->flipped[index][i].layer == layer && !memcmp(&t->flipped[index][i].rect, &rect, sizeof rect)) goto done;
+    if (t->flipped_count[index] >= 4) goto done;  // never seen: more than 4 quads on one image
+    if (!(t->info.usageFlags & XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT)) {  // created before the Vulkan session was known
+        static int warned;
+        if (warned++ < 5) LOG("flip: quad swapchain=%p has no transfer usage, left as it is", (void *)(uintptr_t)q->subImage.swapchain);
+        goto done;
+    }
+    uint32_t w = (uint32_t)rect.extent.width, h = (uint32_t)rect.extent.height;
+    if (!scratch_fit((VkFormat)t->info.format, w, h)) {
+        static int failed;
+        if (failed++ < 5) LOG("flip: no scratch image for %ux%u format %lld", w, h, (long long)t->info.format);
+        goto done;
+    }
+    VkImage app = t->images[index];
+    static int dumps;  // one non-empty image per quad swapchain, at most flip_dump of them
+    int dump = 0;
+    if (dumps < flip_dump && !t->dumped && dump_rect(app, layer, rect, t->info.format, dumps + 1, "raw")) {
+        dump = ++dumps;
+        t->dumped = 1;
+    }
+    VkCommandBufferBeginInfo begin = {VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO, NULL,
+                                      VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT, NULL};
+    vk.ResetCommandBuffer(vk.cmd, 0);
+    vk.BeginCommandBuffer(vk.cmd, &begin);
+    barrier(app, layer, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
             VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT, VK_ACCESS_TRANSFER_READ_BIT);
-    barrier(dst, 0, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 0, VK_ACCESS_TRANSFER_WRITE_BIT);
-    VkImageBlit blit = {
+    barrier(vk.scratch, 0, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 0, VK_ACCESS_TRANSFER_WRITE_BIT);
+    VkImageBlit down = {  // the rectangle into the scratch image, rows reversed
         {VK_IMAGE_ASPECT_COLOR_BIT, 0, layer, 1},
         {{rect.offset.x, rect.offset.y, 0}, {rect.offset.x + rect.extent.width, rect.offset.y + rect.extent.height, 1}},
         {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1},
-        {{0, rect.extent.height, 0}, {rect.extent.width, 0, 1}},  // rows reversed
+        {{0, (int32_t)h, 0}, {(int32_t)w, 0, 1}},
     };
-    vk.CmdBlitImage(vk.cmd, src, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, dst, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1,
-                    &blit, VK_FILTER_NEAREST);
-    barrier(src, layer, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
-            VK_ACCESS_TRANSFER_READ_BIT, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT);
-    barrier(dst, 0, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
+    vk.CmdBlitImage(vk.cmd, app, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, vk.scratch, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
+                    1, &down, VK_FILTER_NEAREST);
+    barrier(vk.scratch, 0, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
+            VK_ACCESS_TRANSFER_WRITE_BIT, VK_ACCESS_TRANSFER_READ_BIT);
+    barrier(app, layer, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
+            VK_ACCESS_TRANSFER_READ_BIT, VK_ACCESS_TRANSFER_WRITE_BIT);
+    VkImageBlit back = {  // and back into the app's image as it is
+        {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1},
+        {{0, 0, 0}, {(int32_t)w, (int32_t)h, 1}},
+        {VK_IMAGE_ASPECT_COLOR_BIT, 0, layer, 1},
+        {{rect.offset.x, rect.offset.y, 0}, {rect.offset.x + rect.extent.width, rect.offset.y + rect.extent.height, 1}},
+    };
+    vk.CmdBlitImage(vk.cmd, vk.scratch, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, app, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
+                    1, &back, VK_FILTER_NEAREST);
+    barrier(app, layer, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
             VK_ACCESS_TRANSFER_WRITE_BIT, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT);
     vk.EndCommandBuffer(vk.cmd);
     VkSubmitInfo submit = {VK_STRUCTURE_TYPE_SUBMIT_INFO, NULL, 0, NULL, NULL, 1, &vk.cmd, 0, NULL};
     int ok = vk.QueueSubmit(vk.queue, 1, &submit, vk.fence) == VK_SUCCESS &&
              vk.WaitForFences(vk.device, 1, &vk.fence, VK_TRUE, 100000000ull) == VK_SUCCESS;
     vk.ResetFences(vk.device, 1, &vk.fence);
-    release(t->shadow, &ri);
     if (!ok) goto done;
-
-    *out = *q;
-    out->subImage.swapchain = t->shadow;
-    out->subImage.imageArrayIndex = 0;
-    out->subImage.imageRect = (XrRect2Di){{0, 0}, rect.extent};
-    result = out;
-    static int logged;
-    if (!logged++) LOG("flip: presenting vertically flipped quad");
+    if (dump) dump_rect(app, layer, rect, t->info.format, dump, "upright");
+    t->flipped[index][t->flipped_count[index]].rect = rect;
+    t->flipped[index][t->flipped_count[index]++].layer = layer;
+    if (!t->logged++)  // once per quad swapchain
+        LOG("flip: turning quad swapchain=%p (%ux%u) upright in place", (void *)(uintptr_t)q->subImage.swapchain, w, h);
 done:
     pthread_mutex_unlock(&flip_lock);
-    return result;
+    return NULL;
 }

native/adapter/frame_adapter.c

@@ -104,6 +104,9 @@ static int fade_quad = 0;
 static uint32_t runtime_max_layers = 16;  // XrSystemGraphicsProperties::maxLayerCount (the Frame: 16)
 static int snapshot = 0;  // seconds between eye-image snapshots (snapshot_gl.c; 0 = off)
 static char snap_dir[256];
+static int gl_error_clear;  // GLES: clear GL errors the app left pending before calling the runtime (Vader)
+static int gles_session;
+static int flip_dump;  // diagnostics: save the first N flipped quads before/after the flip (flip_vk.c)
 static void snap_on_create(XrSwapchain handle, const XrSwapchainCreateInfo *info);
 static void snap_on_destroy(XrSwapchain handle);
 static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapchainImageBaseHeader *images);
@@ -176,6 +179,8 @@ static void read_settings(const char *path) {
         if (sscanf(line, "fade_quad=%f", &value) == 1) fade_quad = value > 0 ? (int)value : 0;
         if (sscanf(line, "frame_balance=%f", &value) == 1) frame_balance = value != 0;
         if (sscanf(line, "snapshot=%f", &value) == 1) snapshot = value > 0 ? (int)value : 0;
+        if (sscanf(line, "flip_dump=%f", &value) == 1) flip_dump = value > 0 ? (int)value : 0;
+        if (sscanf(line, "gl_error_clear=%f", &value) == 1) gl_error_clear = value != 0;
         if (sscanf(line, "controller_fix=%f", &value) == 1) controller_fix = value != 0;
         if (sscanf(line, "swapchain_fix=%f", &value) == 1) swapchain_fix = value != 0;
         if (sscanf(line, "cube_standin=%f", &value) == 1) cube_standin = value != 0;
@@ -256,7 +261,7 @@ static void initialize(void) {
     }
     const char *env = getenv("FRAMEBRIDGE_CONFIG");
     if (env && *env) read_settings(env);
-    if (snapshot && *process && !strchr(process, '/')) {
+    if ((snapshot || flip_dump) && *process && !strchr(process, '/')) {
         snprintf(snap_dir, sizeof(snap_dir), "/sdcard/Android/data/%s/files", process);
         LOG("per-game: snapshot every %d s to %s/fb_snap_N.ppm", snapshot, snap_dir);
     }
@@ -554,6 +559,8 @@ static void forget_swapchain(XrSwapchain handle) {
 }
 
 static void flip_on_create_swapchain(XrSwapchain handle, const XrSwapchainCreateInfo *info);
+static int flip_wants_transfer(const XrSwapchainCreateInfo *info);
+static void clear_gl_errors(const char *where);
 static void flip_on_destroy(XrSwapchain handle);
 static void emul_on_create_swapchain(XrSwapchain handle, const XrSwapchainCreateInfo *info);
 static void emul_on_destroy_swapchain(XrSwapchain handle);
@@ -636,12 +643,16 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchain(XrSession session, const XrSwap
     if(surface_native && fixed.arraySize==2 && fixed.sampleCount==1 &&
         (fixed.usageFlags&XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT))
         fixed.usageFlags |= XR_SWAPCHAIN_USAGE_TRANSFER_SRC_BIT;
+    // in-place flips of upside-down quads (flip_vk.c) blit from and back into these images
+    if (flip_wants_transfer(&fixed))
+        fixed.usageFlags |= XR_SWAPCHAIN_USAGE_TRANSFER_SRC_BIT | XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT;
     if (equirect_emul && swapchain && emul_virtual_create(session, &fixed, swapchain)) {
         remember_swapchain(*swapchain);
         emul_on_create_swapchain(*swapchain, &fixed);
         snap_on_create(*swapchain, &fixed);
         return XR_SUCCESS;
     }
+    clear_gl_errors("xrCreateSwapchain");
     XrResult result = fn(session, &fixed, swapchain);
     LOG("xrCreateSwapchain %ux%u format=%lld samples=%u array=%u faces=%u usage=0x%llx flags=0x%llx result=%d",
         fixed.width, fixed.height, (long long)fixed.format, fixed.sampleCount, fixed.arraySize, fixed.faceCount,
@@ -1096,6 +1107,35 @@ static int ask_graphics_requirements(XrInstance instance, const XrSessionCreateI
     return 0;
 }
 
+// gl_error_clear: the runtime's GL interop checks glGetError after its own GL calls and fails on any error, also one
+// the app left pending on the same context. Vader Immortal leaves GL_INVALID_OPERATION pending before its first
+// frame; the runtime then logs "SXR_GL_CHECK: error:0x502 ... glGenTextures", and from that moment allocates a new
+// command buffer every frame (CVRCompositorSharedTextures::BeginCommandBuffer, ~20 MB/s, GitHub #285).
+static void clear_gl_errors(const char *where) {
+    if (!gl_error_clear || !gles_session) return;
+    static unsigned (*get_error)(void);
+    static void *(*current_context)(void);
+    static int resolved;
+    if (!resolved) {
+        resolved = 1;
+        get_error = (unsigned (*)(void))dlsym(RTLD_DEFAULT, "glGetError");
+        current_context = (void *(*)(void))dlsym(RTLD_DEFAULT, "eglGetCurrentContext");
+        if (!get_error || !current_context) {
+            void *gl = dlopen("libGLESv2.so", RTLD_NOW | RTLD_NOLOAD), *egl = dlopen("libEGL.so", RTLD_NOW | RTLD_NOLOAD);
+            if (!get_error && gl) get_error = (unsigned (*)(void))dlsym(gl, "glGetError");
+            if (!current_context && egl) current_context = (void *(*)(void))dlsym(egl, "eglGetCurrentContext");
+        }
+        LOG("gl_error_clear: %s", get_error && current_context ? "on" : "glGetError/eglGetCurrentContext not found");
+    }
+    if (!get_error || !current_context || !current_context()) return;
+    for (int i = 0; i < 16; ++i) {
+        unsigned err = get_error();
+        if (!err) break;
+        static int logged;
+        if (logged++ < 20) LOG("gl_error_clear: cleared the app's pending GL error 0x%x before %s", err, where);
+    }
+}
+
 XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSessionCreateInfo *info, XrSession *session) {
     PFN_xrCreateSession fn = (PFN_xrCreateSession)lookup(instance, "xrCreateSession");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
@@ -1103,6 +1143,9 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateSession(XrInstance instance, const XrSess
     if (result == XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING && ask_graphics_requirements(instance, info))
         result = fn(instance, info, session);
     if (XR_SUCCEEDED(result)) {
+        gles_session = 0;
+        for (const XrBaseInStructure *b = info ? (const XrBaseInStructure *)info->next : NULL; b; b = b->next)
+            gles_session |= b->type == (XrStructureType)1000024001;  // XR_TYPE_GRAPHICS_BINDING_OPENGL_ES_ANDROID_KHR
         foveation_eye_supported = 0;
         if (foveation_eye_enabled) {
             PFN_xrGetSystemProperties properties = (PFN_xrGetSystemProperties)lookup(instance, "xrGetSystemProperties");
@@ -1496,6 +1539,7 @@ static XrTime last_begin_display_time;
 XRAPI_ATTR XrResult XRAPI_CALL xrBeginFrame(XrSession session, const XrFrameBeginInfo *info) {
     PFN_xrBeginFrame fn = (PFN_xrBeginFrame)lookup(active_instance, "xrBeginFrame");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    clear_gl_errors("xrBeginFrame");
     if (frame_open && frame_balance) {
         PFN_xrEndFrame end = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
         XrFrameEndInfo empty = {XR_TYPE_FRAME_END_INFO, NULL, last_begin_display_time ? last_begin_display_time
@@ -1520,6 +1564,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
     PFN_xrEndFrame fn = (PFN_xrEndFrame)lookup(active_instance, "xrEndFrame");
     if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
     frame_open = 0;
+    clear_gl_errors("xrEndFrame");
     __atomic_add_fetch(&frame_ends, 1, __ATOMIC_RELAXED);
     snap_end_frame(info);
     if(surface_native)++sc_serial;

native/langpack/langpack.c

@@ -300,6 +300,16 @@ static int assets_enabled(void) {
     return ((const volatile char *)g_assets_slot)[sizeof ASSETS_MARK - 1] == '1';
 }
 
+// Triage-only bypass for games blocked on Meta's unavailable asset-file service. No file paths are invented.
+#define STUB_MARK "@FPASSETSTUB@"
+__attribute__((used)) static char g_stub_slot[sizeof STUB_MARK + 1] = STUB_MARK "0";
+
+static int stub_enabled(void) {
+    const char *env = getenv("FRAMEPORT_ASSET_FILES_STUB");
+    if (env && *env) return *env == '1';
+    return ((const volatile char *)g_stub_slot)[sizeof STUB_MARK - 1] == '1';
+}
+
 static u64 hash_name(const char *name) {
     u64 h = 1469598103934665603ULL ^ 0x66;  // FNV-1a, seeded apart from the tags
     for (const char *p = name; *p; p++) {
@@ -754,6 +764,14 @@ EXPORT u64 ovr_LanguagePack_SetCurrent(const char *tag) {
 }
 
 EXPORT u64 ovr_AssetFile_GetList(void) {
+    if (stub_enabled()) {
+        msg_t *m = new_msg(MSG_ASSETFILE_GETLIST, 0);
+        if (!m) return 0;
+        u64 req = m->req;
+        fplog("AssetFile_GetList: stub, empty list");
+        post(m);
+        return req;
+    }
     u64 req = o_AssetFile_GetList();
     fplog("AssetFile_GetList (dispatcher request %llu)", (unsigned long long)req);
     if (req) {
@@ -772,6 +790,19 @@ EXPORT u64 ovr_AssetFile_GetList(void) {
 }
 
 EXPORT u64 ovr_AssetFile_StatusById(u64 id) {
+    if (stub_enabled()) {
+        msg_t *m = new_msg(MSG_ASSETFILE_STATUSBYID, 0);
+        if (!m) return 0;
+        u64 req = m->req;
+        m->has_det = 1;
+        m->det.id = id;
+        snprintf(m->det.type, sizeof m->det.type, "default");
+        snprintf(m->det.status, sizeof m->det.status, "installed");
+        snprintf(m->det.iap, sizeof m->det.iap, "free");
+        fplog("AssetFile_StatusById(%llu): stub, installed without a file", (unsigned long long)id);
+        post(m);
+        return req;
+    }
     fplog("AssetFile_StatusById(%llu)%s", (unsigned long long)id, (id >> 48) == 0x4650 ? " (ours)" : "");
     if ((id >> 48) == 0x4650) {
         pack_t packs[MAXP];

scripts/upload_bench.py

@@ -1,135 +1,415 @@
-"""Upload speed to the Frame by method (GitHub discussion #242: paramiko capped at ~23 MB/s on a reporter's PC).
+"""Compare bulk transports on one paired Frame endpoint and one destination filesystem.
 
-    uv run python scripts/upload_bench.py [--mib 512] [--host <addr>] [--methods app,paramiko-tuned,ssh,ssh-gcm,sftp]
+    uv run python scripts/upload_bench.py --mib 512 --repeat 3 --json /tmp/uploads.json
+    uv run python scripts/upload_bench.py --fast-link --remote-dir /path/on/sdcard --check-resume
 
-Methods, each sending the same random file to ~/frameport-bench on the Frame (removed afterwards):
-- app             FramePort's own upload (Frame.put: pipelined SFTP, 1 MiB writes)
-- paramiko-tuned  the same through a paramiko transport/SFTP with a 64 MiB window
-- ssh             the system's OpenSSH: `ssh … "cat > file"` (default cipher)
-- ssh-gcm         the same with aes128-gcm@openssh.com
-- ssh-chacha      the same with chacha20-poly1305@openssh.com
-- sftp            OpenSSH's sftp in batch mode
-Prints MB/s, wall time and the CPU time spent on this PC (this process + children). Dev tool, not part of the app.
+The script uses a unique scratch folder, verifies SHA-256 outside the timed
+transfer, and removes its own files afterwards. Native SCP/SFTP timings include startup; SSH streaming reports
+handshake separately. Windows-native Python and WSL must be measured separately.
+Use --methods app-files-1,app-files-2,sftp-files-1,sftp-files-2 to compare parallel file uploads.
+Both file methods accept worker counts 1, 2, 3, 4 and 8, using the same eight-file payload.
+app-files-N uses the production backend (OpenSSH preferred, Paramiko fallback); its log records the actual choice.
 """
 from __future__ import annotations
 
 import argparse
+import contextlib
+import csv
+import hashlib
+import io
+import json
 import os
+import platform
+import random
 import shutil
-import socket
 import stat
 import subprocess
 import sys
+import tarfile
 import tempfile
 import time
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
 import paramiko  # noqa: E402
 
-from frameport.frame.connection import Frame, app_key, saved_targets, ssh_dir  # noqa: E402
-
-REMOTE = "frameport-bench"
+from frameport.frame.connection import Frame, saved_targets, sh_quote, ssh_dir  # noqa: E402
 
 
-def cpu() -> float:
-    t = os.times()
-    return t.user + t.system + t.children_user + t.children_system
-
-
-def private_key() -> str:
-    """OpenSSH refuses a key file others can read (the Windows data folder under /mnt/c shows 0777): a 0600 copy."""
+@contextlib.contextmanager
+def private_key():
+    """Temporary private copy; never alter the user's pairing key/ACL."""
     key = ssh_dir() / "id_ed25519"
-    if os.name == "nt" or stat.S_IMODE(key.stat().st_mode) & 0o077 == 0:
-        return str(key)
-    tmp = Path(tempfile.mkdtemp()) / "id_ed25519"
-    shutil.copy(key, tmp)
-    tmp.chmod(0o600)
-    return str(tmp)
+    if os.name != "nt" and stat.S_IMODE(key.stat().st_mode) & 0o077 == 0:
+        yield str(key)
+        return
+    with tempfile.TemporaryDirectory(prefix="frameport-bench-key-") as directory:
+        copy = Path(directory) / "id_ed25519"
+        if os.name == "nt":
+            row = next(csv.reader(io.StringIO(subprocess.check_output(
+                ["whoami", "/user", "/fo", "csv", "/nh"], text=True))))
+            # Restrict the directory before writing the key, including under inherited Windows ACLs.
+            subprocess.run(["icacls", directory, "/inheritance:r", "/grant:r", f"*{row[-1]}:(OI)(CI)F"],
+                           check=True, stdout=subprocess.DEVNULL)
+        shutil.copyfile(key, copy)
+        if os.name == "nt":
+            # Python 3.13's chmod can add an OWNER RIGHTS ACE that Windows OpenSSH refuses.
+            subprocess.run(["icacls", str(copy), "/inheritance:r", "/remove:g", "*S-1-3-4",
+                            "/grant:r", f"*{row[-1]}:F"], check=True, stdout=subprocess.DEVNULL)
+        else:
+            copy.chmod(0o600)
+        yield str(copy)
 
 
-def ssh_base(frame: Frame, key: str, port_flag: str = "-p") -> list[str]:
-    return ["-i", key, "-o", "BatchMode=yes", "-o", "IdentitiesOnly=yes",
+def ssh_base(frame, key, port_flag="-p"):
+    return ["-i", key, "-o", "BatchMode=yes", "-o", "IdentitiesOnly=yes", "-o", "ConnectTimeout=10",
             "-o", f"UserKnownHostsFile={ssh_dir() / 'known_hosts'}", "-o", "StrictHostKeyChecking=yes",
             port_flag, str(frame.target.port)]
 
 
-def m_app(frame, local, remote, key):
-    frame.put(local, remote, resume=False)
+def cpu():
+    t = os.times()
+    return t.user + t.system + t.children_user + t.children_system
 
 
-def m_paramiko_tuned(frame, local, remote, key):
-    sock = socket.create_connection((frame.target.host, frame.target.port), timeout=10)
-    t = paramiko.Transport(sock, default_window_size=64 << 20, default_max_packet_size=32768)
+def digest(path):
+    with open(path, "rb") as source:
+        return hashlib.file_digest(source, "sha256").hexdigest()
+
+
+def sftp_quote(path):
+    """OpenSSH batch syntax, distinct from shell quoting."""
+    value = str(path)
+    if any(c in value for c in "\n\r\x00"):
+        raise ValueError("SFTP paths cannot contain newlines or NUL")
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def native(frame, key, tool="ssh"):
+    return [tool, *ssh_base(frame, key, "-p" if tool == "ssh" else "-P"),
+            f"{frame.target.user}@{frame.target.host}"]
+
+
+def stream_ssh(frame, key, command, writer, cipher=None):
+    args = native(frame, key)
+    if cipher:
+        args[1:1] = ["-c", cipher]
+    t0 = time.monotonic()
+    # Drain stderr to a file: no pipe deadlock for long-running transfers or an authentication failure.
+    with tempfile.TemporaryFile() as errors:
+        process = subprocess.Popen([*args, f"printf 'READY\\n'; {command}"], stdin=subprocess.PIPE,
+                                   stdout=subprocess.PIPE, stderr=errors)
+        try:
+            if process.stdout.readline() != b"READY\n":
+                process.wait(timeout=15)
+                errors.seek(0)
+                raise RuntimeError(errors.read().decode(errors="replace")[-1000:])
+            setup = time.monotonic() - t0
+            writer(process.stdin)
+            process.stdin.close()
+            if process.wait(timeout=60):
+                errors.seek(0)
+                raise RuntimeError(errors.read().decode(errors="replace")[-1000:])
+            return setup
+        finally:
+            if process.poll() is None:
+                process.kill()
+                process.wait()
+            process.stdout.close()
+            if not process.stdin.closed:
+                process.stdin.close()
+
+
+def send(method, frame, local, remote, key, small, large=None, logs=None):
+    """Returns measured setup seconds (None when the native tool cannot expose handshake completion)."""
+    t0 = time.monotonic()
+    if method.startswith(("app-files-", "paramiko-files-")):
+        from frameport.core.events import Reporter
+        from frameport.install.installer import upload_files
+
+        workers = int(method.rsplit("-", 1)[1])
+        with contextlib.closing(Frame(frame.target, frame.password).connect()) as transfer:
+            items = [(path, path.name, path.stat().st_size) for path in large]
+            def record(event):
+                if event.kind == "log":
+                    if logs is not None:
+                        logs.append(event.message)
+                    print(f"  {event.message}", flush=True)
+            reporter = Reporter([record])
+            upload_files(transfer, items, remote, reporter, sum(size for _, _, size in items), workers=workers,
+                         prefer_native=not method.startswith("paramiko-files-"))
+        return None  # worker handshakes overlap transfers; measure the production end-to-end operation
+    if method.startswith("sftp-files-"):
+        workers = min(int(method.rsplit("-", 1)[1]), len(large))
+        frame.run(f"mkdir -p {sh_quote(remote)}")
+        groups = [[] for _ in range(workers)]
+        for path in sorted(large, key=lambda p: p.stat().st_size, reverse=True):
+            group = min(groups, key=lambda group: sum(p.stat().st_size for p in group))
+            group.append(path)
+        def upload(group):
+            args = native(frame, key, "sftp")
+            args[-1:-1] = ["-b", "-"]
+            commands = "".join(f"put {sftp_quote(path)} {sftp_quote(remote + '/' + path.name)}\n"
+                               for path in group)
+            subprocess.run(args, input=commands.encode(), check=True, stdout=subprocess.DEVNULL, timeout=1800)
+        with ThreadPoolExecutor(max_workers=workers) as pool:
+            list(pool.map(upload, groups))
+        return None  # each worker keeps one native SFTP session for its entire batch
+    if method in ("app", "app-tar"):
+        with contextlib.closing(Frame(frame.target).connect()) as transfer:
+            setup = time.monotonic() - t0
+            if method == "app":
+                transfer.put(local, remote)
+            else:
+                transfer.put_tar([(p, p.name) for p in small], remote)
+        return setup
+    if method == "paramiko-tuned":
+        # Authenticate the same paired host key, rather than opening an unchecked raw Transport.
+        with contextlib.closing(Frame(frame.target).connect()) as transfer:
+            transport = transfer.client.get_transport()
+            with paramiko.SFTPClient.from_transport(transport, window_size=64 << 20) as client:
+                setup = time.monotonic() - t0
+                with open(local, "rb") as source, client.open(remote, "wb") as target:
+                    target.set_pipelined(True)
+                    shutil.copyfileobj(source, target, 1 << 20)
+        return setup
+    if method.startswith("ssh"):
+        cipher = {"ssh-gcm": "aes128-gcm@openssh.com", "ssh-chacha": "chacha20-poly1305@openssh.com"}.get(method)
+        if method == "ssh-tar":
+            def writer(pipe):
+                with tarfile.open(fileobj=pipe, mode="w|", format=tarfile.PAX_FORMAT) as archive:
+                    for path in small:
+                        archive.add(path, arcname=path.name, recursive=False)
+            command = f"mkdir -p {sh_quote(remote)} && tar -xf - -C {sh_quote(remote)}"
+        else:
+            def writer(pipe):
+                with open(local, "rb") as source:
+                    shutil.copyfileobj(source, pipe, 1 << 20)
+            command = f"cat > {sh_quote(remote)}"
+        return stream_ssh(frame, key, command, writer, cipher)
+    if method == "sftp":
+        args = native(frame, key, "sftp")
+        args[-1:-1] = ["-b", "-"]
+        subprocess.run(args, input=f"put {sftp_quote(local)} {sftp_quote(remote)}\n".encode(),
+                       check=True, stdout=subprocess.DEVNULL, timeout=1800)
+    elif method == "scp":
+        args = native(frame, key, "scp")
+        destination = args.pop()
+        subprocess.run([*args, str(local), f"{destination}:{remote}"], check=True, timeout=1800)
+    else:
+        raise ValueError(f"unknown method {method}")
+    return None
+
+
+METHODS = ("app", "paramiko-tuned", "ssh", "ssh-gcm", "ssh-chacha", "sftp", "scp", "app-tar", "ssh-tar",
+           "app-files-1", "app-files-2", "app-files-3", "app-files-4", "app-files-8",
+           "paramiko-files-1", "paramiko-files-2", "paramiko-files-3", "paramiko-files-4", "paramiko-files-8",
+           "sftp-files-1", "sftp-files-2", "sftp-files-3", "sftp-files-4", "sftp-files-8")
+
+
+def check_resume(frame, local, remote, key):
+    """Interrupt the app mid-upload, then resume exactly that .part with app and native SFTP reput."""
+    class Interrupted(Exception):
+        pass
+
+    results = []
+    for method in ("app", "sftp"):
+        if method == "sftp" and not shutil.which("sftp"):
+            results.append({"method": method, "skipped": "sftp unavailable"})
+            continue
+        path = remote + "-" + method
+        def interrupt(done, size):
+            if done >= size // 2:
+                raise Interrupted()
+        try:
+            frame.put(local, path, interrupt)
+        except Interrupted:
+            pass
+        offset = frame.sftp.stat(path + ".part").st_size
+        if not 0 < offset < local.stat().st_size:
+            raise RuntimeError("interrupted upload did not leave a partial file")
+        started = time.monotonic()
+        if method == "app":
+            frame.put(local, path)
+        else:
+            args = native(frame, key, "sftp")
+            args[-1:-1] = ["-b", "-"]
+            part = path + ".part"
+            commands = f"reput {sftp_quote(local)} {sftp_quote(part)}\nrename {sftp_quote(part)} {sftp_quote(path)}\n"
+            subprocess.run(args, input=commands.encode(), check=True, timeout=1800, stdout=subprocess.DEVNULL)
+        code, out, err = frame.run(f"sha256sum {sh_quote(path)}")
+        if code or out.split()[0] != digest(local):
+            raise RuntimeError(f"resume checksum mismatch: {err}")
+        results.append({"method": method, "offset": offset, "seconds": time.monotonic() - started,
+                        "sha256_ok": True, "cancelled_app": True})
+    from frameport.core.events import Cancelled, Reporter
+    from frameport.install.installer import upload_files
+
+    root = remote + "-production"
+    items = [(local, "resume.obb", local.stat().st_size)]
+    report = Reporter()
+    report.subscribe(lambda event: report.cancelled.set()
+                     if event.kind == "progress" and event.fraction >= 0.5 else None)
     try:
-        t.connect(username=frame.target.user, pkey=app_key())
-        sftp = paramiko.SFTPClient.from_transport(t, window_size=64 << 20, max_packet_size=32768)
-        with open(local, "rb") as src, sftp.open(remote, "wb") as dst:
-            dst.set_pipelined(True)
-            while chunk := src.read(4 << 20):
-                dst.write(chunk)
-    finally:
-        t.close()
+        upload_files(frame, items, root, report, local.stat().st_size, workers=1)
+    except Cancelled:
+        pass
+    offset = frame.sftp.stat(root + "/resume.obb.part").st_size
+    if not 0 < offset < local.stat().st_size:
+        raise RuntimeError("production cancellation did not leave a partial file")
+    started = time.monotonic()
+    logs = []
+    upload_files(frame, items, root, Reporter([lambda event: logs.append(event.message)
+                                             if event.kind == "log" else None]), local.stat().st_size, workers=1)
+    code, out, err = frame.run(f"sha256sum {sh_quote(root + '/resume.obb')}")
+    if code or out.split()[0] != digest(local):
+        raise RuntimeError(f"production resume checksum mismatch: {err}")
+    results.append({"method": "production", "offset": offset, "seconds": time.monotonic() - started,
+                    "sha256_ok": True, "cancelled_production": True, "logs": logs})
+    return results
 
 
-def _ssh_cat(cipher):
-    def run(frame, local, remote, key):
-        extra = ["-c", cipher] if cipher else []
-        with open(local, "rb") as src:
-            subprocess.run(["ssh", *ssh_base(frame, key), *extra, f"{frame.target.user}@{frame.target.host}",
-                            f"cat > {remote}"], stdin=src, check=True)
-    return run
-
-
-def m_sftp(frame, local, remote, key):
-    subprocess.run(["sftp", *ssh_base(frame, key, "-P"), "-b", "-", f"{frame.target.user}@{frame.target.host}"],
-                   input=f'put "{local}" "{remote}"\n'.encode(), check=True, stdout=subprocess.DEVNULL)
-
-
-METHODS = {"app": m_app, "paramiko-tuned": m_paramiko_tuned, "ssh": _ssh_cat(None),
-           "ssh-gcm": _ssh_cat("aes128-gcm@openssh.com"), "ssh-chacha": _ssh_cat("chacha20-poly1305@openssh.com"),
-           "sftp": m_sftp}
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--mib", type=int, default=512)
-    ap.add_argument("--host", help="the Frame's address (default: the remembered Frame)")
-    ap.add_argument("--methods", default="app,paramiko-tuned,ssh,ssh-gcm,ssh-chacha,sftp")
-    a = ap.parse_args()
-    target = saved_targets()[0]
-    if a.host:
-        target.host = a.host
-    frame = Frame(target).connect()
-    remote = f"{frame.home}/{REMOTE}"
-    key = private_key()
-    with tempfile.NamedTemporaryFile(delete=False) as f:
-        block = os.urandom(1 << 20)
-        for _ in range(a.mib):
-            f.write(block)
-        local = f.name
-    size = a.mib << 20
-    print(f"{a.mib} MiB to {target.host} ({sys.platform}, paramiko {paramiko.__version__})")
-    try:
-        for name in a.methods.split(","):
-            if name.startswith(("ssh", "sftp")) and not shutil.which(name.split("-")[0]):
-                print(f"{name:15} skipped: no {name.split('-')[0]} on PATH")
-                continue
-            c0, t0 = cpu(), time.monotonic()
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--mib", type=int, default=512)
+    parser.add_argument("--repeat", type=int, default=3)
+    parser.add_argument("--small-files", type=int, default=1024)
+    parser.add_argument("--host")
+    parser.add_argument("--fast-link", action="store_true")
+    parser.add_argument("--remote-dir", help="destination filesystem, default: paired user's home")
+    parser.add_argument("--methods", default=",".join(METHODS[:9]))
+    parser.add_argument("--check-resume", action="store_true")
+    parser.add_argument("--json", type=Path)
+    parser.add_argument("--probe", action="store_true", help="show reachable links and storage without transfers")
+    args = parser.parse_args()
+    methods = args.methods.split(",")
+    if args.mib < 1 or args.repeat < 1 or not 1 <= args.small_files <= 10000 or set(methods) - set(METHODS):
+        parser.error("positive size/repeat and 1–10000 small files required; methods: " + ",".join(METHODS))
+    targets = saved_targets()
+    if not targets:
+        parser.error("pair a Frame first")
+    target = targets[0]
+    if args.host:
+        target.host = args.host
+    report = {"platform": platform.platform(), "python": sys.version, "paramiko": paramiko.__version__,
+              "wsl": "microsoft" in platform.release().lower(), "methods": [], "resume": [],
+              "cpu_scope": "Python parent only on Windows; parent + child processes on POSIX"}
+    with contextlib.ExitStack() as stack:
+        control = stack.enter_context(contextlib.closing(Frame(target).connect()))
+        frame, label = control.fast_link() if args.fast_link else (control, "explicit/current endpoint")
+        if frame is not control:
+            stack.callback(frame.close)
+        report.update(host=frame.target.host, port=frame.target.port, link=label or "home/current endpoint",
+                      addresses=control.addresses())
+        _, inventory, _ = frame.run("lsblk -J -o NAME,TYPE,FSTYPE,MOUNTPOINTS")
+        _, wireless, _ = frame.run("iw dev wlan0 link 2>/dev/null")
+        report.update(storage_inventory=inventory, wireless=wireless)
+        if args.probe:
+            print(json.dumps(report, indent=2))
+            return 0
+        # One unique directory on the chosen filesystem; safely quote user-supplied locations.
+        parent = args.remote_dir or frame.home
+        code, scratch, err = frame.run(f"mktemp -d -p {sh_quote(parent)} frameport-bench.XXXXXXXX")
+        if code:
+            raise RuntimeError(err)
+        scratch = scratch.strip()
+        if not scratch or not scratch.startswith(parent.rstrip("/") + "/frameport-bench."):
+            raise RuntimeError("unexpected scratch directory")
+        stack.callback(frame.run, f"rm -rf -- {sh_quote(scratch)}")
+        _, storage, _ = frame.run(f"df -T {sh_quote(scratch)}")
+        report.update(destination=parent, storage=storage.strip())
+        key = stack.enter_context(private_key())
+        folder = Path(stack.enter_context(tempfile.TemporaryDirectory(prefix="frameport-upload-bench-")))
+        local = folder / "payload.bin"
+        # No compression-friendly repeated block: each method sends exactly the same random payload.
+        with local.open("wb") as output:
+            for _ in range(args.mib):
+                output.write(os.urandom(1 << 20))
+        expected = digest(local)
+        small_dir = folder / "small"
+        small_dir.mkdir()
+        small = []
+        with local.open("rb") as source:
+            for i in range(args.small_files):
+                path = small_dir / f"item-{i:05}.bin"
+                source.seek((i * 65536) % local.stat().st_size)
+                path.write_bytes(source.read(65536))
+                small.append(path)
+        small_hashes = {p.name: digest(p) for p in small}
+        large_dir = folder / "large"
+        large_dir.mkdir()
+        large = []
+        # Equal total bytes to the single-file trial; all worker counts send exactly these eight files.
+        with local.open("rb") as source:
+            for i in range(8):
+                path = large_dir / f"main-{i:02}.obb"
+                count = local.stat().st_size // 8 if i < 7 else local.stat().st_size - source.tell()
+                with path.open("wb") as output:
+                    remaining = count
+                    while remaining:
+                        block = source.read(min(remaining, 1 << 20))
+                        output.write(block)
+                        remaining -= len(block)
+                large.append(path)
+        large_hashes = {p.name: digest(p) for p in large}
+        print(f"{platform.system()} {'WSL' if report['wsl'] else 'native'} "
+              f"to {frame.target.host}, {parent}", flush=True)
+        rng = random.Random(0)
+        for repeat in range(args.repeat):
+            order = list(methods)
+            rng.shuffle(order)
+            for method in order:
+                row = {"method": method, "repeat": repeat + 1}
+                tool = ("ssh" if method.startswith("ssh") else "sftp" if method.startswith("sftp-files-")
+                        else method if method in ("scp", "sftp") else None)
+                if tool and not shutil.which(tool):
+                    row["skipped"] = f"no {tool} on PATH"
+                    report["methods"].append(row)
+                    continue
+                remote = f"{scratch}/{method}-{repeat}"
+                size = sum(p.stat().st_size for p in small) if method.endswith("-tar") else local.stat().st_size
+                c0, t0 = cpu(), time.monotonic()
+                try:
+                    row["logs"] = []
+                    setup = send(method, frame, local, remote, key, small, large, row["logs"])
+                    elapsed, used = time.monotonic() - t0, cpu() - c0
+                    row.update(bytes=size, total_s=elapsed, setup_s=setup, cpu_s=used,
+                               total_MB_s=size / elapsed / 1e6,
+                               payload_MB_s=size / (elapsed - setup) / 1e6 if setup is not None else None)
+                    verify_start = time.monotonic()
+                    large_trial = method.startswith(("app-files-", "paramiko-files-", "sftp-files-"))
+                    if method.endswith("-tar") or large_trial:
+                        pattern = "*.obb" if large_trial else "*.bin"
+                        _, out, _ = frame.run(f"cd {sh_quote(remote)} && sha256sum {pattern}")
+                        actual = {line.split(maxsplit=1)[1].strip(): line.split()[0] for line in out.splitlines()}
+                        verified = actual == (large_hashes if large_trial else small_hashes)
+                    else:
+                        code, out, _ = frame.run(f"sha256sum {sh_quote(remote)}")
+                        verified = code == 0 and bool(out.split()) and out.split()[0] == expected
+                    row.update(verify_s=time.monotonic() - verify_start, sha256_ok=verified)
+                    if not verified:
+                        raise RuntimeError("checksum mismatch")
+                    print(f"{repeat + 1} {method:15} {size / elapsed / 1e6:7.1f} MB/s total "
+                          f"{elapsed:6.2f}s setup={setup if setup is not None else 'included'} "
+                          f"CPU={used:.2f}s checksum=OK",
+                          flush=True)
+                except Exception as exc:
+                    row["error"] = str(exc)
+                    print(f"{method}: {exc}", flush=True)
+                report["methods"].append(row)
+                # Exclude deletion and hash verification from transfer timings and retain no previous trial files.
+                frame.run(f"rm -rf -- {sh_quote(remote)} {sh_quote(remote + '.part')}")
+        if args.check_resume:
             try:
-                METHODS[name](frame, local, remote, key)
-            except Exception as exc:  # noqa: BLE001
-                print(f"{name:15} failed: {exc}")
-                continue
-            wall, used = time.monotonic() - t0, cpu() - c0
-            got = int(frame.run(f"stat -c %s {remote}")[1].strip() or 0)
-            frame.run(f"rm -f {remote}")
-            ok = "" if got == size else f"  (size {got} != {size})"
-            print(f"{name:15} {size / wall / 1e6:7.1f} MB/s  {wall:6.1f} s  CPU here {used:5.1f} s{ok}")
-    finally:
-        os.remove(local)
-    return 0
+                report["resume"] = check_resume(frame, local, f"{scratch}/resume", key)
+            except Exception as exc:
+                report["resume"] = [{"error": str(exc)}]
+                print(f"resume check: {exc}", flush=True)
+    if args.json:
+        args.json.write_text(json.dumps(report, indent=2) + "\n")
+    return int(any(r.get("error") for r in [*report["methods"], *report["resume"]]))
 
 
 if __name__ == "__main__":

site/src/data/contributors.json

@@ -1,14 +1,14 @@
 {
- "updated": "2026-10-13",
+ "updated": "2026-10-14",
  "people": [
   {
    "login": "spoopyghosty0",
    "avatar": "https://avatars.githubusercontent.com/u/336754034?v=4",
    "url": "https://github.com/spoopyghosty0",
-   "commits": 578,
+   "commits": 603,
    "issues": 5,
    "prs": 3,
-   "total": 608
+   "total": 633
   },
   {
    "login": "Klownicle",
@@ -46,6 +46,15 @@
    "prs": 0,
    "total": 33
   },
+  {
+   "login": "UnicronNL",
+   "avatar": "https://avatars.githubusercontent.com/u/1267745?v=4",
+   "url": "https://github.com/UnicronNL",
+   "commits": 5,
+   "issues": 6,
+   "prs": 2,
+   "total": 33
+  },
   {
    "login": "Lucas-Mathieu",
    "avatar": "https://avatars.githubusercontent.com/u/184943223?v=4",
@@ -55,15 +64,6 @@
    "prs": 4,
    "total": 29
   },
-  {
-   "login": "UnicronNL",
-   "avatar": "https://avatars.githubusercontent.com/u/1267745?v=4",
-   "url": "https://github.com/UnicronNL",
-   "commits": 5,
-   "issues": 6,
-   "prs": 1,
-   "total": 28
-  },
   {
    "login": "inseend",
    "avatar": "https://avatars.githubusercontent.com/u/11666993?v=4",
@@ -145,6 +145,15 @@
    "prs": 0,
    "total": 15
   },
+  {
+   "login": "coah80",
+   "avatar": "https://avatars.githubusercontent.com/u/100182500?v=4",
+   "url": "https://github.com/coah80",
+   "commits": 0,
+   "issues": 1,
+   "prs": 2,
+   "total": 13
+  },
   {
    "login": "nickwilde77555",
    "avatar": "https://avatars.githubusercontent.com/u/180547421?v=4",
@@ -226,6 +235,15 @@
    "prs": 0,
    "total": 9
   },
+  {
+   "login": "ghost",
+   "avatar": "https://avatars.githubusercontent.com/u/10137?v=4",
+   "url": "https://github.com/ghost",
+   "commits": 0,
+   "issues": 3,
+   "prs": 0,
+   "total": 9
+  },
   {
    "login": "greggray24",
    "avatar": "https://avatars.githubusercontent.com/u/255593097?v=4",
@@ -262,6 +280,24 @@
    "prs": 0,
    "total": 9
   },
+  {
+   "login": "puppet-head",
+   "avatar": "https://avatars.githubusercontent.com/u/8073775?v=4",
+   "url": "https://github.com/puppet-head",
+   "commits": 0,
+   "issues": 3,
+   "prs": 0,
+   "total": 9
+  },
+  {
+   "login": "Tazzash",
+   "avatar": "https://avatars.githubusercontent.com/u/42785850?v=4",
+   "url": "https://github.com/Tazzash",
+   "commits": 0,
+   "issues": 3,
+   "prs": 0,
+   "total": 9
+  },
   {
    "login": "DJ3thenew23",
    "avatar": "https://avatars.githubusercontent.com/u/3744521?v=4",
@@ -289,6 +325,15 @@
    "prs": 1,
    "total": 6
   },
+  {
+   "login": "jeliastam",
+   "avatar": "https://avatars.githubusercontent.com/u/2113009?v=4",
+   "url": "https://github.com/jeliastam",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
   {
    "login": "Loafmeister",
    "avatar": "https://avatars.githubusercontent.com/u/60628625?v=4",
@@ -298,6 +343,15 @@
    "prs": 0,
    "total": 6
   },
+  {
+   "login": "marcoszaballos",
+   "avatar": "https://avatars.githubusercontent.com/u/44778619?v=4",
+   "url": "https://github.com/marcoszaballos",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
   {
    "login": "maxfvd",
    "avatar": "https://avatars.githubusercontent.com/u/337777776?v=4",
@@ -317,9 +371,9 @@
    "total": 6
   },
   {
-   "login": "puppet-head",
-   "avatar": "https://avatars.githubusercontent.com/u/8073775?v=4",
-   "url": "https://github.com/puppet-head",
+   "login": "peetzweg",
+   "avatar": "https://avatars.githubusercontent.com/u/839848?v=4",
+   "url": "https://github.com/peetzweg",
    "commits": 0,
    "issues": 2,
    "prs": 0,
@@ -343,6 +397,15 @@
    "prs": 0,
    "total": 6
   },
+  {
+   "login": "wanwanwanwano",
+   "avatar": "https://avatars.githubusercontent.com/u/341975109?v=4",
+   "url": "https://github.com/wanwanwanwano",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
   {
    "login": "yzfsoldier",
    "avatar": "https://avatars.githubusercontent.com/u/35410319?v=4",
@@ -361,6 +424,15 @@
    "prs": 1,
    "total": 5
   },
+  {
+   "login": "Agent-Gato",
+   "avatar": "https://avatars.githubusercontent.com/u/141082538?v=4",
+   "url": "https://github.com/Agent-Gato",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
   {
    "login": "Akimya49",
    "avatar": "https://avatars.githubusercontent.com/u/46827872?v=4",
@@ -406,6 +478,15 @@
    "prs": 0,
    "total": 3
   },
+  {
+   "login": "bobosand77",
+   "avatar": "https://avatars.githubusercontent.com/u/342317426?v=4",
+   "url": "https://github.com/bobosand77",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
   {
    "login": "chaseflow",
    "avatar": "https://avatars.githubusercontent.com/u/235484785?v=4",
@@ -416,9 +497,9 @@
    "total": 3
   },
   {
-   "login": "coah80",
-   "avatar": "https://avatars.githubusercontent.com/u/100182500?v=4",
-   "url": "https://github.com/coah80",
+   "login": "clockhart192",
+   "avatar": "https://avatars.githubusercontent.com/u/16326214?v=4",
+   "url": "https://github.com/clockhart192",
    "commits": 0,
    "issues": 1,
    "prs": 0,
@@ -478,6 +559,15 @@
    "prs": 0,
    "total": 3
   },
+  {
+   "login": "fazejohny",
+   "avatar": "https://avatars.githubusercontent.com/u/12040179?v=4",
+   "url": "https://github.com/fazejohny",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
   {
    "login": "felis-lynx",
    "avatar": "https://avatars.githubusercontent.com/u/106830854?v=4",
@@ -541,6 +631,15 @@
    "prs": 0,
    "total": 3
   },
+  {
+   "login": "LeaPhant",
+   "avatar": "https://avatars.githubusercontent.com/u/14080165?v=4",
+   "url": "https://github.com/LeaPhant",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
   {
    "login": "leoloopfiets",
    "avatar": "https://avatars.githubusercontent.com/u/215600281?v=4",
@@ -550,6 +649,15 @@
    "prs": 0,
    "total": 3
   },
+  {
+   "login": "LynkWyland",
+   "avatar": "https://avatars.githubusercontent.com/u/54166762?v=4",
+   "url": "https://github.com/LynkWyland",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
   {
    "login": "Mitchlett",
    "avatar": "https://avatars.githubusercontent.com/u/46537377?v=4",
@@ -568,6 +676,15 @@
    "prs": 0,
    "total": 3
   },
+  {
+   "login": "Natouille04",
+   "avatar": "https://avatars.githubusercontent.com/u/60348431?v=4",
+   "url": "https://github.com/Natouille04",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
   {
    "login": "njorbie",
    "avatar": "https://avatars.githubusercontent.com/u/340724129?v=4",
@@ -605,18 +722,18 @@
    "total": 3
   },
   {
-   "login": "TainakaRitsu",
-   "avatar": "https://avatars.githubusercontent.com/u/12560774?v=4",
-   "url": "https://github.com/TainakaRitsu",
+   "login": "SylanaZero",
+   "avatar": "https://avatars.githubusercontent.com/u/9733124?v=4",
+   "url": "https://github.com/SylanaZero",
    "commits": 0,
    "issues": 1,
    "prs": 0,
    "total": 3
   },
   {
-   "login": "Tazzash",
-   "avatar": "https://avatars.githubusercontent.com/u/42785850?v=4",
-   "url": "https://github.com/Tazzash",
+   "login": "TainakaRitsu",
+   "avatar": "https://avatars.githubusercontent.com/u/12560774?v=4",
+   "url": "https://github.com/TainakaRitsu",
    "commits": 0,
    "issues": 1,
    "prs": 0,
@@ -666,6 +783,15 @@
    "issues": 1,
    "prs": 0,
    "total": 3
+  },
+  {
+   "login": "zoomiti",
+   "avatar": "https://avatars.githubusercontent.com/u/34012653?v=4",
+   "url": "https://github.com/zoomiti",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
   }
  ]
 }

site/src/data/patches.json

@@ -74,6 +74,11 @@
   "title": "Draw fades over the picture",
   "group": "Game settings"
  },
+ "adapter.flip_dump": {
+  "anchor": "adapter-flip_dump",
+  "title": "Upside-down panel images (diagnostics)",
+  "group": "Game settings"
+ },
  "adapter.flip_emul": {
   "anchor": "adapter-flip_emul",
   "title": "Fix upside-down menus",
@@ -99,6 +104,11 @@
   "title": "Hide Quest foveation",
   "group": "Game settings"
  },
+ "adapter.gl_error_clear": {
+  "anchor": "adapter-gl_error_clear",
+  "title": "Clear the game's GL errors (GLES)",
+  "group": "Game settings"
+ },
  "adapter.gl_hide_msrtt": {
   "anchor": "adapter-gl_hide_msrtt",
   "title": "Hide fast anti-aliasing (OpenGL ES)",
@@ -379,6 +389,11 @@
   "title": "Content files from the game's data",
   "group": "Steam Frame patches"
  },
+ "frame.asset_files_stub": {
+  "anchor": "frame-asset_files_stub",
+  "title": "Asset-file service bypass",
+  "group": "Steam Frame patches"
+ },
  "frame.avatar_stub": {
   "anchor": "frame-avatar_stub",
   "title": "Skip Meta avatars",
@@ -589,6 +604,11 @@
   "title": "Unreal: start without the OBB check",
   "group": "Steam Frame patches"
  },
+ "frame.unreal_skip_obb_delivery": {
+  "anchor": "frame-unreal_skip_obb_delivery",
+  "title": "Unreal: skip the OBB delivery check",
+  "group": "Steam Frame patches"
+ },
  "frame.unreal_splash_bypass": {
   "anchor": "frame-unreal_splash_bypass",
   "title": "Unreal: bypass the stalled loading splash",

src/frameport/_version.py

@@ -1,2 +1,2 @@
 # The FramePort version: the single source (pyproject reads it via hatch; CI checks a release tag matches it).
-__version__ = "1.1.0"
+__version__ = "1.1.1"

src/frameport/analysis/detect.py

@@ -39,7 +39,8 @@ IL2CPP_METADATA = "assets/bin/Data/Managed/Metadata/global-metadata.dat"
 # 13: validate monolithic CryEngine projects/config, OBB filename formats and foveation cvar (The Climb, GitHub #238)
 # 14: bhaptics_permission (bHaptics asks for Android 12's BLUETOOTH_CONNECT: frame.bhaptics_permission, GitHub #235)
 # 15: verified xLua/LuaJIT 47-bit lightuserdata engine (frame.luajit_pointers, GitHub #257)
-ANALYSIS_VERSION = 15
+# 16: unreal_obb_delivery (Java expansionFilesDelivered gate, GitHub #283) (2026-10)
+ANALYSIS_VERSION = 16
 
 
 # Android versions by API level (for messages); the Frame's Lepton container runs Android 11 (API 30)
@@ -192,6 +193,7 @@ LAYER_EXTENSIONS = ("XR_KHR_composition_layer_cylinder", "XR_KHR_composition_lay
 
 def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Analysis:
     path = Path(path)
+    package, version, label, activity, apk_info = _read_manifest_info(path)
     with zipfile.ZipFile(path) as z:
         names = z.namelist()
         abis = sorted({n.split("/")[1] for n in names if n.startswith("lib/") and n.count("/") >= 2})
@@ -212,6 +214,9 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
                                   for d in dexes)
         # video through Android's decoders (frame.hw_video_decode): Java MediaCodec, ExoPlayer/Media3, or libVLC
         media_codec = any(m in d for d in dexes for m in MEDIA_CODEC_MARKERS) or "libvlc.so" in libs
+        from ..patches.frame.unreal_obb_check import has_delivery_check
+
+        unreal_obb_delivery = any(has_delivery_check(d, package) for d in dexes)
         del dexes
         manifest = z.read("AndroidManifest.xml")
         lib_bytes = {}
@@ -234,7 +239,6 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
         system_cfg = (z.read("assets/system.cfg").decode("utf-8", "replace")
                       if "assets/system.cfg" in names else "")
 
-    package, version, label, activity, apk_info = _read_manifest_info(path)
     libset = set(libs)
     engine = ("Unreal" if libset & {"libUE4.so", "libUnreal.so"} else "Unity" if "libunity.so" in libset
               else "CryEngine" if "libCrySystem.so" in libset or cry_project else "Other")
@@ -366,6 +370,7 @@ def analyze(path: Path, deep: bool = True, data_bytes: int | None = None) -> Ana
             "unity_split": unity_split,
             # Unreal CRC-checks the OBB before the game starts (frame.unreal_skip_obb_check, GitHub #159)
             "unreal_verify_obb": unreal_verify_obb(meta),
+            "unreal_obb_delivery": unreal_obb_delivery,
             # Unreal's Oculus module needs every OVRPlugin function it looks up (frame.unreal_ovrp_entrypoints)
             "unreal_ovrp_lookups": (ovrp_lookups(lib_bytes.get(engine_lib.rsplit("/", 1)[1], b""))
                                     if engine_lib and "libOVRPlugin.so" in libset else []),

src/frameport/analysis/linux.py

@@ -12,6 +12,7 @@ import zipfile
 from pathlib import Path
 
 from ..core.paths import user_data_dir
+from ..i18n import tr
 
 EM_AARCH64, EM_X86_64 = 183, 62
 ARCHIVES = (".zip", ".tar.gz", ".tgz", ".tar.xz", ".txz", ".tar.bz2", ".tar")
@@ -234,6 +235,10 @@ def inspect(path: Path) -> dict:
                 "vr_overlay": False, "vr_overlay_app": None, "vr_overlay_from": ""}
     programs = rank_programs(root)
     if not programs:
+        if any(p.is_file() and p.name.lower() in ("install.sh", "setup.sh")
+               for pattern in ("*", "*/*") for p in root.glob(pattern)):
+            raise ValueError(tr("This folder contains an installer without a launchable Linux program. "
+                             "FramePort runs programs, not installers. Use the project's own install instructions."))
         raise ValueError(f"no Linux program found in {path.name}")
     # an arm64 build wins; x86_64 programs only when there is nothing else (they run through FEX on the Frame)
     for want in (EM_AARCH64, EM_X86_64):

src/frameport/apk/dex.py

@@ -152,17 +152,18 @@ class Dex:
         """Make a void method return at once (see return_early)."""
         return self.return_early(code_off, "V")
 
-    def return_early(self, code_off: int, ret: str) -> bool:
+    def return_early(self, code_off: int, ret: str, *, boolean_value: bool = False) -> bool:
         """Make a method return at once: its first instruction(s) become `return-void` (ret "V"), `const/4 v0, 0;
         return v0` (ret Z/B/S/C/I: false / 0) or `const-string v0, ""; return-object v0` (ret Ljava/lang/String;: the
-        empty string, only when the dex has it), padded with nops to the next instruction boundary. The rest of the
-        code stays as it was (unreachable). False if the method already starts that way, the return type isn't
-        supported (wide, other objects) or its first instructions can't be decoded."""
+        empty string, only when the dex has it). Z can return true with boolean_value=True. Padded with nops to the
+        next instruction boundary. The rest of the code stays as it was (unreachable). False if the method already
+        starts that way, the return type isn't supported (wide, other objects) or its first instructions can't be
+        decoded."""
         regs = struct.unpack_from("<H", self.data, code_off)[0]  # registers_size: v0 must exist for a value
         if ret == "V":
             new = [RETURN_VOID]
         elif ret in ("Z", "B", "S", "C", "I") and regs:
-            new = [CONST4_V0_0, RETURN_V0]
+            new = [0x1012 if ret == "Z" and boolean_value else CONST4_V0_0, RETURN_V0]
         elif ret == "Ljava/lang/String;" and regs and self.strings_n and self.string(0) == "":
             new = [CONST_STRING_V0, 0, RETURN_OBJECT_V0]  # string ids are sorted: "" is always the first
         else:

src/frameport/cli.py

@@ -465,6 +465,7 @@ def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Op
             frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
             password: Optional[str] = typer.Option(None, help="the Frame's password (first connection only)"),
             apk_only: bool = typer.Option(False, help="reuse game data already on the Frame"),
+            force: bool = typer.Option(False, help="rebuild and reinstall even if the Frame is already current"),
             no_library: bool = typer.Option(False, help="don't add to the Steam library now"),
             to: str = typer.Option("frame", help="frame, or pc (PC VR games only: install on this PC)"),
             apk: Optional[Path] = typer.Option(None, help="install this APK instead of the last build (one game; "
@@ -479,12 +480,16 @@ def install(package: Optional[str] = typer.Argument(None), all_: bool = typer.Op
     pkgs = _pkgs(package, all_)
     if apk and len(pkgs) != 1:
         raise typer.BadParameter("--apk needs exactly one game")
+    shortcuts = []
     for pkg in pkgs:
         if not apk_only and pipeline.missing_obb(library.game(pkg) or {}):
             typer.echo(f"{pkg}: warning: " + pipeline.MISSING_OBB_NOTE.format(package=pkg), err=True)
-        pipeline.install_game(pkg, target, printing_reporter(False), apk_only, add_to_library=False, apk=apk)
-    if not no_library:
-        target.add_to_library(pkgs, printing_reporter(False))
+        result = pipeline.install_game(pkg, target, printing_reporter(False), apk_only,
+                                       add_to_library=False, apk=apk, force=force)
+        if result.get("shortcut_required", True):
+            shortcuts.append(pkg)
+    if not no_library and shortcuts:
+        target.add_to_library(shortcuts, printing_reporter(False))
 
 
 @app.command()

src/frameport/core/events.py

@@ -25,6 +25,8 @@ class Reporter:
         self._sinks = list(sinks or [])
         self._lock = threading.Lock()
         self.stage_name = ""
+        self._stage_started = time.monotonic()
+        self._stage_seconds: dict[str, float] = {}
         self.cancelled = threading.Event()
 
     def subscribe(self, sink: Callable[[Event], None]) -> None:
@@ -44,8 +46,21 @@ class Reporter:
         self.emit(Event("log", message, self.stage_name, data=data))
 
     def stage(self, name: str, message: str = "") -> None:
-        self.stage_name = name
-        self.emit(Event("stage", message or name, name))
+        now = time.monotonic()
+        previous = self.stage_name
+        elapsed = now - self._stage_started
+        if previous:
+            self._stage_seconds[previous] = self._stage_seconds.get(previous, 0.0) + elapsed
+        self.stage_name, self._stage_started = name, now
+        self.emit(Event("stage", message or name, name,
+                        data={"previous_stage": previous, "previous_stage_seconds": elapsed} if previous else {}))
+
+    def stage_timings(self) -> dict[str, float]:
+        """Completed stages plus the current stage, for install diagnostics and benchmark comparisons."""
+        result = dict(self._stage_seconds)
+        if self.stage_name:
+            result[self.stage_name] = result.get(self.stage_name, 0.0) + time.monotonic() - self._stage_started
+        return result
 
     def progress(self, fraction: float, message: str = "", **data) -> None:
         """`data` may carry `speed` (e.g. "42.1 MB/s · ~3 min left") for transfers."""

src/frameport/core/instance.py

@@ -62,10 +62,13 @@ def acquire(path: Path | None = None) -> bool:
     f.write(str(os.getpid()))
     f.flush()
     _held = f
-    import psutil
+    try:
+        import psutil
 
-    # Windows denies reading the locked byte, so another launch cannot read the PID from gui.lock itself.
-    write_atomic(_owner_file(path), json.dumps({"pid": os.getpid(), "created": psutil.Process().create_time()}))
+        # Windows denies reading the locked byte, so another launch cannot read the PID from gui.lock itself.
+        write_atomic(_owner_file(path), json.dumps({"pid": os.getpid(), "created": psutil.Process().create_time()}))
+    except Exception:  # noqa: BLE001  the lock is ours; a missing owner file only costs a later launch's recovery
+        pass
     return True
 
 

src/frameport/diag/display.py

@@ -154,10 +154,14 @@ try {
 
 
 def _recent_events() -> dict:
+    from ..updates import _powershell
+
     try:
-        result = subprocess.run(["powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
+        # Windows PowerShell 5.1 without pwsh's PSModulePath: started from pwsh 7 it can't load Get-WinEvent's module
+        exe, env = _powershell()
+        result = subprocess.run([exe, "-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
                                  _EVENT_SCRIPT], capture_output=True, encoding="utf-8", errors="replace",
-                                timeout=EVENT_TIMEOUT, creationflags=0x08000000)
+                                timeout=EVENT_TIMEOUT, creationflags=0x08000000, env=env)
         if result.returncode:
             return {"status": "error", "error": (result.stderr or "PowerShell query failed")[-512:]}
         data = json.loads(result.stdout.lstrip("\ufeff"))

src/frameport/errors.py

@@ -7,11 +7,18 @@ install queue then waits for it instead of failing every remaining job).
 from __future__ import annotations
 
 import errno
+import ssl
 import zipfile
 
 from .i18n import tr
 
 
+class MissingGameSource(ValueError):
+    def __init__(self, path, kind="APK"):
+        self.path, self.kind = path, kind
+        super().__init__(f"missing game {kind}: {path}")
+
+
 def _paramiko():
     try:
         import paramiko
@@ -46,6 +53,16 @@ def explain(exc: BaseException) -> str:
     paramiko, _ = _paramiko()
     msg = " ".join(str(exc).split()).removeprefix("[Errno None] ")
     low = msg.lower()
+    if isinstance(exc, MissingGameSource):
+        kind = {"APK": tr("APK"), "data folder": tr("data folder"), "data file": tr("data file")}.get(exc.kind, exc.kind)
+        return tr("The game's {kind} isn't at {path} any more. Add the game again from the folder that has it.") \
+            .format(kind=kind, path=exc.path)
+    if isinstance(exc, ssl.SSLCertVerificationError) or any(
+            marker in low for marker in ("certificate_verify_failed", "certificate verify failed",
+                                         "self-signed certificate", "self signed certificate")):
+        return tr("The site's HTTPS certificate couldn't be verified. Something on the network, such as antivirus "
+                  "HTTPS scanning, a proxy or a school/work network, may have replaced it. Try another network or "
+                  "turn off HTTPS scanning.")
     if type(exc).__name__ == "HostKeyChanged":
         return tr("This Frame's SSH key changed since FramePort last connected (SteamOS was reset, or another "
                   "device now has its address). If it's your Frame, choose Trust the new key on the Steam Frame "

src/frameport/frame/connection.py

@@ -541,6 +541,17 @@ class Frame:
         self._agent_digest = ""
         self._video_codec_digest = ""
 
+    def upload_session(self) -> Frame:
+        """An independent bulk-upload transport to the same authenticated headset."""
+        from dataclasses import replace
+
+        other = Frame(replace(self.target), self.password).connect()
+        if (other.client.get_transport().get_remote_server_key() !=
+                self.client.get_transport().get_remote_server_key()):
+            other.close()
+            raise paramiko.SSHException("Upload worker reached a different headset; refusing transfer")
+        return other
+
     def alive(self) -> bool:
         """The SSH connection itself still works (a failed agent command doesn't mean the Frame is gone)."""
         transport = self.client.get_transport() if self.client else None
@@ -688,18 +699,24 @@ class Frame:
             self.run("xargs -0 mkdir -p", stdin="\0".join(dirs))
 
     def put(self, local: Path, remote: str, progress=None, resume: bool = True, mkdir: bool = True,
-            attempts: int = 3) -> None:
+            attempts: int = 3, check_cancel=None) -> None:
         """Upload with resume: data goes to <remote>.part, appended from the existing size, then renamed. progress may
         raise (e.g. Cancelled): the .part stays and the next put continues from there. A failed transfer is resumed
         up to `attempts` times (Windows: an occasional OSError [Errno 22] mid-upload that the next try got past)."""
         for attempt in range(attempts):
+            if check_cancel:
+                check_cancel()
             try:
                 return self._put(Path(local), remote, progress, resume, mkdir)
             except OSError as exc:
+                if check_cancel:
+                    check_cancel()
                 if attempt == attempts - 1 or is_unreachable(exc):
                     raise
                 log.warning("upload of %s failed (%s), resuming", Path(local).name, exc)
                 time.sleep(2)
+                if check_cancel:
+                    check_cancel()
                 if not self.alive():
                     self.close()
                     self.connect()
@@ -721,6 +738,8 @@ class Frame:
             dst.set_pipelined(True)
             src.seek(offset)
             done = offset
+            if progress:
+                progress(done, size)  # gives parallel progress an exact resume baseline
             while True:
                 chunk = src.read(1 << 20)
                 if not chunk:

src/frameport/frame/monitor.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import itertools
 import json
+import math
 import posixpath
 import threading
 from collections import deque
@@ -185,6 +186,57 @@ def main_game(sample: dict | None) -> dict | None:
     return next((g for g in (sample or {}).get("games") or [] if not g.get("overlay")), None)
 
 
+SMOOTH_TAU = 1.5  # seconds: the shown numbers follow a change within ~3 s instead of jumping with every tick
+
+
+class Smoother:
+    """Exponential moving average per value, by time (the same feel at 0.1 s or 2 s intervals): the big numbers
+    stopped flickering between neighbours (71/72 fps, 18/21 %) at fast intervals. A gap of several `tau` (paused,
+    reconnected) or a missing value starts that value afresh."""
+
+    def __init__(self, tau: float = SMOOTH_TAU):
+        self.tau = tau
+        self.state: dict[str, tuple[float, float]] = {}  # key -> (value, time)
+
+    def value(self, key: str, v: float | None, t: float | None) -> float | None:
+        if v is None:
+            self.state.pop(key, None)
+            return None
+        prev = self.state.get(key)
+        if prev is None or t is None or not 0 < t - prev[1] < 4 * self.tau:
+            out = float(v)
+        else:
+            alpha = 1 - math.exp(-(t - prev[1]) / self.tau)
+            out = prev[0] + alpha * (v - prev[0])
+        self.state[key] = (out, t if t is not None else 0.0)
+        return out
+
+    def sample(self, s: dict) -> dict:
+        """A copy of the sample with the shown numbers smoothed (tiles + each game's fps/CPU/GPU, by package)."""
+        t = s.get("t")
+        out = dict(s)
+
+        def part(name, keys=None):
+            d = s.get(name)
+            if isinstance(d, dict):
+                out[name] = {**d, **{k: self.value(f"{name}.{k}", d.get(k), t) for k in (keys or d)
+                                     if isinstance(d.get(k), (int, float)) and not isinstance(d.get(k), bool)}}
+
+        part("cpu", ("total",))
+        part("gpu", ("busy",))
+        part("mem", ("avail",))
+        part("temps")
+        part("power")
+        if s.get("games"):
+            out["games"] = [{**g, **{k: self.value(f"game:{g.get('package')}.{k}", g.get(k), t)
+                                     for k in ("fps", "cpu", "gpu") if g.get(k) is not None}}
+                            for g in s["games"]]
+        return out
+
+    def clear(self) -> None:
+        self.state.clear()
+
+
 def series_of(sample: dict) -> dict[str, float | None]:
     """The values one sample adds to the History."""
     mem = sample.get("mem") or {}

src/frameport/frame/native_upload.py

@@ -0,0 +1,183 @@
+"""System OpenSSH for bulk files; the established Frame connection owns trust and progress polling."""
+from __future__ import annotations
+
+import contextlib
+import csv
+import io
+import os
+import posixpath
+import shutil
+import signal
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+from .connection import sh_quote, ssh_dir
+
+
+def quote(value) -> str:
+    value = str(value)
+    if any(c in value for c in "\r\n\x00"):
+        raise ValueError("SFTP paths cannot contain newlines or NUL")
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    for char in "*?[":
+        escaped = escaped.replace(char, "\\" + char)
+    return '"' + escaped + '"'
+
+
+def size_of(sftp, path):
+    try:
+        return sftp.stat(path).st_size
+    except FileNotFoundError:
+        return 0
+
+
+@contextlib.contextmanager
+def credentials(frame):
+    """Private temporary copies avoid modifying pairing keys, including their Windows ACLs."""
+    key_paths = [ssh_dir() / name for name in ("id_ed25519", "id_rsa") if (ssh_dir() / name).exists()]
+    if not key_paths:
+        raise OSError("no FramePort key available for OpenSSH")
+    key = frame.client.get_transport().get_remote_server_key()
+    with tempfile.TemporaryDirectory(prefix="frameport-upload-") as directory:
+        directory = Path(directory)
+        sid = None
+        if os.name == "nt":
+            row = next(csv.reader(io.StringIO(subprocess.check_output(
+                ["whoami", "/user", "/fo", "csv", "/nh"], text=True, **hidden()))))
+            sid = row[-1]
+            subprocess.run(["icacls", str(directory), "/inheritance:r", "/grant:r", f"*{sid}:(OI)(CI)F"],
+                           check=True, stdout=subprocess.DEVNULL, **hidden())
+        else:
+            directory.chmod(0o700)
+        copies = []
+        for path in key_paths:
+            copy = directory / path.name
+            shutil.copyfile(path, copy)
+            if sid:
+                subprocess.run(["icacls", str(copy), "/inheritance:r", "/remove:g", "*S-1-3-4",
+                                "/grant:r", f"*{sid}:F"], check=True, stdout=subprocess.DEVNULL, **hidden())
+            else:
+                copy.chmod(0o600)
+            copies.extend(["-i", str(copy)])
+        known = directory / "known_hosts"
+        host = frame.target.host if frame.target.port == 22 else f"[{frame.target.host}]:{frame.target.port}"
+        known.write_text(f"{host} {key.get_name()} {key.get_base64()}\n")
+        yield ["-F", os.devnull, *copies, "-o", "BatchMode=yes", "-o", "IdentitiesOnly=yes",
+               "-o", "StrictHostKeyChecking=yes", "-o", f'UserKnownHostsFile="{known.as_posix()}"',
+               "-o", f"GlobalKnownHostsFile={os.devnull}", "-o", "ConnectTimeout=10",
+               "-o", "ServerAliveInterval=10", "-o", "ServerAliveCountMax=3",
+               "-P", str(frame.target.port)]
+
+
+def hidden():
+    return {"creationflags": subprocess.CREATE_NO_WINDOW} if os.name == "nt" else {}
+
+
+def stop_process(process):
+    """SFTP starts an ssh child: stop the entire owned process group before resuming with another backend."""
+    if process.poll() is None:
+        if os.name == "nt":
+            subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=10, **hidden())
+            if process.poll() is None:
+                process.kill()
+        else:
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+    process.wait()
+
+
+def upload(frame, items, remote_root, reporter, total, sent, workers):
+    """One persistent SFTP batch per worker. A failure leaves .part files for Paramiko to resume.
+
+    Only successful batches are promoted, after every process has exited successfully. All control operations
+    happen in the supervising thread, so Paramiko's SFTP client is never shared across threads.
+    """
+    executable = shutil.which("sftp")
+    if not executable:
+        raise OSError("system OpenSSH SFTP is unavailable")
+    from ..install.installer import Speed
+
+    reporter.check_cancel()
+    if not items:
+        return sent
+    groups = [[] for _ in range(min(workers, len(items)))]
+    sizes, offsets, progress = {}, {}, {}
+    for path, rel, size in sorted(items, key=lambda item: item[2], reverse=True):
+        remote = posixpath.join(remote_root, rel)
+        quote(path)
+        quote(remote)
+        offset = size_of(frame.sftp, remote + ".part")
+        if offset > size:
+            frame.sftp.remove(remote + ".part")
+            offset = 0
+        offsets[rel] = progress[rel] = offset
+        sizes[rel] = size
+        if offset == size:
+            continue  # complete from an earlier attempt (sftp's reput refuses a target of the same size): rename only
+        group = min(groups, key=lambda group: sum(item[2] for item in group))
+        group.append((path, rel, size))
+    groups = [group for group in groups if group]
+    speed = Speed(total - sent - sum(offsets.values()))
+    reporter.log(f"uploading large files with OpenSSH SFTP ({len(groups)} workers)")
+    setup_started = time.monotonic()
+    with credentials(frame) as args, contextlib.ExitStack() as stack:
+        monitor = stack.enter_context(frame.client.open_sftp())
+        monitor.get_channel().settimeout(2)
+        reporter.log(f"OpenSSH credentials and progress connection ready in {time.monotonic() - setup_started:.2f}s")
+        processes = []
+        try:
+            for group in groups:
+                reporter.check_cancel()
+                batch = stack.enter_context(tempfile.TemporaryFile())
+                for path, rel, _ in group:
+                    remote = posixpath.join(remote_root, rel) + ".part"
+                    command = "reput" if offsets[rel] else "put"
+                    batch.write(f"{command} {quote(path)} {quote(remote)}\n".encode())
+                batch.seek(0)
+                errors = stack.enter_context(tempfile.TemporaryFile())
+                process = subprocess.Popen([executable, *args, "-b", "-",
+                                            f"{frame.target.user}@{frame.target.host}"], stdin=batch,
+                                           stdout=subprocess.DEVNULL, stderr=errors,
+                                           **(hidden() if os.name == "nt" else {"start_new_session": True}))
+                processes.append((process, errors))
+            while True:
+                reporter.check_cancel()
+                for process, errors in processes:
+                    if process.poll() not in (None, 0):
+                        errors.seek(0)
+                        detail = errors.read().decode(errors="replace")[-1500:]
+                        raise OSError(f"OpenSSH SFTP failed ({process.returncode}): {detail}")
+                for rel, size in sizes.items():
+                    reporter.check_cancel()
+                    progress[rel] = max(progress[rel], min(size, size_of(
+                        monitor, posixpath.join(remote_root, rel) + ".part")))
+                done = sum(progress.values())
+                reporter.progress((sent + done) / max(total, 1),
+                                  f"{len(items)} files · {done / 2**20:.0f}/{sum(sizes.values()) / 2**20:.0f} MiB",
+                                  speed=speed.text(done - sum(offsets.values())))
+                if all(process.poll() == 0 for process, _ in processes):
+                    break
+                time.sleep(0.2)
+            for _, rel, size in items:
+                reporter.check_cancel()
+                remote = posixpath.join(remote_root, rel)
+                if size_of(monitor, remote + ".part") != size:
+                    raise OSError(f"OpenSSH upload has an unexpected size: {rel}")
+            for start in range(0, len(items), 100):
+                reporter.check_cancel()
+                commands = []
+                for _, rel, _ in items[start:start + 100]:
+                    remote = posixpath.join(remote_root, rel)
+                    commands.append(f"mv -f -- {sh_quote(remote + '.part')} {sh_quote(remote)}")
+                code, _, error = frame.run(" && ".join(commands))
+                if code:
+                    raise OSError(f"cannot finalize OpenSSH upload: {error}")
+        finally:
+            for process, _ in processes:
+                stop_process(process)
+    return sent + sum(size for _, _, size in items)

src/frameport/game_update.py

@@ -0,0 +1,106 @@
+"""Pure Quest update decisions shared by the pipeline and UI (no filesystem or network I/O)."""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+
+from .patches import base, upstream
+
+
+def fingerprint(value) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, default=str).encode()).hexdigest()[:32]
+
+
+# These settings select APK support as well as runtime behaviour. Keep their revisions too: a newer shim can
+# be needed even though the value did not change. Foveation remains an APK patch, including all its parameters.
+APK_SETTINGS = {"adapter.haptic_fix", "adapter.controller_models", "adapter.surface_native",
+                "adapter.zink_shader_fix", "adapter.zink_shader_dump"}
+
+
+def apk_recipe_fingerprint(recipe: dict, package: str = "", superseded=None) -> str:
+    base.load_all()
+    patches = upstream.without_superseded(recipe.get("patches") or {}, superseded)
+    selected = {}
+    for pid, params in patches.items():
+        patch = base.REGISTRY.get(pid)
+        if patch is None or patch.stage != "install" or pid in APK_SETTINGS:
+            selected[pid] = params
+        elif patch.category == "adapter" and patch.revision_for(package) != 1:
+            # Adapter revisions also track changes to the native code implementing a setting.
+            selected[pid] = {"revision": patch.revision_for(package)}
+    if recipe.get("as_is"):
+        return base.recipe_fingerprint({"as_is": True, "overport": False}, package)
+    return base.recipe_fingerprint({**recipe, "patches": selected, "use_alt": False}, package)
+
+
+def configuration(recipe: dict, package: str = "", superseded=None) -> dict:
+    from .patches.settings import BASE_SETTINGS, SETTINGS, adapter_settings
+
+    patches = upstream.without_superseded(recipe.get("patches") or {}, superseded)
+    # Explicit defaults override settings embedded in an older APK when a recipe removes an override.
+    settings = {key: default for key, _, default, *_ in SETTINGS}
+    settings.update(BASE_SETTINGS)
+    settings.update(adapter_settings(patches))
+    install = {pid: {"params": params or {}, "revision": base.get(pid).revision_for(package)}
+               for pid, params in patches.items() if base.get(pid).stage == "install" and
+               base.get(pid).category != "adapter"}
+    return {"settings": settings, "patches": install}
+
+
+def configuration_fingerprint(recipe: dict, package: str = "", superseded=None) -> str:
+    return fingerprint(configuration(recipe, package, superseded))
+
+
+@dataclass(frozen=True)
+class UpdatePlan:
+    rebuild: bool = False
+    apk: bool = False
+    data: bool = False
+    configure: bool = False
+    artwork: bool = False
+    shortcut: bool = False
+    reasons: tuple[str, ...] = ()
+
+    @property
+    def changed(self) -> bool:
+        return any((self.rebuild, self.apk, self.data, self.configure, self.artwork, self.shortcut))
+
+    @property
+    def launch_test(self) -> bool:
+        return self.rebuild or self.apk or self.data
+
+
+def plan_update(game: dict, deployment: dict | None, *, apk_only: bool = False,
+                data_manifest: dict | None = None) -> UpdatePlan:
+    """Unknown legacy identities use the full path once. Catalog metadata never affects these identities."""
+    recipe, build = game.get("recipe") or {}, game.get("build") or {}
+    package = game.get("package", "")
+    dep = deployment or {}
+    missing = not dep or dep.get("apk_present") is False
+    current = apk_recipe_fingerprint(recipe, package, build.get("superseded"))
+    rebuild = not build.get("ok", True) or not build.get("apk_recipe_fp") or build["apk_recipe_fp"] != current
+    if build.get("source_version") != (game.get("analysis") or {}).get("version"):
+        rebuild = True
+    if game.get("source_sha256") and build.get("source_sha256") != game["source_sha256"]:
+        rebuild = True
+    if recipe.get("use_alt") and not build.get("alt_sha256"):
+        rebuild = True
+    sha = build.get("alt_sha256") if recipe.get("use_alt") else build.get("sha256")
+    apk = missing or rebuild or not sha or dep.get("sha256") != sha
+    configure = apk or dep.get("configuration_fp") != configuration_fingerprint(
+        recipe, package, build.get("superseded"))
+    if data_manifest is None:
+        data_manifest = game.get("data_manifest")
+    data = False
+    if not apk_only and data_manifest:
+        if "data_manifest" in dep:
+            data = any(dep["data_manifest"].get(k) != v for k, v in data_manifest.items())
+        else:
+            data = fingerprint(data_manifest) != dep.get("data_fp")
+    artwork = missing or bool(game.get("steam_art_stale"))
+    shortcut = missing or bool(game.get("steam_name_stale")) or artwork
+    reasons = tuple(name for name, needed in (("APK build inputs changed or unrecorded", rebuild),
+                    ("APK differs", apk), ("Game data differs", data), ("Runtime configuration differs", configure),
+                    ("Artwork differs", artwork), ("Steam entry differs", shortcut)) if needed)
+    return UpdatePlan(rebuild, apk, data, configure, artwork, shortcut, reasons)

src/frameport/install/installer.py

@@ -3,13 +3,15 @@ from __future__ import annotations
 
 import contextlib
 import posixpath
+import threading
 import time
+from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
 from dataclasses import dataclass
 from pathlib import Path
 
 from ..artwork import fetch as artwork
 from ..build import sha256
-from ..core.events import Reporter
+from ..core.events import Cancelled, Reporter
 from ..core.models import Recipe, data_manifest
 from ..frame.connection import Frame, sh_quote
 from ..patches import base
@@ -39,6 +41,56 @@ def install_context(recipe: Recipe) -> base.InstallContext:
     return ctx
 
 
+def configuration_args(entry: dict, recipe: Recipe) -> dict:
+    """One complete configuration for both an APK install and the configuration-only path."""
+    from ..game_update import configuration, configuration_fingerprint
+
+    ctx = install_context(recipe)
+    original = entry["recipe"]
+    build = entry.get("build") or {}
+    applied = configuration(original, recipe.package, build.get("superseded"))
+    settings = applied["settings"]
+    return dict(settings=settings, files={k: v.decode() if isinstance(v, bytes) else v
+                                        for k, v in ctx.files.items()}, env=ctx.env,
+                flatscreen=show_window(ctx, _flatscreen(recipe.package)), config_sync=ctx.config_sync,
+                recipe={"patches": sorted(recipe.patches), "source": recipe.source, "alt": recipe.use_alt},
+                configuration=applied,
+                configuration_fp=configuration_fingerprint(original, recipe.package, build.get("superseded")),
+                apk_recipe_fp=build.get("apk_recipe_fp"), source_version=build.get("source_version"))
+
+
+def update_existing(frame: Frame, entry: dict, deployment: dict, plan, recipe: Recipe,
+                    reporter: Reporter, manifest: dict | None = None) -> dict:
+    """No local converted APK is needed for runtime/data updates to a matching deployed build."""
+    args = configuration_args(entry, recipe)
+    # the library's current Steam tags (user tags, genres): the shortcut check after this update writes them
+    args.update(package=entry["package"], title=entry.get("title") or entry["package"],
+                apk_sha256=deployment["sha256"], tags=_tags(entry["package"]))
+    if plan.data:
+        reporter.stage("Check game data")
+        prep = frame.agent("prepare", package=entry["package"], title=args["title"])
+        manifest = manifest or {}
+        pending = [(Path(entry["data_dir"]) / rel, f"obb/{rel}", size)
+                   for rel, size in manifest.items() if prep["existing_obb"].get(rel) != size]
+        need = sum(size for _, _, size in pending)
+        if need > prep["free_bytes"] - (1 << 30):
+            raise RuntimeError("not enough space on the Frame for the changed game data + 1 GiB headroom")
+        with transfer_link(frame, reporter, need) as xfer:
+            if pending:
+                reporter.stage("Upload changed game data")
+                upload_files(xfer, pending, prep["incoming"], reporter, max(need, 1))
+        args.update(obb_manifest=manifest, existing_only=True, consume_artwork=False,
+                    apk_name=deployment.get("apk", "game.apk"))
+        reporter.stage("Finalize game data")
+        return frame.agent("finalize", **args)
+    reporter.stage("Apply game configuration")
+    result = frame.agent("configure", **args)
+    if result.get("deployment", {}).get("configuration_fp") != args["configuration_fp"]:
+        raise RuntimeError("the Frame did not confirm the applied configuration")
+    reporter.check("Game configuration", True, "applied; used from the game's next start")
+    return result
+
+
 def local_data_manifest(data_dir: Path | None, files: list[str] | None = None) -> dict[str, int]:
     return data_manifest(data_dir, files)
 
@@ -66,6 +118,9 @@ class Speed:
 
 
 def install(frame: Frame, plan: InstallPlan, reporter: Reporter) -> dict:
+    from ..core import library
+
+    entry = library.game(plan.package)
     reporter.stage("Prepare Frame")
     apk_sha = sha256(plan.apk)
     prep = frame.agent("prepare", package=plan.package, title=plan.title, dest=plan.dest,
@@ -93,7 +148,10 @@ def install(frame: Frame, plan: InstallPlan, reporter: Reporter) -> dict:
                 reporter.check_cancel()
                 reporter.progress(done / total, f"APK {done / 2**20:.0f}/{size / 2**20:.0f} MiB",
                                   speed=speed.text(done))
-            xfer.put(plan.apk, posixpath.join(incoming, "game.apk"), apk_cb)
+            if plan.apk.stat().st_size >= BIG_FILE:
+                upload_files(xfer, [(plan.apk, "game.apk", plan.apk.stat().st_size)], incoming, reporter, total)
+            else:
+                xfer.put(plan.apk, posixpath.join(incoming, "game.apk"), apk_cb)
             sent += plan.apk.stat().st_size
         if to_send:
             reporter.stage(f"Upload data ({len(to_send)} files)")
@@ -102,19 +160,25 @@ def install(frame: Frame, plan: InstallPlan, reporter: Reporter) -> dict:
         elif manifest:
             reporter.log("game data already on the Frame; not re-sending")
 
-    artwork.fetch(plan.package, plan.apk)
-    upload_steam_art(frame, plan.package, prep["base"], reporter)
+    artwork_manifest = None
+    if not prep.get("installed") or (entry or {}).get("steam_art_stale"):
+        artwork.fetch(plan.package, plan.apk)
+        artwork_manifest = upload_steam_art(frame, plan.package, prep["base"], reporter)
 
     reporter.stage("Finalize install")
     ctx = install_context(plan.recipe)
+    config = configuration_args(entry, plan.recipe) if entry else dict(
+        settings=ctx.adapter_settings, files={k: v.decode() if isinstance(v, bytes) else v
+                                            for k, v in ctx.files.items()}, env=ctx.env,
+        flatscreen=show_window(ctx, _flatscreen(plan.package)), config_sync=ctx.config_sync or None,
+        recipe={"patches": sorted(plan.recipe.patches), "source": plan.recipe.source, "alt": plan.recipe.use_alt})
+    if artwork_manifest is not None:
+        config["artwork_manifest"] = artwork_manifest
     result = frame.agent(
         "finalize", package=plan.package, title=plan.title, dest=plan.dest, apk_sha256=apk_sha,
         tags=_tags(plan.package),
-        apk_name=plan.apk.name, settings=ctx.adapter_settings,
-        files={k: v.decode() if isinstance(v, bytes) else v for k, v in ctx.files.items()}, env=ctx.env,
-        obb_manifest=manifest or None, flatscreen=show_window(ctx, _flatscreen(plan.package)),
-        config_sync=ctx.config_sync or None,
-        recipe={"patches": sorted(plan.recipe.patches), "source": plan.recipe.source, "alt": plan.recipe.use_alt},
+        apk_name=plan.apk.name, obb_manifest=manifest if not plan.apk_only else None,
+        preserve_data=plan.apk_only, consume_artwork=artwork_manifest is not None, **config,
     )
     reporter.log(f"installed at {result['base']} (Steam shortcut id {result['appid']})")
     log_controller_models(result.get("controller_models"), reporter)
@@ -356,10 +420,102 @@ def ensure_proton(frame: Frame, reporter: Reporter, tool: str | None = None, tim
     raise RuntimeError(f"{name} didn't finish installing on the Frame in time; check Steam's downloads on the Frame")
 
 
-BIG_FILE = 8 << 20  # bigger files go one by one (resumable); smaller ones are streamed in batches
+BIG_FILE = 8 << 20  # bigger files use resumable SFTP; smaller ones are streamed in batches
 BATCH_BYTES, BATCH_FILES = 256 << 20, 2000
 
 
+def upload_threads(value=None) -> int:
+    """Bound the saved preference; the one-job FIFO still bounds concurrent installs."""
+    from ..core import library
+
+    if value is None:
+        value = library.setting("install.upload_threads", 3)
+    try:
+        return max(1, min(8, int(value)))
+    except (TypeError, ValueError, OverflowError):
+        return 3
+
+
+def _upload_parallel(frame, items, remote_root, reporter, total, sent, workers):
+    """Each worker owns one transport; failures stop the cohort and leave resumable .part files."""
+    lock, stop, local = threading.Lock(), threading.Event(), threading.local()
+    sessions, errors, progress, offsets = [], [], {}, {}
+    speed = Speed(total - sent)
+
+    def upload(item):
+        path, rel, size = item
+        try:
+            reporter.check_cancel()
+            if stop.is_set():
+                raise Cancelled()
+            if not hasattr(local, "frame"):
+                session = frame.upload_session()
+                with lock:
+                    sessions.append(session)
+                if stop.is_set():
+                    session.close()
+                    raise Cancelled()
+                local.frame = session
+
+            def show(done, size):
+                reporter.check_cancel()
+                if stop.is_set():
+                    raise Cancelled()
+                with lock:
+                    offsets.setdefault(rel, done)
+                    progress[rel] = max(progress.get(rel, 0), done)
+                    completed = sum(progress.values())
+                    resumed = sum(offsets.values())
+                    speed.total = total - sent - resumed
+                    reporter.progress((sent + completed) / max(total, 1),
+                                      f"{rel} {done / 2**20:.0f}/{size / 2**20:.0f} MiB",
+                                      speed=speed.text(completed - resumed))
+            def check_cancel():
+                reporter.check_cancel()
+                if stop.is_set():
+                    raise Cancelled()
+            local.frame.put(path, posixpath.join(remote_root, rel), show, mkdir=False, check_cancel=check_cancel)
+        except Exception as exc:
+            with lock:
+                if not errors:
+                    errors.append(exc)
+            stop.set()
+            raise
+
+    try:
+        with ThreadPoolExecutor(max_workers=workers, thread_name_prefix="frameport-upload") as pool:
+            pending = {pool.submit(upload, item) for item in items}
+            interrupted = False
+            while pending:
+                if reporter.cancelled.is_set():
+                    with lock:
+                        if not errors:
+                            errors.append(Cancelled())
+                    stop.set()
+                done, pending = wait(pending, timeout=0.2, return_when=FIRST_COMPLETED)
+                for future in done:
+                    if not future.cancelled():
+                        try:
+                            future.result()
+                        except Exception:
+                            stop.set()
+                if stop.is_set() and not interrupted:
+                    interrupted = True
+                    for future in pending:
+                        future.cancel()
+                    pending = {future for future in pending if not future.cancelled()}
+                    with lock:
+                        active = list(sessions)
+                    for session in active:
+                        session.close()  # interrupt blocked transfers; never close the control connection
+            if errors:
+                raise errors[0]
+    finally:
+        for session in sessions:
+            session.close()
+    return sent + sum(size for _, _, size in items)
+
+
 FAST_LINK_MIN = 64 << 20  # below this a second connection isn't worth it
 
 
@@ -384,12 +540,14 @@ def transfer_link(frame: Frame, reporter: Reporter, need: int):
 
 
 def upload_files(frame: Frame, items: list[tuple[Path, str, int]], remote_root: str, reporter: Reporter,
-                 total: int, sent: int = 0, speed: Speed | None = None) -> int:
+                 total: int, sent: int = 0, speed: Speed | None = None, workers: int | None = None,
+                 prefer_native: bool = True) -> int:
     """Upload (local, relative path, size) items under remote_root. Interruptible (Cancel, dropped connection) and
     resumable: finished files are skipped next time (the agent counts files already in incoming/), a cut-off big file
     continues from its .part. Returns bytes sent."""
-    big = [i for i in items if i[2] >= BIG_FILE]
+    big = sorted((i for i in items if i[2] >= BIG_FILE), key=lambda item: item[2], reverse=True)
     small = [i for i in items if i[2] < BIG_FILE]
+    reporter.check_cancel()
     frame.mkdirs(posixpath.dirname(posixpath.join(remote_root, rel)) for _, rel, _ in big)
     state = {"sent": sent}
     speed = speed or Speed(total)
@@ -398,12 +556,45 @@ def upload_files(frame: Frame, items: list[tuple[Path, str, int]], remote_root:
         reporter.check_cancel()
         done = state["sent"] + extra
         reporter.progress(done / total, label, speed=speed.text(done))
-    for local, rel, size in big:
-        reporter.check_cancel()
-        frame.put(local, posixpath.join(remote_root, rel),
-                  lambda done, size, rel=rel: show(done, f"{rel} {done / 2**20:.0f}/{size / 2**20:.0f} MiB"),
-                  mkdir=False)
-        state["sent"] += size
+    threads = min(upload_threads(workers), len(big))
+    native_done = False
+    if big and prefer_native and isinstance(frame, Frame):
+        from ..frame import native_upload
+
+        original = reporter
+        class ProgressReporter:
+            last = 0.0
+
+            def __getattr__(self, name):
+                return getattr(original, name)
+
+            def progress(self, fraction, label, **kwargs):
+                self.last = max(self.last, fraction)
+                original.progress(self.last, label, **kwargs)
+
+        reporter = ProgressReporter()  # fallback resumes in a different order; never move the progress bar backward
+        try:
+            state["sent"] = native_upload.upload(frame, big, remote_root, reporter, total, sent, max(threads, 1))
+            native_done = True
+        except Cancelled:
+            raise
+        except Exception as exc:  # native startup, authentication or transfer failure: retain the portable path
+            reporter.check_cancel()
+            reporter.log(f"OpenSSH unavailable or failed; resuming with Paramiko: {exc}")
+        speed.samples.clear()
+    if native_done:
+        pass
+    elif threads > 1 and hasattr(frame, "upload_session"):
+        reporter.log(f"uploading large files with {threads} workers")
+        state["sent"] = _upload_parallel(frame, big, remote_root, reporter, total, sent, threads)
+        speed.samples.clear()
+    else:
+        for local, rel, size in big:
+            reporter.check_cancel()
+            frame.put(local, posixpath.join(remote_root, rel),
+                      lambda done, size, rel=rel: show(done, f"{rel} {done / 2**20:.0f}/{size / 2**20:.0f} MiB"),
+                      mkdir=False)
+            state["sent"] += size
     batch: list[tuple[Path, str]] = []
     batch_bytes = 0
 
@@ -455,7 +646,16 @@ def _flatscreen(package: str) -> bool:
     return bool(g.get("analysis")) and library.analysis_from_dict(g["analysis"]).vr_kind == "none"
 
 
-def upload_steam_art(frame: Frame, package: str, base: str, reporter: Reporter) -> None:
+def art_manifest(package: str, art: dict) -> dict[str, str]:
+    import hashlib
+
+    from ..artwork.sources import icon_source
+
+    return {**{f"{kind}{path.suffix}": sha256(path) for kind, path in art.items()},
+            ".icon-source": hashlib.sha256(icon_source(package).encode()).hexdigest()}
+
+
+def upload_steam_art(frame: Frame, package: str, base: str, reporter: Reporter) -> dict[str, str]:
     """The complete Steam art set (portrait, wide, hero, logo, icon — composed where the store has no such shape)."""
     from ..artwork.steam import steam_set_for
 
@@ -467,6 +667,7 @@ def upload_steam_art(frame: Frame, package: str, base: str, reporter: Reporter)
         frame.put(f, posixpath.join(remote_art, f"{kind}{f.suffix}"), resume=False)
     send_icon_source(frame, package, remote_art)
     reporter.check("Steam artwork", bool(art) or None, ", ".join(sorted(art)) or "none found")
+    return art_manifest(package, art)
 
 
 def send_icon_source(frame: Frame, package: str, remote_art: str) -> None:
@@ -509,7 +710,8 @@ def update_steam_art(frame: Frame, package: str, reporter: Reporter, title: str
     """Replace an installed game's Steam library art with the current artwork (after the user picked new art):
     the art set goes to the game's anchor, then the shortcut is rewritten (Steam restarts once). `title`: the game's
     name in the library; a different name on the Frame is renamed first (agent v77 `rename`: the shortcut keeps its
-    appid, so Play, grid art and saves stay). Placeholder art shows the name, so it's sent again too."""
+    appid, so Play, grid art and saves stay). Placeholder art shows the name, so it's sent again too.
+    The result has `library: True` when the shortcut was rewritten too (else the caller still checks it)."""
     from ..artwork.steam import steam_set_for
 
     dep = next((d for d in frame.agent("list_installed")["games"] if d.get("package") == package), None)
@@ -526,16 +728,33 @@ def update_steam_art(frame: Frame, package: str, reporter: Reporter, title: str
     art = steam_set_for(package)
     if not art:
         if renamed:
-            return add_to_steam(frame, [package], reporter)
+            return {**(add_to_steam(frame, [package], reporter) or {}), "library": True}
         raise RuntimeError("no artwork to send")
+    manifest = art_manifest(package, art)
+    previous = dep.get("artwork_manifest") or {}
+    if manifest == previous:
+        reporter.log("Steam artwork already current; not re-sending")
+        return {**(add_to_steam(frame, [package], reporter) or {}), "library": True} if renamed else {"unchanged": True}
     reporter.stage("Artwork for the Steam library")
     remote = posixpath.join(dep["anchor"], "artwork")
-    frame.run(f"rm -rf {sh_quote(remote)} && mkdir -p {sh_quote(remote)}")
+    if not previous:
+        # Unrecorded art (installs before agent v86): what's in the folder is unknown, and an old portrait.jpg next
+        # to a new portrait.png would be picked at random for the Steam grid. Start clean as before; all is sent.
+        frame.run(f"rm -rf -- {sh_quote(remote)}")
+    frame.run(f"mkdir -p {sh_quote(remote)}")
+    for name in previous.keys() - manifest.keys():
+        # Deployment records are data, not shell paths. Never act on an unexpected name.
+        if "/" not in name and name not in (".", ".."):
+            frame.run(f"rm -f -- {sh_quote(posixpath.join(remote, name))}")
     for kind, f in art.items():
-        frame.put(f, posixpath.join(remote, f"{kind}{f.suffix}"), resume=False)
-    send_icon_source(frame, package, remote)
+        name = f"{kind}{f.suffix}"
+        if previous.get(name) != manifest[name]:
+            frame.put(f, posixpath.join(remote, name), resume=False)
+    if previous.get(".icon-source") != manifest[".icon-source"]:
+        send_icon_source(frame, package, remote)
+    frame.agent("record_artwork", package=package, manifest=manifest)
     reporter.check("Steam artwork", True, ", ".join(sorted(art)))
-    return add_to_steam(frame, [package], reporter)
+    return {**(add_to_steam(frame, [package], reporter) or {}), "library": True}
 
 
 def add_to_steam(frame: Frame, packages: list[str], reporter: Reporter, wait: float = 120) -> dict:

src/frameport/locales/template.json

@@ -184,6 +184,7 @@
  "Assassin's Creed Nexus (build 207706 only): turns off application space warp and runs at 90 Hz.": "",
  "Assassin's Creed Nexus: smoother picture at 72 Hz (turns off Meta's frame-rate trick).": "",
  "Assassin's Creed Nexus: smoother picture at 90 Hz (turns off Meta's frame-rate trick).": "",
+ "Asset-file service bypass": "",
  "At most this many redraws per second of a 360° layer (0 = no limit). Video players need at least the video's frame rate.": "",
  "Automatic": "",
  "Automatic ({auto:.0%})": "",
@@ -254,6 +255,8 @@
  "Clear search": "",
  "Clear selection": "",
  "Clear tags": "",
+ "Clear the game's GL errors (GLES)": "",
+ "Clears OpenGL errors the game left pending before FrameBridge calls the Frame's runtime. The runtime's GL code fails on any pending error; after one such failure at the start it allocated GPU memory every frame without freeing it (e.g. Vader Immortal, ~20 MB a second).": "",
  "Click here, then type. Every key goes to the Frame.": "",
  "Click to open · right-click for quick actions": "",
  "Click to open · right-click for quick actions · drag across cards to select several": "",
@@ -338,6 +341,8 @@
  "Cylinder layers (curved menus and movie screens, for example 4XVR), which the Frame's runtime lacks, are shown as a few flat strips along the curve. 0 = drop them. 360° (equirect) layers can't be shown on the Frame.": "",
  "Darken lower-resolution regions (test)": "",
  "Data": "",
+ "data file": "",
+ "data folder": "",
  "Data folder": "",
  "Decide later": "",
  "Declare Meta-only permissions": "",
@@ -371,6 +376,7 @@
  "Dev builds are early, less tested versions and may have bugs. You still get the next release as a normal update (you have {version}).": "",
  "Developer Mode lets FramePort find and connect to the Frame; the setup turns it on for you. With it on, you can also open Settings → Developer → Pair new host on the Frame and approve FramePort there.": "",
  "Diagnostics for frame.gl_multiview_fbo: checks for GL errors after every single-view draw of a multiview shader and logs counters every 5 seconds (tag GLMV in launch.log).": "",
+ "Diagnostics: removes layer color fades. Some fades no longer show.": "",
  "Diagnostics: the Vulkan shim (frame.vk_sanitize) adds Khronos' validation layer to the game's instance; its findings go to launch.log. The layer library (libVkLayer_khronos_validation.so) must be in the APK.": "",
  "Disable application space warp if used": "",
  "Disable controller tracking offset": "",
@@ -449,6 +455,8 @@
  "Everything is up to date": "",
  "Experimental": "",
  "experimental": "",
+ "Experimental bypass for a DLC manager blocked on Meta asset-file service errors at startup (e.g. PixelRipped 1995: Asset status error (code 100)). Returns an empty successful asset list and reports requested asset IDs as installed, with an empty file path. Does not supply DLC or change download requests. Enable only to test this startup failure; disable with FRAMEPORT_ASSET_FILES_STUB=0. Shares the language-pack library and needs no language packs.": "",
+ "Experimental bypass for a failed Meta asset-file check at startup. Reports an empty asset list and installed status without a file path; does not provide DLC. Experimental.": "",
  "Experimental Vulkan mutable-format workaround.": "",
  "Experimental. Leave it off unless asked to test it.": "",
  "Experimental: shows HUDs, menus and other flat panels that stay black on the Frame (for example Doom3Quest's HUD and PDA).": "",
@@ -508,7 +516,6 @@
  "For games whose fades to black don't show, so you see the level loading (for example Batman: Arkham Shadow).": "",
  "For games whose hands trail the controllers when you move them (for example BattleSisters).": "",
  "For games whose hands' thumbs never move when you touch the buttons or thumbstick (for example Vader Immortal).": "",
- "For games whose memory use keeps growing (for example Vader Immortal). Some fades no longer show.": "",
  "For games whose menus or screens jump to wherever you look.": "",
  "For games whose picture flickers or smears (for example Into The Radius 2).": "",
  "For heavy games that use application space warp: it causes artifacts or hangs on non-Quest runtimes (for example Asgard's Wrath 2, Batman: Arkham Shadow).": "",
@@ -517,6 +524,7 @@
  "For older Unity games that freeze at the first scene change (for example Sniper Elite VR). Can make loading screens stutter.": "",
  "For older Unity games whose hands trail the controllers (for example Sniper Elite VR). In others the hands lag.": "",
  "For one eye looking wrong (for example a jittering right eye): logs each eye's submitted pose against a fresh one, the eye-to-eye relation and when each eye's image was released, also into framebridge.log in the game's storage (some games stop Android's log early). No effect on the game.": "",
+ "For OpenGL ES games whose memory use keeps growing (e.g. Vader Immortal).": "",
  "For overlay apps (fpsVR, wrist watches and other SteamVR add-ons that draw over games instead of being a game): FramePort registers the app with the Frame's SteamVR, which draws its overlays over whatever you play there, Quest and PC VR games alike. With 'start with SteamVR' on, SteamVR starts it by itself (also after a restart); otherwise start it from the library. It isn't launch-tested (it shows nothing without a game). Ignored on this PC.": "",
  "For troubleshooting: records the game's requests to Meta's online services.": "",
  "For Unity games that crash when they turn on anti-aliasing (for example The Room VR).": "",
@@ -781,6 +789,7 @@
  "KiB": "",
  "Language": "",
  "Language packs from the game's files": "",
+ "Large files upload together using OpenSSH when available. Default: 3. Lower this on a busy network.": "",
  "Last build": "",
  "Last launch test's log": "",
  "Last launch test: passed": "",
@@ -1052,6 +1061,7 @@
  "OVRPort's own VrApi→OpenXR adapter for engines that call libvrapi.so directly: the same upstream code as FramePort's 'VrApi → OpenXR bridge' without its Frame-specific changes. Only in OVRPort's experimental CLI builds (the stable CLI lists it but can't apply it).": "",
  "OVRPort's platform loader answers the Meta Platform SDK's language-pack calls (ovr_LanguagePack_GetCurrent/SetCurrent) with 'no request', so a game that asks for its language pack never gets an answer. Adds a small library that serves language packs (<tag>.lang, for example de.lang) found in the game's own data folders (OBB and app files) through the same calls, the asset-file list and the status call, without any download. The game then finds the file path itself. The pack it applies with SetCurrent wins; otherwise the environment variable FRAMEPORT_LANGPACK (a tag), otherwise the only pack there is. Everything else goes to the loader unchanged. Off by default: turn it on for a game whose data has such files (the game page lists the patch only then).": "",
  "Package": "",
+ "Parallel uploads": "",
  "passed": "",
  "Password (first time only)": "",
  "Paste an install link: an install button's address, a manifest (.json) or a direct link to an APK, .zip or .exe.": "",
@@ -1213,7 +1223,7 @@
  "Removes Meta's old VR library when the game doesn't need it.": "",
  "Removes OVRPort's controller pose offset if controllers look misplaced.": "",
  "Removes requirements for Quest-only system parts.": "",
- "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, for example Vader Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show.": "",
+ "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime doesn't apply it (diagnostics). Fades done this way no longer show.": "",
  "Removes the game from the Frame. Saves are kept, so a reinstall picks up where you left off.": "",
  "Removes {title} from Steam on this PC (Steam restarts once). The game folder stays.": "",
  "Removes {title}'s game files from the Frame. Its saves and own files stay unless you tick the box below. Its Steam entry goes away after Steam's next restart.": "",
@@ -1286,7 +1296,9 @@
  "Saved {name} — drag it into the GitHub issue that opened": "",
  "Saved. Restart the game to use the new settings.": "",
  "Saved. They apply when the game is installed.": "",
+ "Saves a few UI panels before and after FrameBridge turns them upright, for testing without the headset.": "",
  "saves and settings": "",
+ "Saves the first N UI panels that FrameBridge turns upright (Vulkan games whose panels are stored upside down), before and after the flip, as fb_flip_<n>_raw.ppm / fb_flip_<n>_upright.ppm in the game's files folder on the Frame. Shows what the runtime gets without anyone wearing the headset.": "",
  "Saves the game's shaders to capture one for a fix. No effect on the game.": "",
  "Saves the game's shaders to find one that hangs the GPU. No effect on the game.": "",
  "Saves what the game draws every few seconds, for testing without the headset.": "",
@@ -1368,6 +1380,7 @@
  "Skip Meta avatars": "",
  "Skip this version": "",
  "Skips a Quest-only reporting step in Meta's audio library that crashes some games.": "",
+ "Skips a separate data-file check when an Unreal game still hangs at startup with the content check off. Experimental; the game still needs its data.": "",
  "Skips Meta XR Audio's telemetry under x86_64 ARM translation (emulators). Not needed on the Frame, which runs games natively.": "",
  "Skips picture layers the Frame would refuse. Leave it on.": "",
  "Sleep": "",
@@ -1529,6 +1542,8 @@
  "The Frame's Steam library still shows the old artwork.": "",
  "The Frame's Steam library still shows the old name.": "",
  "the game failed its checks (see the list above)": "",
+ "The game's files or settings changed. Update applies only what's needed; saves are kept.": "",
+ "The game's {kind} isn't at {path} any more. Add the game again from the folder that has it.": "",
  "The headset is asleep: put it on, then take the screenshot.": "",
  "The headset's view and sound open in an mpv window. Open it in your browser any time.": "",
  "The headset's view and sound open in your web browser. Stop the stream when you're done.": "",
@@ -1547,8 +1562,8 @@
  "The PC VR counterpart of OVRPort's 'Patch Oculus detection for Unreal'. Unreal's Oculus plugin only starts when the Oculus service announces a headset (the Windows event 'OculusHMDConnected'); without it the game runs as a flat window. On the Frame the launcher runs the game through FramePort's small helper (fp_oculushmd.exe) that provides that event while the game runs, instead of relying only on Revive's hook of the check. Ignored on this PC (the Oculus app or Revive handle it there).": "",
  "the previous version, kept as a backup": "",
  "The processor types the game has code for. The Frame runs only 64-bit ARM (arm64-v8a); 32-bit-only games can't run on it.": "",
- "The recipe or your game files changed since the install. Update to install the new build; saves are kept.": "",
  "The setup turns on Developer Mode, lets FramePort in and installs Lepton if needed. The Frame's desktop closes during it, then FramePort connects by itself. No password needed.": "",
+ "The site's HTTPS certificate couldn't be verified. Something on the network, such as antivirus HTTPS scanning, a proxy or a school/work network, may have replaced it. Try another network or turn off HTTPS scanning.": "",
  "The store's name": "",
  "The time the Frame spends collecting these numbers.": "",
  "The upload to the Frame was damaged. Try again, ideally over a cable or the Frame's hotspot.": "",
@@ -1567,6 +1582,7 @@
  "They're deleted on the Frame for good. Steam's own list may show them until Steam restarts.": "",
  "They're part of SteamOS. Ending them may restart Steam and stop the running game.": "",
  "This deletes the {what} on the Frame. It can't be undone.": "",
+ "This folder contains an installer without a launchable Linux program. FramePort runs programs, not installers. Use the project's own install instructions.": "",
  "This folder is empty. Upload files with the buttons above.": "",
  "This Frame isn't set up for FramePort yet. Go to Steam Frame → Start setup.": "",
  "This Frame isn't set up for FramePort yet. Run the setup once.": "",
@@ -1656,11 +1672,13 @@
  "Unreal builds of Meta XR Audio abort ('ClassNotFoundException com.oculus.os.AnalyticsEvent') on non-Quest devices. Patches that one JNI FindClass call so the library continues (for example NOPE Challenge).": "",
  "Unreal games can check their whole data file (.obb) before starting (bVerifyOBBOnStartUp). On the Frame that check's progress and error screens are invisible (Lepton runs VR games without an Android window), so the game seems to hang on its DownloaderActivity, for example Contractors. This turns the check off in the manifest; Unreal still checks that the OBB is there with the right size, so a missing or wrong-version OBB still stops the game.": "",
  "Unreal games start CrashReportClient when they crash, which leaves a crash dialog instead of simply closing. This passes -nocrashreports to the game and, on the Frame, renames the game's copy of CrashReportClient.exe so it can't start (your game files on this PC aren't changed).": "",
+ "Unreal's Java OBB delivery check can leave a game on an invisible DownloaderActivity screen even with the manifest CRC check off (e.g. Into The Radius). Makes known Unreal expansionFilesDelivered methods return true, bypassing the Java name and size gate. Experimental: the native engine still needs complete, matching, readable OBB data.": "",
  "Unreal's Oculus module looks up every OVRPlugin function it was built against and starts no VR when one is missing; OVRPort's OpenXR OVRPlugin lacks some old ones (for example ovrp_GetPTWNear, which Unreal 4.25 builds like Star Wars Pinball VR look up). The game then never starts an OpenXR session and crashes a few seconds in. Adds a generated library to libOVRPlugin.so with a stand-in for each missing function that reports failure (ovrpFailure), so Unreal's Oculus support starts. The functions OVRPort has are untouched.": "",
  "Unreal: bypass the stalled loading splash": "",
  "Unreal: don't wait for the Quest shader precompile": "",
  "Unreal: match multiview depth to the eye size": "",
  "Unreal: Quest controller bindings (RPOC key map)": "",
+ "Unreal: skip the OBB delivery check": "",
  "Unreal: stand-ins for OVRPlugin functions OVRPort lacks": "",
  "Unreal: start without the OBB check": "",
  "Unreal: thumb follows the capacitive touches": "",
@@ -1703,6 +1721,7 @@
  ],
  "Upside down": "",
  "Upside down and mirrored": "",
+ "Upside-down panel images (diagnostics)": "",
  "Use controllers": "",
  "Use FramePort": "",
  "Use FramePort for these links": "",

src/frameport/patches/frame/langpack.py

@@ -34,6 +34,18 @@ def with_assets(lib: bytes) -> bytes:
     at += len(ASSETS_MARK)
     return lib[:at] + b"1" + lib[at + 1:]
 
+STUB_MARK = b"@FPASSETSTUB@"
+
+
+def with_stub(lib: bytes) -> bytes:
+    """Enable the empty asset-list / installed-status bypass without listing local files."""
+    at = lib.find(STUB_MARK + b"0")
+    if at < 0:
+        return lib
+    at += len(STUB_MARK)
+    return lib[:at] + b"1" + lib[at + 1:]
+
+
 # Every function native/langpack/langpack.c defines. The loader's own exports of these are hidden (see
 # elf.hide_exports) so lookups reach LIB first; tests/test_langpack.py keeps this list equal to the C source.
 EXPORTS = (
@@ -112,6 +124,7 @@ class AssetFiles(Patch):
                    "installed and answers their download request at once with the file's path; nothing is copied or "
                    "downloaded. Shares the language-pack library.")
     order = 33
+    flag_library = staticmethod(with_assets)
 
     def applies(self, a):
         extra = a.extra or {}
@@ -137,11 +150,11 @@ class AssetFiles(Patch):
             ws.put(ws.lib(LOADER), elf.add_needed(patched, LIB))
             ws.put(ws.lib(LIB), with_metadata(artifact(ws.abi, LIB), (ctx.analysis.version or "").strip()))
         lib = ws.read_lib(LIB)
-        flagged = with_assets(lib)
+        flagged = self.flag_library(lib)
         if flagged == lib:
             return False
         ws.put(ws.lib(LIB), flagged)
-        ctx.notes.append(f"content files listed as installed asset files by {LIB}")
+        ctx.notes.append(f"{self.title} enabled by {LIB}")
         return True
 
     def validate(self, ctx: ApkContext):
@@ -151,5 +164,36 @@ class AssetFiles(Patch):
         return [("Content files listed (asset-file library)", ASSETS_MARK + b"1" in ws.read_lib(LIB), LIB)]
 
 
+class AssetFilesStub(AssetFiles):
+    id = "frame.asset_files_stub"
+    title = "Asset-file service bypass"
+    description = ("Experimental bypass for a DLC manager blocked on Meta asset-file service errors "
+                   "at startup (e.g. PixelRipped 1995: Asset status error (code 100)). Returns an empty successful asset list and "
+                   "reports requested asset IDs as installed, with an empty file path. Does not supply DLC or "
+                   "change download requests. Enable only to test this startup failure; disable with "
+                   "FRAMEPORT_ASSET_FILES_STUB=0. Shares the language-pack library and needs no language packs.")
+    order = 34
+    experimental = True
+    flag_library = staticmethod(with_stub)
+
+    @property
+    def summary(self):
+        return ("Experimental bypass for a failed Meta asset-file check at startup. Reports an empty asset list and "
+                "installed status without a file path; does not provide DLC. Experimental.")
+
+    def applies(self, a):
+        return LOADER in a.libs and "arm64-v8a" in a.abis
+
+    def detect(self, a):
+        return None
+
+    def validate(self, ctx: ApkContext):
+        ws = ctx.ws
+        linked = ws.has(ws.lib(LOADER)) and LIB in elf.needed(ws.read_lib(LOADER))
+        enabled = ws.has(ws.lib(LIB)) and STUB_MARK + b"1" in ws.read_lib(LIB)
+        return [("Asset-file bypass linked and enabled", linked and enabled, LIB)]
+
+
+register(AssetFilesStub)
 register(LanguagePacks)
 register(AssetFiles)

src/frameport/patches/frame/tbxr_vendor.py

@@ -38,6 +38,7 @@ class TbxrVendor(Patch):
                    "the Meta path. Keeps GL4ES in charge of its desktop OpenGL draw calls so animated models "
                    "don't turn into stretched triangles.")
     order = 47
+    revision = 2  # 2: GL4ES keeps its draw calls (#191). Ports without GL4ES rebuild to the same APK (nothing re-sent)
 
     def applies(self, a):
         return bool((a.extra or {}).get("tbxr_libs")) and "arm64-v8a" in a.abis

src/frameport/patches/frame/unreal_obb_check.py

@@ -8,13 +8,36 @@ the downloader (GitHub #159, Contractors). Setting the meta-data to false skips
 check stays (a missing or wrong-size OBB still stops at the downloader). One 4-byte manifest value changes."""
 from __future__ import annotations
 
+import struct
+
 from ...analysis.detect import UE_VERIFY_OBB_KEY
 from ...apk import axml
+from ...apk.dex import Dex
 from ..base import ApkContext, Patch, Suggestion, register
 
 MANIFEST = "AndroidManifest.xml"
 
 
+def delivery_methods(dex: Dex, package: str) -> list[tuple[int, int]]:
+    classes = {f"L{package.replace('.', '/')}/{name};" for name in ("DownloaderActivity", "OBBData")}
+    classes.update(f"Lcom/epicgames/{engine}/{name};" for engine in ("ue4", "unreal")
+                   for name in ("DownloadShim", "GameActivity"))
+    return [(idx, code) for cls in dex.class_names() if cls in classes
+            for idx, code in dex.class_methods(cls)
+            if dex.method(idx)[1] == "expansionFilesDelivered" and dex.return_type(idx) == "Z"]
+
+
+def has_delivery_check(data: bytes, package: str) -> bool:
+    if b"expansionFilesDelivered" not in data:
+        return False
+    return bool(delivery_methods(Dex(data), package))
+
+
+def patch_dex(dex: Dex, package: str) -> list[str]:
+    return [dex.method(idx)[0] for idx, code in delivery_methods(dex, package)
+            if dex.return_early(code, "Z", boolean_value=True)]
+
+
 class UnrealSkipObbCheck(Patch):
     id = "frame.unreal_skip_obb_check"
     title = "Unreal: start without the OBB check"
@@ -49,3 +72,52 @@ class UnrealSkipObbCheck(Patch):
 
 
 register(UnrealSkipObbCheck)
+
+
+class UnrealSkipObbDelivery(Patch):
+    id = "frame.unreal_skip_obb_delivery"
+    title = "Unreal: skip the OBB delivery check"
+    description = ("Unreal's Java OBB delivery check can leave a game on an invisible DownloaderActivity screen "
+                   "even with the manifest CRC check off (e.g. Into The Radius). Makes known Unreal "
+                   "expansionFilesDelivered methods return true, bypassing the Java name and size gate. "
+                   "Experimental: the native engine still needs complete, matching, readable OBB data.")
+    order = 24
+    needs_vr = False
+    experimental = True
+
+    def applies(self, a):
+        return bool((a.extra or {}).get("unreal_obb_delivery"))
+
+    def detect(self, a):
+        return None  # triage-only: most games pass the delivery check
+
+    def apply(self, ctx: ApkContext) -> bool:
+        changed = False
+        for name in sorted(n for n in ctx.ws.names() if n.startswith("classes") and n.endswith(".dex")):
+            data = ctx.ws.read(name)
+            if not has_delivery_check(data, ctx.analysis.package):
+                continue
+            dex = Dex(data)
+            done = patch_dex(dex, ctx.analysis.package)
+            if done:
+                ctx.ws.put(name, dex.finish())
+                ctx.notes.append(f"{name}: expansionFilesDelivered=true in {', '.join(sorted(done))}")
+                changed = True
+        return changed
+
+    def validate(self, ctx):
+        checks = []
+        for name in sorted(n for n in ctx.ws.names() if n.startswith("classes") and n.endswith(".dex")):
+            data = ctx.ws.read(name)
+            if not has_delivery_check(data, ctx.analysis.package):
+                continue
+            dex = Dex(data)
+            for idx, code in delivery_methods(dex, ctx.analysis.package):
+                ready = (struct.unpack_from("<H", data, code)[0] > 0
+                         and struct.unpack_from("<I", data, code + 12)[0] >= 2
+                         and struct.unpack_from("<2H", data, code + 16) == (0x1012, 0x000F))
+                checks.append(("OBB delivery check bypassed", ready, f"{name}: {dex.method(idx)[0]}"))
+        return checks
+
+
+register(UnrealSkipObbDelivery)

src/frameport/patches/settings.py

@@ -22,10 +22,17 @@ SETTINGS = [
      "Every N seconds, saves the left-eye image the game submits (a quarter of its size) as fb_snap_0-7.ppm in the "
      "game's files folder on the Frame. Launch tests run without anyone wearing the headset, so the headset view stays "
      "black; this shows what the game itself draws. OpenGL ES games only."),
+    ("gl_error_clear", "int", 0, "Clear the game's GL errors (GLES)",
+     "Clears OpenGL errors the game left pending before FrameBridge calls the Frame's runtime. The runtime's GL code "
+     "fails on any pending error; after one such failure at the start it allocated GPU memory every frame without "
+     "freeing it (e.g. Vader Immortal, ~20 MB a second)."),
+    ("flip_dump", "int", 0, "Upside-down panel images (diagnostics)",
+     "Saves the first N UI panels that FrameBridge turns upright (Vulkan games whose panels are stored upside down), "
+     "before and after the flip, as fb_flip_<n>_raw.ppm / fb_flip_<n>_upright.ppm in the game's files folder on the "
+     "Frame. Shows what the runtime gets without anyone wearing the headset."),
     ("strip_color_bias", "int", 0, "Drop layer color fades",
      "Removes the color scale/bias (XR_KHR_composition_layer_color_scale_bias) from the game's layers, so the runtime "
-     "doesn't apply it. The Frame's runtime allocates GPU memory for it every frame without freeing it, for example "
-     "Vader Immortal leaked ~20 MB/s on its loading screen. Fades done this way no longer show."),
+     "doesn't apply it (diagnostics). Fades done this way no longer show."),
     ("fade_quad", "int", 0, "Draw fades over the picture",
      "Games that fade to black by dimming their picture with a layer color scale (XR_KHR_composition_layer_color_"
      "scale_bias, for example Batman: Arkham Shadow's loading screens) can show the level loading instead of black on "
@@ -392,11 +399,15 @@ UI: dict[str, dict] = {
                 help="For Unity games that crash when they turn on anti-aliasing (for example The Room "
                      "VR).", control=("switch",)),
     "strip_color_bias": dict(group="troubleshooting", level="advanced", label="Drop layer color fades",
-                help="For games whose memory use keeps growing (for example Vader Immortal). Some fades no"
-                     " longer show.", control=("switch",)),
+                help="Diagnostics: removes layer color fades. Some fades no longer show.", control=("switch",)),
     "snapshot": dict(group="troubleshooting", level="advanced", label="Eye-image snapshots (diagnostics)",
                 help="Saves what the game draws every few seconds, for testing without the headset.",
                 control=("switch",)),
+    "gl_error_clear": dict(group="troubleshooting", level="advanced", label="Clear the game's GL errors (GLES)",
+                help="For OpenGL ES games whose memory use keeps growing (e.g. Vader Immortal).", control=("switch",)),
+    "flip_dump": dict(group="troubleshooting", level="advanced", label="Upside-down panel images (diagnostics)",
+                help="Saves a few UI panels before and after FrameBridge turns them upright, for testing without the "
+                     "headset.", control=("switch",)),
     "strip_depth": dict(group="troubleshooting", level="advanced", label="Strip depth layers",
                 help="Removes depth information from the game's layers. For testing.", control=("switch",)),
     "respace_kick": dict(group="troubleshooting", level="advanced", label="Re-create play space",

src/frameport/patches/summaries.py

@@ -72,6 +72,8 @@ SUMMARIES = {
                                     "the Frame.",
     "frame.sdl_clipboard": "Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).",
     "frame.godot_clipboard": "Lets Godot games start on the Frame (they'd crash looking for a clipboard).",
+    "frame.unreal_skip_obb_delivery": "Skips a separate data-file check when an Unreal game still hangs at startup "
+                                      "with the content check off. Experimental; the game still needs its data.",
     "frame.unreal_skip_obb_check": "Starts Unreal games without re-checking their data file (they'd seem to hang "
                                    "on an invisible check screen).",
     "frame.bhaptics_permission": "Stops bHaptics from asking for a Bluetooth permission the Frame doesn't have (the "

src/frameport/pipeline.py

@@ -598,7 +598,10 @@ def install_linux(package: str, target: Target, reporter: Reporter, add_to_libra
 def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
     if reporter:
         reporter.log(f"analyzing {src.apk.name}")
-    a = analyze(src.apk, data_bytes=src.data_bytes())
+    from .core.models import data_manifest
+
+    manifest = data_manifest(src.data_dir, src.data_files)
+    a = analyze(src.apk, data_bytes=sum(manifest.values()))
     a.extra["lang_packs"] = langpacks.find_tags(_data_folder(src))
     a.extra["asset_files"] = langpacks.find_content_files(_data_folder(src))
     recipe = engine.suggest(a)
@@ -607,7 +610,8 @@ def add_game(src: SourceGame, reporter: Reporter | None = None) -> dict:
     names = {"auto_title": recipe.title or a.label} if old.get("title_locked") else {"title": recipe.title or a.label}
     return library.upsert_game(
         a.package, **names, name=src.name, apk=str(src.apk),
-        data_dir=str(src.data_dir) if src.data_dir else None, data_files=src.data_files, data_bytes=src.data_bytes(),
+        data_dir=str(src.data_dir) if src.data_dir else None, data_files=src.data_files,
+        data_bytes=sum(manifest.values()), data_manifest=manifest, source_sha256=builder.sha256(src.apk),
         origin=str(src.origin),
         analysis=a.to_dict(), recipe=library.recipe_to_dict(recipe), suggested=library.recipe_to_dict(recipe),
         status=recipe.status,
@@ -759,6 +763,23 @@ def source_of(entry: dict) -> SourceGame:
                       Path(entry["origin"]) if entry.get("origin") else None, data_files=entry.get("data_files"))
 
 
+def check_source(entry: dict) -> SourceGame:
+    from .errors import MissingGameSource
+
+    src = source_of(entry)
+    if not src.apk.is_file():
+        raise MissingGameSource(src.apk)
+    if src.data_dir is not None:
+        if not src.data_dir.is_dir():
+            raise MissingGameSource(src.data_dir, "data folder")
+        # only files the user picked: the folder's other files can change (newer OBBs) and are listed again at build
+        for name in src.data_files or ():
+            path = src.data_dir / name
+            if not path.is_file():
+                raise MissingGameSource(path, "data file")
+    return src
+
+
 def set_recipe(package: str, recipe: Recipe) -> None:
     library.upsert_game(package, recipe=library.recipe_to_dict(recipe))
 
@@ -827,7 +848,7 @@ def prepare_as_is(package: str, reporter: Reporter) -> dict:
     from .build import sha256
 
     entry = library.game(package)
-    apk = Path(entry["apk"])
+    apk = check_source(entry).apk
     a = entry["analysis"]
     reporter.stage("Checking the game (installing it as it is)")
     checks = []
@@ -852,8 +873,10 @@ def prepare_as_is(package: str, reporter: Reporter) -> dict:
     art, store_title = artwork.fetch(package, apk)
     info = {"apk": str(apk), "alt_apk": None, "sha256": sha256(apk), "alt_sha256": None, "applied": [],
             "checks": checks, "ok": all(c["ok"] is not False for c in checks), "as_is": True,
-            "recipe_fp": recipe_fingerprint(entry["recipe"], package), "source_version": _source_version(entry)}
-    library.upsert_game(package, build=info, title=entry.get("title") or store_title)
+            "recipe_fp": recipe_fingerprint(entry["recipe"], package), "source_version": _source_version(entry),
+            **_build_record(entry)}
+    library.upsert_game(package, build=info, title=entry.get("title") or store_title,
+                        source_sha256=info["source_sha256"])
     return info
 
 
@@ -877,7 +900,82 @@ def _build_lock(package: str) -> threading.Lock:
         return _build_locks.setdefault(package, threading.Lock())
 
 
+def _build_inputs(entry: dict, native_names: list[str] | None = None) -> dict:
+    """Only the native assets carried by this APK and the local converter; no downloads or Java invocations."""
+    from .core.paths import artifacts_dir
+    from .tools import toolchain
+
+    build = entry.get("build") or {}
+    previous = build.get("build_inputs") or {}
+    recipe = entry.get("recipe") or {}
+    native_names = native_names if native_names is not None else build.get("native_names") or []
+    native = previous.get("native") or {}
+    manifest = artifacts_dir() / "SHA256SUMS"
+    if manifest.is_file():
+        checksums = {line.split(maxsplit=1)[1].strip().removeprefix("./"): line.split()[0]
+                     for line in manifest.read_text().splitlines() if len(line.split()) == 2}
+        native = {name: checksums.get(name) for name in native_names}
+    jar = toolchain.overport_jar() if recipe.get("overport", True) and not recipe.get("as_is") else None
+    converter = previous.get("overport")
+    if jar and jar.is_file():
+        st = jar.stat()
+        stat = {"path": str(jar), "size": st.st_size, "mtime_ns": st.st_mtime_ns}
+        if stat != build.get("overport_stat"):
+            converter = builder.sha256(jar)
+    return {"native": native, "overport": converter}
+
+
+def _source_stat(entry: dict) -> dict | None:
+    source = Path(entry["apk"])
+    try:
+        st = source.stat()
+    except OSError:
+        return None
+    return {"path": str(source.resolve()), "size": st.st_size, "mtime_ns": st.st_mtime_ns}
+
+
+def _build_record(entry: dict, apk: Path | None = None, superseded=None) -> dict:
+    import zipfile
+
+    from .core.paths import artifacts_dir
+    from .game_update import apk_recipe_fingerprint
+    from .tools import toolchain
+
+    native_names = []
+    if apk and not entry["recipe"].get("as_is"):
+        with zipfile.ZipFile(apk) as archive:
+            native_names = [name.removeprefix("lib/") for name in archive.namelist()
+                            if name.startswith("lib/") and (artifacts_dir() / name.removeprefix("lib/")).is_file()]
+        if "frame.oculusos" in (entry["recipe"].get("patches") or {}):
+            native_names.append("dex/oculusos-stubs.dex")
+    jar = toolchain.overport_jar()
+    converter_stat = None
+    if jar and jar.is_file():
+        st = jar.stat()
+        converter_stat = {"path": str(jar), "size": st.st_size, "mtime_ns": st.st_mtime_ns}
+    return {"apk_recipe_fp": apk_recipe_fingerprint(entry["recipe"], entry["package"], superseded),
+            "source_stat": _source_stat(entry), "source_sha256": builder.sha256(Path(entry["apk"])),
+            "build_inputs": _build_inputs(entry, native_names), "native_names": native_names,
+            "overport_stat": converter_stat}
+
+
+def _build_inputs_changed(entry: dict) -> bool:
+    build = entry.get("build") or {}
+    if not build.get("build_inputs") or build["build_inputs"] != _build_inputs(entry):
+        return True
+    stat = _source_stat(entry)
+    if stat is None:
+        # An unavailable dump does not prevent configuration updates to a known installed APK.
+        return False
+    if stat != build.get("source_stat"):
+        return builder.sha256(Path(entry["apk"])) != build.get("source_sha256")
+    return False
+
+
 def build_game(package: str, reporter: Reporter, outdir: Path | None = None) -> dict:
+    entry = library.game(package)
+    if not is_linux(entry) and not is_rift(entry):
+        check_source(entry)  # fail before reanalysis or tool setup when the original files have gone
     if analysis_outdated(library.game(package) or {}):  # analysed by an older FramePort: new fields first
         refresh_analyses([package], reporter)
     entry = library.game(package)
@@ -897,8 +995,10 @@ def build_game(package: str, reporter: Reporter, outdir: Path | None = None) ->
     build_info = {"apk": str(res.apk), "alt_apk": str(res.alt_apk) if res.alt_apk else None, "sha256": res.sha256,
                   "alt_sha256": res.alt_sha256, "applied": res.applied, "checks": res.checks, "ok": res.ok,
                   "overport": res.meta.get("overport"), "recipe_fp": recipe_fingerprint(entry["recipe"], package),
-                  "superseded": res.meta.get("superseded") or {}, "source_version": _source_version(entry)}
-    library.upsert_game(package, build=build_info, title=entry.get("title") or store_title)
+                  "superseded": res.meta.get("superseded") or {}, "source_version": _source_version(entry),
+                  **_build_record(entry, res.apk, res.meta.get("superseded"))}
+    library.upsert_game(package, build=build_info, title=entry.get("title") or store_title,
+                        source_sha256=build_info["source_sha256"])
     return build_info
 
 
@@ -918,33 +1018,101 @@ def _find_late_data(entry: dict, reporter: Reporter | None = None) -> dict:
 
 
 def install_game(package: str, target: Target, reporter: Reporter, apk_only: bool = False,
-                 add_to_library: bool = True, apk: Path | None = None) -> dict:
+                 add_to_library: bool = True, apk: Path | None = None, force: bool = False) -> dict:
     """Install the game's last build (or `apk`, e.g. a test build of the same package signed with the same key)."""
+    reporter = reporter or Reporter()
     entry = library.game(package)
     if is_linux(entry):
         return install_linux(package, target, reporter, add_to_library)
     if is_rift(entry):
         return install_rift(package, target, reporter, add_to_library)
+    from .game_update import plan_update
+
     test_build = apk is not None
+    optimized = not test_build and hasattr(target, "update_existing")
+    deployment, update, manifest = None, None, None
+    if optimized:
+        reporter.stage("Check update requirements")
+        deployment = next((d for d in target.installed() if d.get("package") == package), None)
+        if not apk_only:
+            entry = _find_late_data(entry, reporter) if not entry.get("data_dir") and entry.get("apk") else entry
+            from .core.models import data_manifest
+
+            manifest = data_manifest(Path(entry["data_dir"]) if entry.get("data_dir") else None,
+                                     entry.get("data_files"))
+            # Cache desired data for badges without doing filesystem I/O in render paths.
+            library.update_game(package, lambda game: game.update(data_manifest=manifest))
+            entry["data_manifest"] = manifest
+        update = plan_update(entry, deployment, apk_only=apk_only, data_manifest=manifest)
+        if update.data and not update.apk and hasattr(target, "deployment"):
+            deployment = target.deployment(package)
+            update = plan_update(entry, deployment, apk_only=apk_only, data_manifest=manifest)
+        if force or _build_inputs_changed(entry):
+            update = dataclasses.replace(update, rebuild=True, apk=True, configure=True)
+        for reason in update.reasons:
+            reporter.log(reason)
+        if update.rebuild:
+            info = build_game(package, reporter)
+            if not info["ok"]:
+                raise RuntimeError("the game failed its checks (see the list above)")
+            entry = library.game(package)
+        b = entry.get("build") or {}
+        recipe = library.recipe_from_dict(entry["recipe"])
+        if b.get("superseded"):
+            recipe = dataclasses.replace(recipe, patches=upstream.without_superseded(recipe.patches, b["superseded"]))
+        if deployment and not update.apk:
+            if update.configure or update.data:
+                result = target.update_existing(entry, deployment, update, recipe, reporter, manifest)
+            else:
+                reporter.log("APK, game data and runtime configuration already current")
+                result = {"base": deployment["base"], "appid": deployment["appid"]}
+            art = None
+            if update.artwork or update.shortcut:
+                art = target.update_steam_art(package, reporter, title=steam_title(entry))
+                library.update_game(package, lambda game: game.pop("steam_art_stale", None))
+            # The deployment can't tell whether Steam still has the shortcut (a connection lost during "Add to
+            # Steam", or Steam putting its old shortcuts.vdf back, GitHub #21/#41): check it every time. The agent
+            # restarts Steam only when the library entry really changes.
+            check_shortcut = not (art or {}).get("library")
+            if add_to_library and check_shortcut:
+                target.add_to_library([package], reporter)
+            result["launch_test_required"] = update.launch_test
+            result["shortcut_required"] = check_shortcut
+            result["stage_seconds"] = reporter.stage_timings()
+            _record_install(package, target.label, {"result": result, "time": time.time()})
+            return result
     b = entry.get("build") or {}
     recipe = library.recipe_from_dict(entry["recipe"])
-    if not test_build and not b.get("apk"):  # never built yet (e.g. `frameport install` right after a scan)
+    if not test_build and not b.get("apk"):
         build_game(package, reporter)
         return install_game(package, target, reporter, apk_only, add_to_library)
     apk = Path(apk) if apk else Path(b["alt_apk"] if recipe.use_alt and b.get("alt_apk") else b["apk"])
-    if not test_build and not apk.exists():  # the converted copy was removed after an earlier install: make it again
+    if not test_build and not apk.is_file():
         build_game(package, reporter)
         return install_game(package, target, reporter, apk_only, add_to_library)
-    if not test_build and b.get("superseded"):  # workarounds this build left out (upstream fixed): not in settings.conf
+    if optimized and not update.rebuild:
+        expected_sha = b.get("alt_sha256") if recipe.use_alt else b.get("sha256")
+        reporter.check_cancel()
+        if builder.sha256(apk) != expected_sha:
+            reporter.log("the cached APK changed; rebuilding before installation")
+            build_game(package, reporter)
+            return install_game(package, target, reporter, apk_only, add_to_library)
+    if not test_build and b.get("superseded"):
         recipe = dataclasses.replace(recipe, patches=upstream.without_superseded(recipe.patches, b["superseded"]))
     if not entry.get("data_dir") and entry.get("apk") and not apk_only:
         entry = _find_late_data(entry, reporter)  # OBBs copied next to the APK after it was added (GitHub #156)
     data_dir = Path(entry["data_dir"]) if entry.get("data_dir") else None
     title = steam_title(entry)
-    result = target.install(package, title, apk, data_dir, recipe, reporter, apk_only,
+    preserve_data = apk_only or (optimized and deployment is not None and not update.data and not force)
+    result = target.install(package, title, apk, data_dir, recipe, reporter, preserve_data,
                             data_files=entry.get("data_files"))
-    if add_to_library:
+    if add_to_library:  # also after a reinstall: the agent restarts Steam only when the entry changes
         target.add_to_library([package], reporter)
+    result["launch_test_required"] = True
+    result["shortcut_required"] = True
+    result["stage_seconds"] = reporter.stage_timings()
+    if optimized and update.artwork:
+        library.update_game(package, lambda game: game.pop("steam_art_stale", None))
     _record_install(package, target.label, {"apk": str(apk), "result": result, "time": time.time()})
     if not test_build:
         remove_converted_copies(package)

src/frameport/targets/frame_lepton.py

@@ -39,6 +39,10 @@ class FrameLeptonTarget(Target):
     def installed(self) -> list[dict]:
         return self.connect().frame.agent("list_installed")["games"]
 
+    def deployment(self, package: str) -> dict | None:
+        games = self.connect().frame.agent("list_installed", package=package, details=True)["games"]
+        return games[0] if games else None
+
     def install(self, package, title, apk: Path, data_dir, recipe: Recipe, reporter: Reporter, apk_only=False,
                 data_files=None):
         plan = installer.InstallPlan(package, title, apk, data_dir, recipe, apk_only, dest=self.install_dest(),
@@ -48,6 +52,9 @@ class FrameLeptonTarget(Target):
     def add_to_library(self, packages, reporter):
         return installer.add_to_steam(self.connect().frame, packages, reporter)
 
+    def update_existing(self, entry, deployment, plan, recipe, reporter, manifest=None):
+        return installer.update_existing(self.connect().frame, entry, deployment, plan, recipe, reporter, manifest)
+
     def update_steam_art(self, package, reporter, title=None):
         return installer.update_steam_art(self.connect().frame, package, reporter, title=title)
 
@@ -67,6 +74,10 @@ class FrameLeptonTarget(Target):
         return self.connect().frame.agent("launch", package=package, timeout=60)
 
     def set_settings(self, package, settings):
+        from ..core import library
+
+        superseded = ((library.game(package) or {}).get("build") or {}).get("superseded") or {}
+        settings = {key: value for key, value in settings.items() if f"adapter.{key}" not in superseded}
         return self.connect().frame.agent("set_settings", package=package, settings=settings)
 
     def uninstall(self, package, keep_data=True):

src/frameport/ui/app.py

@@ -268,7 +268,10 @@ class FramePortApp:
         if sys.platform == "win32":
             from ..diag import display
 
-            display.record_window(event, self.page.window, theme=T.THEME, reduce_motion=self.reduce_motion)
+            try:  # diagnostics only: never let a window property stop the app from starting
+                display.record_window(event, self.page.window, theme=T.THEME, reduce_motion=self.reduce_motion)
+            except Exception as exc:  # noqa: BLE001
+                applog.log.debug("window diagnostics: %s", exc)
 
     def _on_window_event(self, e) -> None:
         """Remember the window's size and position (once a resize/move ends; not while maximized or full screen) and
@@ -1527,6 +1530,8 @@ class FramePortApp:
         if not g:
             return None  # removed from the library meanwhile
         rift = g.get("kind") == "rift"
+        # An explicit install action on a current game is the existing "Reinstall" action.
+        force = to == "frame" and C.install_state(g, getattr(self, "frame_info", None)) == "installed"
         where = tr("your Frame") if to == "frame" else tr("this PC")
         self._record(pkg, to=to, state="queued", apk_only=apk_only)
 
@@ -1535,12 +1540,13 @@ class FramePortApp:
             self._record(pkg, to=to, state="running")
             as_is = library.recipe_from_dict(library.game(pkg)["recipe"]).as_is
             rep.stage("Checking the game" if rift or as_is else "Patching the game")
-            info = pipeline.build_game(pkg, rep)
-            if not info["ok"]:
-                raise RuntimeError(tr("the game failed its checks (see the list above)"))
+            if rift or to != "frame":
+                info = pipeline.build_game(pkg, rep)
+                if not info["ok"]:
+                    raise RuntimeError(tr("the game failed its checks (see the list above)"))
             rep.check_cancel()
             target = self._target_for(to)
-            pipeline.install_game(pkg, target, rep, apk_only=apk_only)
+            result = pipeline.install_game(pkg, target, rep, apk_only=apk_only, force=force)
             self._record(pkg, remove=True)  # installed; the launch test below is a separate question
             if to == "frame":  # the install sent the current artwork to the Frame's Steam library
                 library.update_game(pkg, lambda e: e.pop("steam_art_stale", None))
@@ -1553,7 +1559,7 @@ class FramePortApp:
                 rep.stage("Installed")
                 return tr("{get} is installed on {where}: SteamVR shows it over your games").format(
                     get=g.get('title'), where=where)
-            if not library.setting("install.launch_test", True):  # Settings → Installing
+            if result.get("launch_test_required") is False or not library.setting("install.launch_test", True):
                 rep.stage("Installed")
                 return tr("{get} is installed on {where}: put the headset on and launch it from your Steam "
                           "library").format(get=g.get('title'), where=where)

src/frameport/ui/components.py

@@ -174,6 +174,10 @@ def install_state(game: dict, frame_info: dict | None) -> str | None:
     if not dep or (dep.get("apk_present") is False and not dep.get("drive_missing")):
         return "missing"
     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
+
+        return "outdated" if plan_update(game, dep).changed else "installed"
     built = {b.get("sha256"), b.get("alt_sha256")} - {None}
     if built and dep.get("sha256") and dep["sha256"] not in built:
         return "outdated"

src/frameport/ui/help.py

@@ -22,8 +22,7 @@ HELP: dict[str, str] = _Translated({
     # ---- game status / library
     "status": "How well the game runs on the Steam Frame. \"Works\" and \"Works with issues\" were tested on a Frame; "
               "\"Untested\" is a suggestion nobody has confirmed yet. \"Can't run\" means a known blocker.",
-    "update_ready": "The recipe or your game files changed since the install. Update to install the new build; saves "
-                    "are kept.",
+    "update_ready": "The game's files or settings changed. Update applies only what's needed; saves are kept.",
     "check_exe": "FramePort isn't sure which program starts this game. Open the game and use … → Change program… to "
                  "pick it.",
     "platform_quest": "A Meta Quest game. FramePort patches it for the Frame, where it runs in Lepton, Valve's Android "

src/frameport/ui/views/library.py

@@ -297,8 +297,9 @@ class LibraryView:
         self._lock = threading.Lock()
         self._search_timer: threading.Timer | None = None
         self._gen = 0
+        # (left padding: the grid clips at its edge, and a hovered card's lift and accent border were cut off there)
         self.grid = ft.GridView(expand=True, max_extent=T.px(196), child_aspect_ratio=0.62, spacing=T.S4,
-                                run_spacing=T.S4, padding=ft.Padding(0, T.S2, T.S2, T.S5))
+                                run_spacing=T.S4, padding=ft.Padding(T.S2, T.S2, T.S2, T.S5))
         self.count = C.meta("")
         self.subtitle = C.body("", max_lines=1, overflow=ft.TextOverflow.ELLIPSIS)
         # typing anywhere on the Library goes here (app._on_key); search_focused tracks where keys already land
@@ -663,12 +664,12 @@ class LibraryView:
             tile.border = ft.Border.all(1, T.ACCENT if on else T.BORDER)
             quick.opacity = 1 if on else 0
             button.show(on)
-            tile.update()
+            C.update(tile)  # a hover can still arrive for a card the shelf just replaced
         tile.on_hover = hover
         # (padding: room for the hover lift and shadow inside the scrolling row, which clips)
         return ft.Container(ft.GestureDetector(content=tile,
                                                on_secondary_tap_down=lambda e: self.open_menu(pkg, e.global_position)),
-                            padding=ft.Padding(T.px(2), T.px(6), T.px(2), T.px(8)))
+                            padding=ft.Padding(T.px(6), T.px(6), T.px(6), T.px(8)))
 
     # ---------------------------------------------------------------- header / filter bar
     def _update_hint(self):
@@ -855,7 +856,7 @@ class LibraryView:
             if quick:
                 quick.opacity = 1 if show else 0
                 button.show(show)
-            tile.update()
+            C.update(tile)  # a hover can still arrive for a card the grid just replaced (it raised and crashed)
         tile.on_hover = hover
         self.marks[pkg] = (tile, overlay, False)
         self._paint_card(pkg)

src/frameport/ui/views/live.py

@@ -99,6 +99,8 @@ class LiveView:
         self.stop_btn = C.ghost(tr("Stop"), ft.Icons.STOP_ROUNDED, self._stop_click)
         self.sound_btn = C.ghost(tr("Sound off"), ft.Icons.VOLUME_OFF_ROUNDED, self._toggle_sound)
         self.window_btn = C.ghost(tr("Show the mpv window"), ft.Icons.OPEN_IN_NEW_ROUNDED, self._reopen_mpv)
+        # a Steam screenshot of what you're watching, without going to the Screenshots tab
+        self.shot_btn = C.secondary(tr("Take screenshot"), G.SHOT, self._take_shot)
         self.url = C.meta("", selectable=True)
         self._push = None  # components.LoopUpdater (updates from background threads; a direct update dropped patches)
         # where the stream plays (ui/live_players): the user's pick, what's available here, what plays it now
@@ -170,7 +172,7 @@ class LiveView:
                 # squeezed the status into a column of single words while streaming)
                 C.card(ft.Column([
                     ft.Row([self.dot, ft.Column([self.state, self.detail], spacing=T.px(2), expand=True),
-                            self.start_btn, self.sound_btn, self.window_btn, self.open_btn, self.stop_btn],
+                            self.start_btn, self.shot_btn, self.sound_btn, self.window_btn, self.open_btn, self.stop_btn],
                            spacing=T.S3, vertical_alignment=ft.CrossAxisAlignment.CENTER),
                     ft.Row([self.player_dd, self.quality_dd, ft.Container(self.url, expand=True)],
                            spacing=T.S3, vertical_alignment=ft.CrossAxisAlignment.CENTER),
@@ -214,6 +216,7 @@ class LiveView:
         self.start_btn.visible = not running
         self.start_btn.disabled = self.idle_start.disabled = self._busy
         self.open_btn.visible = self.stop_btn.visible = running
+        self.shot_btn.visible = running
         self.sound_btn.visible = running and self.mode == "app"
         self.sound_btn.content = tr("Sound on") if self.muted else tr("Sound off")
         self.sound_btn.icon = ft.Icons.VOLUME_UP_ROUNDED if self.muted else ft.Icons.VOLUME_OFF_ROUNDED
@@ -236,7 +239,8 @@ class LiveView:
         if update:  # called from the ticker / start / stream-end threads: send through Flet's event loop
             if self._push is None:
                 self._push = C.LoopUpdater(self.app.page)
-            self._push(self.dot, self.state, self.detail, self.where, self.start_btn, self.open_btn, self.stop_btn,
+            self._push(self.dot, self.state, self.detail, self.where, self.start_btn, self.shot_btn, self.open_btn,
+                       self.stop_btn,
                        self.sound_btn, self.window_btn, self.quality_dd, self.url, self.idle, self.idle_text,
                        self.idle_start, self.idle_open, self.idle_title, self.screen)
 
@@ -411,6 +415,26 @@ class LiveView:
     def _on_stream_end(self) -> None:
         self._dismiss_player()
 
+    def _take_shot(self, e=None) -> None:
+        """Take screenshot (while streaming): the same Steam screenshot as the Screenshots tab's button; that tab
+        shows it the next time it's opened."""
+        if self.shot_btn.disabled:
+            return
+        self.shot_btn.disabled = True
+        C.update(self.shot_btn)
+
+        def work():
+            from .screenshots import take_screenshot
+
+            try:
+                if take_screenshot(self.app) and self.app.screenshots_view is not None:
+                    self.app.screenshots_view._loaded = False  # reload on the next visit
+            finally:
+                self.shot_btn.disabled = False
+                C.update(self.shot_btn)
+
+        self.app.run_bg(work)
+
     def _open(self, e=None) -> None:
         if self.live and self.live.running:
             self.app.open_url(self.live.url)

src/frameport/ui/views/monitor.py

@@ -146,6 +146,7 @@ class MonitorView:
         self.stopped = True          # not subscribed to the app's monitor hub (the tab isn't shown)
         self.root = None
         self.history = M.History()
+        self.smooth = M.Smoother()  # the big numbers (sparklines keep their per-second averages)
         self.static: dict = {}
         self.procs: list[dict] = []
         self.sort_key, self.descending = "cpu", True
@@ -448,7 +449,8 @@ class MonitorView:
         self.last_sample = s
         for name, value in M.series_of(s).items():
             self.history.add(name, value, s.get("t"))
-        changed = [self._apply_tiles(s), self._apply_game(s), self._apply_details(s)]
+        shown = self.smooth.sample(s)
+        changed = [self._apply_tiles(shown), self._apply_game(shown), self._apply_details(s)]
         if "procs" in s:
             self.procs = s.get("procs") or []
             changed.append(self._bind_rows(update=False))

src/frameport/ui/views/screenshots.py

@@ -441,24 +441,9 @@ class ScreenshotsView:
         self.app.run_bg(self._take_bg)
 
     def _take_bg(self) -> None:
-        from ...install import screenshots
-
-        app = self.app
         try:
-            r = screenshots.take(app.target.frame)
-            if r.get("taken"):
-                app.toast(tr("Screenshot taken"))
+            if take_screenshot(self.app):
                 self.load()
-            elif r.get("reason") == "steamvr":
-                app.toast(tr("SteamVR isn't running on the Frame: put the headset on, then take the screenshot."),
-                          error=True)
-            elif r.get("reason") == "capture" or r.get("hmd") == "Standby":
-                app.toast(tr("The headset is asleep: put it on, then take the screenshot."), error=True)
-            else:
-                app.toast(tr("The Frame didn't save a screenshot ({why}). Try again.").format(
-                    why=r.get("reason") or tr("no reason given")), error=True)
-        except Exception as exc:  # noqa: BLE001
-            app.toast(tr("Couldn't take a screenshot: {error}").format(error=explain(exc)), error=True)
         finally:
             self.take_btn.disabled = False
             C.update(self.take_btn)
@@ -530,3 +515,26 @@ class ScreenshotsView:
         C.confirm(self.app.page, tr_n("Delete {n} screenshot?", "Delete {n} screenshots?", len(shots)),
                   tr("They're deleted on the Frame for good. Steam's own list may show them until Steam "
                      "restarts."), tr("Delete"), go, danger=True)
+
+
+def take_screenshot(app) -> bool:
+    """A Steam screenshot of the headset's view, saved on the Frame (Screenshots tab and Live view; runs on a
+    background thread, waits while the Frame saves it). Tells the user how it went; True when one was taken."""
+    from ...install import screenshots
+
+    try:
+        r = screenshots.take(app.target.frame)
+        if r.get("taken"):
+            app.toast(tr("Screenshot taken"))
+            return True
+        if r.get("reason") == "steamvr":
+            app.toast(tr("SteamVR isn't running on the Frame: put the headset on, then take the screenshot."),
+                      error=True)
+        elif r.get("reason") == "capture" or r.get("hmd") == "Standby":
+            app.toast(tr("The headset is asleep: put it on, then take the screenshot."), error=True)
+        else:
+            app.toast(tr("The Frame didn't save a screenshot ({why}). Try again.").format(
+                why=r.get("reason") or tr("no reason given")), error=True)
+    except Exception as exc:  # noqa: BLE001
+        app.toast(tr("Couldn't take a screenshot: {error}").format(error=explain(exc)), error=True)
+    return False

src/frameport/ui/views/settings.py

@@ -94,12 +94,16 @@ class SettingsView:
 
     def installing(self) -> ft.Control:
         from ...core import library
+        from ...install.installer import upload_threads
 
         def changed(e):
             library.set_setting("install.launch_test", bool(e.control.value))
         def keep_changed(e):
             library.set_setting("build.keep_copies", bool(e.control.value))
 
+        def threads_changed(e):
+            library.set_setting("install.upload_threads", upload_threads(e.control.value))
+
         def video_changed(e):
             library.set_setting("video.hw_decode", bool(e.control.value))
             target = self.app.target if self.app.frame_state == "connected" else None
@@ -120,7 +124,12 @@ class SettingsView:
                                              value=bool(library.setting("video.hw_decode", True)),
                                              on_change=video_changed), expand=True),
                         C.help_icon("hw_video_decode")], spacing=T.S1)
-        return ft.Column([launch, keep, video,
+        parallel = C.dropdown(label=tr("Parallel uploads"), value=str(upload_threads()), width=T.px(240),
+                              options=[ft.DropdownOption(str(n), str(n)) for n in range(1, 9)],
+                              on_select=threads_changed)
+        return ft.Column([launch, keep, video, parallel,
+                          C.meta(tr("Large files upload together using OpenSSH when available. "
+                                    "Default: 3. Lower this on a busy network.")),
                           C.ghost(tr("Remove converted copies now"), ft.Icons.CLEANING_SERVICES_OUTLINED, clean,
                                   tooltip=tr("Your own game files aren't touched."))],
                          spacing=T.S2, horizontal_alignment=ft.CrossAxisAlignment.START)
@@ -423,7 +432,11 @@ class SettingsView:
         self._mark(key)
         C.update(*self.index.values())
         if self.page_col is not None:
-            await self.page_col.scroll_to(scroll_key=scroll_key(key), duration=0 if self.app.reduce_motion else 300)
+            try:
+                await self.page_col.scroll_to(scroll_key=scroll_key(key),
+                                              duration=0 if self.app.reduce_motion else 300)
+            except RuntimeError:  # the page left the screen (or the window closed) before the scroll ran
+                pass
 
     def build(self) -> ft.Control:
         app = self.app

tests/test_agent.py

@@ -1053,6 +1053,35 @@ def test_launch_re_adds_a_forgotten_devkit_entry_live(monkeypatch, tmp_path):
     got = a.cmd_launch({"package": "com.x.y"})  # no NOT_IN_LIBRARY (whose repair restarts Steam)
     assert got["via"] == "devkit" and got["steam"]["appid"] == 333
 
+def test_library_falls_back_to_a_devkit_entry_when_steam_drops_the_shortcut(monkeypatch, tmp_path):
+    # this Frame's Steam drops every shortcuts.vdf entry on restart (GitHub #41): "Add to Steam library" failed every
+    # time with "Steam removed the new library entry again"; the devkit entry is the one Steam keeps
+    a = load_agent(monkeypatch, tmp_path)
+    anchor = tmp_path / "Applications/quest-frame/com.x.y"
+    anchor.mkdir(parents=True)
+    (anchor / "deployment.json").write_text(json.dumps({"package": "com.x.y", "appid": 1, "title": "X", "base": "b"}))
+    (tmp_path / ".local/share/Steam/userdata/42/config").mkdir(parents=True)
+    monkeypatch.setattr(a, "library_users", lambda: ["42"])
+    monkeypatch.setattr(a, "game_running", lambda: False)
+    monkeypatch.setattr(a, "desktop_mode", lambda: False)
+    monkeypatch.setattr(a, "stop_steam", lambda: True)
+    monkeypatch.setattr(a, "start_steam", lambda s: None)
+    monkeypatch.setattr(a, "shortcuts_lost", lambda users, pkgs, wait=25: list(pkgs))
+    registered = []
+    monkeypatch.setattr(a, "devkit_register", lambda pkg: registered.append(pkg) or 333)
+    a.shortcuts_worker(json.dumps({"packages": ["com.x.y"], "remove": []}))
+    status = json.load(open(a.STATUS_FILE))
+    assert registered == ["com.x.y"] and status["state"] == "done" and not status["errors"]
+    assert status["added"] == [{"package": "com.x.y", "appid": 333, "expected": 1, "via": "devkit"}]
+
+    monkeypatch.setattr(a, "devkit_register", lambda pkg: (_ for _ in ()).throw(a.AgentError("no answer")))
+    (tmp_path / ".local/share/Steam/userdata/42/config/shortcuts.vdf").unlink()  # Steam dropped it, as above
+    a.shortcuts_worker(json.dumps({"packages": ["com.x.y"], "remove": []}))
+    status = json.load(open(a.STATUS_FILE))
+    assert not status["added"] and "Steam removed the new library entry" in status["errors"][0]
+    assert "no answer" in status["errors"][0]
+
+
 def test_shortcuts_lost_after_steam_restart(monkeypatch, tmp_path):
     a = load_agent(monkeypatch, tmp_path)
     anchor = tmp_path / "Applications/quest-frame/com.x.y"

tests/test_app_source_errors.py

@@ -0,0 +1,85 @@
+"""Missing original APK/data files fail before tools or reanalysis run (#278)."""
+from unittest.mock import Mock
+
+import pytest
+
+from frameport import pipeline
+from frameport.errors import MissingGameSource, explain
+
+
+@pytest.mark.parametrize("as_is", [False, True])
+@pytest.mark.parametrize("directory", [False, True])
+def test_build_missing_apk_before_tools(tmp_path, monkeypatch, as_is, directory):
+    apk = tmp_path / "base.apk"
+    if directory:
+        apk.mkdir()
+    entry = {"package": "com.example.game", "apk": str(apk), "recipe": {"as_is": as_is}}
+    monkeypatch.setattr(pipeline.library, "game", lambda package: entry)
+    refresh, build = Mock(), Mock()
+    monkeypatch.setattr(pipeline, "refresh_analyses", refresh)
+    monkeypatch.setattr(pipeline.builder, "build", build)
+    with pytest.raises(MissingGameSource) as caught:
+        pipeline.build_game(entry["package"], Mock())
+    assert explain(caught.value) == (
+        f"The game's APK isn't at {apk} any more. Add the game again from the folder that has it.")
+    refresh.assert_not_called()
+    build.assert_not_called()
+
+
+def test_changed_folder_contents_dont_block(tmp_path):
+    # a folder scanned without picked files: newer OBBs may replace the ones listed at scan time
+    apk = tmp_path / "base.apk"
+    apk.write_bytes(b"apk")
+    (tmp_path / "obb").mkdir()
+    entry = {"package": "com.example.game", "apk": str(apk), "data_dir": str(tmp_path / "obb"),
+             "data_manifest": {"main.1.com.example.game.obb": 3}}
+    assert pipeline.check_source(entry).apk == apk
+
+
+@pytest.mark.parametrize("mode", ["folder", "selected"])
+def test_missing_saved_data(tmp_path, mode):
+    apk = tmp_path / "base.apk"
+    apk.write_bytes(b"apk")
+    data = tmp_path / "obb"
+    entry = {"package": "com.example.game", "apk": str(apk), "data_dir": str(data)}
+    if mode != "folder":
+        data.mkdir()
+        entry["data_files"] = ["main.obb"]
+    with pytest.raises(MissingGameSource) as caught:
+        pipeline.check_source(entry)
+    assert "data" in explain(caught.value) and "Add the game again" in explain(caught.value)
+    if mode == "folder":
+        data.mkdir()
+    else:
+        (data / "main.obb").write_bytes(b"obb")
+    assert pipeline.source_of(entry).apk == apk
+
+
+def test_existing_missing_obb_warning_is_nonblocking(tmp_path):
+    apk = tmp_path / "base.apk"
+    apk.write_bytes(b"apk")
+    entry = {"package": "com.example.game", "apk": str(apk), "data_dir": None, "data_bytes": 0,
+             "analysis": {"extra": {"expects_obb": True}}}
+    assert pipeline.missing_obb(entry)
+    assert pipeline.source_of(entry).data_dir is None
+
+
+@pytest.mark.parametrize("missing", ["apk", "folder", "file"])
+def test_source_of_allows_missing_original_files(tmp_path, missing):
+    apk = tmp_path / "base.apk"
+    data = tmp_path / "obb"
+    if missing != "apk":
+        apk.write_bytes(b"apk")
+    if missing != "folder":
+        data.mkdir()
+    entry = {"package": "com.example.game", "apk": str(apk), "data_dir": str(data),
+             "data_files": ["main.obb"]}
+    src = pipeline.source_of(entry)
+    assert src.apk == apk and src.data_dir == data
+
+
+def test_prepare_as_is_checks_source_before_analysis(tmp_path, monkeypatch):
+    entry = {"package": "com.example.game", "apk": str(tmp_path / "base.apk")}
+    monkeypatch.setattr(pipeline.library, "game", lambda package: entry)
+    with pytest.raises(MissingGameSource):
+        pipeline.prepare_as_is(entry["package"], Mock())

tests/test_display_diag.py

@@ -52,7 +52,9 @@ def test_window_events_are_cached_without_running_queries(monkeypatch, caplog):
 ])
 def test_event_query_distinguishes_empty_results_from_failures(monkeypatch, response, status):
     def run(args, **kwargs):
-        assert args[:4] == ["powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive"]
+        assert args[0].lower().endswith(("powershell.exe", "powershell"))
+        assert args[1:4] == ["-NoLogo", "-NoProfile", "-NonInteractive"]
+        assert not any(k.upper() == "PSMODULEPATH" for k in kwargs["env"])  # pwsh 7's modules break 5.1
         assert kwargs["timeout"] == 5 and kwargs["creationflags"] == 0x08000000
         assert "-FilterXPath" in args[-1] and "-MaxEvents 60" in args[-1]
         assert ".Message" not in args[-1]  # event metadata, not unrelated free text or device IDs

tests/test_errors.py

@@ -41,3 +41,46 @@ def test_other_errors_keep_their_message():
     assert explain(auth).startswith("This Frame isn't set up") and not is_connection_error(auth)
     assert explain(AgentFailed("Lepton is not installed (Developer Mode → …)")).startswith("Lepton is not installed")
     assert explain(RuntimeError()) == "RuntimeError"
+
+
+@pytest.mark.parametrize("wrapped", [False, True])
+def test_certificate_verification_explanation(wrapped):
+    import ssl
+
+    import requests
+
+    exc = ssl.SSLCertVerificationError(1, "self-signed certificate in certificate chain")
+    if wrapped:
+        exc = requests.exceptions.SSLError(exc)
+    message = explain(exc)
+    assert "HTTPS certificate couldn't be verified" in message
+    assert "another network" in message and "HTTPS scanning" in message
+    assert not is_connection_error(exc)
+
+
+def test_unrelated_ssl_error_keeps_message():
+    import requests
+
+    assert explain(requests.exceptions.SSLError("TLS protocol mismatch")) == "TLS protocol mismatch"
+
+
+@pytest.mark.parametrize("stage", ["metadata", "archive"])
+def test_java_certificate_failure_reaches_explain(monkeypatch, stage):
+    from unittest.mock import Mock
+
+    import requests
+
+    from frameport.tools import toolchain
+
+    exc = requests.exceptions.SSLError("[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed")
+    get = Mock(side_effect=exc)
+    if stage == "archive":
+        get = Mock(return_value=Mock(json=lambda: [{"binary": {"package": {
+            "link": "https://example.invalid/java.tar.gz", "name": "java.tar.gz", "checksum": "unused"}},
+            "version": {"semver": "test"}}]))
+        monkeypatch.setattr(toolchain.cache, "download", Mock(side_effect=exc))
+    monkeypatch.setattr(toolchain.cache, "http_get", get)
+    with pytest.raises(requests.exceptions.SSLError) as caught:
+        toolchain.install_java()
+    assert "another network" in explain(caught.value)
+    assert "verify" not in get.call_args.kwargs

tests/test_game_update.py

@@ -0,0 +1,519 @@
+"""Update classification and the operations it must skip, including persisted live settings."""
+from pathlib import Path
+
+import pytest
+from test_agent import load_agent
+
+from frameport import pipeline
+from frameport.core import library
+from frameport.core.events import Reporter
+from frameport.game_update import apk_recipe_fingerprint, configuration, configuration_fingerprint, plan_update
+from frameport.ui.components import install_state
+
+PKG = "com.example.update"
+
+
+def game_and_dep(patches=None):
+    recipe = {"package": PKG, "source": "user", "patches": patches or {"adapter.scale": {"value": 1.5}}}
+    game = {"package": PKG, "title": "Example", "recipe": recipe, "analysis": {"version": "1"},
+            "build": {"apk": "/missing/converted.apk", "sha256": "apk-a", "ok": True,
+                      "source_version": "1", "apk_recipe_fp": apk_recipe_fingerprint(recipe, PKG)}}
+    dep = {"package": PKG, "base": "/frame/game", "appid": 42, "sha256": "apk-a", "apk_present": True,
+           "configuration_fp": configuration_fingerprint(recipe, PKG),
+           "configuration": configuration(recipe, PKG), "data_manifest": {"main.obb": 4}}
+    return game, dep
+
+
+def test_custom_recipe_and_catalog_metadata_do_not_force_update():
+    game, dep = game_and_dep()
+    game["recipe"].update(catalog_rev="new", notes="changed", title="New", source="user")
+    game["catalog_update"] = "newer-tested-recipe"
+    assert not plan_update(game, dep).changed
+    assert install_state(game, {"installed": [dep]}) == "installed"
+
+
+def test_runtime_parameter_change_and_removal_do_not_rebuild():
+    game, dep = game_and_dep()
+    game["recipe"]["patches"]["adapter.scale"]["value"] = 1.2
+    plan = plan_update(game, dep)
+    assert plan.configure and not plan.rebuild and not plan.apk and not plan.launch_test
+    game["recipe"]["patches"].clear()
+    assert configuration(game["recipe"], PKG)["settings"]["scale"] == 1.0
+    assert plan_update(game, dep).configure and not plan_update(game, dep).rebuild
+    dep["configuration_fp"] = configuration_fingerprint(game["recipe"], PKG)
+    assert not plan_update(game, dep).changed
+
+
+@pytest.mark.parametrize("patch", ["frame.unity_text_input", "device.foveation", "adapter.controller_models",
+                                   "adapter.surface_native", "adapter.zink_shader_dump"])
+def test_apk_support_changes_require_rebuild(patch):
+    game, dep = game_and_dep()
+    game["recipe"]["patches"][patch] = {}
+    assert plan_update(game, dep).rebuild
+    assert plan_update(game, dep).launch_test
+
+
+def test_alternate_variant_can_reuse_an_existing_build():
+    game, dep = game_and_dep()
+    game["build"].update(alt_sha256="apk-b", alt_apk="/missing/alt.apk")
+    game["recipe"]["use_alt"] = True
+    plan = plan_update(game, dep)
+    assert plan.apk and not plan.rebuild
+    dep["sha256"] = "apk-b"
+    assert not plan_update(game, dep).rebuild
+    game["build"].pop("alt_sha256")
+    assert plan_update(game, dep).rebuild
+
+
+def test_data_and_artwork_have_separate_actions():
+    game, dep = game_and_dep()
+    plan = plan_update(game, dep, data_manifest={"main.obb": 5})
+    assert plan.data and plan.launch_test and not plan.apk and not plan.rebuild
+    assert not plan_update(game, dep, data_manifest={"main.obb": 5}, apk_only=True).data
+    game["steam_art_stale"] = True
+    plan = plan_update(game, dep)
+    assert plan.artwork and plan.shortcut and not plan.launch_test
+
+
+def test_legacy_and_source_changes_use_full_path():
+    game, dep = game_and_dep()
+    game["build"].pop("apk_recipe_fp")
+    assert plan_update(game, dep).rebuild
+    game, dep = game_and_dep()
+    game["analysis"]["version"] = "2"
+    assert plan_update(game, dep).rebuild
+
+
+def test_superseded_setting_does_not_stay_pending():
+    game, dep = game_and_dep({"adapter.haptic_fix": {"value": 1}})
+    game["build"]["superseded"] = {"adapter.haptic_fix": "upstream"}
+    game["build"]["apk_recipe_fp"] = apk_recipe_fingerprint(game["recipe"], PKG, game["build"]["superseded"])
+    dep["configuration_fp"] = configuration_fingerprint(game["recipe"], PKG, game["build"]["superseded"])
+    assert not plan_update(game, dep).changed
+    assert configuration(game["recipe"], PKG, game["build"]["superseded"])["settings"]["haptic_fix"] == 0
+    game["recipe"]["patches"].clear()  # removing an omitted workaround is also a no-op
+    assert not plan_update(game, dep).changed
+
+
+class Target:
+    label = "test-frame"
+
+    def __init__(self, dep):
+        self.dep, self.calls = dep, []
+
+    def installed(self):
+        return [self.dep]
+
+    def update_existing(self, entry, dep, plan, recipe, reporter, manifest=None):
+        self.calls.append("configure" if not plan.data else "data")
+        return {"base": dep["base"], "appid": dep["appid"]}
+
+    def update_steam_art(self, package, reporter, title=None):
+        self.calls.append("artwork")
+
+    def install(self, *args, **kwargs):
+        self.calls.append("install")
+        return {"base": self.dep["base"], "appid": self.dep["appid"]}
+
+    def add_to_library(self, *args):
+        self.calls.append("shortcut")
+
+
+def store_game(monkeypatch, game):
+    monkeypatch.setattr(library, "_migrate", lambda data: False)
+    library.upsert_game(PKG, **{k: v for k, v in game.items() if k != "package"}, apk="/missing/source.apk")
+    monkeypatch.setattr(pipeline, "_find_late_data", lambda entry, rep: entry)
+    monkeypatch.setattr(pipeline, "_build_inputs_changed", lambda entry: False)
+    monkeypatch.setattr(pipeline, "build_game", lambda *a, **k: pytest.fail("unnecessary rebuild"))
+
+
+def test_pipeline_configure_without_any_local_apk(monkeypatch):
+    game, dep = game_and_dep()
+    game["recipe"]["patches"]["adapter.scale"]["value"] = 1.2
+    store_game(monkeypatch, game)
+    target = Target(dep)
+    result = pipeline.install_game(PKG, target, Reporter())
+    assert target.calls == ["configure", "shortcut"]
+    assert result["launch_test_required"] is False
+    assert result["shortcut_required"] is True
+
+
+def test_pipeline_noop_and_artwork_skip_build_and_install(monkeypatch):
+    game, dep = game_and_dep()
+    store_game(monkeypatch, game)
+    target = Target(dep)
+    result = pipeline.install_game(PKG, target, Reporter())
+    # nothing to send, but Steam may have lost the shortcut since: the agent checks it (no restart if present)
+    assert target.calls == ["shortcut"] and result["launch_test_required"] is False
+    target.calls.clear()
+    library.update_game(PKG, lambda entry: entry.update(steam_art_stale=True))
+    pipeline.install_game(PKG, target, Reporter())
+    assert target.calls == ["artwork", "shortcut"]
+
+
+def test_pipeline_artwork_that_rewrote_the_shortcut_is_not_added_twice(monkeypatch):
+    game, dep = game_and_dep()
+    store_game(monkeypatch, game)
+    target = Target(dep)
+    target.update_steam_art = lambda *a, **k: (target.calls.append("artwork"), {"library": True})[1]
+    library.update_game(PKG, lambda entry: entry.update(steam_art_stale=True))
+    result = pipeline.install_game(PKG, target, Reporter())
+    assert target.calls == ["artwork"] and result["shortcut_required"] is False
+
+
+def test_pipeline_cli_mode_asks_for_the_shortcut_check(monkeypatch):
+    game, dep = game_and_dep()
+    store_game(monkeypatch, game)
+    target = Target(dep)
+    result = pipeline.install_game(PKG, target, Reporter(), add_to_library=False)
+    assert target.calls == [] and result["shortcut_required"] is True
+
+
+def test_pipeline_changed_data_without_local_apk(monkeypatch, tmp_path):
+    game, dep = game_and_dep()
+    data = tmp_path / "data"
+    data.mkdir()
+    (data / "main.obb").write_bytes(b"12345")
+    game["data_dir"] = str(data)
+    store_game(monkeypatch, game)
+    target = Target(dep)
+    result = pipeline.install_game(PKG, target, Reporter())
+    assert target.calls == ["data", "shortcut"] and result["launch_test_required"] is True
+    target.calls.clear()
+    pipeline.install_game(PKG, target, Reporter(), apk_only=True)
+    assert target.calls == ["shortcut"]
+
+
+def installed_agent(monkeypatch, tmp_path):
+    agent = load_agent(monkeypatch, tmp_path)
+    base = tmp_path / "Applications/quest-frame" / PKG
+    (base / "lepton-app").mkdir(parents=True)
+    (base / "lepton-app/game.apk").write_bytes(b"apk")
+    dep = {"package": PKG, "title": "Example", "base": str(base), "appid": 42, "sha256": "apk-a",
+           "tags": ["Favorite"], "apk": "original.apk", "apk_size": 3, "data_manifest": {"modded.obb": 4}}
+    dep["apk_stat"] = {"size": 3, "mtime_ns": (base / "lepton-app/game.apk").stat().st_mtime_ns}
+    agent.write_deployment(PKG, dep)
+    monkeypatch.setattr(agent, "new_base", lambda args, pkg, deployment: (deployment["base"], 10 << 30))
+    monkeypatch.setattr(agent, "container_running", lambda appid: False)
+    monkeypatch.setattr(agent, "lepton_path", lambda: ("/lepton", None))
+    monkeypatch.setattr(agent, "install_controller_models", lambda *a: {"ok": True})
+    monkeypatch.setattr(agent, "write_launcher", lambda *a: None)
+    monkeypatch.setattr(agent, "sync_game_config", lambda *a: {})
+    return agent, base, dep
+
+
+def test_agent_configuration_preserves_apk_data_tags_and_ignores_staging(monkeypatch, tmp_path):
+    agent, base, _ = installed_agent(monkeypatch, tmp_path)
+    pending = base / "incoming"
+    pending.mkdir()
+    (pending / "game.apk").write_bytes(b"pending different apk")
+    recipe = {"patches": {"adapter.scale": {"value": 1.5}}}
+    applied = configuration(recipe, PKG)
+    result = agent.cmd_configure({"package": PKG, "apk_sha256": "apk-a", "settings": applied["settings"],
+                                  "configuration": applied, "configuration_fp": configuration_fingerprint(recipe, PKG),
+                                  "recipe": {"patches": ["adapter.scale"]}})
+    assert "data_manifest" not in result["deployment"]
+    dep = agent.deployment(PKG)
+    assert dep["tags"] == ["Favorite"] and dep["apk"] == "original.apk" and dep["sha256"] == "apk-a"
+    assert dep["data_manifest"] == {"modded.obb": 4}
+    assert (base / "lepton-app/game.apk").read_bytes() == b"apk"
+    assert (pending / "game.apk").exists()
+    # Live writes update the applied baseline, including resetting a deleted recipe override.
+    agent.cmd_set_settings({"package": PKG, "settings": {"scale": 1.0}})
+    assert agent.deployment(PKG)["configuration_fp"] == configuration_fingerprint({"patches": {}}, PKG)
+    settings_conf = (base / "settings.conf").read_text()
+    for bad in (".", "1.2.3", "-", "abc"):  # refused before anything is written
+        with pytest.raises(agent.AgentError):
+            agent.cmd_set_settings({"package": PKG, "settings": {"scale": bad}})
+    assert (base / "settings.conf").read_text() == settings_conf
+
+
+@pytest.mark.parametrize("failure", ["running", "missing", "different", "drive"])
+def test_agent_refuses_unsafe_configurations(monkeypatch, tmp_path, failure):
+    agent, base, original = installed_agent(monkeypatch, tmp_path)
+    sha = "apk-a"
+    if failure == "running":
+        monkeypatch.setattr(agent, "container_running", lambda appid: True)
+    elif failure == "missing":
+        (base / "lepton-app/game.apk").unlink()
+    elif failure == "different":
+        sha = "other-apk"
+    else:
+        def unavailable(*args):
+            raise agent.AgentError("drive missing")
+        monkeypatch.setattr(agent, "new_base", unavailable)
+    with pytest.raises(agent.AgentError):
+        agent.cmd_configure({"package": PKG, "apk_sha256": sha, "settings": {"scale": 1.5}})
+    assert agent.deployment(PKG) == original
+    assert not (base / "settings.conf").exists()
+
+
+def test_generated_config_removal_restores_original_and_preserves_user_changes(monkeypatch, tmp_path):
+    agent, base, _ = installed_agent(monkeypatch, tmp_path)
+    files = Path(agent.data_files_dir(str(base), PKG))
+    files.mkdir(parents=True)
+    (files / "user.cfg").write_text("original")
+    args = {"package": PKG, "apk_sha256": "apk-a", "files": {"user.cfg": "managed"}}
+    agent.cmd_configure(args)
+    agent.cmd_configure({**args, "files": {}})
+    assert (files / "user.cfg").read_text() == "original"
+    agent.cmd_configure(args)
+    (files / "user.cfg").write_text("user mod")
+    agent.cmd_configure({**args, "files": {}})
+    assert (files / "user.cfg").read_text() == "user mod"
+
+
+def test_failed_configuration_does_not_record_success(monkeypatch, tmp_path):
+    agent, base, original = installed_agent(monkeypatch, tmp_path)
+    def fail(*args):
+        raise RuntimeError("configuration sync failed")
+    monkeypatch.setattr(agent, "sync_game_config", fail)
+    with pytest.raises(RuntimeError):
+        agent.cmd_configure({"package": PKG, "apk_sha256": "apk-a", "settings": {"scale": 1.5},
+                             "configuration_fp": "new"})
+    assert agent.deployment(PKG) == original
+
+
+def test_generated_paths_checked_before_writing_settings(monkeypatch, tmp_path):
+    agent, base, original = installed_agent(monkeypatch, tmp_path)
+    with pytest.raises(agent.AgentError):
+        agent.cmd_configure({"package": PKG, "apk_sha256": "apk-a", "settings": {"scale": 1.5},
+                             "files": {"../../escape": "bad"}})
+    assert agent.deployment(PKG) == original
+    assert not (base / "settings.conf").exists()
+
+
+def test_build_inputs_ignore_unrelated_native_assets_and_detect_source_changes(monkeypatch, tmp_path):
+    import zipfile
+
+    from frameport.core import paths
+    from frameport.tools import toolchain
+
+    game, _ = game_and_dep()
+    source = tmp_path / "source.apk"
+    source.write_bytes(b"source")
+    game["apk"] = str(source)
+    native = tmp_path / "artifacts"
+    (native / "arm64-v8a").mkdir(parents=True)
+    (native / "arm64-v8a/chosen.so").write_bytes(b"native")
+    manifest = native / "SHA256SUMS"
+    manifest.write_text("a" * 64 + "  ./arm64-v8a/chosen.so\n")
+    output = tmp_path / "output.apk"
+    with zipfile.ZipFile(output, "w") as archive:
+        archive.writestr("lib/arm64-v8a/chosen.so", b"native")
+    monkeypatch.setattr(paths, "artifacts_dir", lambda: native)
+    monkeypatch.setattr(toolchain, "overport_jar", lambda: None)
+    game["build"].update(pipeline._build_record(game, output))
+    assert not pipeline._build_inputs_changed(game)
+    manifest.write_text(manifest.read_text() + "b" * 64 + "  ./arm64-v8a/unrelated.so\n")
+    assert not pipeline._build_inputs_changed(game)
+    manifest.write_text("c" * 64 + "  ./arm64-v8a/chosen.so\n")
+    assert pipeline._build_inputs_changed(game)
+    manifest.write_text("a" * 64 + "  ./arm64-v8a/chosen.so\n")
+    source.write_bytes(b"different source, same version")
+    assert pipeline._build_inputs_changed(game)
+
+
+def test_stage_timings_include_the_final_stage(monkeypatch):
+    from frameport.core import events
+
+    now = [10.0]
+    monkeypatch.setattr(events.time, "monotonic", lambda: now[0])
+    reporter = Reporter()
+    reporter.stage("Build")
+    now[0] += 3
+    reporter.stage("Upload")
+    now[0] += 2
+    assert reporter.stage_timings() == {"Build": 3, "Upload": 2}
+    assert reporter.stage_timings() == {"Build": 3, "Upload": 2}  # snapshots do not double-count
+
+
+def test_artwork_update_transfers_only_changed_slot(monkeypatch, tmp_path):
+    from frameport.artwork import sources, steam
+    from frameport.install import installer
+
+    portrait, hero = tmp_path / "portrait.png", tmp_path / "hero.png"
+    portrait.write_bytes(b"portrait")
+    hero.write_bytes(b"old hero")
+    art = {"portrait": portrait, "hero": hero}
+    monkeypatch.setattr(steam, "steam_set_for", lambda package: art)
+    monkeypatch.setattr(sources, "icon_source", lambda package: "custom")
+    manifest = installer.art_manifest(PKG, art)
+    hero.write_bytes(b"new hero")
+    calls = []
+    dep = {"package": PKG, "title": "Example", "anchor": "/frame/anchor", "artwork_manifest": manifest}
+
+    class Frame:
+        def agent(self, command, **args):
+            calls.append(command)
+            return {"games": [dep]} if command == "list_installed" else {"verified": True}
+
+        def run(self, command):
+            calls.append("mkdir")
+
+        def put(self, local, remote, **kwargs):
+            calls.append(local.name)
+    monkeypatch.setattr(installer, "add_to_steam", lambda *a: calls.append("shortcut"))
+    installer.update_steam_art(Frame(), PKG, Reporter(), title="Example")
+    assert "hero.png" in calls and "portrait.png" not in calls
+    assert "record_artwork" in calls and "shortcut" in calls
+    calls.clear()
+    dep["artwork_manifest"] = installer.art_manifest(PKG, art)
+    installer.update_steam_art(Frame(), PKG, Reporter(), title="Example")
+    assert calls == ["list_installed"]
+
+
+def test_artwork_update_without_a_recorded_manifest_starts_clean(monkeypatch, tmp_path):
+    """Installs before agent v86 have no artwork_manifest: an old portrait.jpg must not stay next to portrait.png."""
+    from frameport.artwork import sources, steam
+    from frameport.install import installer
+
+    portrait = tmp_path / "portrait.png"
+    portrait.write_bytes(b"portrait")
+    monkeypatch.setattr(steam, "steam_set_for", lambda package: {"portrait": portrait})
+    monkeypatch.setattr(sources, "icon_source", lambda package: "custom")
+    monkeypatch.setattr(installer, "send_icon_source", lambda *a: None)
+    monkeypatch.setattr(installer, "add_to_steam", lambda *a: {"state": "done"})
+    dep = {"package": PKG, "title": "Example", "anchor": "/frame/anchor"}
+    commands, puts = [], []
+
+    class Frame:
+        def agent(self, command, **args):
+            return {"games": [dep]} if command == "list_installed" else {"verified": True}
+
+        def run(self, command):
+            commands.append(command)
+
+        def put(self, local, remote, **kwargs):
+            puts.append(remote)
+
+    result = installer.update_steam_art(Frame(), PKG, Reporter(), title="Example")
+    assert commands[0] == "rm -rf -- '/frame/anchor/artwork'" and commands[1].startswith("mkdir -p")
+    assert puts == ["/frame/anchor/artwork/portrait.png"] and result["library"] is True
+
+
+def test_agent_artwork_manifest_requires_matching_uploaded_content(monkeypatch, tmp_path):
+    agent, base, _ = installed_agent(monkeypatch, tmp_path)
+    art = base / "artwork"
+    art.mkdir()
+    (art / "hero.png").write_bytes(b"hero")
+    manifest = {"hero.png": agent.sha256_file(str(art / "hero.png"))}
+    assert agent.cmd_record_artwork({"package": PKG, "manifest": manifest})["verified"]
+    with pytest.raises(agent.AgentError):
+        agent.cmd_record_artwork({"package": PKG, "manifest": {"hero.png": "f" * 64}})
+    assert agent.deployment(PKG)["artwork_manifest"] == manifest
+
+
+def test_apk_only_finalize_does_not_apply_staged_data_or_artwork(monkeypatch, tmp_path):
+    agent, base, _ = installed_agent(monkeypatch, tmp_path)
+    (base / "lepton-app/obb").mkdir()
+    (base / "lepton-app/obb/main.obb").write_bytes(b"user mod")
+    incoming = base / "incoming"
+    (incoming / "obb").mkdir(parents=True)
+    (incoming / "obb/main.obb").write_bytes(b"old staged copy")
+    (incoming / "game.apk").write_bytes(b"new apk")
+    (base / "incoming-artwork").mkdir()
+    (base / "incoming-artwork/hero.png").write_bytes(b"old staged art")
+    monkeypatch.setattr(agent, "cmd_prepare", lambda args: {"base": str(base), "anchor": str(base), "appid": 42,
+                                                          "incoming": str(incoming), "lepton": "/lepton"})
+    result = agent.cmd_finalize({"package": PKG, "title": "Example", "preserve_data": True,
+                                 "consume_artwork": False,
+                                 "apk_sha256": agent.sha256_file(str(incoming / "game.apk"))})
+    assert result["moved_data_files"] == 0
+    assert (base / "lepton-app/obb/main.obb").read_bytes() == b"user mod"
+    assert (incoming / "obb/main.obb").read_bytes() == b"old staged copy"
+    assert not (base / "artwork").exists()
+    assert (base / "incoming-artwork/hero.png").exists()
+
+
+def test_data_digest_fast_path_and_subset_manifest():
+    from frameport.game_update import fingerprint
+
+    game, dep = game_and_dep()
+    dep.pop("data_manifest")
+    dep["data_fp"] = fingerprint({"main.obb": 4})
+    assert not plan_update(game, dep, data_manifest={"main.obb": 4}).data
+    assert plan_update(game, dep, data_manifest={"main.obb": 5}).data
+    dep["data_manifest"] = {"main.obb": 4, "unused.obb": 10}
+    assert not plan_update(game, dep, data_manifest={"main.obb": 4}).data
+
+
+def test_routine_deployment_summary_excludes_large_manifests():
+    import importlib.util
+
+    path = Path(__file__).resolve().parents[1] / "agent/frameport_agent.py"
+    spec = importlib.util.spec_from_file_location("frameport_agent_summary", path)
+    agent = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(agent)
+    full = {"package": PKG, "data_fp": "digest", "configuration_fp": "runtime", "sha256": "apk",
+            "data_manifest": {"main.obb": 123}, "configuration": {"settings": {}}, "managed_config_files": {}}
+    summary = agent.deployment_summary(full)
+    assert summary == {"package": PKG, "data_fp": "digest", "configuration_fp": "runtime", "sha256": "apk"}
+    assert "data_manifest" in full  # summarizing does not mutate the durable record
+
+
+@pytest.mark.parametrize("changed_data, force, preserve", [(False, False, True), (True, False, False),
+                                                           (False, True, False)])
+def test_apk_recipe_update_preserves_unchanged_source_data(monkeypatch, tmp_path, changed_data, force, preserve):
+    game, dep = game_and_dep()
+    data = tmp_path / "data"
+    data.mkdir()
+    (data / "main.obb").write_bytes(b"12345" if changed_data else b"1234")
+    game["data_dir"] = str(data)
+    game["recipe"]["patches"]["frame.unity_text_input"] = {}
+    store_game(monkeypatch, game)
+    output = tmp_path / "built.apk"
+    output.write_bytes(b"checked new build")
+    def build(package, reporter):
+        current = library.game(package)
+        library.update_game(package, lambda entry: entry["build"].update(
+            apk=str(output), sha256=pipeline.builder.sha256(output),
+            apk_recipe_fp=apk_recipe_fingerprint(current["recipe"], package)))
+        return {"ok": True}
+    monkeypatch.setattr(pipeline, "build_game", build)
+    target = Target(dep)
+    installed = []
+    def install(*args, **kwargs):
+        installed.append(args[6])
+        return {"base": dep["base"], "appid": dep["appid"]}
+    target.install = install
+    result = pipeline.install_game(PKG, target, Reporter(), force=force)
+    assert installed == [preserve]
+    assert result["launch_test_required"] is True
+
+
+def test_agent_drops_records_an_older_app_did_not_send(monkeypatch, tmp_path):
+    """An app before agent v86 installs without fingerprints: a newer PC mustn't skip work on the old record."""
+    agent, base, dep = installed_agent(monkeypatch, tmp_path)
+    agent.write_deployment(PKG, {**dep, "configuration_fp": "old", "apk_recipe_fp": "old",
+                                 "artwork_manifest": {"portrait.jpg": "a" * 64}})
+    anchor = tmp_path / "Applications/quest-frame" / PKG
+    prep = {"base": str(base), "anchor": str(anchor), "appid": 42, "lepton": "/lepton"}
+    # no new art: the record of the art in place stays
+    agent.configure_install({"package": PKG, "title": "Example", "settings": {}}, prep, 0)
+    record = agent.deployment(PKG)
+    assert "configuration_fp" not in record and "apk_recipe_fp" not in record
+    assert record["artwork_manifest"] == {"portrait.jpg": "a" * 64}
+    # new art moved in without a manifest: its record is dropped too
+    (base / "incoming-artwork").mkdir()
+    (base / "incoming-artwork/portrait.png").write_bytes(b"new")
+    agent.configure_install({"package": PKG, "title": "Example", "settings": {}, "consume_artwork": True}, prep, 0)
+    assert "artwork_manifest" not in agent.deployment(PKG)
+    assert (anchor / "artwork/portrait.png").exists()
+
+
+def test_agent_config_written_by_an_older_frameport_is_not_kept_as_the_users(monkeypatch, tmp_path):
+    agent, base, dep = installed_agent(monkeypatch, tmp_path)
+    files = base / "lepton-data/external/Android/data" / PKG / "files"
+    files.mkdir(parents=True)
+    (files / "user.cfg").write_text("r_x=0\n")  # FramePort's own, from before agent v86 kept records
+    (files / "mine.cfg").write_text("users own\n")
+    prep = {"base": str(base), "anchor": str(tmp_path / "Applications/quest-frame" / PKG), "appid": 42,
+            "lepton": "/lepton"}
+    agent.configure_install({"package": PKG, "title": "Example", "settings": {},
+                             "files": {"user.cfg": "r_x=0\n", "mine.cfg": "r_y=1\n"}}, prep, 0)
+    managed = agent.deployment(PKG)["managed_config_files"]
+    assert managed["user.cfg"]["backup"] is False and managed["mine.cfg"]["backup"] is True
+    # the recipe drops both: FramePort's file goes away, the user's own comes back
+    agent.configure_install({"package": PKG, "title": "Example", "settings": {}, "files": {}}, prep, 0)
+    assert not (files / "user.cfg").exists() and (files / "mine.cfg").read_text() == "users own\n"

tests/test_instance.py

@@ -127,3 +127,15 @@ def test_claim_recovers_a_legacy_windows_holder_without_readable_pid(monkeypatch
     monkeypatch.setattr(instance, "end_leftover", lambda pid: ended.append(pid))
     assert instance.claim(lambda: False)
     assert ended == [123]
+
+
+def test_lock_is_kept_when_the_owner_file_cannot_be_written(tmp_path, monkeypatch):
+    """An antivirus or a read-only file must not stop the GUI from starting once it holds the lock."""
+    def fail(*args, **kwargs):
+        raise PermissionError("locked by another program")
+
+    monkeypatch.setattr(instance, "write_atomic", fail)
+    try:
+        assert instance.acquire(tmp_path / "gui.lock")
+    finally:
+        instance.release()

tests/test_langpack.py

@@ -484,3 +484,89 @@ def test_asset_files_patch_switches_the_library_on(built, tmp_path):
                   extra={"size": 1, "asset_files": ["Season1Taco-Android_ASTC.pak"], "asset_file_api": True})
     assert p.applies(a) and p.detect(a)
     assert not p.detect(_analysis(libs=["libovrplatformloader.so"], extra={"size": 1, "asset_files": ["a.pak"]}))
+
+
+def test_asset_stub_empty_list_and_installed_status(api, packs, monkeypatch):
+    monkeypatch.setenv("FRAMEPORT_ASSET_FILES_STUB", "1")
+    monkeypatch.setenv("FAKE_SILENT_LIST", "1")
+    m = api.ask("ovr_AssetFile_GetList")  # immediate, even with packs and a silent dispatcher
+    arr = api.f("ovr_Message_GetAssetDetailsArray", VOIDP, VOIDP)(m)
+    assert arr and api.f("ovr_AssetDetailsArray_GetSize", C.c_size_t, VOIDP)(arr) == 0
+    get = api.f("ovr_AssetDetailsArray_GetElement", VOIDP, VOIDP, C.c_size_t)
+    assert get(arr, 0) is None and get(arr, 2**32) is None
+    api.free(m)
+    for asset in (7, 0x4650000000001234):
+        m = api.ask("ovr_AssetFile_StatusById", asset)
+        assert api.msg_type(m) == STATUSBYID and not api.is_error(m)
+        det = api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m)
+        assert api.details(det) == {"id": asset, "type": b"default", "status": b"installed", "path": b""}
+        assert api.f("ovr_AssetDetails_GetIapStatus", C.c_char_p, VOIDP)(det) == b"free"
+        path = api.f("ovr_AssetDetails_GetFilepath", VOIDP, VOIDP)(det)
+        assert path and C.string_at(path) == b""  # allocated empty string, not a NULL pointer
+        assert api.f("ovr_AssetDetails_GetMetadata", C.c_char_p, VOIDP)(det) == b""
+        api.free(m)
+    assert api.pop() is None
+    assert api.loader.fake_freed() == 0  # no dispatcher requests were sent
+    monkeypatch.setenv("FRAMEPORT_ASSET_FILES_STUB", "0")
+    m = api.ask("ovr_AssetFile_StatusById", 7)
+    assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["path"] == b"/store/a"
+    api.free(m)
+
+
+def test_asset_stub_patch_without_language_packs(built, tmp_path, monkeypatch):
+    lib = built["lib"].read_bytes()
+    assert patch_mod.STUB_MARK + b"0" in lib
+    assert patch_mod.STUB_MARK + b"0" in patch_mod.with_assets(lib)
+    assert patch_mod.STUB_MARK + b"0" in patch_mod.with_metadata(lib, "1.0")
+    on = patch_mod.with_stub(lib)
+    assert len(on) == len(lib) and patch_mod.STUB_MARK + b"1" in on
+    assert patch_mod.with_stub(on) == on
+    monkeypatch.setattr(patch_mod, "artifact", lambda abi, name: lib)
+    patch = base.get("frame.asset_files_stub")
+    a = _analysis(libs=["libovrplatformloader.so"])
+    assert patch.applies(a) and patch.detect(a) is None
+    assert not patch.applies(_analysis(libs=[]))
+    assert not patch.applies(_analysis(libs=["libovrplatformloader.so"], abis=["armeabi-v7a"]))
+    with ApkWorkspace(_apk(tmp_path, built)) as ws:
+        ctx = base.ApkContext(ws, a, {}, Reporter(), {})
+        assert patch.apply(ctx)
+        loader = ws.read_lib(patch_mod.LOADER)
+        assert elf.needed(loader)[0] == patch_mod.LIB
+        assert not elf.hide_exports(loader, patch_mod.EXPORTS)[1]
+        assert patch_mod.STUB_MARK + b"1" in ws.read_lib(patch_mod.LIB)
+        assert all(ok for _, ok, _ in patch.validate(ctx))
+        assert not patch.apply(ctx)
+
+
+def test_asset_stub_marker_and_environment_override(built, tmp_path, monkeypatch):
+    marked = tmp_path / "marked.so"
+    marked.write_bytes(patch_mod.with_stub(built["lib"].read_bytes()))
+    monkeypatch.delenv("FRAMEPORT_ASSET_FILES_STUB", raising=False)
+    for api in _api({**built, "marked": marked}, tmp_path, monkeypatch, "marked"):
+        assert _list(api) == []
+        m = api.ask("ovr_AssetFile_StatusById", 7)
+        assert not api.is_error(m)
+        assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["status"] == b"installed"
+        api.free(m)
+        monkeypatch.setenv("FRAMEPORT_ASSET_FILES_STUB", "0")
+        assert _list(api)[0]["path"] == b"/store/a"
+
+
+def test_asset_stub_via_platform_loader_handle(built, tmp_path, monkeypatch):
+    """Unity's P/Invoke resolves against the dispatcher's handle, including its DT_NEEDED library."""
+    lib = tmp_path / "libfp_langpack.so"
+    lib.write_bytes(patch_mod.with_stub(built["lib"].read_bytes()))
+    loader_path = tmp_path / "libovrplatformloader.so"
+    loader_path.write_bytes(elf.add_needed(built["patched"], str(lib)))
+    monkeypatch.delenv("FRAMEPORT_ASSET_FILES_STUB", raising=False)
+    loader = C.CDLL(str(loader_path))
+    api = Api(loader, loader)
+    try:
+        assert _list(api) == []
+        m = api.ask("ovr_AssetFile_StatusById", 7)
+        assert api.msg_type(m) == STATUSBYID and not api.is_error(m)
+        assert api.details(api.f("ovr_Message_GetAssetDetails", VOIDP, VOIDP)(m))["status"] == b"installed"
+        api.free(m)
+        assert api.pop() is None
+    finally:
+        _dlclose(loader)

tests/test_linux_apps.py

@@ -235,3 +235,37 @@ def test_install_takes_the_icon_the_frame_found(tmp_path):
     installer.apply_app_icon(frame, pkg, "/anchor", result, Reporter())  # unchanged: nothing sent
     installer.apply_app_icon(frame, pkg, "/anchor", {"app_icon": {"file": "app-icon.svg"}}, Reporter())
     assert frame.puts == []
+
+
+@pytest.mark.parametrize("script", ["install.sh", "setup.sh"])
+@pytest.mark.parametrize("archive", [False, True])
+def test_installer_only_linux_app_refused(tmp_path, script, archive):
+    from frameport.errors import explain
+
+    root = tmp_path / "service"
+    root.mkdir()
+    (root / script).write_text("#!/bin/sh\necho install\n")
+    path = root
+    if archive:
+        path = tmp_path / "service.tar.gz"
+        with tarfile.open(path, "w:gz") as t:
+            t.add(root, arcname="service")
+    with pytest.raises(ValueError) as caught:
+        pipeline.add_linux_app(path)
+    message = explain(caught.value)
+    assert "FramePort runs programs, not installers" in message
+    assert "project's own install instructions" in message
+
+
+def test_installer_beside_program_does_not_prevent_detection(tmp_path):
+    (tmp_path / "install.sh").write_text("#!/bin/sh\n")
+    (tmp_path / "program").write_bytes(elf(linux.EM_AARCH64))
+    assert linux.inspect(tmp_path)["exe"] == "program"
+
+
+def test_deep_installer_is_not_used_for_refusal(tmp_path):
+    nested = tmp_path / "release" / "scripts"
+    nested.mkdir(parents=True)
+    (nested / "install.sh").write_text("#!/bin/sh\n")
+    with pytest.raises(ValueError, match="no Linux program found"):
+        linux.inspect(tmp_path)

tests/test_monitor.py

@@ -254,3 +254,42 @@ def test_modules_need_the_agent_that_has_them():
     assert not M.MonitorSession.supports_modules.fget(s)
     s.static["agent"] = 73
     assert M.MonitorSession.supports_modules.fget(s)
+
+
+def test_smoother_steadies_flickering_numbers_whatever_the_interval():
+    # fps flickering 71/73 every 0.1 s settles near 72 instead of jumping with each tick
+    sm = M.Smoother()
+    shown = [sm.value("fps", 71 if i % 2 else 73, i * 0.1) for i in range(60)]
+    assert max(shown[30:]) - min(shown[30:]) < 0.3
+    # a real change still comes through within a few seconds, at 0.1 s and at 2 s ticks alike
+    for dt in (0.1, 2.0):
+        sm = M.Smoother()
+        sm.value("cpu", 10, 0.0)
+        t, v = 0.0, 10.0
+        while t < 4.5:
+            t += dt
+            v = sm.value("cpu", 50, t)
+        assert v > 45
+
+
+def test_smoother_restarts_after_a_gap_or_a_missing_value():
+    sm = M.Smoother()
+    sm.value("gpu", 10, 0.0)
+    assert sm.value("gpu", 90, 30.0) == 90  # paused / reconnected: no slow slide from old numbers
+    assert sm.value("gpu", None, 30.5) is None
+    assert sm.value("gpu", 40, 31.0) == 40
+
+
+def test_smoother_sample_smooths_tiles_and_games_and_keeps_the_rest():
+    sm = M.Smoother()
+    s1 = {"t": 0.0, "cpu": {"total": 20.0, "mhz": [2000]}, "mem": {"total": 100, "avail": 50},
+          "temps": {"cpu": 40.0}, "power": {"system": 5.0}, "battery": {"percent": 80},
+          "games": [{"package": "a.b", "fps": 72.0, "title": "A"}]}
+    sm.sample(s1)
+    s2 = {**s1, "t": 0.5, "cpu": {"total": 60.0, "mhz": [2400]},
+          "games": [{"package": "a.b", "fps": 60.0, "title": "A"}]}
+    out = sm.sample(s2)
+    assert 20 < out["cpu"]["total"] < 60 and out["cpu"]["mhz"] == [2400]
+    assert 60 < out["games"][0]["fps"] < 72 and out["games"][0]["title"] == "A"
+    assert out["battery"] == {"percent": 80} and out["mem"]["total"] == 100
+    assert s2["cpu"]["total"] == 60.0  # the raw sample (history, details, processes) is untouched

tests/test_native_upload.py

@@ -0,0 +1,176 @@
+"""Bulk backend selection, paired-host trust, resumable native batches and cancellation."""
+import contextlib
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+from frameport.core.events import Cancelled, Reporter
+from frameport.frame import native_upload as native
+from frameport.frame.connection import Frame, FrameTarget
+from frameport.install import installer
+
+
+def test_pinned_credentials(tmp_path, monkeypatch):
+    monkeypatch.setattr(native, "ssh_dir", lambda: tmp_path)
+    (tmp_path / "id_ed25519").write_text("private")
+    key = SimpleNamespace(get_name=lambda: "ssh-ed25519", get_base64=lambda: "PAIRED_KEY")
+    client = SimpleNamespace(get_transport=lambda: SimpleNamespace(get_remote_server_key=lambda: key))
+    frame = Frame(FrameTarget("paired.example", port=2222), client=client)
+    with native.credentials(frame) as args:
+        known = next(arg.split("=", 1)[1].strip('"') for arg in args if arg.startswith("UserKnownHostsFile="))
+        from pathlib import Path
+        assert Path(known).read_text() == "[paired.example]:2222 ssh-ed25519 PAIRED_KEY\n"
+        assert "StrictHostKeyChecking=yes" in args
+        assert "BatchMode=yes" in args
+        copy = args[args.index("-i") + 1]
+        assert Path(copy).read_text() == "private"
+        assert Path(copy) != tmp_path / "id_ed25519"
+    assert not Path(copy).exists()
+    assert (tmp_path / "id_ed25519").read_text() == "private"
+
+
+@pytest.mark.parametrize("value", ["bad\npath", "bad\rpath", "bad\x00path"])
+def test_quote_refuses_batch_injection(value):
+    with pytest.raises(ValueError):
+        native.quote(value)
+
+
+def test_quote_protects_spaces_quotes_globs():
+    assert native.quote('a *?["b') == '"a \\*\\?\\[\\"b"'
+
+
+def test_size_lookup_does_not_hide_connection_errors():
+    sftp = Mock()
+    sftp.stat.side_effect = ConnectionError("lost connection")
+    with pytest.raises(ConnectionError):
+        native.size_of(sftp, "/file")
+
+
+def setup_batch(tmp_path, monkeypatch, code=0):
+    paths = [tmp_path / "main.obb", tmp_path / "patch.obb"]
+    for path in paths:
+        path.write_bytes(b"0123456789")
+    items = [(path, path.name, 10) for path in paths]
+    files = {"/incoming/main.obb.part": 4, "/incoming/patch.obb.part": 20}
+    monitor = Mock()
+    monitor.__enter__ = Mock(return_value=monitor)
+    monitor.__exit__ = Mock(return_value=False)
+    def stat(path):
+        if path not in files:
+            raise FileNotFoundError(path)
+        return SimpleNamespace(st_size=files[path])
+    monitor.stat.side_effect = stat
+    monitor.remove.side_effect = lambda path: files.pop(path)
+    frame = SimpleNamespace(sftp=monitor, client=SimpleNamespace(open_sftp=lambda: monitor),
+                            target=FrameTarget("paired"), run=Mock(return_value=(0, "", "")))
+    monkeypatch.setattr(native.shutil, "which", lambda _: "sftp")
+    @contextlib.contextmanager
+    def creds(frame):
+        yield ["-o", "StrictHostKeyChecking=yes"]
+    monkeypatch.setattr(native, "credentials", creds)
+    commands, processes = [], []
+    def popen(args, **kwargs):
+        commands.append(kwargs["stdin"].read().decode())
+        for _, rel, size in items:
+            files["/incoming/" + rel + ".part"] = size
+        process = Mock(returncode=code)
+        process.poll.return_value = code
+        processes.append(process)
+        return process
+    monkeypatch.setattr(native.subprocess, "Popen", popen)
+    return frame, items, files, commands, processes
+
+
+def test_native_batches_resume_reset_oversize_and_verify(tmp_path, monkeypatch):
+    frame, items, files, commands, processes = setup_batch(tmp_path, monkeypatch)
+    assert native.upload(frame, items, "/incoming", Reporter(), 20, 0, 3) == 20
+    assert len(processes) == 2  # never more processes than files
+    assert commands[0].startswith("reput ")
+    assert commands[1].startswith("put ")
+    assert all(".part" in command for command in commands)
+    frame.sftp.remove.assert_called_once_with("/incoming/patch.obb.part")
+    assert frame.run.call_count == 1
+    assert all("mv -f --" in call.args[0] for call in frame.run.call_args_list)
+    frame.sftp.get_channel().settimeout.assert_called_once_with(2)
+    assert all(process.wait.called for process in processes)
+
+
+def test_native_complete_parts_are_only_renamed(tmp_path, monkeypatch):
+    """A .part as big as its file (left by a cancelled run) isn't sent again: sftp's reput refuses it."""
+    frame, items, files, commands, processes = setup_batch(tmp_path, monkeypatch)
+    files["/incoming/main.obb.part"] = 10
+    assert native.upload(frame, items, "/incoming", Reporter(), 20, 0, 3) == 20
+    assert len(processes) == 1 and "main.obb" not in commands[0] and commands[0].startswith("put ")
+    assert "main.obb.part" in frame.run.call_args.args[0]
+    files["/incoming/patch.obb.part"] = 10
+    commands.clear()
+    processes.clear()
+    assert native.upload(frame, items, "/incoming", Reporter(), 20, 0, 3) == 20
+    assert not processes and frame.run.call_count == 2
+
+
+def test_native_failure_does_not_promote_files(tmp_path, monkeypatch):
+    frame, items, files, commands, processes = setup_batch(tmp_path, monkeypatch, code=1)
+    with pytest.raises(OSError, match="OpenSSH SFTP failed"):
+        native.upload(frame, items, "/incoming", Reporter(), 20, 0, 2)
+    assert not frame.run.called
+    assert files["/incoming/main.obb.part"] == 10
+    assert all(process.wait.called for process in processes)
+
+
+def test_native_success_still_checks_remote_sizes(tmp_path, monkeypatch):
+    frame, items, files, commands, processes = setup_batch(tmp_path, monkeypatch)
+    original = native.subprocess.Popen
+    def truncated(*args, **kwargs):
+        process = original(*args, **kwargs)
+        files["/incoming/main.obb.part"] = 9
+        return process
+    monkeypatch.setattr(native.subprocess, "Popen", truncated)
+    with pytest.raises(OSError, match="unexpected size"):
+        native.upload(frame, items, "/incoming", Reporter(), 20, 0, 2)
+    assert not frame.run.called
+    assert all(process.wait.called for process in processes)
+
+
+def test_native_cancel_stops_owned_processes(tmp_path, monkeypatch):
+    frame, items, files, commands, processes = setup_batch(tmp_path, monkeypatch)
+    report = Reporter()
+    report.progress = lambda *args, **kwargs: report.cancelled.set()
+    monkeypatch.setattr(native, "stop_process", Mock())
+    with pytest.raises(Cancelled):
+        native.upload(frame, items, "/incoming", report, 20, 0, 2)
+    assert not frame.run.called
+    assert native.stop_process.call_count == 2
+
+
+@pytest.mark.parametrize("cancel", [False, True])
+def test_production_fallback_and_cancel(tmp_path, monkeypatch, cancel):
+    path = tmp_path / "game.apk"
+    path.write_bytes(b"apk")
+    frame = Frame(FrameTarget("paired"))
+    frame.mkdirs = Mock()
+    frame.put = Mock()
+    report = Reporter()
+    fractions = []
+    report.progress = lambda fraction, *args, **kwargs: fractions.append(fraction)
+    def fail(frame, items, remote, reporter, *args):
+        reporter.progress(0.8, "native")
+        if cancel:
+            raise Cancelled()
+        raise OSError("native unavailable")
+    def fallback(local, remote, progress, **kwargs):
+        progress(0, installer.BIG_FILE)
+        progress(installer.BIG_FILE, installer.BIG_FILE)
+    frame.put.side_effect = fallback
+    monkeypatch.setattr(native, "upload", fail)
+    call = lambda: installer.upload_files(frame, [(path, "game.apk", installer.BIG_FILE)],
+                                          "/incoming", report, installer.BIG_FILE, workers=1)
+    if cancel:
+        with pytest.raises(Cancelled):
+            call()
+        assert not frame.put.called
+    else:
+        assert call() == installer.BIG_FILE
+        frame.put.assert_called_once()
+        assert fractions == sorted(fractions)

tests/test_parallel_uploads.py

@@ -0,0 +1,213 @@
+"""Bounded independent upload sessions, aggregate progress and cancellation of blocked workers."""
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+from frameport.core import library
+from frameport.core.events import Cancelled, Reporter
+from frameport.install import installer
+
+
+@pytest.mark.parametrize("value, expected", [(1, 1), (2, 2), (8, 8), (0, 1), (99, 8),
+                                             ("3", 3), ("bad", 3), (float("inf"), 3)])
+def test_upload_threads_bounds(value, expected):
+    assert installer.upload_threads(value) == expected
+
+
+def test_upload_threads_default_and_setting():
+    assert installer.upload_threads() == 3
+    library.set_setting("install.upload_threads", 8)
+    assert installer.upload_threads() == 8
+
+
+def items(tmp_path, count=4):
+    result = []
+    for n in range(count):
+        path = tmp_path / f"main-{n}.obb"
+        path.write_bytes(b"a" * 10)
+        result.append((path, f"obb/{path.name}", 10))
+    return result
+
+
+class Control:
+    def __init__(self, action):
+        self.action = action
+        self.sessions, self.calls, self.tars, self.dirs = [], [], [], []
+        self.lock = threading.Lock()
+
+    def mkdirs(self, dirs):
+        self.dirs.extend(dirs)
+
+    def upload_session(self):
+        owner = self
+        class Session:
+            def __init__(self):
+                self.closed = threading.Event()
+
+            def put(self, path, remote, progress, **kwargs):
+                progress(0, 10)
+                owner.action(self, path, progress)
+                with owner.lock:
+                    owner.calls.append((remote, kwargs))
+
+            def close(self):
+                self.closed.set()
+        session = Session()
+        with self.lock:
+            self.sessions.append(session)
+        return session
+
+    def put(self, path, remote, progress, **kwargs):
+        self.calls.append((remote, kwargs))
+        progress(0, 10)
+        progress(10, 10)
+
+    def put_tar(self, files, root, progress):
+        self.tars.append([rel for _, rel in files])
+        progress(sum(path.stat().st_size for path, _ in files), files[-1][1])
+
+    def close(self):
+        pytest.fail("the control connection must remain open")
+
+
+def test_two_workers_and_monotonic_aggregate_progress(monkeypatch, tmp_path):
+    monkeypatch.setattr(installer, "BIG_FILE", 5)
+    barrier = threading.Barrier(2)
+    activity = {"active": 0, "peak": 0}
+    lock = threading.Lock()
+    def action(session, path, progress):
+        with lock:
+            activity["active"] += 1
+            activity["peak"] = max(activity["peak"], activity["active"])
+        barrier.wait(timeout=3)
+        progress(5, 10)
+        progress(10, 10)
+        with lock:
+            activity["active"] -= 1
+    frame = Control(action)
+    events = []
+    reporter = Reporter([events.append])
+    assert installer.upload_files(frame, items(tmp_path), "/incoming", reporter, 40, workers=2) == 40
+    assert activity["peak"] == 2
+    assert len(frame.sessions) == 2 and all(session.closed.is_set() for session in frame.sessions)
+    assert sorted(remote for remote, _ in frame.calls) == [f"/incoming/obb/main-{n}.obb" for n in range(4)]
+    assert all(kwargs["mkdir"] is False and callable(kwargs["check_cancel"]) for _, kwargs in frame.calls)
+    fractions = [event.fraction for event in events if event.kind == "progress"]
+    assert fractions == sorted(fractions) and fractions[-1] == 1.0
+
+
+def test_one_worker_uses_existing_serial_transport(monkeypatch, tmp_path):
+    monkeypatch.setattr(installer, "BIG_FILE", 5)
+    frame = Control(lambda *args: pytest.fail("no worker transport needed"))
+    installer.upload_files(frame, items(tmp_path), "/incoming", Reporter(), 40, workers=1)
+    assert not frame.sessions and len(frame.calls) == 4
+
+
+def test_worker_count_is_limited_to_large_files_and_tar_is_sequential(monkeypatch, tmp_path):
+    monkeypatch.setattr(installer, "BIG_FILE", 5)
+    barrier = threading.Barrier(2)
+    def action(session, path, progress):
+        assert not frame.tars
+        barrier.wait(timeout=3)
+        progress(10, 10)
+    frame = Control(action)
+    selected = items(tmp_path, 2)
+    small = tmp_path / "small.txt"
+    small.write_bytes(b"x")
+    selected.append((small, "obb/small.txt", 1))
+    assert installer.upload_files(frame, selected, "/incoming", Reporter(), 21, workers=8) == 21
+    assert len(frame.sessions) == 2
+    assert frame.tars == [["obb/small.txt"]]
+
+
+def test_cancel_interrupts_blocked_workers_and_stops_queued_files(monkeypatch, tmp_path):
+    monkeypatch.setattr(installer, "BIG_FILE", 5)
+    started = threading.Barrier(3)
+    def action(session, path, progress):
+        started.wait(timeout=3)
+        assert session.closed.wait(3), "cancellation must close blocked worker sockets"
+        raise OSError("transport closed")
+    frame, reporter, errors = Control(action), Reporter(), []
+    def run():
+        try:
+            installer.upload_files(frame, items(tmp_path), "/incoming", reporter, 40, workers=2)
+        except Exception as exc:
+            errors.append(exc)
+    thread = threading.Thread(target=run)
+    thread.start()
+    started.wait(timeout=3)
+    reporter.cancelled.set()
+    thread.join(timeout=3)
+    assert not thread.is_alive()
+    assert len(errors) == 1 and isinstance(errors[0], Cancelled)
+    assert all(session.closed.is_set() for session in frame.sessions)
+    assert not frame.calls
+
+
+def test_failure_propagates_and_closes_sessions(monkeypatch, tmp_path):
+    monkeypatch.setattr(installer, "BIG_FILE", 5)
+    def fail(session, path, progress):
+        raise OSError("disk full")
+    frame = Control(fail)
+    with pytest.raises(OSError, match="disk full"):
+        installer.upload_files(frame, items(tmp_path), "/incoming", Reporter(), 40, workers=2)
+    assert all(session.closed.is_set() for session in frame.sessions)
+    assert not frame.calls
+
+
+def test_parallel_upload_setting_options_and_persistence():
+    import flet as ft
+
+    from frameport.ui.views.settings import SettingsView
+
+    app = SimpleNamespace(target=None, frame_state="disconnected")
+    controls = SettingsView(app).installing().controls
+    dropdown = next(control for control in controls if isinstance(control, ft.Dropdown))
+    assert dropdown.value == "3"
+    assert [option.key for option in dropdown.options] == [str(n) for n in range(1, 9)]
+    dropdown.on_select(SimpleNamespace(control=SimpleNamespace(value="8")))
+    assert library.setting("install.upload_threads") == 8
+
+
+def test_upload_session_checks_paired_headset_key_and_keeps_control(monkeypatch):
+    import paramiko
+
+    from frameport.frame.connection import Frame, FrameTarget
+
+    closed, children = [], []
+    def client(key):
+        return SimpleNamespace(get_transport=lambda: SimpleNamespace(get_remote_server_key=lambda: key),
+                               close=lambda: closed.append(key))
+    control = Frame(FrameTarget("frame"))
+    control.client = client("paired")
+    def connect(other):
+        other.client = client("other headset")
+        children.append(other)
+        return other
+    monkeypatch.setattr(Frame, "connect", connect)
+    with pytest.raises(paramiko.SSHException, match="different headset"):
+        control.upload_session()
+    assert closed == ["other headset"]
+    assert control.client.get_transport().get_remote_server_key() == "paired"
+    assert children[0].target is not control.target
+
+
+def test_closed_worker_does_not_retry_after_cancellation(monkeypatch, tmp_path):
+    from frameport.frame.connection import Frame, FrameTarget
+
+    frame = Frame(FrameTarget("frame"))
+    calls = []
+    cancelled = threading.Event()
+    def put(*args):
+        calls.append("put")
+        cancelled.set()
+        raise OSError("socket closed")
+    def check():
+        if cancelled.is_set():
+            raise Cancelled()
+    monkeypatch.setattr(frame, "_put", put)
+    monkeypatch.setattr(frame, "connect", lambda *args: pytest.fail("must not reconnect a cancelled worker"))
+    with pytest.raises(Cancelled):
+        frame.put(tmp_path / "file", "/incoming/file", check_cancel=check)
+    assert calls == ["put"]

tests/test_triage.py

@@ -474,3 +474,11 @@ def test_crash_after_the_headless_tracking_deadline_passes_a_launch_test():
     # no frames before the deadline: the game never ran
     no_frames = "\n".join(ln for ln in HEADLESS_END.splitlines() if "pacing:" not in ln)
     assert triage(no_frames, "EXITED", "ru.targem.blazerush", headless=True).verdict == "fail"
+
+
+def test_pixelripped_asset_status_error():
+    log = "E Unity : |||||||||| Asset status error  (code 100)\nE Unity : DLC_Manager:AssetStatusCallback(Message`1)\n"
+    result = triage(log, "RUNNING")
+    assert "meta-asset-status-error" in {f.id for f in result.findings}
+    assert "frame.asset_files_stub" in result.suggestions()
+    assert "meta-asset-status-error" not in {f.id for f in triage("Asset status OK\n", "RUNNING").findings}

tests/test_unreal_obb_check.py

@@ -107,7 +107,7 @@ STUCK = f"""Boot complete!
 def test_triage_flags_the_stuck_downloader():
     res = triage(STUCK, "RUNNING", PKG)
     f = next(f for f in res.findings if f.id == "unreal-obb-check-stuck")
-    assert f.severity == "fatal" and f.suggest == ["frame.unreal_skip_obb_check"]
+    assert f.severity == "fatal" and f.suggest == ["frame.unreal_skip_obb_check", "frame.unreal_skip_obb_delivery"]
     assert "DownloaderActivity" in f.evidence
     assert res.verdict == "fail"  # used to pass with only "Lepton container started"
 
@@ -124,3 +124,154 @@ def test_triage_ignores_a_downloader_that_returned():
 def test_triage_keeps_only_the_games_own_activity_lines():
     other = STUCK.replace(f"{PKG}/.DownloaderActivity", "com.other.app/.DownloaderActivity")
     assert not any(f.id == "unreal-obb-check-stuck" for f in triage(other, "RUNNING", PKG).findings)
+
+
+def test_delivery_predicates_return_true_in_place():
+    import hashlib
+    import struct
+    import zlib
+
+    from test_vivox_audio_route import build_dex
+
+    from frameport.apk.dex import Dex
+    from frameport.patches.frame.unreal_obb_check import has_delivery_check, patch_dex
+
+    cls = f"L{PKG.replace('.', '/')}/DownloaderActivity;"
+    obb = f"L{PKG.replace('.', '/')}/OBBData;"
+    shim = "Lcom/epicgames/ue4/DownloadShim;"
+    methods = [(cls, "expansionFilesDelivered", "Z", [0x0013, 5, 0x000F]),
+               (obb, "expansionFilesDelivered", "Z", [0x0012, 0x000F]),
+               (shim, "expansionFilesDelivered", "Z", [0x0071, 0, 0, 0x000A, 0x000F]),
+               (cls, "other", "Z", [0x0012, 0x000F]),
+               ("Lother/DownloaderActivity;", "expansionFilesDelivered", "Z", [0x0012, 0x000F]),
+               (cls, "expansionFilesDelivered", "I", [0x0012, 0x000F])]
+    raw = build_dex(methods)
+    dex = Dex(raw)
+    assert has_delivery_check(raw, PKG)
+    assert set(patch_dex(dex, PKG)) == {cls, obb, shim}
+    out = dex.finish()
+    assert len(out) == len(raw)
+    assert out[12:32] == hashlib.sha1(out[32:]).digest()
+    assert struct.unpack_from("<I", out, 8)[0] == zlib.adler32(out[12:]) & 0xFFFFFFFF
+    for idx, (_c, _n, _r, units) in enumerate(methods):
+        off = next(code for i, code in dex.class_methods(_c) if i == idx)
+        code = list(struct.unpack_from(f"<{len(units)}H", out, off + 16))
+        expected = ([0x1012, 0x000F] + ([0] if idx == 2 else []) + units[3 if idx == 2 else 2:]
+                    if idx < 3 else units)
+        assert code == expected
+        assert out[off:off + 16] == raw[off:off + 16]
+    assert patch_dex(Dex(out), PKG) == []
+
+
+def test_delivery_detection_and_multidex_apply_with_crc_already_off(tmp_path):
+    from test_vivox_audio_route import build_dex
+
+    from frameport.patches.frame.unreal_obb_check import UnrealSkipObbDelivery
+
+    patch = UnrealSkipObbDelivery()
+    path = _apk(tmp_path, _manifest(verify=False))
+    raw = build_dex([(f"L{PKG.replace('.', '/')}/DownloaderActivity;", "expansionFilesDelivered", "Z",
+                      [0x0012, 0x000F])])
+    with zipfile.ZipFile(path, "a") as z:
+        z.writestr("classes2.dex", raw)
+    analysis = analyze(path)
+    assert analysis.extra["analysis_version"] == 16
+    assert analysis.extra["unreal_obb_delivery"] is True
+    assert patch.applies(analysis) and patch.detect(analysis) is None
+    assert patch.experimental and not patch.default_on
+    assert not patch.applies(_analysis())
+    original = base.get("frame.unreal_skip_obb_check")
+    assert original.detect(analysis) is None and not original.applies(analysis)
+    assert original.revision == 1
+    with ApkWorkspace(path) as ws:
+        ctx = base.ApkContext(ws, analysis, {}, Reporter(), {patch.id: {}})
+        assert patch.validate(ctx)[-1][1] is False
+        assert patch.apply(ctx)
+        assert all(ok for _title, ok, _detail in patch.validate(ctx))
+        assert ws.read("AndroidManifest.xml") == _manifest(verify=False)
+        assert ws.read("classes.dex") == b"dex\n035\0"
+        assert len(ws.read("classes2.dex")) == len(raw)
+        assert "expansionFilesDelivered=true" in ctx.notes[-1]
+        assert not patch.apply(ctx)
+
+
+def test_delivery_ignores_unrelated_referenced_and_unsupported_methods():
+    from test_vivox_audio_route import build_dex
+
+    from frameport.apk.dex import Dex
+    from frameport.patches.frame.unreal_obb_check import has_delivery_check, patch_dex
+
+    cls = f"L{PKG.replace('.', '/')}/DownloaderActivity;"
+    raw = build_dex([("Lother/DownloaderActivity;", "expansionFilesDelivered", "Z", [0x0012, 0x000F]),
+                     (cls, "expansionFilesDelivered", "I", [0x0012, 0x000F]),
+                     (cls, "expansionFilesDelivered", "Z", None)])
+    assert not has_delivery_check(raw, PKG)
+    dex = Dex(raw)
+    assert patch_dex(dex, PKG) == [] and bytes(dex.data) == raw
+    raw = build_dex([(cls, "expansionFilesDelivered", "Z", [0x000F])])
+    dex = Dex(raw)
+    assert patch_dex(dex, PKG) == []  # too short for const/4 + return
+    assert bytes(dex.data) == raw
+
+
+def test_triage_does_not_blame_only_a_wrong_version_when_crc_is_off():
+    log = STUCK.replace("Boot complete!", "Boot complete!\nbVerifyOBBOnStartUp=false")
+    finding = next(f for f in triage(log, "RUNNING", PKG).findings if f.id == "unreal-obb-check-stuck")
+    assert "skip patch already applied" in finding.diagnosis
+    assert "external-storage path" in finding.diagnosis
+
+
+def test_ue5_shim_and_zero_register_method():
+    import struct
+
+    from test_vivox_audio_route import build_dex
+
+    from frameport.apk.dex import Dex
+    from frameport.patches.frame.unreal_obb_check import has_delivery_check, patch_dex
+
+    cls = "Lcom/epicgames/unreal/DownloadShim;"
+    raw = build_dex([(cls, "expansionFilesDelivered", "Z", [0x0012, 0x000F])])
+    assert has_delivery_check(raw, PKG)
+    dex = Dex(raw)
+    off = dex.code_items(cls, "expansionFilesDelivered")[0]
+    struct.pack_into("<H", dex.data, off, 0)
+    before = bytes(dex.data)
+    assert patch_dex(dex, PKG) == [] and bytes(dex.data) == before
+    dex = Dex(raw)
+    assert patch_dex(dex, PKG) == [cls]
+
+
+def test_crc_patch_preserves_head_output_with_delivery_dex(tmp_path):
+    from test_vivox_audio_route import build_dex
+
+    patch = base.get("frame.unreal_skip_obb_check")
+    manifest = _manifest()
+    raw = build_dex([(f"L{PKG.replace('.', '/')}/DownloaderActivity;", "expansionFilesDelivered", "Z",
+                      [0x0012, 0x000F])])
+    path = _apk(tmp_path, manifest)
+    with zipfile.ZipFile(path, "a") as z:
+        z.writestr("classes2.dex", raw)
+    with ApkWorkspace(path) as ws:
+        before = {name: ws.read(name) for name in ws.names()}
+        ctx = base.ApkContext(ws, analyze(path), {}, Reporter(), {patch.id: {}})
+        assert patch.detect(ctx.analysis).recommended
+        assert patch.apply(ctx)
+        # HEAD writes only the manifest boolean; all other APK entries stay byte-identical.
+        expected = {**before, "AndroidManifest.xml": axml.set_meta_data_bool(manifest, VERIFY, False)}
+        assert {name: ws.read(name) for name in ws.names()} == expected
+        assert ctx.notes == ["bVerifyOBBOnStartUp=false"]
+        assert patch.validate(ctx) == [("OBB check at start off", True, "bVerifyOBBOnStartUp=false")]
+
+
+def test_triage_offers_delivery_when_crc_patch_already_enabled(monkeypatch):
+    from dataclasses import asdict
+
+    from frameport import pipeline
+
+    base.load_all()
+    monkeypatch.setattr(pipeline.library, "game", lambda _pkg: {
+        "analysis": asdict(_analysis(unreal_verify_obb=True, unreal_obb_delivery=True)),
+        "recipe": {"patches": {"frame.unreal_skip_obb_check": {}}},
+    })
+    assert pipeline.useful_suggestions(PKG, triage(STUCK, "RUNNING", PKG).suggestions()) == [
+        "frame.unreal_skip_obb_delivery"]