fexrift: prefix setup creates the Quick Launch folder (Meta's runtime quit right after starting without it)

Meta's app framework stops with "Error acquiring quick launch directory" when
%APPDATA%\Microsoft\Internet Explorer\Quick Launch is missing, and OVRServer then
leaves its event loop as soon as it has initialised. The Frame's prefix had the folder,
a fresh one doesn't.

.gitignore

@@ -19,8 +19,6 @@ CLAUDE.local.md
 # outputs of `frameport report` / `parity` / ruff
 REPORT.md
 .ruff_cache/
-.eval-home/
-.eval-results/
 .claude/worktrees/
 
 # project page (site/)

CLAUDE.md

@@ -6,7 +6,6 @@ FramePort ports Meta Quest standalone APKs to the **Valve Steam Frame** (SteamOS
 install over SSH (agent) → Steam shortcut → headless launch test + log triage`.
 
 Read `docs/PLAYBOOK.md` (symptom → fix) before debugging a game, and `docs/FRAME_RUNTIME.md` for runtime facts.
-Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debugging a game).
 
 ## Layout
 - `src/frameport/` — Python package. `pipeline.py` is the API the CLI (`cli.py`) and GUI (`ui/`, Flet 1.0) share.
@@ -124,9 +123,8 @@ Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debug
     `ft.AnimatedSwitcher` (`app._show_view`): a new route gets a new wrapper (150 ms fade), a same-route redraw swaps
     the wrapper's content (no animation; persistent views just remount); the wordmark's portal (`wordmark().data`)
     pulses once when frame_state turns "connected"; both off with setting `ui.reduce_motion` (Settings → Appearance
-    "Reduce motion", `app.reduce_motion`). Settings has a fixed index column (`settings.SECTIONS` order: most users'
-    needs first (Updates, which also holds game recipe + install-link updates, Installing, Library folders,
-    Appearance), niche ones later (Install links, Tools, This PC), Remove FramePort last): entries scroll the section column via `scroll_to(scroll_key=…)` (sections wrapped
+    "Reduce motion", `app.reduce_motion`). Settings has a fixed index column (`settings.SECTIONS` order, Appearance
+    first, Remove FramePort last): entries scroll the section column via `scroll_to(scroll_key=…)` (sections wrapped
     in Containers with `ft.ScrollKey`), the header stays; `app.settings_view.show_section(key)` (ui_smoke
     `settings-index`).
     Help hints: wording for non-obvious terms lives in `ui/help.py` (`HELP`); show it with `C.help_icon(key)` or the
@@ -140,7 +138,6 @@ Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debug
     uploads are interruptible (Cancel checked per MiB) and resumable (big files via SFTP `.part` append, small files
     streamed in tar batches; the agent counts files already in `incoming/`). Multi-select in the Library queues
     installs after asking every needed question up front. Failures end in one pop-up (Resume / Uninstall / log).
-  - Library folders (GitHub discussion #351): `core/folders.py` (no Flet) owns setting `scan.roots` (remember/add/remove/status/rescan_roots; the origin-based fallback only while the setting was never set, so removing every folder doesn't guess them back), Settings → Library folders (`settings.library_folders`, status read via run_bg), CLI `frameport folders [--add/--remove/--json]` + `frameport rescan`. Scans relink moved games (`pipeline.ScanReport`: a library game found elsewhere whose own files are gone and the copy is the same build (Quest: source_sha256, else versionName; Rift: same program path + size from the fingerprint, matched by game id or, renamed, by program) → only paths change (`relink_quest`/`_relink_rift`), user fields/builds/installs stay; another version → Scan a folder… takes it via `replace_apk(found=)`/`replace_rift_game`, Rescan only reports it; the old copy still there → kept). `add_game` no longer overwrites a user recipe (refreshes `suggested` only). Linux apps aren't scanned. PC installs of a moved Rift game (Steam shortcut path) untested.
   - Other drives (GitHub #90, agent v63): anchors stay in ~/Applications/quest-frame, a game's files may live in
     `<mount>/FramePort/<pkg>` (`deployment.json` base). Agent `drives` (/proc/mounts, /run/media + Steam library
     drives; vfat/exfat/ntfs/read-only refused), prepare*/finalize_linux `dest` (unmounted = error, never a fallback;
@@ -226,13 +223,6 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     store matches and links then only update `auto_title`; a locked name gets no twin suffix); `sync_title` → Frame
     agent v77 `rename` (deployment.json title, same shortcut appid: upsert matches by Exe) + art + one Steam restart, PC
     `PcReviveTarget.rename`; an unreachable Frame → `steam_name_stale` (game page "Update name on Frame", next install).
-  - Newer versions (GitHub #161): game menu "Update with a newer APK…" (`pipeline.replace_apk`, outdated via
-    `build.source_version`) and, for Linux apps / PC VR games, "Update with a newer version…" (`replace_linux_app` /
-    `replace_rift_game` via `add_linux_app(replace=)` / `add_rift_game(replace=)`, CLI `frameport new-version`): the
-    entry keeps package, name, art, tags, switches, user recipe (a confirmed exe if the new folder has it); a new
-    `source_id` goes into the deployment's `recipe` dict at install (no agent change) → `C.source_replaced` = outdated
-    (Frame + `pc_outdated`); such an install re-sends same-size files changed after the last install (mtime/ctime,
-    `installer.changed_since`); the old Rift folder is in `replaced_dirs` (rescans skip it). Untested on the device.
   - `Recipe.as_is` = install unchanged (pre-patched libraries): `pipeline.prepare_as_is`; auto for APKs that already
     contain FrameBridge (`frame_patched`). For Rift it changes nothing (the dump is never modified; the Frame copy
     still gets launch fixes like the crash-reporter rename — `-nocrashreports` alone doesn't stop UE 4.23) — it does
@@ -244,14 +234,6 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     flask icon (SCIENCE_OUTLINED) so they aren't confused with Play.
   - `uninstall.py` + `frameport uninstall-app` + Settings: removes the data dir (after an optional key backup zip),
     PC Steam shortcuts, the WSL Revive copy, and via agent `purge` FramePort's games/files on the Frame.
-  - Save backups (discussion #352, agent v95; docs/FRAME_RUNTIME.md "Save backups"): agent `_backup_saves`/
-    `_restore_saves '<json>'` stream a tar.gz of `lepton-data/internal/<pkg>` + `external/Android/data/<pkg>` (caches,
-    IL2CPP/shader caches, FrameBridge files, videos/OBBs, files >64 MiB left out; manifest `frameport-saves.json` last)
-    over the exec channel, file work in `podman unshare` (`_saves_ns`), launch lock held, refused while running;
-    restore = untrusted input (staged + checked first), rollback copy `<base>/saves-before-restore.tar.gz` (undo =
-    `rollback: true`). PC `install/saves.py` (`<data>/save-backups/<pkg>/<ts>.tar.gz` + `.json`, keep `saves.keep`
-    = 10), GUI `ui/views/saves_dialog.py` (game menu section "Saves", Frame page "Back up all saves", uninstall's
-    "back up before deleting"), CLI `frameport saves backup|list|restore|undo`.
   - `patches/` — **the unit of modularity**. `base.py` (Patch interface, registry), `overport.py` (overport CLI patch ids,
     discovered dynamically via `overport patches`), `frame/*.py` (one module per Frame fix), `settings.py` (FrameBridge
     adapter keys + device files as patches). Add a patch = add a module that calls `register(...)`.
@@ -285,15 +267,6 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
     `working-config.yml` issue → maintainer label `catalog-accepted` (a plain issue needs `working-config` added by
     hand) → `catalog-from-issue.yml` workflow (`scripts/catalog_from_issue.py` validates) opens a catalog PR. App log:
     `core/applog.py` (`<data>/logs/app.log`, finished GUI jobs in `<data>/logs/jobs/`).
-  - Announcements (2026-10-15, announcements/README.md; app only, the owner dropped the site pop-up): source of
-    truth `announcements/current.md` on `main` (front matter id/title/date + optional image/image_alt/button+url/
-    expires/active, Markdown body; ships `active: false`). `announcements.py` (no Flet; raw GitHub via
-    `cache.cached_text`, 6 h) + `ui/announcer.py` (pop-up 20 s after start / every 6 h when no dialog is open and not
-    on welcome; `C.dialog` with the portal edge, image downloaded + Pillow-checked into `<data>/announcements/`, shown
-    by asset URL). Shown only if the user was around before `date` (setting `announce.since`, set once at the GUI's
-    first start: 0 when `USED_BEFORE` settings exist, else now), once: any close (X, outside click, Escape, button)
-    stores the id (`announce.dismissed`, last 50). New announcement = new id; same id = typo fix.
-    `FRAMEPORT_NO_ANNOUNCEMENTS`; `ui_smoke.py --announcement` renders it.
   - Self-update (docs/ARCHITECTURE.md "Self-update", docs/INSTALL.md "Updating"): `_version.py` = the only version
     (`frameport.__version__`; pyproject reads it via hatch `dynamic`; app log, diagnostics, User-Agent, Settings use
     it — never `importlib.metadata`, bundles have no dist-info). `updates.py` (no Flet): `check()` = GitHub
@@ -360,7 +333,45 @@ Rick and Morty runs on the Frame via its catalog recipe (OpenVR, no Revive),
   `a32_bridge_on` turned the bridge on once in every 32-bit recipe, user ones too, unless the catalog's frame_remove
   names it).
   Analysis `extra.headset` (ANALYSIS_VERSION 15): gearvr / go / quest → "Gear VR" / "Oculus Go" platform + Steam tag.
-  Catalog: `headset:` field; com.fallen.affected, net.mobilemischief.spunkydungeon, com.ccpgames.gunjack (works, 2026-10-12). Per-game a32 findings (AFFECTED, Spunky Dungeon, Gunjack's signature check `fp_a32_signature.txt`, synthetic Gear VR input, Quest builds `fp_a32_headset.txt` / `quest_touch`, recenter, debugging aids `A32_BREAK` / `A32_STRACE` / `A32_PERFMAP`, translator profiling): docs/DEVICE_NOTES.md#a32-bridge-games-lessons-debugging-aids-profiling.
+  Catalog: `headset:` field; com.fallen.affected, net.mobilemischief.spunkydungeon, com.ccpgames.gunjack (works, 2026-10-12). Learned: Unity 2019 contexts
+  have no EGLConfig (EGL_KHR_no_config_context: the VrApi bridge takes the window's or an RGBA8 ES3 config); Unity's
+  floor origin = vrapi_SetTrackingSpace(1) (the VrApi bridge now honours LOCAL_FLOOR/STAGE); mapped GL buffers are
+  per buffer object (a per-target guest copy leaked ~10 MB/s and garbled vertices); the guest runtime's own scudo
+  names its maps `[anon:scudo:*]` below 4 GiB (watch them for guest leaks). The Go controller = the right Frame
+  controller (stick = touchpad touch, sideways > 0.6 or press = click). Gunjack (CCP, UE 4.10 NativeActivity, Gear VR,
+  2026-10-10): needed the native_app_glue imports (ALooper/AInputQueue/AConfiguration/AAsset*, imports.txt), an arm64
+  libvrapi.so for Java's System.loadLibrary("vrapi") and MOUNTED under OVP_HEADLESS_TEST; it then loads its map and
+  quit on purpose: AndroidMain compares AndroidThunkCpp_GetSignature() with an obfuscated copy. **Works since
+  2026-10-11 (owner-verified in the headset):** GameActivity.AndroidThunkJava_GetSignature() = Base64.DEFAULT(SHA-1(
+  signing certificate DER)) (jadx); `a32_bridge.original_signature` computes it from the original APK's
+  META-INF/*.RSA|DSA|EC, `convert()` stores it as `assets/fp_a32_signature.txt` for libUE4.so games, the bridge loads
+  it at activity creation (native_activity.c) and jni.c answers Call*Method on the method ID of
+  `AndroidThunkJava_GetSignature()Ljava/lang/String;` with it. After loading, Unreal leaves VR mode and enters it again on
+  the same GL context; a second OpenXR session there aborted in vrclient (CSharedSemaphoreLinux::WaitFromGPU from the GL
+  binding's PreBeginFrame, also with OVP_HEADLESS_TEST) → the VrApi bridge keeps a running GLES session across
+  LeaveVrMode and reuses it for an EnterVrMode with the same context (upstream-patches/runtime.cpp.patch).
+  Debugging aids added: A32_BREAK=<guest addr>[,..] (stack of the first hits; guest libs load at fixed addresses, e.g.
+  libUE4 0xf25d5000), A32_STRACE in bridge mode = path/exit calls to logcat, activity lifecycle + LeaveVrMode caller
+  logs. Lepton's logcat mirror often dies for these games: read `podman exec <container> logcat` instead. Gunjack input
+  (2026-10-11): it imports no vrapi input functions and reads the Gear VR touchpad/back as AInputEvents from its
+  AInputQueue (native_app_glue), so dispatchKeyEvent never reached it (no control at all) → input.c queues synthetic
+  events there (ALooper_poll* return the queue's ident while one waits; AInputQueue_getEvent/finishEvent and the
+  AInputEvent/AKeyEvent/AMotionEvent getters are hand-written "!" imports that know them; touch positions scaled to the
+  window size). Same mapping as AFFECTED: trigger = hold touchpad, A = tap, right stick = swipe, B = back; for NativeActivity games the stick's up/down = swipe forward/back (touchpad X: Gunjack's OnFlick = reload at ~0°, special weapon at ~180°). Not yet
+  headset-verified. Quest builds on the bridge (2026-10-13, Sports Scramble = a 32-bit Santa Cruz build,
+  UE 4.21 + OVRPlugin on VrApi 1.21): manifest requires `android.hardware.vr.headtracking` version 1
+  (`detect.requires_6dof`, headset "quest", ANALYSIS_VERSION 16) → convert writes `assets/fp_a32_headset.txt`
+  = "quest" → vrapi.c `quest_touch` (read in vrapi_Initialize via the activity's AssetManager; A32_TOUCH=1/0
+  overrides) passes the 64-bit bridge's Touch controllers through (enumerate/caps/state/tracking/haptics, struct
+  tails per VrApi minor) and starts no synthetic input. It also needed AAsset_getBuffer (guest copy, freed in
+  AAsset_close), AKeyEvent_getFlags and the other AConfiguration getters. Headset (owner, 2026-10-13): plays,
+  both controllers work. Recenter (holding the Frame's menu button) turned VrApi games ~90-120 degrees aside: the bridge's app space is LOCAL + the start yaw and the runtime moves LOCAL to the head → the bridge now takes the origin from the head again on XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING (LOCAL) and on vrapi_RecenterPose (owner-verified with Gunjack, 2026-10-13). Next: the other 32-bit catalog games (Journey of the Gods, Shadow Point: still "unsupported" until
+  tested), translator speed. Profiled on the Frame
+  (2026-10-12, `A32_PERFMAP` + perf): FPCR switches are negligible (8 of 86k samples); the cost was the run loop
+  (a mutex + hash-chain walk on every dispatch, a contended counter, inline-lookup slots never refilled: Gunjack
+  ~45 % of its CPU) and `jit_invalidate` scanning every block on each Mono `cacheflush` (72 % of Spunky Dungeon's
+  main thread). Now lock-free lookups, ltab refill, per-thread flags, per-page block lists: Gunjack's dispatcher
+  23.6 % -> 1.6 %, CPU in the same phase about -55 %, still 72 fps.
 - `scripts/` — `package.py` (flet build/pack), `eval_heuristics.py` (score heuristics), `ui_smoke.py` (GUI screenshots).
 - `docs/` — PLAYBOOK, FRAME_RUNTIME, ARCHITECTURE, INSTALL (end users), parity reports (offline + device).
 
@@ -448,9 +459,6 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
   XR_KHR_composition_layer_equirect2/cylinder, XR_FB_composition_layer_image_layout (flip emulated by Vulkan blit).
 - `xrConvertTimespecTimeToTimeKHR`/`xrConvertTimeToTimespecTimeKHR` return FUNCTION_UNSUPPORTED → adapter emulates
   (offset = predictedDisplayTime − period − CLOCK_MONOTONIC, sampled in xrWaitFrame).
-- No XR_FB_display_refresh_rate (`xrGetDisplayRefreshRateFB` -7), yet OVRPort's dispatcher offers it and answered 0 Hz
-  → FrameBridge always answers with the measured rate (1/predictedDisplayPeriod, else 72). PreyVR (#306, idTech 4:
-  `USERCMD_MSEC = 1000 / GetRefresh()`) had 0 ms tics: async thread spinning, `com_frameTime` stuck at 0, menu black.
 - Guardian STAGE bounds report 1×1 m (scene emulation uses ≥1.5 m).
 - GL goes through **Zink** (Mesa GL on Vulkan). Mesa GLSL is strict: `#pragma` before `#extension` fails, implicit
   int/float conversions fail (enable `GL_EXT_shader_implicit_conversions`), num_views=2 shaders on single-view FBOs
@@ -520,14 +528,83 @@ Launch tests ignore log files older than the launch (stale Proton/game logs used
 (`\\wsl$` is unreliable), so PC mode copies Revive to `%LOCALAPPDATA%\FramePort`.
 FramePort never bypasses Oculus entitlement checks (Platform SDK games: flagged, PC mode with the Oculus app only).
 
-**Upload speed:** home Wi-Fi caps uploads at ~11-18 MB/s whatever the SSH method; the Frame's hotspot (`wlanap`) ~83-97 MB/s; `Frame.fast_link()` (installer `transfer_link`, uploads ≥64 MiB) prefers usb0 > wlanap when the host key matches. → docs/DEVICE_NOTES.md#upload-speed
+**Upload speed (measured 2026-09-29):** via the home router (PC Wi-Fi → router → Frame wlan0) only 15-18 MB/s, the
+same for paramiko, OpenSSH and 4 parallel streams, so the network path is the limit, not the SSH code. Direct to the
+Frame's hotspot (`wlanap` 10.35.78.1; the owner's PC has Valve's USB Wi-Fi dongle on it) 83 MB/s OpenSSH / 97 MB/s
+paramiko; reading dumps from D: via WSL drvfs is then the cap (~82 MB/s). `Frame.fast_link()` (installer
+`transfer_link`, uploads ≥64 MiB) uses usb0 > wlanap when reachable **and** the host key matches the paired Frame.
 **Platform SDK detection** must include delay imports (`PEInfo.delay_imports`), modular Unreal's
 `*-OnlineSubsystemOculus-*.dll` and Ready At Dawn's `pnsovr.dll`: Robo Recall, Lies Beneath and Lone Echo I/II all use
 it; without the Oculus app they crash with 0xc06d007e (triage `delayload-missing`) — not fixable legitimately.
 GUI: Frame → Installed → folder icon = file browser (agent `list_files`, flags files missing vs the install
 manifest); Settings → About shows the bundled agent version and the Frame's.
 
-**Revive under Proton arm64:** Revive's Detours hooks don't take effect (Wine's kernelbase is ARM64EC); a system32 `LibOVRRT64_1.dll` symlink gets past -3001 to -3021 = ovrError_LibSignCheck (Oculus-signed runtime required; not bypassed). → docs/DEVICE_NOTES.md#revive-under-proton-arm64-lone-echo
+**Revive under Proton arm64 (Lone Echo, 2026-09-29):** Revive's Detours hooks (LoadLibraryW/ExW, OpenEventW, the
+signature check) don't take effect: Wine's kernelbase is ARM64EC. The LibOVR shim in the game then does a plain
+`LoadLibrary("LibOVRRT64_1.dll")` search (exe dir, cwd, system32, windows, PATH — no registry, `OculusBase` or
+`LIBOVR_DLL_DIR` used by this build) → `Failed to initialize Oculus API (-3001)` (= Lies Beneath's "Unable to load
+LibOVRRT DLL"). A symlink `pfx/drive_c/windows/system32/LibOVRRT64_1.dll -> <base>/revive/LibReviveXR64.dll` (Wine
+maps a symlink to the already-loaded module) gets past it to **-3021 = ovrError_LibSignCheck**: the shim only accepts
+an Oculus-signed runtime. Next step (not done): make the runtime check pass without Detours, e.g. an injected helper
+that patches the game's import table (IAT) for LoadLibrary*/WinVerifyTrust, or a prefix-level override. This is
+runtime interop (what Revive does), not the Platform SDK licence check (which FramePort never touches).
+**Rift via x86_64 Wine under FEX (research, 2026-10-08, headless on the dev Frame, SteamOS 0.4.5; no product code):**
+why Revive failed is confirmed upstream: x64 Detours returns ERROR_NOT_SUPPORTED on ARM64EC targets (microsoft/Detours
+PR #388; only an ARM64EC build of Detours can hook them). A fully x86_64 Wine avoids it: GE-Proton11-7 **x86_64** runs
+under the FEX tool (`fex-compat-tool run -- <x86 binary>`; RootFS /usr/share/guestos/fex-mesa, no FreeType there)
+— prefix boot 35 s, kernelbase.dll is x86-64. Proton's script needs help without the x86_64 SLR (app 4183110, not
+installed): its Python runs natively (the RootFS has none), so `files/bin/wine{,server}` and the two direct
+`wine-preloader` argv calls must go through a FEX wrapper that also unsets `FEX_APP_CONFIG(_LOCATION)` (Proton sets
+them on aarch64 for its own ARM64EC FEX → "RootFS path set to ''"); GE's game drive needs STEAM_COMPAT_INSTALL_PATH
+unset. SteamVR now ships `bin/linux64/vrclient.so` + `bin/vrclient.so` (i386) + `vrclient_x64.dll` (Oct 6 build; not
+there on 09-30): Proton's x86_64 vrclient bridge reaches the arm64 vrserver. **Rick and Morty ran as the scene app**
+("OpenVR initialized!", controller tracking, 9176 presents / 6 dropped, CPU 11.6 / GPU 17.9 ms, target 72).
+**ReviveInjector: "Succesfully injected!"**, LibRevive64.dll loaded next to OVRPlugin.dll in Lies Beneath, which then
+died on 0xc06d007e = delay-loaded `libovrplatform64_1.dll` (Platform SDK) before connecting to SteamVR — so Revive's
+signature hook and Revive→SteamVR are still unproven. Every Rift game in the library except Rick and Morty uses the
+Platform SDK → the Meta (Link) app in the prefix, logged in with the user's own account, is the real blocker; the
+only public attempt (github.com/michauMiau/oculus-wine-linux, 2026-10) never got OculusSetup.exe (32-bit .NET)
+past its HTTPS config fetch. Scratch files on the Frame: `~/frameport-rifttest/` (scripts t1-t4.sh).
+Meta runtime in the same Wine (2026-10-09): Platform SDK games reach OVRServer's IPC on the Frame. The apparent
+intermittent handshake hang was **OVRLibrarian.exe** (.NET, Wine Mono): under FEX it finishes its work but never exits,
+its AppTracker entry stays, and the runtime then tracks no later client (Meta app, game), so the game waits forever
+for the reply event the runtime only sets after identifying it (found with wineserver `+server` traces PC vs Frame).
+Ending OVRLibrarian before the game → game tracked, "Missing entitlement" exactly as on the PC (needs a login).
+Logged in (2026-10-09, owner's own account, browser sign-in; the `oculus://` answer had to be forwarded into the Wine
+app's `\\.\pipe\oculus`), the runtime also needed a WinRT `Windows.Devices.WiFi.WiFiAdapter` stand-in (Air Link code
+fail-fasts without it), Wine's DeviceWatcher add/remove_Updated/Removed implemented, and the C: volume name
+(`\\?\Volume{...0043}`) linked in dosdevices. Copying the logged-in `sessions/` + CoreData to the Frame prefix kept the
+login. **Oculus First Contact then ran in VR on the Frame** (Revive in OpenVR mode; `/openxr` failed in wineopenxr):
+scene app at 72 Hz target, but 92 % of frames "timed out" (game CPU-bound under FEX) → stutter/flicker/lag.
+Performance (2026-10-10, headless with patched Revive visibility + SteamVR `pauseCompositorOnStandby=false`, numbers from
+`IVRCompositor::GetFrameTimings`): the frame loop waited on sync round trips through the FEX-run x86_64 wineserver.
+`native/fexwine/`: a **native aarch64 wineserver** built from GE's exact source (protocol 938) + **ntsync** (works once
+OVRLibrarian is ended) took hitches 17 → 0-4 per 20 s. The rest were Unreal's large-block allocator committing,
+filling (one `rep stos`) and freeing 514 MB every 1-8 s: ~130k 4 KB page faults each under FEX. `fp_mem.so`
+(`FP_BIGCACHE_MB=256`, guest preload via `FEX_ENV=LD_PRELOAD=…`: fex-compat-tool deletes LD_PRELOAD) keeps that block
+→ 0 hitches, steady 36 fps + motion smoothing, ~5.5 % timed out. 72 fps would need ~30 % less GPU (game ~55 % busy
+at 36 fps); THP (fragmentation), MSAA off, Turnip gmem don't help. Also needed: Unreal's
+`Slate.DeferWindowsMessageProcessing` = 0 (exe patch; the default deadlocks Wine's IME window ~1/3 of starts).
+Headset (owner, 2026-10-10): with motion smoothing off for the game (SteamVR per-app `motionSmoothingOverride=2`:
+smoothing cost ~15 % GPU) "much much better", 95 % of frames new at 72 Hz; MSAA off (DXVK `d3d11.disableMsaa`, -25 %
+GPU) helped but the owner misses smooth edges → the game's MSAA CVar is `r.MobileMSAA` (Oculus' clustered-forward
+branch; no r.MSAACount in the exe), 2x untested. Headless tests need the headset worn once per boot (else "IMU
+fallback" and the game waits at startup forever).
+**Experimental mode on branch `rift-on-frame` (the owner's single linkable branch for this work):** CLI only,
+`FRAMEPORT_EXPERIMENTAL_FEX=1 frameport fex setup | import-login <signed-in PC prefix> [--app <meta name>] | install
+[<meta name>] [--msaa N] [--force-unverified] | status` (hidden group). Generic per game: exe + arguments from Meta's
+manifest (`Software/Manifests/<app>.json` launchFile/launchParameters), the Unreal IME-deadlock fix found in the binaries
+(`find_ime_patch`: the CVar's UTF-16 name → its `lea` xref → `lea r8` member/global → `mov [reg+disp],1` / int 1;
+also modular ApplicationCore/Slate DLLs), `static_checks` (engine, imported graphics DLLs: monolithic Unreal imports
+every RHI, so it can't tell which runs). `agent/fexrift.py` `GAMES` = verified games + per-game opt-ins only (fp_mem's
+unzeroed big-block cache, `msaa_ini`); others need `--force-unverified`. PC `src/frameport/fexrift.py` uploads `agent/fexrift.py` + `artifacts/fexrift`
+(sources native/fexwine) + Revive 3.2.0 with 6 byte patches (refused for other builds); the Frame helper downloads
+GE-Proton11-7 x86_64 (SHA-512), x86 GnuTLS (Arch archive), installs Meta's runtime (Meta's signature checks kept) and
+writes the game's launcher. Agent v79 `fex_prepare/status/setup/import_login/install`, kind `frame_fex` (uninstall
+keeps the shared prefix; launch tests refused). Everything under `~/.local/share/frameport/fexrift` (purge removes it,
+login tokens included). Not yet run end to end on the device; the login still comes from a PC prefix signed in by hand.
+Uninstall (Quest, saves kept) used to leave `deployment.json` → still "installed"; fixed (agent v16).
+
 **Discovery/network:** Developer-Mode SteamOS devices announce `_steamos-devkit._tcp` (TXT `login=steamos`) — use it;
 they don't publish `_ssh._tcp`. The Frame has several links: `wlan0` (home Wi-Fi), `wlanap` = its own hotspot at
 10.35.78.1/24 (a PC can join it directly), `usb0` = USB gadget network 10.86.200.233/29 (up when cabled to a PC).
@@ -541,7 +618,23 @@ stopping Steam kills them → always run that work via `systemd-run --user` (the
 **overport:** always `--version=latest`; `--workspace` holds runtimes and **per-package keystores (password
 "password", alias "key") — never lose them**: updates must be signed with the same key or saves are lost on reinstall.
 Output is deterministic (same input + runtime → same bytes), which is what makes parity testing possible.
-**OVRPort 1.2.5 (2026-10-01):** `patch` rejects unknown/duplicate args, unknown ids and an empty `--patches=`; it adds `libovrplatformcompat.so` itself (`frame.ovrplatformcompat` then skips). New patches `patch_ac_nexus_no_appsw_72/_90` (AC Nexus build 207706 only; `_90` = catalog default; STRICT patches only from a catalog recipe where `applies()` holds), `patch_disable_meta_xr_audio_telemetry`, `patch_vrapi_openxr` (OVRPort's VrApi translator fails on the Frame → keep `frame.vrapi_bridge`). The owner prefers OVRPort's fixes over ours where they work as well. `frameport install <pkg> --apk <file>` installs a test build. → docs/DEVICE_NOTES.md#ovrport-125
+**OVRPort 1.2.5 (2026-10-01, the fork's first release; CLI-only):** same commands (`patches [--json]`, `patch`, `help`,
+`install`), but `patch` rejects unknown/duplicate args, unknown patch ids and an empty `--patches=`
+(`tools/overport.patch` refuses empty lists). After patching it adds `libovrplatformcompat.so` itself when the platform
+loader lacks `ovrMessageType_ToString` (our `frame.ovrplatformcompat` then skips: same library). New patches (all off;
+`patches/overport.py`): `patch_ac_nexus_no_appsw_72/_90` (AC Nexus build 207706 only, exclusive),
+`patch_disable_meta_xr_audio_telemetry` (x86_64 emulators: hidden), `patch_vrapi_openxr` = OVRPort's VrApi adapter =
+the **unpatched** upstream of our `frame.vrapi_bridge` (`native/vrapi` unchanged since our 5e7df52), only usable with an
+experimental CLI built with `-PwithVrApi=true` (stable jars list it but fail). The owner prefers OVRPort's fixes over
+ours where they work as well (less to maintain): compare in the headset before switching a default.
+`frameport install <pkg> --apk <file>` installs a specific (test) build signed with the game's key.
+Headset results (2026-10-02, `PATCHED/_test-ovrport-1.2.5/TESTING.md`): OVRPort's own VrApi translator fails on the
+Frame (Climb 2: requests VkFormat 37 → crash; POTW: no GLES path, missing `vrapi_GetTextureSwapChainHandle`) → keep
+`frame.vrapi_bridge`; those two changes are upstream candidates. 1.2.5 builds (its platform compat, new permissions)
+work. AC Nexus: `patch_ac_nexus_no_appsw_90` is the catalog default (owner preferred 90 Hz); `STRICT` patches are only
+taken from a catalog recipe where `applies()` holds (the AC Nexus ones need build MAIN.450412.207706.final, else the
+whole overport run fails).
+
 **Patching gotchas:**
 - UnityPy re-serialization breaks scene loading → patch QualitySettings ints in place.
 - LIEF's DT_NEEDED injection shifts segments; our `elf.add_needed` appends a new PT_LOAD (reuses PT_NOTE, else moves the
@@ -553,64 +646,414 @@ Output is deterministic (same input + runtime → same bytes), which is what mak
 - VrApi-direct engines (CryEngine Climb 2, POTW) need the VrApi bridge; the bridge drops whole frames on unknown layer
   types (→ black screen with audio).
 
-**Steam Frame controller models:** adapter setting `controller_models` (`native/adapter/render_model.c`, emulates XR_FB_render_model) + agent `install_controller_models` (Frame's SteamVR models → glb at finalize); no catalog game uses runtime models; Valve's models are never committed or copied off the Frame. → docs/DEVICE_NOTES.md#steam-frame-controller-models
+**Steam Frame controller models (2026-09-30, not yet seen in a game):** adapter setting `controller_models`
+(`native/adapter/render_model.c`) emulates XR_FB_render_model and serves `files/framebridge/controller_{left,right}.glb`;
+agent v20 (`install_controller_models`, command `controller_models`) converts the Frame's SteamVR render models
+(folder name matching "frame" + left/right, OBJ+PNG, `openxr_grip` component → grip space) at finalize/set_settings.
+Valve's models are never committed or copied off the Frame. Only games that use Meta's runtime controller models
+benefit (manifest `RENDER_MODEL` permission/feature → suggested); **none of the 34 catalog games do** (they ship their
+own meshes: that would need per-game asset replacement). Model discovery and conversion
+checked on the device 2026-09-30: `/opt/steamvr/drivers/frame_controller/resources/rendermodels/frame_controller_{left,right}`
+(component OBJs in model space = the whole `<name>.obj`, one `_color.png` 2048² near-black, `openxr_grip` rotates about
+X only; hidden-by-default components like `status` are skipped) → ~2 MB glb each, ~1 s. Not yet seen in a game (none
+of the installed builds has the new adapter, and none requests runtime models), so whether Meta's SDK attaches runtime models at the grip pose is unverified.
 **overport's dispatcher (`libopenxr_loader.so`) only forwards functions in its own table** (`overportOXR: Unknown
 proc addr: …`), so adapter emulations of functions it doesn't know are unreachable. For XR_FB_render_model,
 `native/xrshim` fills the gap: OVRPlugin's `dlopen("libopenxr_loader.so")` string is rewritten to the shim (see
 native/README). Verified on the device with Toy Master (2026-09-30): `extension shim: xrLoadRenderModelFB -> FrameBridge`.
 Toy Master doesn't request a model after that (it uses its own), so the glb loading path is only unit-tested.
 
-**Crash backtraces:** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (launch tests return `crash_log`). Fossilize loads into every app (userdebug guest) → `frame.vk_sanitize` (`native/vkshim`); overport's dispatcher aborts on swapchains > 4096 px → `frame.swapchain_limit`; cylinder layers → quad strips (`cylinder_strips`). Drawing equirect layers ourselves and a focus debounce were tried and removed: don't retry without a new approach. → docs/DEVICE_NOTES.md#crash-backtraces-fossilize-swapchain-limit-cylinder-and-equirect-layers
-**360° layers / 4XVR:** the Frame's Android runtime composites only quad + projection layers (quads always above projection layers). Per-game adapter settings (off by default): `equirect_emul` (GLES), `equirect_flip/face/res/fps/stereo`, `stable_local`, `focus_hold` (default on), `aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug`; agent `link_media` / `app_media_dirs` put sent files into a player's own folder. → docs/DEVICE_NOTES.md#360-layers--4xvr
-**Companion apps / intents:** a second APK can run inside a game's Lepton container, but Lepton turns every `android.intent.action.VIEW` with data into `steam://openurl` → "open in external player" hand-offs can't work; Lepton installs exactly one `*.apk` per app folder. → docs/DEVICE_NOTES.md#companion-apps--intents-stremio--4xvr
-**Text input:** Lepton's Android has no IME and VR apps run headless (no focused window); `lepton-show-flatscreen` keeps VR and gives focus + Steam's keyboard (`device.text_input_window`); `frame.unity_text_input` patches Unity's TMP_InputField/InputField at Cpp2IL offsets; agent `_keyboard` = uinput "Type on Frame". `pm install` of a second APK corrupts the main app (`cmd_real package install` skips the hook). → docs/DEVICE_NOTES.md#text-input-stremio-vr
-**User reports #4-#10:** shortcuts go to the signed-in account (agent `library_users`), `launch` errors `NOT_IN_LIBRARY`; shared Cpp2IL run (`unity_text_input.Il2cppReturnPatch`) for `frame.unity_runtime_msaa_off` and `frame.unity_multipass`; VR4 → catalog `use_alt`. **Catalog changes reach existing games**: recipes store `catalog_rev`, `library._follow_catalog` re-derives non-user recipes. → docs/DEVICE_NOTES.md#user-reports-2026-10-04-issues-4-10
-**Round 2 of reports / headset rounds 2-3 (2026-10-04):** vkshim `vk_shader_fix` (VR4); `Il2cppReturnPatch.field_loads` (I Am Cat); builds record `recipe_fp` (changed recipe/revised patch → "Update on Frame"); `Frame.relocate`; adapter `profile_remap` (Touch Plus/Pro); `sync_guard` (Myst); `focus_hold` tuning; ovrpshim for Unity 2017 (Accounting+); Steam library to every account, `shortcuts_lost` / `add_devkit_entry`; no clipboard service → `frame.sdl_clipboard`, `frame.godot_clipboard`; 2D apps keep non-VR patches (`needs_vr = False`); `frame/local.py` (FramePort on the Frame); after every app update `library._follow_catalog` re-derives non-user recipes once (`recipes.app_version`, `library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (re-analysis at GUI start + `pipeline.refresh_analyses`; `analysis_failed`). Roblox and BONELAB crash (unsupported). → docs/DEVICE_NOTES.md#round-2-of-reports-headset-rounds-2-3-2026-10-04
-**Round 4:** XR_KHR_android_surface_swapchain is listed but unsupported → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`); save folders without u/g+rwx → launch.sh `fix_perms`; Lucky's Tale OOM (no fix); `perf` works as steamos (gdb blocked); QuestCraft JRE, WiiCompiled import by hand (Lepton has no document picker). → docs/DEVICE_NOTES.md#round-4-2026-10-04-surface-swapchains-save-folder-permissions
-**Steam library failures (GitHub #21/#30/#41/#42):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (Play → AppError_9) → fallback: register through Steam's devkit interface (`devkit-1 … create-shortcut`, `~/devkit-game/<id>/`; `devkit_appid`, `devkit_appid_from_log`, `devkit_unregister`, `copy_grid_art`; ids: letter first, letters/digits/_ only); `collect_diag` adds `steam_library`. Cause still unknown. → docs/DEVICE_NOTES.md#steam-library-failures-and-the-devkit-fallback-github-21304142
-**Exit game (GitHub #36):** `Apps.TerminateApp` (Steam CEF devtools on 127.0.0.1:8080) closes games; launch.sh ends the game when its parent reaper is gone (`upgrade_launchers` adds it). → docs/DEVICE_NOTES.md#exit-game-github-36
-**SteamVR dashboard at game start:** launch.sh's `_dashboard_worker` hides the dashboard via `SteamClient.OpenVR.VROverlay` (agent `steam_js`) from the first FrameBridge `new layer:` line (120 s, ≤10 times, stops after `toggle_dashboard_action`); log `<base>/dashboard.log`, opt out `FRAMEPORT_KEEP_DASHBOARD=1`. → docs/DEVICE_NOTES.md#steamvr-dashboard-at-game-start
-**Space warp / ITR2:** OVRPort's dispatcher offers XR_FB_space_warp itself (`patch_disable_space_warp` doesn't reach UE5) → FrameBridge `hide_space_warp` (per game, off; suggested for UE5 + OVRPlugin). `equirect_emul` switches itself off on Vulkan. → docs/DEVICE_NOTES.md#space-warp--itr2
-**PR #34 (Lucas-Mathieu):** `native/adapter/audio_metadata.h` keeps Meta XR Audio Wwise metadata alive (Batman: Arkham Shadow 1.4.1 smoke-bomb crash). Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally. → docs/DEVICE_NOTES.md#pr-34-meta-xr-audio-metadata-batman
-**Heuristics eval (2026-10-04):** 19/44 recipes exact (superseded by the 2026-10-15 numbers under Heuristics). → docs/DEVICE_NOTES.md#heuristics-eval-2026-10-04
+**Crash backtraces (2026-09-30):** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (after "Dumping logcat"), not launch.log; agent v23 launch tests wait for it and return `crash_log`, triage gets it via `triage(..., crash=)` (not pid-filtered: tombstones come from crash_dump's pid). The guest is `userdebug` (`ro.debuggable=1`), so Lepton's Fossilize layer loads into every app whatever the APK's debuggable flag; it has no off switch. Fossilize crashed Deadpool VR on uninitialized attachment-reference pNexts (several, in FVulkanRenderPass and the render-target layout) → `frame.vk_sanitize` = `native/vkshim` (engine's `dlopen("libvulkan.so")` string → `libfp_vk.so`, wraps vkCreateRenderPass2/KHR, drops unreadable/wrong-sType pNexts; verified: game runs). overport's dispatcher aborts on swapchains > 4096 px (`cmp wN,#4096` in xrCreateSwapchain) → `frame.swapchain_limit` (verified with 4XVR, 7680×3840 accepted by the runtime). Both are default-on (parity classifies their rewrites as
+"expected"; library migration `quest_binary_fixes_v2`). The adapter shows cylinder layers (4XVR's movie screen) as ~15° quad strips (`cylinder_strips`, setting
+`cylinder_strips`); the runtime composites them at full resolution. Equirect (360°) layers are dropped: drawing
+them ourselves (GLES renderer in xrEndFrame: stutter, never showed 4XVR's VR video; Vulkan renderer: hung the
+Frame's GPU in AC Nexus; reading the newest *released* image broke 4XVR's theatre) was removed again on the owner's
+request — don't retry without a new approach. Converted layers must count as "swapped" or the original layer list
+is submitted (runtime returns -2 for every frame). A focus debounce (hiding the Frame's brief
+FOCUSED→VISIBLE→SYNCHRONIZED dips, which make 4XVR recenter) was also removed: AC Nexus stayed black with it (it
+hid 521 ms focus changes at start). The new approach (below) is per-game, off the app's render thread, GLES-only.
+
+**360° layers / 4XVR (2026-09-30):** the Frame's Android SteamVR runtime (`/opt/steamvr/bin/androidarm64/vrclient.so`,
+mounted in Lepton as `/data/steamvr/runtime`) only composites quad + projection layers (cube/cylinder/equirect(2)
+are enum names only) — nothing to unlock. Per-game adapter settings (off by default, hooks installed only when on):
+`equirect_emul` (GLES only: a worker thread with a shared EGL context converts each 360° image to a cube map when it
+changes and draws one adapter projection layer from it for every frame with exactly that frame's views (the app's own
+projection views, else xrLocateViews at displayTime); xrEndFrame waits ≤6 ms for the worker's CPU submit, never the
+GPU. Learned in the headset: quads can't be a background (the Frame draws quad layers above all projection layers
+whatever the order: hid 4XVR's balcony/controllers), and the Frame doesn't reproject a projection layer from its own
+pose (images drawn only after head turns, or ahead from xrWaitFrame and sometimes late, wobbled);
+`equirect_flip/face/res/fps/stereo`), `stable_local`, `focus_hold` (only after 3 s FOCUSED, dips <600 ms),
+`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics); focus_hold is default-on since 2026-10-05. 4XVR re-creates LOCAL spaces every 2–4 s
+(menu recentring suspect); its theatres are baked 7680×3840 equirect2 images (`assets/100.png` …). Test 360° videos
+(NASA, public domain) are in the Frame's ~/Videos; copies in `~/Downloads/frameport-360`. 4XVR's "Internal Storage"
+lists its own `/sdcard/4XPlayer`, not Movies: agent v25 `link_media` hard-links sent files into an app's own top-level
+folder (`app_media_dirs`), `frameport frame send --app <pkg>`, GUI game page "Add videos" (players) / "Add videos &
+files…". A 4XVR webm stereo swapchain was refused with XR_ERROR_LIMIT_REACHED (-10) → right eye grey; our projection
+swapchain was halved (1536/eye) in case memory is the limit (unverified). Frame data snapshot
+(SteamVR runtimes, Lepton scripts, logs; never commit Valve binaries): `~/frameport-research/frame-data-2026-09-30/`.
+Not yet verified in the headset.
+
+**Companion apps / intents (2026-10-03, tested with Stremio + 4XVR):** a second APK can be installed into a running
+Lepton container (`podman exec -i lepton-steamlaunch-<appid> pm install -g -S <size> < apk`) and runs there, VR
+included (4XVR in Stremio's flatscreen container: FrameBridge 72 fps, settings via LEPTON_ENV_FRAMEBRIDGE_CONFIG). But
+Lepton's services.jar (`ActivityStarter.execute`) intercepts **every** `android.intent.action.VIEW` with data (any
+scheme, explicit component or not, no property to disable): it writes `steam://openurl/<uri>` to `/lepton/steam.pipe`
+(= the host Steam client's `~/.steam/steam.pipe`) and starts nothing. So "open in external player" hand-offs (Stremio
+→ 4XVR) can't work inside Lepton; don't retry without Valve changing it. Lepton installs exactly one `*.apk` per app
+folder (two break `get_apk_path`).
+**Text input (2026-10-03, verified in the headset with Stremio VR):** Lepton's Android has no IME (`ime list` empty)
+and runs VR apps headless (`lepton.headless=true`): no Android window has input focus (`dumpsys input` FocusedWindows
+empty), so neither `input text`, a USB keyboard nor Steam's keyboard reach the app. `lepton-show-flatscreen` on a VR
+app keeps VR working (FrameBridge 72 fps) and gives the window focus; Steam's on-screen keyboard then opens for text
+fields. Unity's TMP_InputField on non-Quest Android waits for the system keyboard (`TouchScreenKeyboardShouldBeUsed`)
+and deselects a frame later unless `isKeyboardUsingEvents` (Android: `InPlaceEditing() && m_HideSoftKeyboard`);
+uGUI InputField's LateUpdate keeps the field when `InPlaceEditing()`. Patch `frame.unity_text_input` rewrites them
+(`mov w0,#0|#1; ret`) at Cpp2IL's **Offset** (= file offset; RVA differs by 0x4000 in Stremio's lib), Cpp2IL
+2022.1 pre-release (Unity 6 / metadata v31; Il2CppDumper can't), cached per libil2cpp sha. `/dev/uinput` has an ACL
+for steamos (Steam Input) → agent v33 `_keyboard` uinput keyboard ("Type on Frame") reaches everything with focus.
+Installing a second APK into a container with `pm install` re-runs Lepton's post-install hook on the **main** app
+(`lepton.active_app_id`; moves its files to /data/steam_app) and corrupts it on the next start (fix: touch the APK →
+re-bake); `cmd_real package install` skips the hook.
+**User reports (2026-10-04, issues #4-#10):** Steam shortcuts go to the signed-in account (`loginusers.vdf`
+MostRecent) else every account (agent v35 `library_users`; it used to refuse with >1 account → Play gave Steam's "Game
+configuration unavailable"); `launch` uses the shortcut's own appid and errors `NOT_IN_LIBRARY`, the app then adds it
+and plays. Unity IL2CPP fixes share one Cpp2IL run (`unity_text_input.Il2cppReturnPatch`, `ALL_TARGETS`, cache keyed by
+global-metadata.dat): `frame.unity_runtime_msaa_off` (OVRManager raises MSAA to 4x at runtime: "Switching to the
+recommended level" → Lucky's Tale restarted the headset; `OVRDisplay.get_recommendedMSAALevel` → 0) and
+`frame.unity_multipass` (Oculus XR Plugin multiview → MultiPass via `OculusSettings.GetStereoRenderingMode`; I Am Cat's
+right eye grey). Both checked against Toy Master's Cpp2IL output, not yet in a headset. VR4 quits itself (System.exit
+after the intro movie) → catalog `use_alt`. **Catalog changes reach existing games** without hardcoded migrations:
+recipes store `catalog_rev` (= `CatalogEntry.rev()`), `library._follow_catalog` re-derives non-user recipes whose entry
+changed; a maintained entry beats the user's shared copy when its `updated`/verified date is later (`catalog._newer`).
+**Round 2 of reports (2026-10-04):** VR4's campaign hang = one fragment shader reading an uninitialized loop counter
+(reporter's capture): vkshim `vk_shader_fix` setting (`<size>:<sha256>:<offset>:<words>`, from the recipe's `adapter:`;
+matched by size + SHA-256, words inserted into a copy) — on the device the module is fixed at load ("fixed shader
+module (6488 -> 6512 bytes)"); campaign itself not yet seen in a headset by us. Text settings (kind "str") stay out of
+the Game settings dialog (saving it dropped them). I Am Cat: `GetStereoRenderingMode` is inlined (no call sites) →
+`Il2cppReturnPatch.field_loads` rewrites the field read in `OculusLoader.Initialize` (Cpp2IL gives the field offset,
+`field:<name>`); verified with Toy Master: eye swapchains array=1 ×2 instead of array=2. Builds record `recipe_fp`
+(`patches/base.recipe_fingerprint`, `Patch.revision`): a changed recipe or revised patch shows "Update on Frame".
+Remembered Frames are found again after an address change (`Frame.relocate`: scan, same SSH host key, before
+login). Packaged apps show artwork by file path (`thumbs.use_file_paths`, #16). Diagnostics: this boot's kernel log.
+Device tests of requested games (2026-10-04, headless): I Am Cat, Myst 3.3.0, BattleGlide, Blade & Sorcery: Nomad
+start (RUNNING, frames). Roblox: SIGSEGV in je_free from libroblox.so ~3 s in (likely its anti-tamper vs the re-signed
+APK). BONELAB (Unity 2021.3 Vulkan, OVRPlugin 1.94): SIGSEGV with pc == fault addr in vkCreateInstance, called from
+libSLZQuestNative.so's Vulkan hooks into an unmapped (unloaded) library right after OVRPlugin's pre-init
+xrDestroyInstance; pinning openxr/vrclient libraries (RTLD_NODELETE) did NOT help — find the unloaded library with the
+linker's dlopen/dlclose logging next. Accounting+ (Unity 2017.4 built-in Oculus, libOVRPlugin + libvrapi): Unity
+never starts VR on the Frame (no OVRPlugin/OpenXR lines; runs as a 2D app), which is why its "controller setup"
+screen can't be passed — Unity 2017's Oculus device check, not the controller profiles. Cpp2IL can't read Unity 2017.
+The Frame's Android runtime (vrclient.so) knows oculus/touch_controller but not Meta's Touch Plus/Pro profiles
+(OVRPlugin suggests those too, routinely) → adapter `profile_remap`.
+Headset round 2 (2026-10-04): the Frame drops focus often (ms to 7 s; only some are presence/standby) → games pause
+or recentre (B&S Player.OnVRPresence → Teleport, BattleGlide/Unreal pauses); focus_hold now 1 s focused / 1 s max dip
+(longer must still pause). Myst crash = vrclient xrSyncActions race after FOCUSED → `sync_guard` (confirmed); its
+object glitches: app space warp suspected (FB_space_warp is advertised and used) → recipe `patch_disable_space_warp`.
+I Am Cat multipass: poses/times consistent, but every frame is submitted after the next xrWaitFrame (one period late;
+Zink + doubled draws) and the game clamps its physics step to 10 ms → judder while still; testing scale 0.8. Roblox's
+newest crash is on Fossilize's recording thread → vk_sanitize extended to own-engine libs (engine "Other").
+Accounting+: unity_oculus_check + native/ovrpshim (libfp_ovrp.so waits via ovrp_WaitToBeginFrame before Unity
+2017's ovrp_Update2) → VR in the headset at ~72 fps (2026-10-04), but stuck at "press any button" although input
+reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual buttons, input focus 1) → works with issues.
+"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`); 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
+the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). Godot 4.2-4.4 (Kotlin `as ClipboardManager`,
+GitHub #134 EndoparasiticVR) → `frame.godot_clipboard` (nops the `Intrinsics.checkNotNull` before that check-cast; Godot's
+clipboard methods return at once; analysis `godot_clipboard`, ANALYSIS_VERSION 10; checked on real godot-lib/templates
+4.2.2-4.4.1, not on the device; 4.1 and 4.5+ don't throw). 2D apps (vr_kind none)
+keep every suggested patch that isn't about VR (`needs_vr = False`), not a fixed list. FramePort on the Frame:
+`frame/local.py` (127.0.0.1, own key authorized; "This Frame (experimental)"; app data in
+~/.local/share/frameport-app because ~/.local/share/frameport is the agent's) and Steam library changes wait while
+Desktop Mode is open. Verified on the device 2026-10-04 (install + launch test from the Frame). Library updates on the
+Frame run one at a time (agent v40 flock): two quick uninstalls used to bring a removed shortcut back (Roblox).
+Headset round 3 (owner's verdicts, 2026-10-04): Blade & Sorcery works — its freezes were the headset's wear sensor
+flickering off while worn (vrserver.txt "HMD off/on" 0.5-2 s) → per-game `focus_hold_ms=2500` (only this game reacts;
+not a default). BattleGlide works (focus_hold). Myst works with issues (object glitches; space warp ruled out, its
+recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Roblox unsupported (je_free in
+libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
+game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
+`library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
+`library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (stored as `analysis.extra.analysis_version`); older entries whose APK is still there are analysed again at the GUI's start (background thread, not a job: ~8 s per 900 MB APK) and before a build (`pipeline.refresh_analyses`, GitHub #104); only `analysis`/`suggested` change, user recipes stay; an unreadable APK gets `analysis_failed` = the version (not retried until the next bump). Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
+(I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
+**Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
+FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
+swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
+XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
+buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
+(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
+launch.sh `fix_perms` adds u+rwx,g+rwx (agent v41). Lucky's Tale: Unity's Loading.PreloadManager thread grows the
+native heap ~1 GB/s until the OOM killer (Frame freezes); no fix. `perf` works as steamos (paranoid 2; ptrace_scope 1
+blocks gdb/eu-stack/debuggerd) — see PLAYBOOK "Debugging techniques". QuestCraft downloads its JRE at first run into
+`files/runtimes/JRE` (Pojlib Installer); on the Frame it was missing (unpacked by hand, unverified). WiiCompiled: its launcher shows
+(lepton-show-flatscreen) but imports .wcgame files through Android's document picker (OPEN_DOCUMENT), which Lepton
+lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json → internal files/game/<profile>,
+DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
+picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
+Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
+**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
+**Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
+**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v59: watches 120 s and hides up to 10 times (the menu came back after 30 s in the owner's sessions). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
+**Space warp / ITR2 (2026-10-04):** Into The Radius 2 (UE5, `libUnreal.so` + OVRPlugin, Vulkan) uses Application SpaceWarp (extra swapchains `376x376 format=97` motion vectors + `format=129` depth); #35 reports flickering textures. OVRPort's `patch_disable_space_warp` has no effect on UE5, and hiding XR_FB_space_warp in FrameBridge's enumerate doesn't reach the game either: **OVRPort's dispatcher offers/enables XR_FB_space_warp itself**. FrameBridge `hide_space_warp` (per game, off) hides it and strips `XrCompositionLayerSpaceWarpInfoFB` (1000171000) from the projection views (log `hide_space_warp: removed space warp info`); the game still renders its MV swapchains. Test build installed on the dev Frame; flicker not yet checked in a headset. Heuristic: UE5 + OVRPlugin shows it as an option (off). `equirect_emul` is suggested for Unreal games whose graphics API isn't detected ("GLES or unknown"); on Vulkan it switches itself off (Myst/Riven/ITR2): harmless, but Unreal Vulkan detection is a known gap.
+**PR #34 (merged 2026-10-04, Lucas-Mathieu):** `native/adapter/audio_metadata.h` patches Meta XR Audio Wwise (only build ID e1619e7f…, Batman: Arkham Shadow 1.4.1) so queued audio metadata isn't freed while the current audio frame references it (smoke-bomb crash). Verified headless: installs ("metadata reclamation follows …"), 72 fps; we added a once-per-second scan limit. Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally (contributor's commit kept), push main.
+**Heuristics eval (2026-10-04):** `scripts/eval_heuristics.py "<VR CyberDeck Portable>"` → 19/44 recipes exact, 322/352 fields (most diffs: `frame.unity_text_input` suggested where older catalog recipes lack it; the rest are runtime-only findings: use_alt, vk_shader_fix, focus_hold, sync_guard, multipass). `PATCHED/` copies aren't scored (already converted).
 **Power (0.9, agent v47):** sidebar bar below the Frame card: Sleep / Restart / Shut down, each confirmed (`app.frame_power`, a running game asks again). logind answers CanSuspend/CanReboot/CanPowerOff = "challenge" for an SSH session but "yes" inside a user unit, so agent `power` runs `systemctl suspend|reboot|poweroff` from a transient `systemd-run --user --on-active=3` timer (the command answers first). Restart verified on the device (back in ~84 s, new boot id).
-**Proton default:** the newest **stable** ARM64 Proton (`pick_proton`; owner's headset A/B); `pcvr.proton_tool` dropdown (Experimental = alias `proton-experimental`), `ensure_proton`, `proton_alternative_worth_trying`. → docs/DEVICE_NOTES.md#proton-default-stable-vs-experimental
-**USB cable link:** `usb0` is a USB NCM gadget (Developer Mode only); Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py`); ~37 MB/s; `scripts/usb_autotest.py`, `frameport frame usb-check`; discovery prefers USB > hotspot > network (`discovery.dedupe`). → docs/DEVICE_NOTES.md#usb-cable-link
+**Proton default (agent v51, owner's choice 2026-10-05):** the newest **stable** ARM64 Proton is the default for PC VR games (`pick_proton`: asked-for name/alias, else newest installed stable, else any stable). Agent v49-50 defaulted to Experimental; the owner's headset A/B with Rick and Morty (Experimental 69 % reprojected frames, stable felt much smoother) reverted it. The game page's Customize shows `pcvr.proton_tool` as a dropdown (Stable (default) / Experimental = alias `proton-experimental`); `ensure_proton` installs a chosen one (it asks once more for the runtime Steam only names after Proton is installed; Experimental installed unattended on the device in 53 s). A PC VR launch test that fails on stable suggests Experimental (`pipeline.PROTON_TOOL`, `proton_alternative_worth_trying`, button "Try Proton Experimental and reinstall"). Remaining Rick and Morty stutter on head turns = the game rendering below the refresh rate (reprojection), not Proton.
+**USB cable link (verified 2026-10-05, cabled to the dev PC):** `usb0` is a USB **NCM** gadget (configfs g1: `ncm.usb0` + `ffs.adb`, Valve 28de:2460) set up by `usb-ncm-gadget@usb0.service`, which only runs with `ConditionPathExists=|/etc/systemd/system/adbd.service.d/steamos-devkit-enabled` = **Developer Mode only**. `usb-ncm-dnsmasq@usb0` serves DHCP with fixed `dhcp-host` entries: Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py` FRAME_USB_IP/PC_USB_IP). Windows 11 binds its built-in "UsbNcm Host Device" (no driver); WSL mirrored sees eth 10.86.200.234. USB is high-speed (USB 2.0): upload 36.9 MB/s vs 11.3 MB/s home Wi-Fi. Frame→PC over the cable worked without a firewall change. `scripts/usb_autotest.py` (Windows via powershell.exe from WSL), `frameport frame usb-check`. Wizard "Set up with a USB cable" (`PairingServer(host=PC_USB_IP)`; the real bootstrap ran end to end over USB). Discovery dedupes by SSH host key and prefers USB > Frame hotspot > network (`discovery.dedupe`); a lost address is re-found by key (`Frame.relocate`, tested with a dead saved address).
 **Catalog updates without a release (2026-10-05):** apps fetch `catalog/games/*.yaml` from GitHub `main` (`recommend/catalog.refresh_remote`: one API call `git/trees/main?recursive=1` + raw.githubusercontent downloads of changed blobs, cached as `catalog-gh-<sha>.yaml`, every 6 h; GUI at start + Settings → Data "Check now"; CLI background thread + `frameport catalog-update`). `catalog.load()` only reads the cache. A remote entry is skipped (`unusable_reason`) when it names a patch/adapter key this app doesn't register, has a field `CatalogEntry` doesn't know, or `min_app` > this version: add `min_app` (or rely on new patch ids) when a config needs an unreleased FramePort. Remote beats bundled unless the bundled entry has a later updated/verified date; the user's own entries still win as before. Off: setting `catalog.auto_update`, env FRAMEPORT_NO_CATALOG_UPDATE; FRAMEPORT_CATALOG_URL still overrides the source. So: **pushing a catalog change to main reaches users within 6 h** (their recipes follow via catalog_rev → Update on Frame).
-**Start activity / QuestCraft / ITR2 pop-in:** `frame.start_activity` (analysis `extra.vr_activity`, `axml.set_start_activity`; OVRPort gives every MAIN activity LAUNCHER, so take the VR activity from the original APK); Unreal reads user config from **internal** storage; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>` (QuestCraft `LIBGL_NOERROR`); vkshim `vk_query_slots` left off. → docs/DEVICE_NOTES.md#start-activity--questcraft--itr2-pop-in
-**Vulkan validation / ITR2 solved:** bundle Khronos' `libVkLayer_khronos_validation.so` into a test APK + vkshim `vk_validation=1` (logcat tag VALIDATION); `vk_spec_fixes=1` drops ITR2's invalid depth resolve; VALVE_rpo removed its fog (catalog `lepton_env: VK_INSTANCE_LAYERS`). Agent `not_started` waits 30 s for "Boot complete!". → docs/DEVICE_NOTES.md#vulkan-validation--itr2-solved
-**GitHub #38/#39:** SteamVR rejects image rects past their swapchain (-25) → FrameBridge `rect_clamp` (default on), triage `swapchain-rect-invalid`; The Room VR MSAA crash in libgallium. → docs/DEVICE_NOTES.md#github-3839-powerwash-simulator-the-room-vr
-**Headset round 2026-10-05:** FrameBridge `pose_consistency` (I Am Cat judder), xrshim `haptic_fix` (Lucky's Tale), **`focus_hold` on by default with 5 s** (wear-sensor dips, `logs/eyetracking.txt`), `unity_no_overlay_copy` (The Room VR), ovrpshim frame wait for Unity 2019 (`UnityOculusCheck.legacy_loop`), `frame.ovr_trace` (opt-in, `native/ovrtrace`, logcat `fp_ovrtrace`). → docs/DEVICE_NOTES.md#headset-round-2026-10-05-evening
-**Unity built-in VR input:** probe builds `FRAMEPORT_INPUT_PROBE=1`; ovrpshim adds a `GetMouseButtonDown` icall click (Accounting+); libunity 2019 only polls Touch when the device model starts with "Oculus" → `unity_oculus_check` revision 4 `oculus_model_checks` (BattleSisters); `haptic_fix` suggested for every game with libOVRPlugin.so. → docs/DEVICE_NOTES.md#unity-built-in-vr-input-accounting-battlesisters
-**Vader Immortal (GitHub #49):** stuck on its loading card and leaked GPU mappings (solved below: `gl_error_clear`); diagnostics FrameBridge `layer_debug`, `strip_color_bias`, `frame_balance`, `snapshot=N` (`snapshot_gl.c`: saves the submitted left-eye image as `files/fb_snap_*.ppm`). → docs/DEVICE_NOTES.md#vader-immortal-headless-investigation
-**SteamVR overlay apps:** host OpenVR overlays composite over Lepton games; detection `analysis/vroverlay.py`, patch `pcvr.vr_overlay`, Linux fields `vr_overlay`/`vr_overlay_autostart`, agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay`; SteamVR on the Frame reads only `binary_path_linux_arm`; FramePort's own autostart (`ensure_overlay_service`, `frameport-vr-overlays.service`). See also docs/FRAME_RUNTIME.md "Overlay apps". → docs/DEVICE_NOTES.md#steamvr-overlay-apps
-**Vader's leak solved / AC Nexus flips:** stale GL errors broke SteamVR's GL interop → adapter `gl_error_clear` (GLES, catalog for Vader ep1-3); read `xrclient_<pkg>.txt` in Steam's logs for runtime errors; the runtime caps swapchains per session (~15) → flip emulation in place; adapter `flip_dump`. → docs/DEVICE_NOTES.md#vaders-leak-solved--ac-nexus-flips
-**Unreal's self-restart:** UE 4.21+ restarts itself after the first shader precompile and Lepton ends the container → launch.sh RESTART_BLOCK starts Lepton once more (`upgrade_launchers`; `FRAMEPORT_NO_RESTART=1` off). → docs/DEVICE_NOTES.md#unreals-self-restart
-**xrWaitFrame runs ahead:** the runtime sometimes returns a display time <1 refresh after the last submit and rejects the second submission (`VRCompositorError_AlreadySubmitted`) → the VrApi bridge re-waits (`pacing 2s:` counters). → docs/DEVICE_NOTES.md#xrwaitframe-runs-ahead-journey-of-the-gods
-**Lepton's logcat mirror dies** (EOF, read failure, or silent) → launch.sh `_logcat_keeper` reads `podman exec <container> logcat` itself into launch.log (log `<base>/logcat-keeper.log`). → docs/DEVICE_NOTES.md#leptons-logcat-mirror-dies
-**Double launch:** launch.sh takes `flock` on `<base>/.launch.lock` (fd 9); a second launch exits 0 and logs to `<base>/launch-dup.log` (`upgrade_launchers` adds it). → docs/DEVICE_NOTES.md#double-launch
-**Issue triage round 2026-10-06:** FrameBridge turns haptic amplitude 0 into xrStopHapticFeedback, per-game `haptic_scale`; Lambda1VR → `frame.tbxr_vendor`; Jurassic World → `frame.vrapi_stub`; Metro Awakening / Pinball FX → `hide_space_warp`; `frame.ovr_trace` can't trace Unity games; the VrApi bridge's 30 s head-pose deadline ends headless VR mode. → docs/DEVICE_NOTES.md#issue-triage-round-2026-10-06
-**Lepton storage:** each app's /sdcard has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (agent `storage_targets`); the media index never works; Lepton grants all runtime permissions. → docs/DEVICE_NOTES.md#lepton-storage
-**SteamVR per-app settings:** `native/vrsettings` = `fp_vrsettings.exe` sets `steam.app.<appid>` `preferredRefreshRate` / `motionSmoothingOverride` live; `pcvr.steamvr_tuning` (default on, PC only). → docs/DEVICE_NOTES.md#steamvr-per-app-settings
-**Language packs:** `frame.langpacks` (opt-in, `native/langpack`, `elf.hide_exports`, logcat tag `fp_langpack`) serves `<tag>.lang` files; Unreal needs the pack's Metadata = the game's version (`with_metadata`, `FRAMEPORT_LANGPACK_META`) and the `/storage/emulated/0/...` path spelling; `FRAMEPORT_LANGPACK_SKIP`. → docs/DEVICE_NOTES.md#language-packs
-**Cube swapchains:** the runtime refuses `faceCount=6` → FrameBridge `cube_standin` (default on, GLES only, `native/adapter/cube_standin.c`). → docs/DEVICE_NOTES.md#cube-swapchains
-**Hardware video decoding:** `native/hevc` OMX plugin (`OMX.frameport.{avc,hevc,vp9}.decoder`), installed once per Frame (`ensure_video_codec`, agent `video_codec_status`/`install_video_codec`/`video_codec_switch`); **bump `revision` in native/hevc/build.py with every artifact change**; per game `frame.hw_video_decode` (analysis `media_codec`), Settings `video.hw_decode`, `FRAMEPORT_NO_HW_VIDEO=1`; Batman migration `batman_video_patches` + `surface_native`. → docs/DEVICE_NOTES.md#hardware-video-decoding
-**Vulkan shader dump:** adapter `vk_shader_dump=1` (`native/vkshim/shader_dump.h`) writes SPIR-V modules + `index.txt` to `files/fp_vk_shaders/`; `collect_diag` returns the newest session's modules (`shader_dumps`); triage `gpu-hang`, `triage.graphics_api`. → docs/DEVICE_NOTES.md#vulkan-shader-dump
-**Unreal OBB check (#159):** `frame.unreal_skip_obb_check` (analysis `unreal_verify_obb`) turns off Epic's OBB CRC pass; triage `unreal-obb-check-stuck`. → docs/DEVICE_NOTES.md#unreal-obb-check
-**Issue round 2026-10-12:** Lepton breaks on unquoted paths with spaces → launchers give Lepton a `~/.local/share/frameport/lepton-paths/<pkg>` link (`app_dir_lines`/`set_app_dir`/`launcher_base`); `frame.eos_keychain_loop`, `frame.unity_tls_key_pool` (`libfp_tkeys.so`, `elf.rename_imports`), `frame.vermillion_scene_canvas`; `tools/cpp2il.py` falls back to Cpp2IL's dev build for metadata v107; Linux `desktop_icon`; `scripts/upload_bench.py`. → docs/DEVICE_NOTES.md#issue-round-2026-10-12
-**OpenSSH uploads (#324/#242):** `native_upload.quote` escapes only backslash and `"`, Win32 local paths go as `C:/…`; `Frame.auth` records the login that worked (app_key / user_key from `ssh.extra_keys`, `frame ssh-keys`, agent, password); strict IdentitiesOnly first, relaxed retry. → docs/DEVICE_NOTES.md#openssh-uploads
-**Meta user id (#182):** OVRPort's platform loader makes up a new user id every start → `frame.ovr_stable_user` (default on) returns a stable per-game, per-user id. → docs/DEVICE_NOTES.md#meta-user-id
-**Vivox API 31 (#101):** newer Vivox calls Android 12 AudioManager methods → `frame.vivox_audio_route` (analysis `vivox_api31`, `Dex.return_early`). → docs/DEVICE_NOTES.md#vivox-api-31
-**Steam Input gamepad for 2D apps (#162):** opt-in `device.steam_gamepad` (deployment `steam_gamepad` → launcher `GAMEPAD_LINE` → `PODMAN_WRAPPER` / `podman_run_args` bind-mount Steam's virtual pads). → docs/DEVICE_NOTES.md#steam-input-gamepad-for-2d-apps
-**Multiview programs on flat framebuffers (#77):** Mesa drops num_views=2 draws on single-view FBOs → `frame.gl_multiview_fbo` (`native/glmv` = `libfpglmv.so`, analysis `gl_multiview_libs`); headset-verified with Doom3Quest. → docs/DEVICE_NOTES.md#multiview-programs-on-flat-framebuffers-doom3quest
-**BlazeRush (#57):** `frame.blazerush` (1.0.349 only), GL shim `gl_int_attribs` / `gl_highp_markers`, saved VrApi FOV (`files/framebridge-vrapi-fov.txt`), `device.config_sync` (catalog `config_sync`); launch tests treat an end after the headless deadline as a pass (triage `headless_end`). → docs/DEVICE_NOTES.md#blazerush
-**Session triage:** real play sessions are triaged too: agent `last_play` / `session_log` (`<anchor>/plays.log`), `pipeline.sessions_due` / `triage_session` = `validate/session.analyze` (incl. `space-warp-used`, `gpu-hang`, `slow-frames`, `focus-dips`) → library `last_session` → game page "Last session"; `apply_suggestions_live`; CLI `frameport session <pkg> [--apply]`; pac_hints stays triage-only. → docs/DEVICE_NOTES.md#session-triage
+**Start activity / QuestCraft / ITR2 pop-in (2026-10-05):** WiiCompiled's VR part (`QuestActivity`, SDL, process `:game`) stays behind Lepton's flat window when the launcher is shown (`device.text_input_window`). `frame.start_activity` (opt-in; analysis `extra.vr_activity` = the original APK's activity with Meta's VR category when it isn't the launcher) gives that activity's filter LAUNCHER and every other LAUNCHER becomes INFO, per element (`axml.set_start_activity`); Lepton's own `apk-info-extractor --print-activity-name` (on the Frame under Lepton/liblepton/apk_extractor) then answers QuestActivity. **OVRPort gives every MAIN activity LAUNCHER + VR categories**, so the VR activity must come from the original APK's analysis, not the converted manifest. Lepton has no activity override (`APP_ACTIVITY` is reset when app_metadata.sh is sourced). QuestCraft reaches Minecraft 1.21.5 (Fabric, Vivecraft, Sodium; LTW "Large Thin Wrapper" GL 3.0 on the Frame's Zink) and stops at `OpenGL error 1282` in `WindowFramebuffer` createTexture (Minecraft's crash report in `files/instances/1.21.5/crash-reports/`, Pojlib's `files/latestlog.txt`); the vrclient SIGSEGV / "pthread_mutex_lock called on a destroyed mutex" afterwards is only the shutdown (Unity's render thread still in vrclient while the instance is destroyed). ITR2 "models popping in and out" in game: Unreal reads user config from **internal** storage (`lepton-data/internal/<pkg>/files/UnrealGame/<Project>/<Project>/Saved/Config/Android/Engine.ini`, not external); `r.AllowOcclusionQueries=0` there broke its menus (removed again). Vulkan shim `vk_query_slots` (two slots per occlusion query) never saw ITR2 create an occlusion query pool, and the run with it crashed (Unreal RenderThread SIGSEGV, caught by sentry-native: no tombstone; the backtrace is in `cache/sentry/*/.sentry-native/*.run/*.envelope` with module offsets) - left off. Next suspect: Unreal 5 mobile HZB occlusion reading depth stored with Valve's FDM injection layer; test = launcher `VK_INSTANCE_LAYERS=''` (Lepton then loads neither VALVE_rpo nor VALVE_fdm_injection, Fossilize still). QuestCraft: LTW overrides glGetError and returns 0 with `LIBGL_NOERROR` set; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>`, so catalog `lepton_env: {LEPTON_ENV_LIBGL_NOERROR: '1'}` gets Minecraft past the GL error 1282; then black picture (see the catalog entry). FrameBridge logs `new layer` once per layer type per process and projection views only for the first frames, so a second session in the same process (Vivecraft after Unity) needs `layer_debug=1`.
+**Vulkan validation / ITR2 solved (2026-10-05):** Khronos' validation layer can't come from Lepton (its layer dir is in the read-only guest image; the Linux copies on the Frame are glibc) and a global `debug.vulkan.layers` property (via the LEPTON_GFXRECON_FP_PROPS trick) kills the container at boot. Working recipe: bundle `libVkLayer_khronos_validation.so` (Khronos android-binaries release, arm64-v8a, stored uncompressed) into a test APK re-signed with the game's key (`apk.sign.sign`), install with `frameport install <pkg> --apk`, and set the Vulkan shim's `vk_validation=1` (it adds the layer at vkCreateInstance; findings under the logcat tag VALIDATION in launch.log, each message ID capped at 10). ITR2's flicker + windows behind models = Unreal's Qualcomm shader-resolve subpasses with a depth resolve of a single-sampled depth attachment (VUID-04908/-03179); `vk_spec_fixes=1` drops that resolve (its TRANSFER_DST half never applies to ITR2: the main depth is transient). Valve's VALVE_rpo layer removed ITR2's fog (catalog `lepton_env: VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection`). `r.ViewDistanceScale=2` in the internal Saved/Config/Android/Engine.ini only exists on the owner's Frame (the catalog can't write internal storage yet). Launch tests: Lepton prints a transient "is not a running context" on the first start after an APK change (agent v54 `not_started` waits 30 s for "Boot complete!").
+**GitHub #38/#39 (2026-10-05):** PowerWash Simulator stuck at "Waiting.." on a reporter's Frame = Unity sized the right-eye image rect past its swapchain (rect 268+1656 on a 1920-wide swapchain; the runtime's recommended size differs per Frame) and SteamVR rejected every frame (`xrEndFrame failed -25`, XR_ERROR_SWAPCHAIN_RECT_INVALID), after which the game stopped calling xrEndFrame. FrameBridge `rect_clamp` (default on; sizes noted in xrCreateSwapchain; clamped layers count as swapped) keeps projection/quad rects inside their swapchain; triage `swapchain-rect-invalid`. Not reproducible on the dev Frame with `scale` (Unity's eye sizing isn't just the recommended width); no regression there (72 fps). The adapter's revision was NOT bumped (that would mark every installed game outdated): affected users rebuild. The Room VR (#38) = Unity's render thread SIGSEGV in libgallium_dri.so ~30 ms after the game recreates its eye swapchain with samples=4 (FrameBridge retries samples=1); the game's own code turns MSAA on (not OVRManager); candidate fix: hide GL_EXT_multisampled_render_to_texture (GL shim) - needs the APK to test. The launch test passed both (render thread dead / no frames): triage gap.
+**Headset round 2026-10-05 (evening):** I Am Cat's judder = repeated xrLocateViews of one display time returning
+slightly different poses → FrameBridge `pose_consistency` (owner-verified, works). Lucky's Tale freeze on touching a
+save slot = OVRPort's OpenXR dispatcher converting XR_FB_haptic_amplitude_envelope with ns read as s (GitHub #9) →
+xrshim `haptic_fix` (owner-verified); its remaining short pauses were the wear sensor ("HMD off/on" 0.5-1 s in
+`logs/eyetracking.txt`, not vrserver.txt) → **`focus_hold` is on by default with 5 s** (owner's choice; C defaults
+too). The Room VR works (`unity_no_overlay_copy`). BattleSisters (Unity 2019.4 built-in VR, no libOculusXRPlugin.so)
+flooded "outside of frame bounds" ~2400/s and hung the GPU (kernel hangcheck, zink DEVICE LOST) → the ovrpshim frame
+wait now also applies to Unity 2019 without the Oculus XR Plugin (`UnityOculusCheck.legacy_loop`). Vader Immortal
+(UE4, stuck on the loading image after the intro, GitHub #49): VRP repacks carry a Frida gadget (`libfrda.so`,
+config `hijack_responses`), but OVRPort's `patch_clean_up_frida` removes its loadLibrary call, so it never runs on
+the Frame; `frame.ovr_trace` (opt-in, `native/ovrtrace`: 1138 exported ovr_* stubs → real loader functions, logcat
+tag `fp_ovrtrace`: calls, PopMessage answers, unanswered requests every 10 s) is the next diagnostic.
+**Unity built-in VR input (2026-10-05):** probe builds (`FRAMEPORT_INPUT_PROBE=1 frameport build …`; it logs
+trigger/grip crossings too) showed OVRPlugin returns the full Touch state for every controller mask (also Go masks);
+presses reach the games' OVRInput. Accounting+ (Il2CppDumper v6.7.46 reads its Unity 2017 metadata v24, run on Windows)
+passes stance selection (NewtonVR grip/trigger) but its motion warning waits for `Input.GetMouseButtonDown(0/1)`,
+which Lepton never delivers (no focused Android window) → ovrpshim registers its own
+`UnityEngine.Input::GetMouseButtonDown(System.Int32)` icall (il2cpp_add_internal_call, after Unity's: resolve first)
+that adds a click in the frame a Touch trigger or A/B/X/Y is newly pressed (`unity_oculus_check` revision 3).
+BattleSisters (Unity 2019 InputSystem/XR InputDevices via `VrHandInput`): libunity's Oculus module (OVRPlugin
+function table: a global pointer at 0x16b57c0 in this build, slots filled by name, e.g. +0x160 GetControllerState,
++0x168 State2, +0xe8 GetNodePresent) only reports controllers when `strncmp(deviceModel, "Oculus", 6) == 0` (next to
+the Go check `deviceModel == "Oculus Pacific"`); Lepton's model is "Valve Lepton" → Go/unknown → only Go masks polled,
+buttons dead. `unity_oculus_check` revision 4 (`oculus_model_checks`, Unity 2019 only) turns the 17 compares' length
+into 0 (`orr w2, wzr, #6` → `mov w2, #0` after the adrp/add of the "Oculus" literal; the string stays: it is also
+Unity's VR device name). Device result: libunity now polls `ovrp_GetControllerState(0x3)` (Touch); owner-confirmed
+2026-10-06: buttons work. Its first controller vibration then hit OVRPort's haptic-envelope bug (11 GB, OOM kill) →
+`haptic_fix` is now suggested for every game with libOVRPlugin.so (settings detect), BattleSisters works. Ruled out before: ProductName, GetNodePresent, the device-model string itself, exports.
+Accounting+ works (owner, 2026-10-06).
+**Vader Immortal (UE4, GitHub #49, 2026-10-06, headless):** stuck after the intro on an in-game image (the splash
+quad ends ~6 s in; then the game's own projection frames, 72 fps, balanced xrBeginFrame/xrEndFrame). Not the Platform
+SDK (`frame.ovr_trace`: only user + entitlement, both answered) and not the repack's Frida gadget (OVRPort's
+`patch_clean_up_frida` removes its loadLibrary). It **leaks ~430 GPU mappings (/dev/dri/renderD128) and ~20 MB a
+second** (6.5 GB + swap after 5 min, then 26 fps): page-fault stacks (perf -e page-faults, offsets resolved with the
+process maps + vrclient.so's own symbols; its text segment is at file offset + 0x4000) end in SteamVR's runtime:
+`xrBeginFrame → CSxrCompositorOpenVR::BeginFrame → SubmitExplicitTimingData → CVRCompositorSharedTextures::
+BeginGPUTimingCommandBuffer` and `xrEndFrame → CVRCompositorClient::SubmitWithArrayIndexAndTime`. Ruled out: the
+layer color scale/bias + image layout structs (FrameBridge `strip_color_bias` 1/2, diagnostic), Valve's Vulkan
+layers (VK_INSTANCE_LAYERS=""), array swapchains in general (Lucky's Tale/I Am Cat flat). Kernel tracepoints aren't
+allowed for steamos. FrameBridge: `layer_debug` logs xrDestroySwapchain and per-5 s xrBeginFrame/xrEndFrame counts;
+`frame_balance` (ends an open frame before the next begin) exists but Vader never leaves one open. Next (built,
+not yet run: the Frame slept): `layer_debug` also counts xrAcquire/Wait/ReleaseSwapchainImage per 5 s (hooked only
+with layer_debug, after the other conditional hooks) to see whether Vader skips a wait or release: it doesn't (361/361/361 per 5 s).
+FrameBridge `snapshot=N` (`snapshot_gl.c`, GLES): every N s the left-eye image the game submits is read back on its
+own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless launches show a black headset view, this
+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).
+**Unreal's self-restart (agent v90, 2026-10-13):** UE 4.21+ restarts the app once after its first-run shader
+precompile ("optimizing" screen; `r.ProgramBinaryCache.RestartAndroidAfterPrecompile`): it starts its own LAUNCHER
+activity and calls System.exit(0); Lepton ends the container with the first process (the restarted one with it).
+Skipping `AndroidThunkJava_RestartApplication` or the cvar = 0 (accepted via UE4CommandLine.txt `-ini:`) left Sports
+Scramble on that level for good. launch.sh (RESTART_BLOCK, `upgrade_launchers` adds it) starts Lepton once more when
+`_restart_requested` sees the app's own LAUNCHER start (system log, uid >= 10000) <= 5 s before its exit; first run
+kept as `launch-before-restart.log`; `FRAMEPORT_NO_RESTART=1` off. Owner-verified with Sports Scramble's first start (2026-10-13).
+**xrWaitFrame runs ahead (Journey of the Gods, 2026-10-14, owner-verified):** with real frames (headset on) the
+Frame's runtime sometimes returns from xrWaitFrame at once with a display time less than one refresh after the frame
+just submitted, and then rejects the second submission for that refresh (`VRCompositorError_AlreadySubmitted` in
+Steam's `logs/xrclient_<pkg>.txt`; FrameBridge pacing above the display rate). VrApi games that render faster than
+the display ran ahead (~120 submits/s at 90 Hz) and the scene slid and snapped back. The VrApi bridge re-waits when
+the new display time is under half a period after the last submitted one (`pacing 2s:` counters). Headless runs only
+submit empty frames and never show it. Lepton's logcat mirror also missed the whole verifying session (launch.log =
+Lepton's own lines only): the keeper now catches a silent mirror too (agent v91).
+**Lepton's logcat mirror dies (agent v67, 2026-10-09; v91 2026-10-14):** Lepton's mirror (`podman exec -it <container> logcat -v threadtime,color`) fails three ways: `logcat: Unexpected EOF!` right after the game starts, `Logcat read failure`, or running and writing nothing at all (Lepton 3.0.5: seen twice on 2026-10-14, once in the owner's session, once headless). launch.sh's `_logcat_keeper` reads `podman exec <container> logcat -v threadtime -T <epoch>` itself into launch.log after a failure line or 20 s without a logcat line (from the launcher's start when the mirror never wrote, else from just before its last line), restarts it from where it ended (≤5), stops it when Lepton's coloured lines come back, sets the container's log buffer to 16 MiB (`logcat -G`), and logs every decision to `<base>/logcat-keeper.log`. Checked on the dev Frame: a mirror killed mid-game (hand-over without a gap) and a silent mirror (the whole session recovered).
+**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
+"(starting)", "Clearing baked app data due to early exit") and both died (Vader, BattleSisters). launch.sh now takes
+`flock` on `<base>/.launch.lock` (fd 9, inherited by Lepton; the watchdog and dashboard helpers close it with
+`9>&-`); a second launch exits 0 and logs to `<base>/launch-dup.log`. `upgrade_launchers` adds it to existing
+launchers. Verified on the device (second launch during boot: ignored, the first kept running). Vader on its loading
+card ignores input too (owner pressed/held every button: presses reach the runtime, the card never changes).
+**Issue triage round (2026-10-06, owner's headset):** vibration in OVRPlugin games = 2 s vibrations updated per frame and
+stopped with amplitude 0; FrameBridge turns amplitude 0 into xrStopHapticFeedback (else each buzz ran 2 s), haptic_fix
+uses the envelope RMS (was its peak), per-game `haptic_scale` → Creed/The Boys/Jurassic World fine. Lambda1VR (TBXR):
+loader named by Build.MANUFACTURER (`frame.tbxr_vendor`), no graphics extension enabled (FrameBridge adds
+XR_KHR_opengl_es_enable + asks for the requirements on -50), always multisampled render-to-texture (GL shim gives
+single-sampled stand-ins when GL_EXT_multisampled_render_to_texture is hidden) + its xash/ data → works. Jurassic World:
+`frame.vrapi_stub`. Metro Awakening: contributor's vkshim fixes + hide_space_warp + no VALVE_rpo (jumping polygons like
+ITR2). Pinball FX VR: hide_space_warp (stutters). Eleven: a Meta online request fails after platform init → needs Meta
+services. Star Wars Tales: top half black + freeze after loading; ruled out: asset-file paks (never requested), Valve
+foveation (off: no change), GL errors (MESA_DEBUG=1: none), EGL_BAD_ACCESS once in OVRPlugin init (harmless); the game's
+eye image reads back black. BlazeRush: VrApi bridge exports + ovr*_ToString stubs + avatar stub get it to the menu room
+at 72 fps, full input reaches it (diagnostics `input 5s`: Touch type only, sticks 1.0, buttons, poses 0x8f), but the room
+draws no controllers and ignores input; avatar loader forced to its "Failed" path (no logged-in user) changed nothing.
+`frame.ovr_trace` can't trace Unity games (P/Invoke dlsym; nothing imports ovr_*). Headless: the VrApi bridge's 30 s
+head-pose deadline ends VR mode without a worn headset (not a game bug).
+**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
+**SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
+
+**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
+
+**Cube swapchains (GitHub #107, 2026-10-09):** the Frame's runtime refuses `faceCount=6` swapchains (-2,
+XR_ERROR_RUNTIME_FAILURE); OVRPlugin ignores that ("CreateSwapchain for eye 0: 0x0, 0 stages") and crashes in
+ovrp_EndFrame4 (memset). FrameBridge `cube_standin` (default on, `native/adapter/cube_standin.c`) serves a refused cube
+swapchain as one GL cube-map texture in the app's context (GLES only) and drops its layers. Verified headless with
+Budget Cuts Ultimate (2048² sRGB, 12 mips; runs on at ~70 fps); what the cube layer showed is simply missing.
+**Hardware video decoding (PR #96, PR #128 by Lucas-Mathieu, adapted 2026-10-10, agent v71):** `native/hevc` = one
+OMX plugin `OMX.frameport.{avc,hevc,vp9}.decoder` (FFmpeg v4l2m2m on Iris /dev/video-dec0, FFmpeg software decoders as
+fallback inside the component, Vulkan copy for big native surfaces). The connection installs it once per Frame
+(`ensure_video_codec` → agent `video_codec_status`/`install_video_codec`: `~/.local/share/frameport/video-codec/versions/
+<manifest sha>` + `current` symlink). A Frame keeps the same or a newer `revision` (no flip-flop between PCs) → **bump
+`revision` in native/hevc/build.py with every artifact change**; a failed install isn't retried during the connection.
+Per game: only launchers of games whose recipe has `frame.hw_video_decode` (install stage, no APK change; suggested
+from analysis `media_codec`, ANALYSIS_VERSION 8; deployment.json `hw_video_decode`) get the codec line → the Podman
+wrapper (native/hevc/podman.py) mounts the plugin into that container (merged media_codecs.xml in
+$XDG_RUNTIME_DIR/frameport-video). Off for every game: Settings → Installing (library `video.hw_decode` → agent
+`video_codec_switch` = video-codec/disabled); one game: `FRAMEPORT_NO_HW_VIDEO=1 %command%`. `upgrade_launchers`
+converts agent ≤70 launchers (Batman's `<base>/frameport-codec` → keeps the line, folder then removed). Batman: catalog
++ migration `batman_video_patches` (`frame.hw_video_decode` + hidden adapter setting `surface_native`). Iris: 8K
+refused (ENOMEM) while any other decoder session is open; SteamVR's vrlinkrunthread holds one ~12 s at game start →
+refused opens retry until 20 s after the plugin loaded (else 2 s), then software; VP9 7680x3840 never returned a
+picture → VP9 ≤4096x2304; hidden VP9 frames come back as empty capture buffers (bytesused 0, no LAST):
+FFmpeg's wrapper ended the EOS drain at the first one (two-pass VP9 lost its last ~25 frames) → build.py requeues
+them (codec revision 8; drain ends at LAST, or 1 s after a skipped empty buffer; dev Frame 2026-10-10: 600/600 =
+OMX.google.vp9 Y hashes). Rebuilds are deterministic (ext4 + NTFS path
+with spaces, two NDK copies → same; rev 8 141de01f…; PR #128's own sources → its 27a2d749…). Not yet run on the device.
+**Vulkan shader dump (GitHub #140, 2026-10-10):** adapter `vk_shader_dump=1` (Vulkan shim, `native/vkshim/shader_dump.h`;
+applies where vk_sanitize can: Unreal/Other arm64) writes each distinct SPIR-V module once to
+`files/fp_vk_shaders/<size>_<sha256>.spv` (tmp + rename) and one `index.txt` line per vkCreateShaderModule (`<seq> <ms>
+<unix ms> <name> new|known|again|failed`, O_APPEND) to find the module behind a GPU hang. Agent v72 `collect_diag`
+returns `shaders` (newest modules of fp_vk_shaders + fp_spirv, ≤4 MB each, base64) → bundle
+`games/<pkg>/target/shaders/`. Triage `gpu-hang` suggests both dumps; `triage.graphics_api` (FrameBridge's
+xrCreateSwapchain formats: <0x1000 Vulkan, else GL) keeps only the session's API's (`API_ONLY`). Host-tested only.
+Agent v74: a reporter's hang came ~10 s after the last new module, so the culprit wasn't among the newest written →
+with an index naming modules, `shader_dumps` sends every module of the index's **newest session** (after the last
+`# start`), deduplicated, last used first, each ≤4 MB, ≤30 MB in all (`session` = how many it names) + that session's
+index lines; no index (fp_spirv) = the old newest-by-mtime 4 MB. One JSON line (~40 MB base64) over the SSH channel
+is read whole by `Frame.agent` (fine at that size); `_Writer.fit` drops the least recently used modules last, after
+cutting logs, to stay under the 24 MB zip limit.
+**Unreal OBB check (GitHub #159, 2026-10-10):** Epic's DownloaderActivity checks OBB name+size (OBBData), then with `bVerifyOBBOnStartUp=true` CRCs the whole OBB; its screens are invisible in Lepton (stuck at `Displayed …/.DownloaderActivity`, triage `unreal-obb-check-stuck`) → `frame.unreal_skip_obb_check` (analysis `unreal_verify_obb`, ANALYSIS_VERSION 11) flips the manifest boolean (`axml.set_meta_data_bool`); skips only the CRC pass. Host-tested only.
+**Issue round 2026-10-12 (agent v83):** Lepton pastes STEAM_COMPAT_DATA_PATH unquoted into `sh -c "ln -s …/internal/<pkg>
+/data/data/<pkg>"` (mounting.sh): a game on a card named "Steam Frame 512g" got no internal storage (no saves/prefs;
+Beyond Sandbox's EOS then looped `createKeychain→resetKeychain` forever, 1.85 GB log). Quest launchers with an unsafe
+path now `ln -sfn <base> ~/.local/share/frameport/lepton-paths/<pkg>` at every start and give Lepton that path
+(`app_dir_lines`/`set_app_dir`/`launcher_base`; upgrade_launchers converts; deployment.json keeps the real base).
+Verified on the device with a spaced copy of Stremio (old: the `ln` error; new: /data/data link, shared_prefs
+writable). `frame.eos_keychain_loop` (opt-in, triage `eos-keychain-loop`) returns from EOSSDK.resetKeychain. Wander
+0.3570 (Unity 6.5, Firebase, Gecko) ran out of bionic's 128 pthread keys → `frame.unity_tls_key_pool` (Klownicle's
+approach, #198: libunity's 4 key imports renamed `fp_tkey_*` via `elf.rename_imports`, `libfp_tkeys.so` pools
+destructor-less keys behind one real key); device: past Firestore, 72 fps. Cpp2IL releases can't read metadata v107
+(Unity 6.5) → `tools/cpp2il.py` falls back to the development CI build (nightly.link) on that error. Vermillion's canvas
+is an OVROverlay quad (drawn above the hand) → `frame.vermillion_scene_canvas` (PaintableMesh getters → false;
+installed build checked, 72 fps headless; headset not yet). Linux apps: `desktop_icon` switch, a deleted desktop copy
+stays deleted (#212). Findings: OLAR (#201) RHIThread null deref in libUnreal (`ldr x8,[x19,#792]`, x19=0) not fixed by
+hide_space_warp / vk_hide_fdm / no Valve layers; FNAF HW (#135) "freeze" = first-start GL program-binary-cache compile
+on Zink (threads busy in zink/disk cache), not a hang; VR4 (#199) reporter's patch.203 OBB truncated. Upload benchmark
+(`scripts/upload_bench.py`, #242): home Wi-Fi caps every method at ~11 MB/s; paramiko uses ~3x OpenSSH's CPU; Windows
+OpenSSH refuses FramePort's key file (ACL "bad permissions") until its permissions are tightened.
+**Meta user id (GitHub #182, 2026-10-11):** OVRPort's platform loader (runtimes 3.4.3-23204ea and -aa54c3f) answers
+`ovr_GetLoggedInUserID` (and two other callers) without a Meta account with a made-up id from a helper (`stp; mov x29,
+sp; bl random; …; mov/movk x9 = 0x53444835ec580000 (6e18); add x0, x8, x9; ldp; ret`), kept only in memory → a new id
+every start; Walkabout Mini Golf files saves under `Profiles/Oculus/<id>/` and lost all progress. `frame.ovr_stable_user`
+(default_on, detect = the game has libovrplatformloader.so) rewrites the helper to `mov x0, <6e18 + 32 bits of
+sha256(package, keystore)>; ret`: stable per game and per user (keystores are personal), so online games never see two
+FramePort users as one. Found in every PATCHED build checked. Host-tested only; upstream candidate.
+**Vivox API 31 (GitHub #101, 2026-10-09):** newer Vivox builds (Green Hell VR) call Android 12 AudioManager
+communication-device methods from `com.vivox.sdk.AudioChangeListener` with no SDK check → NoSuchMethodError on Lepton's
+Android 11. `frame.vivox_audio_route` (analysis `vivox_api31`, ANALYSIS_VERSION 4) makes every such method return at
+once (`Dex.return_early`: return-void / `const/4 v0,0; return v0`; nopping the invoke would leave a move-result the
+verifier rejects). Older Vivox (Eleven Table Tennis, BattleSisters) lacks that code and isn't matched. Verified
+headless: Vivox initialises, 150 s at ~65-70 fps.
+**Steam Input gamepad for 2D apps (GitHub #162, agent v72, 2026-10-10):** Lepton's Android only has the Wayland seat's `wayland_touch/keyboard/pointer`. Steam makes its virtual pad (uinput, `/devices/virtual/input`, 28de:11ff, "Microsoft X-Box 360 pad N", ACL for steamos) only while the Frame's controllers are on (controller.txt "Steam Controller reserving XInput slot 0"; gone when they sleep), also with no game running; steamos-manager's 28de:0000 keys device isn't a pad (no BTN_SOUTH). Lepton's container root (system_server too) = steamos (`keep-id:uid=0`), so a bind-mounted `/dev/input/eventN` opens. Opt-in `device.steam_gamepad` (vr_kind none; suggested for `android.hardware.gamepad`/`LEANBACK_LAUNCHER`, analysis `gamepad`, ANALYSIS_VERSION 9): deployment.json `steam_gamepad` → launcher `GAMEPAD_LINE` (after the codec line: exports FRAMEPORT_GAMEPAD + LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD, puts `agent/bin` first on PATH) → `PODMAN_WRAPPER` (written by ensure_host_fixes; non-`run` calls go straight on; `run` imports the agent's `podman_run_args`; hands on to the next Podman after its own PATH entry with itself removed from PATH, so it chains to the codec wrapper either way round) adds the pads + `Vendor_28de_Product_<pid>.kl` (Xbox 360 layout). Verified headless with a uinput stand-in pad (Stremio's container: EventHub `classes=0x80000141`, our key layout, KeyEvent BUTTON_A dispatched); with Steam's real pad and a game: not yet. Pads made after the start aren't seen until the next one.
+**Multiview programs on flat framebuffers (GitHub #77, Doom3Quest, 2026-10-09, prototype):** Mesa enforces OVR_multiview's
+"program num_views == draw framebuffer views" rule (`draw_validate.c`, the draw is dropped silently); Qualcomm doesn't.
+Doom3Quest compiles every VS with `layout(num_views=2) in;` and draws its HUD/PDA into 2D-texture FBOs → black. Opt-in
+`frame.gl_multiview_fbo` (analysis `gl_multiview_libs`, ANALYSIS_VERSION 6; own-engine GLES only): `native/glmv` =
+`libfpglmv.so` (12 chars = "libGLESv3.so": libdoom3.so's one `.rodata` dlopen string is rewritten in place, its qgl*
+table comes from dlsym on that handle; also first DT_NEEDED for its direct gl*/egl* imports). Such draws use a lazily
+built single-view twin (view 0, uniforms copied per draw); eglMakeCurrent resets the per-thread cache. Host-tested only
+(rewriter on all 19 Doom3Quest shaders + glmv.c against a stand-in GL, `tests/test_gl_multiview_fbo.py`); the host's
+Mesa 23.2 llvmpipe has no OVR_multiview. Headset-verified by Xandrix1987 (2026-10-09: HUD/PDA shown, no fps drop) -> in the Doom3Quest catalog recipe.
+**BlazeRush (GitHub #57, Klownicle's verified guide, 2026-10-10; FramePort's version headless-tested only):**
+`frame.blazerush` (1.0.349 only: exec-segment SHA + every word checked, offsets from PT_LOAD) NOPs the avatar-readiness
+wait (0x4b2dbc), RETs the avatar renderer (0x4b2adc), renames `cache/shader_cache` → `cache/br_shader_v1`. GL shim
+(now also exports glShaderSource/glLinkProgram/glProgramBinary/glDeleteProgram/glDraw*: pass-through unless a setting
+is on) `gl_int_attribs` (integer inputs fed via glVertexAttribPointer re-set with glVertexAttribIPointer per draw,
+reflection cached per EGL context + program, dropped on link/binary/delete) and `gl_highp_markers` (vertex shaders with
+every '|' marker: mediump→highp except on in/out/uniform lines); host test `tests/test_blazerush.py` with a stand-in
+GL. FOV: the game reads VrApi props 7/8 right after vrapi_Initialize (no session; the Frame has no
+XR_EPIC_view_configuration_fov) → the bridge saves the live FOV (also located before tracking, headless: 118.87×120.04
+on the dev Frame) in `files/framebridge-vrapi-fov.txt` and answers with it at the next start (log `FOV properties: …
+(saved by an earlier session)`). `device.config_sync` (catalog field `config_sync`, agent v78): user_config.xml
+r_3dwidth/height, r_width/height from the runtime eye size (FrameBridge logs `runtime recommended eye size`) × scale,
+written at finalize, set_settings and by launch.sh before Lepton starts (`_config_sync`). Headless runs at scale 1.7
+end in `zink: DEVICE LOST` right after the bridge's 30 s no-tracking deadline tears the session down (gpu fault at the
+teardown; not at scale 1.0): a headless-only artifact, the headset never hits that deadline. Launch tests count an exit/crash after
+such a line as a pass (triage.yaml `headless_end`, finding `headless-end`; GitHub #57 "Failed to launch" on install).
+**Session triage (agent v70, 2026-10-09):** launch tests never reach FOCUSED, so real play sessions are triaged
+too. list_installed gives each game `last_play` {start, end, test} from `<anchor>/plays.log` (launch tests write a
+`test <unix>` line first → test sessions are only marked); `session_log` returns the newest session's launch.log
+(`<base>/session.log`, ≤4 MB: head + tail + FrameBridge/crash lines between) + that session's logcat-crash.log +
+`journalctl -k` GPU lines ("kernel: …"). The GUI's connection refresh (`app._check_sessions` → `pipeline.sessions_due`,
+background thread; sessions >7 days old are skipped) runs `pipeline.triage_session` = `validate/session.analyze`
+(triage.yaml signatures incl. `space-warp-used` (info, `question:`, never auto-applied), `gpu-hang` (`report: true`)
++ computed `slow-frames` (pacing windows vs the nearest refresh rate) and `focus-dips` (FrameBridge always logs
+`focus: lost` / `focus: back after N ms`, session_fixes.c)) → library `last_session` / `last_session_checked` → game
+page "Last session" callout (Try this fix / Rebuild with this fix / Yes-No question / Report / Dismiss). Suggestions may
+be values (`adapter.scale=0.85`, `triage.split_suggestion`); adapter-only fixes are pushed live (`apply_suggestions_live`
+→ agent set_settings, like the Game settings dialog). CLI `frameport session <pkg> [--apply]`. PC VR (Proton) launchers
+log no session end, so they aren't triaged yet. pac_hints stays triage-only: a survey of all 68 dump APKs found unpaired
+PAC hints in 21 libraries of 18 games (OpenSSL's 38/40 in most UE4 libUE4.so and libEOSSDK.so, UE5 libUnreal.so ~400
+vs +2-3, libass, libopencv, …), most of them games that work, so default-on would rewrite many working builds.
 **Unresolved (as of 2026-09-28):** Arcsmith (right-eye distortion) and Time Stall (both eyes) — swap, tracking, Valve
 layers, depth, pacing ruled out. Sniper Elite VR (DEVICE LOST), Espire 1 (Mesa GL upload crash), HITMAN 3 (freedreno
 crash): use PC versions.
 
-**Install links / FrameDrop button protocol:** `deeplink.py` parses framedrop://, frameport:// and https install links (strict URL rules, manifest ≤256 KiB, downloads into `<data>/downloads/`), `pipeline.add_from_link`, `views/link_dialog.py`, CLI `frameport open-link`; `urlhandler.py` registers a script (bundles can't take URL arguments), `<data>/links/*.link` + `gui.alive` heartbeat; Settings → Install links (`links.framedrop`/`links.frameport`); `ui/dropped.py`, `pipeline.add_windows_exe`, `device.display_mode`; demo link `deeplink.DEMO_MANIFEST`. → docs/DEVICE_NOTES.md#install-links--framedrop-button-protocol
-**Install link updates:** manifest `version` → library `link.version`; `pipeline.check_link_updates` (GUI start, 6 h, setting `links.check_updates` = Settings → Updates → Games) marks `link_update` → Library bar / game page → `link_dialog.update_from_link`; CLI `frameport link-updates`; the demo link is never checked. → docs/DEVICE_NOTES.md#install-links--framedrop-button-protocol
+**Install links / FrameDrop button protocol (2026-10-07, not yet clicked end to end from a browser):** FrameDrop
+(framedropvr.com, a closed-source Windows sideloader) defines "Install with FrameDrop" buttons:
+`https://framedropvr.com/install?manifest=<url>|url=<file>` → that page opens `framedrop://install?…` (1.6 s, else its
+home page); manifest `{"schema":"framedrop.install/v1","name","files":[{"url","sha256"}]}` (name = Steam title; .apk
+or Linux .zip). `deeplink.py` (no Flet) parses framedrop://, frameport:// and the pasted https link, enforces its
+rules (https; http only on loopback; no credentials; no LAN/loopback/link-local IPs, also after DNS and redirects; URL
+ends in a file name), caps manifests at 256 KiB, ignores non-hex sha256 (FrameDrop's own example has a placeholder),
+downloads into `<data>/downloads/<slug>-<hash>/` (OBBs → `obb/` next to the APK, `.part` removed on cancel/mismatch);
+`pipeline.add_from_link` routes APK / Linux / exe and sets `title` + `title_locked` + `link` (a bare file link keeps
+FramePort's title). GUI: `views/link_dialog.py` (always asks first), Add games → "Install from a link…", CLI
+`frameport open-link [--yes --no-install --gui]`. **A `flet build` bundle can't take a URL argument** (the Flutter
+host treats any argv as a developer page URL), so `urlhandler.py` registers a script, not FramePort.exe: Windows
+HKCU `Software\Classes\{framedrop,frameport}` → hidden PowerShell `frameport-link-handler.ps1`; WSL (source runs)
+the same keys → `wsl.exe -d <distro> -e sh frameport-link-handler.sh`; Linux `frameport-links.desktop` +
+`xdg-mime`; macOS unsupported (Apple Events, paste instead). The script drops the link into `<data>/links/*.link`
+and starts FramePort unless `<data>/gui.alive` is < 10 s old (`gui.starting` stops double starts); the GUI's
+`_watch_links` thread touches the heartbeat and opens links (newest window session). Settings → Install links: one
+switch per scheme (`links.framedrop`, `links.frameport`, default on); a scheme another program owns (FrameDrop) is
+only taken with "Use FramePort for these links" (`register([s], force=True)`); off removes only FramePort's own
+registration (`MARK` in the command). Never registered with FRAMEPORT_HOME/FRAMEPORT_NO_LINK_HANDLER (tests,
+screenshots). Same round: files dropped on the Library (`ui/dropped.py`, bundles only like the Files tab), "Add a
+Windows program (.exe)…" (`pipeline.add_windows_exe`: exe in Downloads/home/drive root copied alone into
+`<data>/windows-apps/<slug>/`), patch `device.display_mode` (Automatic / VR / Flat window → `InstallContext.display`,
+`installer.show_window`). FramePort-only manifest extension `"frameport": {"description", "icon"}` (bad values ignored; icon: same URL rules,
+≤2 MiB, Pillow-checked, ≥32 px, saved as PNG in `<data>/downloads/icons/`, shown in the question by asset URL, then
+`sources.apply_custom(pkg, "icon")` unless `.picked` exists; description fills `details.description` only when
+empty). Bare file links get a title guessed from the file name (`title_from_filename`: version/arch dropped, package
+names → last part). Windows test of 0.12.1.dev191 (2026-10-07): a button click opened the dialog; but a click right
+after closing FramePort did nothing (the closed window's heartbeat was < 10 s old) → the handler scripts now wait
+up to 4 s for the link file to be taken before trusting the heartbeat, the window's CLOSE event / atexit delete
+`gui.alive`, and the Windows command runs under `conhost.exe --headless` (plain `-WindowStyle Hidden` flashed a
+console). Screens: `scripts/ui_smoke.py --links --fake-frame --game <pkg>` (tall pages: `--viewport
+1280x7000`; Flutter's popup menu ignores Escape).
+Demo link: the homepage's example button = `deeplink.DEMO_MANIFEST` (https://frameport.app/demo/cool-game.json, published
+from site/public/demo/); every form (https button page, frameport://, framedrop://, pasted) → `InstallRequest.demo`,
+no network (fetch_manifest returns `demo_manifest()`, download refuses), `link_dialog.show_demo` (Install =
+`easter.demo_install`: Cool Game's cover out of the portal; eggs off → "Nice, it works!"), CLI just says so.
 
 ## Releases, CI, GitHub
 Maintainer-only notes (accounts, credentials, key locations) live in the git-ignored `CLAUDE.local.md`.
@@ -667,13 +1110,6 @@ GitHub identity + credentials are maintainer-local (`CLAUDE.local.md`): check `g
 GitHub write. **The owner approves before posting, labelling or closing anything.** Reply style: "I"/neutral, never
 we/our/us; never mention agent version numbers or internal tool versions; show the owner every draft in full with a
 short recap of the thread so far; read **all** comments on a thread first (a later one often has the zip or the answer).
-- **Every triage also sweeps for unanswered comments**, not just new threads: open AND recently closed issues, PRs
-  (incl. merged/closed ones) and discussions (top-level comments and their replies) whose latest comment isn't the
-  maintainer's, plus earlier user comments a later maintainer reply skipped. Users often ask follow-ups after a fix or
-  after closing (#294: two questions after the reporter closed it; #249: a Q&A discussion with no reply for days;
-  #161/#110: requests posted after the close). Quick check: `gh issue list --state all --search "updated:>=<date>"
-  --json number,comments --jq '.[] | select(.comments[-1].author.login != "spoopyghosty0")'`; discussions via GraphQL
-  (`discussions(orderBy:UPDATED_AT)` with `comments{replies}`).
 - **Issue templates & labels** (`.github/ISSUE_TEMPLATE/`): `[Game report]` → `game-compatibility` (a game that
   doesn't work right); `[Working recipe]` (`working-config.yml`) → `working-config` (a headset-verified config to add);
   `[App]` → `bug` (FramePort itself). Mislabel/relabel to match.
@@ -719,15 +1155,9 @@ MR-only (PASSTHROUGH required + BOUNDARYLESS_APP) → force_passthrough, + USE_S
 hand tracking required → controller_fix=0; OVRPlugin + ≥20 GiB → disable_space_warp; Unreal ≤4.21 or Unreal Meta XR
 Audio → nodebug; Oculus-OS class referenced by the Unreal audio build or ≥2 Meta libs → oculusos; legacy-VrApi Unity
 GLES with MSAA → unity_no_msaa; CryEngine → user.cfg r_variable_rate_shading=0; direct VrApi → bridge (+GL shim for
-GLAD/GLES); Unreal → alternate no-ForceQuit build. Scoring (docs/HEURISTICS_EVAL.md, 2026-10-15): analyse the dumps
-once (`scripts/heuristics_snapshot.py <out.json> "<VR CyberDeck Portable>" "<PATCHED>"`, ~30 min, keep out of git),
-then `scripts/eval_heuristics.py --snapshot <out.json> --split dev|holdout|all [--fit-report]` (catalog-only truth,
-per-patch precision/recall, a fixed 20% holdout to catch rules fitted to one game). Read the **dated** score: an
-"extra" on an entry verified before the patch existed is a catalog gap, and adapter/device picks are inherited by
-catalog recipes anyway. 2026-10-15: strict 5/65 exact, F1 73.8%; dated 39/65, F1 88.6%; remaining misses are
-one-game runtime fixes. Don't key a rule on one game's code fingerprint (an Unreal splash/depth "detect" matching
-only Star Wars Tales + FNAF HW was rejected: it would also have bumped ANALYSIS_VERSION for every user). Add a rule →
-re-run dev + holdout + `pytest -m games`.
+GLAD/GLES); Unreal → alternate no-ForceQuit build. Score changes with
+`python scripts/eval_heuristics.py "<dumps>"` (catalog off vs verified recipes; currently 33/34 exact — Phantom's
+"use the no-ForceQuit build" is only detectable at runtime via triage). Add a rule → re-run the eval + `pytest -m games`.
 
 ## Frame operations
 - Find/connect: `frameport frame discover` / `frame info` (the remembered Frame is in `<user data>/frames.json`).
@@ -761,15 +1191,3 @@ the unresolved eye distortion, and testing the release bundles on real Windows/m
   (regenerates docs/PATCHES.md + site/src/data/patches.json, the site's id → anchor map; a test runs `--check`).
 - Known-good backups of every working APK and the signing keys: `PATCHED/_known-good-2026-09-28/` (don't delete).
 - Your development Frame: `frameport frame info` (remembered in `<user data>/frames.json`); SSH as `steamos@<frame>`.
-
-
-Steam library scheduling (#305, agent v99): `install.steam_library` = now/later/off; agent `library_mode` persists it.
-Automatic restarts also hold on a fresh local `frameport-app/gui.alive` (10 s; existing 12 h cap).
-Later journals changes and installs steam.service ExecStartPre/ExecStartPost hooks to reapply after Steam's exit
-writes and verify before clearing; preserve this ordering and avoid locking across systemctl's startup hooks.
-Off Play (also pending Later Play) uses detached systemd-run launch.sh, with no shortcut/devkit registration;
-Steam's per-game controller/overlay/Exit game integration is lost. Restart Steam now explicitly bypasses holds,
-asks before ending a running game, and closes local FramePort/Desktop Mode. Purge removes the startup hook.
-Hook hardening: both lines `-` + `/usr/bin/timeout -k 5 20`; ExecStartPost only `systemd-run --no-block`s the
-verify (unit frameport-library-verify) so Steam's start never waits; drop-in removed once mode != later and nothing
-pending (`drop_library_hooks_if_idle`). Steam = static user unit steam.service (Type=simple, Restart=always, 90 s).

agent/fexrift_compat.py

@@ -0,0 +1,133 @@
+"""Data-driven FEX game compatibility. No entitlement/runtime-signature changes; stdlib only on the Frame."""
+import hashlib
+import os
+import re
+import shlex
+import struct
+
+STATUSES = {"verified", "likely", "untested", "blocked"}
+GRAPHICS = {"d3d11", "d3d9", "d3d12", "opengl", "vulkan"}
+
+
+def exe_facts(path):
+    """Read just the PE headers. A 32-bit client still needs GE's WoW64 and a working 32-bit VR/graphics bridge."""
+    try:
+        with open(path, "rb") as f:
+            head = f.read(64)
+            if head[:2] != b"MZ" or len(head) < 64:
+                return {}
+            f.seek(struct.unpack_from("<I", head, 0x3c)[0])
+            pe = f.read(26)
+        if len(pe) < 26 or pe[:4] != b"PE\0\0":
+            return {}
+        machine = struct.unpack_from("<H", pe, 4)[0]
+        return {"exe_32bit": machine == 0x14c, "exe_machine": hex(machine)}
+    except (OSError, struct.error):
+        return {}
+
+
+def sha256(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def match_profile(games, app, path):
+    """Exact canonical name OR SHA-256 OR (exe basename AND byte size). No fuzzy title matches: different store
+    builds can need different routes. Multiple matches are refused rather than silently picking one."""
+    hits, digest = [], None
+    for key, profile in games.items():
+        match = profile.get("match", {"canonical_names": [key]})
+        hit = app in match.get("canonical_names", [])
+        if not hit and path and os.path.isfile(path):
+            hit = any(os.path.basename(path).lower() == e["name"].lower() and os.path.getsize(path) == e["size"]
+                      for e in match.get("executables", []))
+            if not hit and match.get("sha256"):
+                digest = digest or sha256(path)
+                hit = digest in match["sha256"]
+        if hit:
+            hits.append((key, profile))
+    if len(hits) > 1:
+        raise ValueError("ambiguous FEX compatibility profiles: " + ", ".join(k for k, _ in hits))
+    return hits[0] if hits else (None, None)
+
+
+def graphics_lines(route):
+    if route not in GRAPHICS:
+        raise ValueError(f"unknown FEX graphics route: {route}")
+    # Proton owns DLL selection/copying: DXVK for D3D9/11, vkd3d-proton for D3D12. Do not override DLLs or copy
+    # anything into the game. Clearing inherited flags also keeps a prior game's wined3d choice from leaking in.
+    lines = ["unset PROTON_USE_WINED3D PROTON_NO_D3D12 PROTON_NO_D3D11"]
+    if route == "opengl":
+        lines.append("export PROTON_USE_WINED3D=1")
+    lines.append(f"echo 'FramePort FEX: graphics={route}'")
+    return lines
+
+
+def register(core):
+    original_find = core.find_ime_target
+
+    def find_ime_target(bins):
+        # Before ApplicationCore was split out, FWindowsApplication (including its deferral CVar) lived in Core.
+        # Robo Recall's modular UE4 build has the SAME CVar and constructor instruction there. Search that module
+        # with the existing anchored finder; never infer a member offset from bAllowedToDeferMessageProcessing.
+        extra = []
+        for folder in sorted({os.path.dirname(b) for b in bins}):
+            extra += [os.path.join(folder, n) for n in sorted(os.listdir(folder))
+                      if re.search(r"(?:^|-)core(?:-win(?:32|64)-shipping)?\.dll$", n, re.I)]
+        return original_find(list(dict.fromkeys(list(bins) + extra)))
+
+    def game_info(app, info):
+        path = os.path.join(info.get("game_dir") or os.path.join(core.META_DIR, "Software", "Software", app),
+                            info.get("exe", ""))
+        key, profile = match_profile(core.GAMES, app, path)
+        if profile is None:
+            return
+        status = profile.get("status", "verified")     # backward compatible with First Contact's original data
+        if status not in STATUSES:
+            raise ValueError(f"invalid FEX profile status: {status}")
+        info.update({k: v for k, v in profile.items() if k != "match"})
+        info.update(profile=key, status=status)
+
+    def launcher_env(app, info):
+        lines = graphics_lines(info.get("graphics", "d3d11"))
+        if info.get("fp_mem") == "enabled":
+            if info.get("status") != "verified":
+                raise ValueError("fp_mem requires a verified per-game opt-in")
+            lines.append("export FP_MEM=1")
+            lines.append("export FP_BIGCACHE_MB=" + str(int(info.get("bigcache_mb", 256))))
+        # candidate is informational: never enable the unzeroed cache merely because the engine uses Binned2.
+        for k, v in info.get("env", {}).items():
+            if not re.fullmatch(r"[A-Za-z_][A-Za-z_0-9]*", k) or not isinstance(v, str):
+                raise ValueError("invalid FEX profile environment")
+        # with the perf extension loaded, perf_prepare writes the game's one dxvk.conf (profile lines + its settings)
+        if info.get("dxvk") and "perf_prepare" not in core.COMMANDS:
+            lines += ["printf '%s\\n' " + " ".join(shlex.quote(line) for line in info["dxvk"]) + ' > "$A/dxvk.conf"',
+                      'export DXVK_CONFIG_FILE="$A/dxvk.conf"']
+        return lines
+
+    def checks(app, info, result):
+        facts = exe_facts(result["exe"])
+        facts.update(profile=info.get("profile"), profile_status=info.get("status", "untested"),
+                     graphics=info.get("graphics", "d3d11"), fp_mem=info.get("fp_mem", "off"))
+        # frameport_agent forwards checks to the PC and deployment.json; top-level helper warnings aren't forwarded.
+        if result.get("warnings"):
+            facts["profile_warnings"] = result["warnings"]
+        if facts.get("exe_32bit"):
+            facts["wow64"] = "untested: requires GE WoW64, 32-bit graphics and SteamVR vrclient bridge under FEX"
+        if facts["graphics"] == "opengl":
+            facts["opengl"] = "untested: no FEX GL thunk configured; rootfs GL may use software rendering or Zink"
+        if facts["graphics"] == "d3d12":
+            # GE versions have used both split lib/lib64 and architecture-qualified Wine directories. Report what
+            # is actually installed; the Proton script remains responsible for selecting its own layout.
+            paths = [os.path.join(core.GE, "files", lib, "wine", "vkd3d-proton", tail, "d3d12.dll")
+                     for lib in ("lib", "lib64") for tail in ("", "x86_64-windows", "i386-windows")]
+            facts["vkd3d_dlls"] = [os.path.relpath(p, core.GE) for p in paths if os.path.isfile(p)]
+        return facts
+
+    core.GAME_INFO_HOOKS.append(game_info)
+    core.find_ime_target = find_ime_target
+    core.LAUNCHER_ENV_HOOKS.append(launcher_env)
+    core.INSTALL_CHECK_HOOKS.append(checks)

agent/fexrift_games.json

@@ -0,0 +1,396 @@
+{
+  "_comment": [
+    "FEX compatibility profiles, loaded by fexrift.py and matched by fexrift_compat.py. No entitlement changes.",
+    "match: OR of canonical_names (exact Meta names), sha256 (list of exe hashes), executables (list of {name,size}, both required). Without match the key is the exact canonical name. Ambiguous matches are refused.",
+    "status: verified (headset checked), likely (static evidence; install with warning), untested (force_unverified required), blocked (refuse even force). graphics: d3d11|d3d9 (DXVK), d3d12 (vkd3d-proton), opengl (PROTON_USE_WINED3D), vulkan.",
+    "env: string-valued environment; args: optional launch arguments override (absent keeps manifest). dxvk: dxvk.conf lines written only to the launcher anchor. notes: evidence and first-launch checks. revive: false for direct OpenVR games, otherwise true.",
+    "ime_patch: optional fallback {rva,old,new}, RVA may be hex; generic finder always wins, including old modular Core.dll. Null means no fallback, never an exemption from IME checks.",
+    "fp_mem: off|candidate|enabled; candidate is informational and NEVER enables the unzeroed cache. enabled requires verified status. bigcache_mb: cache size when enabled, default 256. env FP_MEM is an explicit opt-in retained for First Contact.",
+    "exe is the verified First Contact fallback only; other profiles keep the Meta manifest launch path. msaa_ini allows --msaa for that verified game only."
+  ],
+  "oculus-first-contact": {
+    "title": "Oculus First Contact",
+    "exe": "TouchNUX/Binaries/Win64/TouchNUX-Win64-Shipping.exe",
+    "args": [
+      "-gamemode=\"experienceonly\""
+    ],
+    "ime_patch": {
+      "rva": "0x22a605",
+      "old": "c7862001000001000000",
+      "new": "c7862001000000000000"
+    },
+    "_env": "Unreal's large-block allocator gives 0.5-1.6 GB blocks back every few seconds and this game overwrites them completely: fp_mem keeps them (native/fexwine/fp_mem.c)",
+    "env": {
+      "FP_MEM": "1",
+      "FP_BIGCACHE_MB": "256"
+    },
+    "msaa_ini": true,
+    "status": "verified",
+    "graphics": "d3d11",
+    "fp_mem": "enabled",
+    "bigcache_mb": 256,
+    "notes": "Headset verified; r.MobileMSAA=2 prevented rendering. Other games remain unverified."
+  },
+  "arktika-1": {
+    "title": "Arktika 1",
+    "match": {
+      "executables": [
+        {
+          "name": "arktika1.exe",
+          "size": 20181504
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "graphics API unclear (?); custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown; d3d11 is a trial default, not a detected API"
+  },
+  "asgards-wrath": {
+    "title": "Asgards Wrath",
+    "match": {
+      "executables": [
+        {
+          "name": "WrathGame-Win64-Shipping.exe",
+          "size": 63707648
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "candidate",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenVR); Media Foundation videos need a playback test"
+  },
+  "brass-tactics": {
+    "title": "Brass Tactics",
+    "match": {
+      "executables": [
+        {
+          "name": "Brass-Win64-Shipping.exe",
+          "size": 52790272
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenVR); Media Foundation videos need a playback test"
+  },
+  "chronos": {
+    "title": "Chronos",
+    "match": {
+      "executables": [
+        {
+          "name": "Chronos-Win64-Shipping.exe",
+          "size": 40722432
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": "off",
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "IME fix OFF: the generic finder matched member +0x100 in this UE 4.10 build and the patched game never submitted a frame; unpatched it renders (Frame headless 2026-10-16: 202 frames / 105 s, 1.9 fps while loading, headset not yet checked). Media Foundation videos need a playback test"
+  },
+  "defector": {
+    "title": "Defector",
+    "match": {
+      "executables": [
+        {
+          "name": "DFCTR.exe",
+          "size": 16204288
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown"
+  },
+  "hubris": {
+    "title": "Hubris",
+    "match": {
+      "executables": [
+        {
+          "name": "HubrisVR-Win64-Shipping.exe",
+          "size": 85706240
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "candidate",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenXR/OpenVR); Media Foundation videos need a playback test"
+  },
+  "lies-beneath": {
+    "title": "Lies Beneath",
+    "match": {
+      "executables": [
+        {
+          "name": "Kodiak-Win64-Shipping.exe",
+          "size": 63537664
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "candidate",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenVR); Media Foundation videos need a playback test"
+  },
+  "lone-echo": {
+    "title": "Lone Echo",
+    "match": {
+      "executables": [
+        {
+          "name": "loneecho.exe",
+          "size": 22336512
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown"
+  },
+  "lone-echo-2": {
+    "title": "Lone Echo 2",
+    "match": {
+      "executables": [
+        {
+          "name": "loneecho2.exe",
+          "size": 33436160
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d12",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "D3D12: needs vkd3d-proton on Turnip under FEX (untested); custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown"
+  },
+  "rick-and-morty-virtual-rick-ality": {
+    "title": "Rick and Morty - Virtual Rick-ality",
+    "match": {
+      "executables": [
+        {
+          "name": "RickAndMortyVR.exe",
+          "size": 21284352
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "opengl",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "OpenGL: no FEX GL thunk configured; rootfs GL renderer unverified; OpenVR directly, no Platform SDK; guest GL and speech WinRT need a device check",
+    "revive": false
+  },
+  "robo-recall": {
+    "title": "Robo Recall",
+    "match": {
+      "executables": [
+        {
+          "name": "RoboRecall-Win64-Shipping.exe",
+          "size": 198144
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenVR)"
+  },
+  "skydances-behemoth": {
+    "title": "Skydances BEHEMOTH",
+    "match": {
+      "executables": [
+        {
+          "name": "BHM-Win64-Shipping.exe",
+          "size": 144449024
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "candidate",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenXR); Media Foundation videos need a playback test"
+  },
+  "stormland": {
+    "title": "Stormland",
+    "match": {
+      "executables": [
+        {
+          "name": "Stormland.exe",
+          "size": 85195776
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown; Media Foundation videos need a playback test"
+  },
+  "the-climb": {
+    "title": "The Climb",
+    "match": {
+      "executables": [
+        {
+          "name": "Climb.exe",
+          "size": 95534080
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d9",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "D3D9: DXVK under FEX (untested); CryEngine engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown; D3D9 preferred over imported GL; confirm the actual selected renderer"
+  },
+  "the-unspoken": {
+    "title": "The Unspoken",
+    "match": {
+      "executables": [
+        {
+          "name": "Unspoken.exe",
+          "size": 69496320
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown; Media Foundation videos need a playback test"
+  },
+  "vader-immortal-episode-i": {
+    "title": "Vader Immortal - Episode I",
+    "match": {
+      "executables": [
+        {
+          "name": "WKND-Win64-Shipping.exe",
+          "size": 58100736
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR); Media Foundation videos need a playback test"
+  },
+  "vader-immortal-episode-ii": {
+    "title": "Vader Immortal - Episode II",
+    "match": {
+      "executables": [
+        {
+          "name": "WKND-Win64-Shipping.exe",
+          "size": 59464192
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR); Media Foundation videos need a playback test"
+  },
+  "vader-immortal-episode-iii": {
+    "title": "Vader Immortal - Episode III",
+    "match": {
+      "executables": [
+        {
+          "name": "WKND-Win64-Shipping.exe",
+          "size": 59814912
+        }
+      ]
+    },
+    "status": "likely",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "same profile as First Contact (x64, D3D11, LibOVR/OpenVR); Media Foundation videos need a playback test"
+  },
+  "wilsons-heart": {
+    "title": "Wilsons Heart",
+    "match": {
+      "executables": [
+        {
+          "name": "WHVR.exe",
+          "size": 15379968
+        }
+      ]
+    },
+    "status": "untested",
+    "graphics": "d3d11",
+    "env": {},
+    "ime_patch": null,
+    "fp_mem": "off",
+    "bigcache_mb": 256,
+    "dxvk": [],
+    "notes": "custom engine: no Unreal/Unity fixes apply; startup/allocator behaviour unknown"
+  }
+}

agent/fexrift_install.py

@@ -0,0 +1,361 @@
+"""Local Rift copies in Meta libraries. Runs on the Frame, stdlib only; never touches entitlement or login data."""
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+import uuid
+import zlib
+
+SEGMENT_SIZE = 10000000                       # Meta's manifest format uses decimal 10 MB, not MiB
+
+
+def canonical(value):
+    if not isinstance(value, str) or not re.fullmatch(r"[a-z0-9][a-z0-9_-]+", value):
+        raise ValueError("invalid Meta canonical name")
+    return value
+
+
+def relative(value):
+    if not isinstance(value, str):
+        raise ValueError("invalid relative game path")
+    value = value.replace("\\", "/")
+    if (not value or value.startswith("/") or any(p in ("", ".", "..") for p in value.split("/"))
+            or any(c in value for c in ':\x00\r\n')):
+        raise ValueError("game path escapes its folder")
+    return value
+
+
+def skipped(name):
+    name = name.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    return (name.endswith((".7z", ".ag")) or bool(re.search(r"\.7z\.0", name))
+            or name in ("data.bin", "agrepackinstaller.exe", "vd.bat"))
+
+
+def confined(path, root):
+    """Reject symlink components too: an upload or delete must never follow a game-controlled link."""
+    root, path = os.path.abspath(root), os.path.abspath(path)
+    if os.path.commonpath([path, root]) != root:
+        raise ValueError("path escapes the library")
+    cursor = path
+    while True:
+        if os.path.islink(cursor):
+            raise ValueError("symlink in local game path")
+        if cursor == root:
+            break
+        cursor = os.path.dirname(cursor)
+    if os.path.realpath(root) != root:
+        raise ValueError("symlink in library root")
+    return path
+
+
+def hash_file(path):
+    total, segments = hashlib.sha256(), []
+    size = 0
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(SEGMENT_SIZE)
+            if not chunk:
+                break
+            size += len(chunk)
+            total.update(chunk)
+            # The fixture's last element is the zlib-compressed length, not the uncompressed chunk size. The first
+            # element is an opaque Meta segment identifier: 0 explicitly means unknown for a local-only copy. These
+            # records register existing bytes; they are NOT a CDN download/repair recipe (device validation needed).
+            segments.append([0, hashlib.sha256(chunk).hexdigest(), len(zlib.compress(chunk))])
+    return {"sha256": total.hexdigest(), "size": size, "segmentSize": SEGMENT_SIZE, "segments": segments}
+
+
+def register(core):
+    def record_path(app):
+        return os.path.join(core.ROOT, "local-games", canonical(app) + ".json")
+
+    def read_record(app):
+        return core.read_json(record_path(app)) or {}
+
+    def save_record(app, record):
+        os.makedirs(os.path.dirname(record_path(app)), exist_ok=True)
+        path = record_path(app)
+        with open(path + ".tmp", "w") as f:
+            json.dump(record, f, indent=1)
+        os.replace(path + ".tmp", path)
+
+    def layout(app, dest):
+        app = canonical(app)
+        if dest:
+            # The main agent validates this against list_drives / resolve_dest on EVERY command. No fallback when a
+            # drive disappears. Keep the physical game path simple while Meta sees its required Software/ layout.
+            if not os.path.isabs(dest) or not os.path.isdir(dest):
+                raise ValueError("destination drive is not mounted")
+            base = confined(os.path.join(dest, "FramePort", "fexrift-games"), dest)
+            library = confined(os.path.join(dest, "FramePort", "fexrift-library"), dest)
+            guid = str(uuid.uuid5(uuid.NAMESPACE_URL, "frameport-fex-library:" + dest))
+        else:
+            library = os.path.join(core.META_DIR, "Software")
+            base, guid = os.path.join(library, "Software"), core.LIBRARY_GUID
+        return {"game_dir": confined(os.path.join(base, app), base), "library": library,
+                "library_guid": guid, "dest": dest}
+
+    def validated_record(app):
+        rec = read_record(app)
+        if not rec:
+            raise ValueError("no local-copy upload reservation for this game")
+        expected = layout(app, rec.get("dest"))
+        if any(rec.get(k) != v for k, v in expected.items()):
+            raise ValueError("local-copy reservation has an invalid storage path")
+        return rec
+
+    def prepare(args):
+        app = canonical(args["app"])
+        package = args["package"]
+        files, seen = {}, set()
+        for name, st in args["files"].items():
+            rel = relative(name)
+            if skipped(rel) or rel.casefold() in seen:
+                raise ValueError("skipped or duplicate file in upload inventory")
+            if not isinstance(st["size"], int) or st["size"] < 0 or not isinstance(st["mtime_ns"], int):
+                raise ValueError("invalid source file stat")
+            seen.add(rel.casefold())
+            files[rel] = st
+        if not files:
+            raise ValueError("no game files to upload")
+        old = read_record(app)
+        dest = args.get("dest") or None
+        loc = layout(app, dest)
+        if old and (old.get("dest") != dest or old.get("package") != package):
+            raise ValueError("local copy already has another package or drive; uninstall it before changing either")
+        if not old and (os.path.exists(os.path.join(loc["library"], "Manifests", app + ".json"))
+                        or os.path.exists(loc["game_dir"])):
+            raise ValueError("game already exists outside FramePort's local-copy installer")
+        existing = {}
+        for rel, st in files.items():
+            path = confined(os.path.join(loc["game_dir"], rel), loc["game_dir"])
+            confined(path + ".part", loc["game_dir"])
+            if old.get("files", {}).get(rel) != st:
+                # Delete completed bytes too: if this new attempt is cancelled before uploading them, the next
+                # prepare must not mistake the old same-size file for a completed transfer of the new source.
+                for stale in (path, path + ".part"):
+                    if os.path.isfile(stale):
+                        os.unlink(stale)
+            if (old.get("files", {}).get(rel) == st and os.path.isfile(path)
+                    and os.path.getsize(path) == st["size"]):
+                existing[rel] = st["size"]
+        if old and set(old.get("files", {})) - set(files):
+            raise ValueError("source removed files since the last upload; uninstall the local copy before replacing it")
+        os.makedirs(loc["game_dir"], exist_ok=True)
+        st = os.statvfs(loc["game_dir"])
+        save_record(app, dict(old, **loc, app=app, package=package, files=files))
+        return dict(loc, existing=existing, free_bytes=st.f_bavail * st.f_frsize)
+
+    def registry_library(rec, remove=False):
+        guid, dest = rec["library_guid"], rec.get("dest")
+        key = rf"HKEY_CURRENT_USER\Software\Oculus VR, LLC\Oculus\Libraries\{guid}"
+        if remove:
+            text = f"Windows Registry Editor Version 5.00\r\n\r\n[-{key}]\r\n"
+        else:
+            if dest:
+                devices = os.path.join(core.PFX, "dosdevices")
+                os.makedirs(devices, exist_ok=True)
+                volume = os.path.join(devices, "volume{" + guid + "}")
+                if os.path.lexists(volume):
+                    if not os.path.islink(volume) or os.path.realpath(volume) != dest:
+                        raise ValueError("Wine volume mapping is already in use")
+                else:
+                    os.symlink(dest, volume)
+                # Do not appropriate a user's drive letter. Reuse our mount mapping, else pick the first unused one.
+                letter = next((c for c in "defghijklmnopqrstuvwxy"
+                               if os.path.islink(os.path.join(devices, c + ":"))
+                               and os.path.realpath(os.path.join(devices, c + ":")) == dest), None)
+                if not letter:
+                    letter = next((c for c in "defghijklmnopqrstuvwxy"
+                                   if not os.path.lexists(os.path.join(devices, c + ":"))), None)
+                    if not letter:
+                        raise ValueError("no free Wine drive letter")
+                    os.symlink(dest, os.path.join(devices, letter + ":"))
+                rec["drive_letter"] = letter
+                original = letter.upper() + ":\\FramePort\\fexrift-library"
+                path = "\\\\?\\Volume{" + guid + "}\\FramePort\\fexrift-library"
+            else:
+                original = "C:\\Program Files\\Meta Horizon\\Software"
+                path = "\\\\?\\Volume{00000000-0000-0000-0000-000000000043}\\Program Files\\Meta Horizon\\Software"
+            text = "Windows Registry Editor Version 5.00\r\n\r\n"
+            if not dest:
+                text += (r"[HKEY_CURRENT_USER\Software\Oculus VR, LLC\Oculus\Libraries]" + "\r\n"
+                         + '"DefaultLibrary"=' + core.meta_reg_str(guid) + "\r\n\r\n")
+            text += (f"[{key}]\r\n" + '"OriginalPath"=' + core.meta_reg_str(original) + "\r\n"
+                     + '"Path"=' + core.meta_reg_str(path) + "\r\n")
+        reg = os.path.join(core.ROOT, "local-library.reg")
+        core.put_text(reg, text)
+        core.wine("regedit", "/S", core.winpath(reg), timeout=90)
+
+    def register_local(args):
+        app = canonical(args["app"])
+        rec = validated_record(app)
+        if args.get("package") != rec["package"]:
+            raise ValueError("upload belongs to another package")
+        exe = relative(args["exe"])
+        if exe not in rec["files"]:
+            raise ValueError("launch program is not an uploaded file")
+        app_id = args["app_id"]
+        if not isinstance(app_id, str) or not re.fullmatch(r"[1-9][0-9]*", app_id):
+            raise ValueError("invalid Meta app ID")
+        files = {}
+        for rel, st in rec["files"].items():
+            path = confined(os.path.join(rec["game_dir"], rel), rec["game_dir"])
+            if not os.path.isfile(path) or os.path.getsize(path) != st["size"]:
+                raise ValueError(f"upload incomplete: {rel}")
+            files[rel] = hash_file(path)
+        library = rec["library"]
+        os.makedirs(library, exist_ok=True)
+        if rec.get("dest"):
+            software = os.path.join(library, "Software")
+            target = os.path.dirname(rec["game_dir"])
+            if os.path.lexists(software):
+                if not os.path.islink(software) or os.path.realpath(software) != target:
+                    raise ValueError("external Meta library Software path is already in use")
+            else:
+                os.symlink(target, software)
+        args_list = args.get("args") or []
+        if not isinstance(args_list, list) or any(not isinstance(a, str) or "\x00" in a for a in args_list):
+            raise ValueError("launch arguments must be strings")
+        # list2cmdline follows Windows argv quoting; Meta's own launchFile uses forward slashes. The local launcher
+        # keeps the original argv list in the reservation, avoiding POSIX reinterpretation of Windows quotes.
+        manifest = core.dawn_manifest({"packageType": "APP", "isCore": False, "appId": app_id,
+                                      "canonicalName": app, "launchFile": exe,
+                                      "launchParameters": subprocess.list2cmdline(args_list),
+                                      "launchParameters2D": "", "version": str(args.get("version") or "0.0.0"),
+                                      "versionCode": 1, "files": files})
+        # App fixtures serialize the manifest's derived properties before the package base properties. Match that
+        # order (core's runtime package writer uses base-first); both use the same defaults, CRLF and indentation.
+        first = ("parentCanonicalName", "files", "dlcs", "assetFiles")
+        manifest = {**{k: manifest[k] for k in first}, **{k: v for k, v in manifest.items() if k not in first}}
+        manifests = os.path.join(library, "Manifests")
+        os.makedirs(manifests, exist_ok=True)
+        for suffix, content in ((".json", manifest), (".json.mini", dict(manifest, files={
+                k: v for k, v in manifest["files"].items() if k.lower().endswith(".exe")}))):
+            path = os.path.join(manifests, app + suffix)
+            core.write_manifest(path + ".tmp", content)
+            os.replace(path + ".tmp", path)
+        registry_library(rec)
+        rec.update({k: args.get(k) for k in ("app_id", "app_id_source", "store_app_id", "skipped", "title")})
+        rec.update(source="local_copy", exe=exe, args=args_list, registered=True)
+        save_record(app, rec)
+        return local_info({"app": app})
+
+    def local_info(args):
+        rec = validated_record(args["app"])
+        return {k: rec.get(k) for k in ("source", "app_id", "app_id_source", "store_app_id", "skipped", "dest",
+                                        "package", "game_dir", "library_guid", "registered")}
+
+    def unregister_local(args):
+        app = canonical(args["app"])
+        rec = validated_record(app)
+        if args.get("package") != rec["package"]:
+            raise ValueError("local copy belongs to another package")
+        # Shared/default library stays. An external library is removed from the registry only after its last local
+        # game goes; other games, the Wine prefix, sign-in and save directories remain intact.
+        peers = [core.read_json(os.path.join(core.ROOT, "local-games", f)) or {}
+                 for f in os.listdir(os.path.dirname(record_path(app))) if f.endswith(".json") and f != app + ".json"]
+        if rec.get("dest") and not any(p.get("library_guid") == rec["library_guid"] for p in peers):
+            registry_library(rec, remove=True)
+        if os.path.isdir(rec["game_dir"]):
+            shutil.rmtree(rec["game_dir"])
+        for suffix in (".json", ".json.mini"):
+            path = os.path.join(rec["library"], "Manifests", app + suffix)
+            if os.path.isfile(path):
+                os.unlink(path)
+        os.unlink(record_path(app))
+        return {"removed": True}
+
+    def runtime_state(args):
+        app = canonical(args["app"])
+        rec = validated_record(app) if read_record(app) else None
+        # Read only newly appended runtime log text. Never return log lines: runtime logs can contain account data.
+        logdir = os.path.join(core.USER_DIR, "AppData", "Local", "Oculus")
+        def logs():
+            return [os.path.join(logdir, n) for n in os.listdir(logdir)
+                    if n.lower().endswith((".txt", ".log")) and any(
+                        s in n.lower() for s in ("server", "service"))] if os.path.isdir(logdir) else []
+        offsets = {p: os.path.getsize(p) for p in logs()}
+        librarian = os.path.join(logdir, "OVRLibrarian.log")
+        lib_offset = os.path.getsize(librarian) if os.path.isfile(librarian) else 0
+        probe = subprocess.run(["pgrep", "-f", "[O]VRServer_x64.exe"], capture_output=True, timeout=5)
+        started, proc = probe.returncode != 0, None
+        end = time.monotonic() + 95              # leave room for wineserver's bounded cleanup, total <=120 s
+        state = "timeout"
+        try:
+            if started:
+                runtime = os.path.join(core.META_DIR, "Support", "oculus-runtime")
+                proc = subprocess.Popen([os.path.join(core.GEF, "files/bin/wine"), "./OVRServer_x64.exe"],
+                                        cwd=runtime, env=core.wine_env(), stdout=subprocess.DEVNULL,
+                                        stderr=subprocess.DEVNULL, start_new_session=True)
+            while time.monotonic() < end:
+                if started and os.path.isfile(librarian):
+                    with open(librarian, errors="replace") as f:
+                        if os.path.getsize(librarian) < lib_offset:
+                            lib_offset = 0
+                        f.seek(lib_offset)
+                        done = "invocation completed" in f.read(65536).lower()
+                        lib_offset = f.tell()
+                    if done:
+                        subprocess.run(["pkill", "-9", "-f", "[O]VRLibrarian.exe"], capture_output=True, timeout=3)
+                for path in logs():
+                    with open(path, errors="replace") as f:
+                        off = offsets.get(path, 0)
+                        f.seek(off if os.path.getsize(path) >= off else 0)
+                        text = f.read(1 << 20)
+                        offsets[path] = f.tell()
+                    for line in text.splitlines():
+                        if app not in line and (not rec or rec.get("app_id", "_") not in line):
+                            continue
+                        match = re.search(r"\bstate\s*:\s*(ready|install_available)\b", line, re.I)
+                        if match:
+                            state = match[1].lower()
+                        # Meta's PackageManager lists every registered package at start ("Currently installed
+                        # package: <name>, version code: N"); the "state:" line only comes later (app tracker / sign-in)
+                        elif state == "timeout" and re.search(r"Currently installed package:\s*" + re.escape(app) + r"\s*,",
+                                                              line):
+                            state = "installed"
+                if state != "timeout" or (proc is not None and proc.poll() is not None):
+                    break
+                time.sleep(1)
+        finally:
+            if started:
+                subprocess.run([os.path.join(core.GEF, "files/bin/wineserver"), "-k"], env=core.wine_env(),
+                               capture_output=True, timeout=10)
+                if proc is not None:
+                    try:
+                        proc.wait(timeout=2)
+                    except subprocess.TimeoutExpired:
+                        proc.kill()
+        return {"runtime_state": state, "reused_server": not started}
+
+    original_manifest = core.manifest_launch
+    original_info = core.game_info
+
+    def manifest_launch(app):
+        rec = read_record(app)
+        if not rec.get("registered"):
+            return original_manifest(app)
+        rec = validated_record(app)
+        manifest = core.read_json(os.path.join(rec["library"], "Manifests", app + ".json")) or {}
+        if not manifest.get("launchFile"):
+            raise ValueError("local-copy Meta manifest is missing; register the copy again")
+        return {"exe": relative(manifest["launchFile"]), "args": rec["args"], "title": rec["title"],
+                "game_dir": rec["game_dir"], "args_argv": True}
+
+    def game_info(app):
+        rec = read_record(app)
+        if not rec.get("registered"):
+            return original_info(app)
+        info = dict(core.GAMES.get(app) or {})
+        info.update(manifest_launch(app))
+        return info, app in core.GAMES
+
+    core.manifest_launch = manifest_launch
+    core.game_info = game_info
+    core.COMMANDS.update(prepare_local=prepare, register_local=register_local, unregister_local=unregister_local,
+                         local_info=local_info, runtime_state=runtime_state)
+    core.INSTALL_CHECK_HOOKS.append(lambda app, info, result: {"local_copy": True} if read_record(app) else {})

agent/fexrift_login.py

@@ -0,0 +1,400 @@
+"""Meta's own browser sign-in, in the Frame's shared prefix. No credential files are read.
+
+The broker is a separate, owner-only Unix socket process: native_sso URLs live only in its memory, never in a
+status file, launcher, journal or argv sent over SSH. Helpers and Wine subprocesses have their output discarded.
+"""
+import base64
+import json
+import os
+import re
+import shlex
+import signal
+import socket
+import subprocess
+import sys
+import time
+import urllib.parse
+from pathlib import Path
+
+CORE = None
+DESKTOP = "frameport-oculus.desktop"
+REGKEY = r"HKCU\Software\Wine\WineBrowser"
+MAX_URL = 65536
+
+
+def folder():
+    return Path(CORE.ROOT) / "login"
+
+
+def request(message):
+    with socket.socket(socket.AF_UNIX) as s:
+        s.settimeout(90)
+        s.connect(str(folder() / "broker.sock"))
+        s.sendall(json.dumps(message).encode())
+        s.shutdown(socket.SHUT_WR)
+        return json.loads(receive(s))
+
+
+def receive(s):
+    data = bytearray()
+    while True:
+        part = s.recv(8192)
+        if not part:
+            return data.decode()
+        data.extend(part)
+        if len(data) > MAX_URL * 2:
+            raise ValueError("sign-in message too long")
+
+
+def valid_url(url, callback=False):
+    if not isinstance(url, str) or len(url) > MAX_URL or any(ord(c) < 32 for c in url):
+        return False
+    try:
+        u = urllib.parse.urlsplit(url)
+        return (u.scheme, u.netloc, u.path) == (("oculus", "link", "/frl_login") if callback else
+                                                ("https", "auth.meta.com", "/native_sso/confirm"))
+    except ValueError:
+        return False
+
+
+def host_env():
+    env = dict(os.environ)
+    env.update(CORE.steam_display_env())
+    env.update(XDG_RUNTIME_DIR=f"/run/user/{os.getuid()}",
+               DBUS_SESSION_BUS_ADDRESS=f"unix:path=/run/user/{os.getuid()}/bus")
+    env.pop("LD_PRELOAD", None)
+    return env
+
+
+def quiet(argv, **kw):
+    return subprocess.run(argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=60, **kw)
+
+
+def wine_env():
+    env = CORE.wine_env({"ENABLE_GAMESCOPE_WSI": "0", "PROTON_NO_ZENITY": "1", "PROTONFIXES_DISABLE": "1",
+                         "STEAM_COMPAT_CLIENT_INSTALL_PATH": CORE.STEAM})
+    env.pop("LD_PRELOAD", None)
+    env.pop("STEAM_COMPAT_INSTALL_PATH", None)
+    return env
+
+
+def snapshot(paths):
+    return {str(p): base64.b64encode(p.read_bytes()).decode() if p.exists() else None for p in paths}
+
+
+def restore_files(saved):
+    for name, data in saved.items():
+        p = Path(name)
+        if data is None:
+            p.unlink(missing_ok=True)
+        else:
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_bytes(base64.b64decode(data))
+
+
+def desktop_paths():
+    config = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    apps = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local/share") / "applications"
+    paths = {apps / DESKTOP, config / "mimeapps.list", apps / "mimeapps.list", apps / "defaults.list"}
+    for base in (config, apps):
+        paths.update(base.glob("*-mimeapps.list"))
+        for desktop in os.environ.get("XDG_CURRENT_DESKTOP", "").lower().split(":"):
+            if desktop and re.fullmatch(r"[a-z0-9_-]+", desktop):
+                paths.add(base / f"{desktop}-mimeapps.list")
+    return apps, paths
+
+
+def desktop_entry(helper):
+    # Desktop Exec has its own quoting (single shell quotes are not valid here); %% is a literal percent.
+    escaped = str(helper).replace("%", "%%")
+    for c in ("\\", '"', "`", "$"):
+        escaped = escaped.replace(c, "\\" + c)
+    escaped = re.sub(r"[\r\n\t]", " ", escaped.replace("\\", "\\\\"))   # Desktop string-value layer
+    return ('[Desktop Entry]\nType=Application\nName=Meta sign-in (FramePort)\n'
+            f'Exec="{escaped}" %u\nNoDisplay=true\nTerminal=false\nMimeType=x-scheme-handler/oculus;\n')
+
+
+def helper_script(op):
+    # This tiny script never imports the core or prints exceptions (which could contain the supplied URL).
+    return ("#!/usr/bin/python3 -I\nimport json,socket,sys\ntry:\n"
+            "    with socket.socket(socket.AF_UNIX) as s:\n"
+            "        s.settimeout(90)\n"
+            f"        s.connect({str(folder() / 'broker.sock')!r})\n"
+            f"        s.sendall(json.dumps({{'op': {op!r}, 'url': sys.argv[1]}}).encode())\n"
+            "        s.shutdown(socket.SHUT_WR)\n        s.recv(4096)\n"
+            "except Exception:\n    sys.exit(1)\n")
+
+
+def launcher():
+    q = shlex.quote
+    env = wine_env()
+    keys = ("STEAM_COMPAT_DATA_PATH", "WINEPREFIX", "WINEDLLOVERRIDES", "WINEDEBUG", "FP_NATIVE_WSERVER",
+            "PROTON_NO_ZENITY", "PROTONFIXES_DISABLE", "STEAM_COMPAT_CLIENT_INSTALL_PATH", "XDG_RUNTIME_DIR",
+            "DBUS_SESSION_BUS_ADDRESS", "ENABLE_GAMESCOPE_WSI")
+    exports = "".join(f"export {k}={q(env[k])}\n" for k in keys)
+    display = "".join(f"export {k}={q(v)}\n" for k, v in CORE.steam_display_env().items())
+    return f'''#!/usr/bin/env bash
+# FramePort Meta sign-in: discard Electron output, which can contain native_sso URLs.
+exec >/dev/null 2>&1
+exec 9>{q(str(folder() / '.launch.lock'))}; flock -n 9 || exit 0
+{exports}{display}unset LD_PRELOAD STEAM_COMPAT_INSTALL_PATH STEAM_COMPAT_LIBRARY_PATHS PROTON_LOG PROTON_LOG_DIR
+python3 -I {q(str(Path(CORE.HERE) / 'fexrift.py'))} login_ping '{{}}' || exit 0
+G={q(CORE.GEF)}
+L="$WINEPREFIX/drive_c/users/steamuser/AppData/Local/Oculus"
+cleanup() {{
+    kill $LK 2>/dev/null
+    "$G/files/bin/wineserver" -k
+    rm -f {q(str(folder() / 'launch.pid'))}
+}}
+trap cleanup EXIT
+trap 'exit 0' TERM INT HUP
+# The start tick prevents --stop from signalling a reused PID after an interrupted launcher.
+printf '%s %s\\n' "$$" "$(awk '{{print $22}}' /proc/$$/stat)" > {q(str(folder() / 'launch.pid'))}
+cd {q(str(Path(CORE.META_DIR) / 'Support/oculus-runtime'))}
+"$G/files/bin/wine" ./OVRServer_x64.exe </dev/null &
+for i in $(seq 1 45); do
+    sleep 2
+    tail -n 3 "$L/OVRLibrarian.log" 2>/dev/null | grep -qi "invocation completed" && break
+done
+sleep 3; pkill -9 -f "[O]VRLibrarian.exe"; sleep 10
+( while sleep 5; do pkill -9 -f "[O]VRLibrarian.exe"; done ) & LK=$!
+cd {q(str(Path(CORE.META_DIR) / 'Support/oculus-client'))}
+"$G/proton" run ./Client.exe
+'''
+
+
+def signed_in():
+    sessions = Path(CORE.PFX) / "drive_c/users/steamuser/AppData/Roaming/Oculus/sessions"
+    return CORE.signed_in(str(sessions))   # sessions/<numeric user id>/, not Meta's _oaf framework folder
+
+
+def running(name):
+    # /proc, rather than pgrep -f, avoids matching the command requesting status. Scope to this prefix.
+    for p in Path("/proc").glob("[0-9]*/environ"):
+        try:
+            if (f"WINEPREFIX={CORE.PFX}".encode() in p.read_bytes().split(b"\0") and
+                    name.encode().lower() in p.with_name("cmdline").read_bytes().lower()):
+                return True
+        except OSError:
+            pass
+    return False
+
+
+def status(args):
+    st = CORE.read_json(str(folder() / "state.json"), {}) or {}
+    out = {"runtime_running": running("OVRServer_x64.exe"), "client_running": running("Client.exe"),
+           "page_opened_at": st.get("page_opened_at"), "callback_received_at": st.get("callback_received_at"),
+           "signed_in": signed_in()}
+    if args.get("take_url"):
+        try:
+            out.update(request({"op": "take_url"}))
+        except (OSError, ValueError):
+            pass
+    return out
+
+
+def deliver(url):
+    if not valid_url(url, callback=True):
+        return {"delivered": False}
+    try:
+        # Never put the callback in argv, even between two local processes. The PE reads UTF-8 on stdin.
+        p = quiet([str(Path(CORE.GEF) / "proton"), "run", str(Path(CORE.HERE) / "fp_pipesend.exe")],
+                  input=url.encode(), env=wine_env())
+        return {"delivered": p.returncode == 0}
+    except (OSError, subprocess.SubprocessError):
+        return {"delivered": False}
+
+
+class Broker:
+    def __init__(self, via_pc):
+        self.via_pc = via_pc
+        self.pending = None
+        self.stopped = False
+
+    def handle(self, msg):
+        op = msg.get("op")
+        if op in ("page", "callback"):
+            url = msg.get("url")
+            if not valid_url(url, callback=op == "callback"):
+                return {"accepted": False}
+            st = CORE.read_json(str(folder() / "state.json"), {}) or {}
+            st["page_opened_at" if op == "page" else "callback_received_at"] = time.time()
+            if op == "page":
+                st["page_url"] = "https://auth.meta.com/native_sso/confirm"
+            CORE.write_json(str(folder() / "state.json"), st)
+            if op == "callback":
+                return deliver(url)
+            if self.via_pc:
+                self.pending = url
+            else:
+                quiet(["xdg-open", url], env=host_env())
+            return {"accepted": True}
+        if op == "take_url":
+            url, self.pending = self.pending, None
+            return {"open_url": url} if url else {}
+        if op == "stop":
+            self.pending = None
+            self.stopped = True
+        return {"ready": True}
+
+
+def broker(args):
+    path = folder() / "broker.sock"
+    service = Broker(bool(args.get("via_pc")))
+    try:
+        with socket.socket(socket.AF_UNIX) as s:
+            s.bind(str(path))
+            os.chmod(path, 0o600)
+            s.listen(4)
+            s.settimeout(1)
+            end = time.monotonic() + int(args.get("timeout", 900))
+            while not service.stopped and time.monotonic() < end:
+                try:
+                    conn, _ = s.accept()
+                except TimeoutError:
+                    continue
+                with conn:
+                    conn.settimeout(5)
+                    try:
+                        reply = service.handle(json.loads(receive(conn)))
+                        conn.sendall(json.dumps(reply).encode())
+                    except (OSError, ValueError, subprocess.SubprocessError):
+                        pass   # do not serialize an exception that might contain a URL
+    finally:
+        service.pending = None
+        restore()
+        path.unlink(missing_ok=True)
+    return {"stopped": True}
+
+
+def restore():
+    path = folder() / "restore.json"
+    saved = CORE.read_json(str(path), None)
+    if saved is None:
+        return
+    # Keep the restore record until every step succeeds: --stop can repair an interrupted cleanup.
+    launcher_pid = stop_launcher()
+    CORE.wineserver_kill()
+    if launcher_pid:
+        for _ in range(100):
+            if process_tick(launcher_pid[0]) != launcher_pid[1]:
+                break
+            time.sleep(.1)
+        else:
+            raise CORE.FexError("Meta sign-in launcher is still stopping; retry fex login --stop")
+    (folder() / "launch.pid").unlink(missing_ok=True)
+    old = saved.get("browser")
+    if old:
+        CORE.wine("reg", "add", REGKEY, "/v", "Browsers", "/t", old[0], "/d", old[1], "/f")
+    else:
+        CORE.wine("reg", "delete", REGKEY, "/v", "Browsers", "/f", check=False)
+    restore_files(saved["files"])
+    path.unlink()
+
+
+def stop_launcher():
+    # Killing Wine alone while launch.sh is waiting for OVRLibrarian lets it start Client.exe *after* cleanup.
+    # Signal the owning shell too; its pending TERM exits the startup loop as soon as the current sleep ends.
+    path = folder() / "launch.pid"
+    try:
+        pid, tick = path.read_text().split()
+        pid = int(pid)
+        if pid <= 1:
+            return
+        if process_tick(pid) == tick:
+            os.kill(pid, signal.SIGTERM)
+            return pid, tick
+    except (OSError, ValueError, IndexError):
+        pass
+
+
+def process_tick(pid):
+    try:
+        return Path(f"/proc/{pid}/stat").read_text().rpartition(")")[2].split()[19]
+    except (OSError, IndexError):
+        return None
+
+
+def stop(args):
+    try:
+        request({"op": "stop"})
+        for _ in range(900):
+            if not (folder() / "broker.sock").exists():
+                break
+            time.sleep(.1)
+        else:
+            raise CORE.FexError("Meta sign-in is still stopping; retry fex login --stop")
+    except (OSError, ValueError):
+        restore()
+        (folder() / "broker.sock").unlink(missing_ok=True)
+    return {"stopped": True, "signed_in": signed_in()}
+
+
+def start(args):
+    timeout = int(args.get("timeout") or 900)
+    if not 1 <= timeout <= 86400:
+        raise CORE.FexError("sign-in timeout must be between 1 and 86400 seconds")
+    if not (Path(CORE.HERE) / "fp_pipesend.exe").is_file():
+        raise CORE.FexError("fp_pipesend.exe missing: build native/fexwine/pipesend.c and upload it with fex setup")
+    if not (Path(CORE.META_DIR) / "Support/oculus-client/Client.exe").is_file():
+        raise CORE.FexError("Meta's PC app isn't installed yet; run fex setup first")
+    if running("Client.exe") or running("OVRServer_x64.exe"):
+        raise CORE.FexError("close the Rift game or Meta app before starting sign-in (the prefix is shared)")
+    try:
+        request({"op": "ping"})
+    except (OSError, ValueError):
+        pass
+    else:
+        raise CORE.FexError("Meta sign-in already active; use fex login --stop first")
+    stop({})   # repair a previous interrupted run before snapshotting its handler
+    folder().mkdir(parents=True, exist_ok=True, mode=0o700)
+    folder().chmod(0o700)
+    apps, paths = desktop_paths()
+    previous = subprocess.run(["xdg-mime", "query", "default", "x-scheme-handler/oculus"],
+                              capture_output=True, text=True, timeout=10, env=host_env()).stdout.strip()
+    reg = CORE.wine("reg", "query", REGKEY, "/v", "Browsers", check=False)
+    match = re.search(r"Browsers\s+(REG_\w+)\s+(.*)", reg.stdout)
+    CORE.write_json(str(folder() / "restore.json"),
+                    {"browser": list(match.groups()) if match else None, "handler": previous,
+                     "files": snapshot(paths)})
+    try:
+        for name, text in (("fp-open-url", helper_script("page")),
+                           ("fp-oculus-callback", helper_script("callback")), ("launch.sh", launcher())):
+            CORE.put_text(str(folder() / name), text, 0o700)
+        CORE.write_json(str(folder() / "state.json"), {})
+        apps.mkdir(parents=True, exist_ok=True)
+        (apps / DESKTOP).write_text(desktop_entry(folder() / "fp-oculus-callback"))
+        if quiet(["xdg-mime", "default", DESKTOP, "x-scheme-handler/oculus"], env=host_env()).returncode:
+            raise CORE.FexError("couldn't register the Frame's temporary oculus link handler")
+        CORE.wine("reg", "add", REGKEY, "/v", "Browsers", "/t", "REG_SZ", "/d",
+                  str(folder() / "fp-open-url"), "/f")
+        subprocess.Popen([sys.executable, "-I", str(Path(CORE.HERE) / "fexrift.py"), "login_broker",
+                          json.dumps({"via_pc": bool(args.get("via_pc")), "timeout": timeout + 180})],
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                         start_new_session=True)
+        for _ in range(100):
+            try:
+                request({"op": "ping"})
+                break
+            except (OSError, ValueError):
+                time.sleep(.05)
+        else:
+            raise CORE.FexError("couldn't start Meta sign-in's private URL broker")
+        if args.get("start_now"):
+            if quiet(["systemd-run", "--user", "--collect", "--quiet", "--unit=frameport-fexlogin",
+                      "--property=StandardOutput=null", "--property=StandardError=null",
+                      str(folder() / "launch.sh")], env=host_env()).returncode:
+                raise CORE.FexError("couldn't start Meta's app; retry without --start-now and use Steam")
+        return {"launcher": str(folder() / "launch.sh"), "started": bool(args.get("start_now")),
+                "signed_in": signed_in()}
+    except Exception:
+        stop({})
+        raise
+
+
+def register(core):
+    global CORE
+    CORE = core
+    core.COMMANDS.update(login_start=start, login_status=status, login_stop=stop, login_broker=broker,
+                         login_ping=lambda args: request({"op": "ping"}),
+                         login_callback=lambda args: request({"op": "callback", "url": args.get("url")}))

agent/fexrift_perf.py

@@ -0,0 +1,575 @@
+"""Launch-time performance experiments. Frame side, stdlib only; no account data is read here.
+
+Settings contain numbers/booleans and a small environment whitelist, never arbitrary shell. A launch prepares its
+own config and exports it before Proton starts. Bench owns the otherwise-idle shared prefix for at most 120 s.
+"""
+import collections
+import ctypes as C
+import fcntl
+import hashlib
+import json
+import math
+import os
+import sys
+import re
+import shlex
+import shutil
+import signal
+import struct
+import subprocess
+import time
+from pathlib import Path
+
+CORE = None
+FEX_KEYS = {"FEX_TSOENABLED", "FEX_VECTORTSOENABLED", "FEX_MEMCPYSETTSOENABLED", "FEX_MULTIBLOCK",
+            "FEX_X87REDUCEDPRECISION"}
+DEFAULTS = {"dxvk_disable_msaa": False, "dxgi_sync_interval": -1, "dxgi_max_frame_latency": 0,
+            "eye_scale": 1.5, "motion_smoothing": 2, "cores": "4-7", "ntsync": True,
+            "fp_mem": False, "bigcache_mb": 256, "fp_mem_zero": False, "fex": {},
+            "wine_large_address_aware": False}
+BOOL_KEYS = {"dxvk_disable_msaa", "ntsync", "fp_mem", "fp_mem_zero", "wine_large_address_aware"}
+INT_KEYS = {"dxgi_sync_interval": (-1, 4), "dxgi_max_frame_latency": (0, 16), "motion_smoothing": (0, 2),
+            "bigcache_mb": (1, 6144)}
+
+
+def app_name(app):
+    if not isinstance(app, str) or not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}", app):
+        raise ValueError("invalid Meta app name")
+    return app
+
+
+def validate(values):
+    if not isinstance(values, dict):
+        raise ValueError("settings must be an object")
+    out = {}
+    for key, value in values.items():
+        if key in BOOL_KEYS:
+            if type(value) is not bool:
+                raise ValueError(f"{key} must be true or false")
+        elif key in INT_KEYS:
+            lo, hi = INT_KEYS[key]
+            if type(value) is not int or not lo <= value <= hi:
+                raise ValueError(f"{key} must be an integer in {lo}..{hi}")
+        elif key == "eye_scale":
+            if type(value) not in (float, int) or value not in (1.0, 1.25, 1.5):
+                raise ValueError("eye_scale must be 1.0, 1.25 or 1.5 (a divisor)")
+        elif key == "cores":
+            if not isinstance(value, str) or not re.fullmatch(r"[0-7](?:-[0-7])?(?:,[0-7](?:-[0-7])?)*", value):
+                raise ValueError("cores must be a taskset CPU list within 0..7")
+            if any(len(p) == 3 and p[0] > p[2] for p in value.split(",")):
+                raise ValueError("cores range is reversed")
+        elif key == "fex":
+            if not isinstance(value, dict) or any(k not in FEX_KEYS or type(v) not in (str, int) or
+                                                   str(v) not in ("0", "1") for k, v in value.items()):
+                raise ValueError("fex permits only boolean TSO, MULTIBLOCK and X87REDUCEDPRECISION keys")
+            value = {k: str(v) for k, v in value.items()}
+        else:
+            raise ValueError(f"unknown performance setting: {key}")
+        out[key] = value
+    return out
+
+
+def settings_path(app):
+    return os.path.join(CORE.ROOT, "settings", app_name(app) + ".json")
+
+
+def settings_get(args):
+    app = app_name(args["app"])
+    info = CORE.GAMES.get(app, {})
+    env = info.get("env", {})
+    defaults = dict(DEFAULTS, fp_mem=env.get("FP_MEM", "") not in ("", "0"),
+                    bigcache_mb=int(env.get("FP_BIGCACHE_MB", 256)))
+    defaults.update(validate(info.get("perf", {})))
+    overrides = validate(CORE.read_json(settings_path(app), {}) or {})
+    return {"app": app, "settings": dict(defaults, **overrides), "overrides": overrides}
+
+
+def settings_set(args):
+    app = app_name(args["app"])
+    # Validate the whole request before writing. Null removes an override (the catalog/default becomes active).
+    updates = {k: v for k, v in args.items() if k != "app"}
+    if any(k not in DEFAULTS for k in updates):
+        raise ValueError("unknown performance setting")
+    values = settings_get({"app": app})["overrides"]
+    values.update(validate({k: v for k, v in updates.items() if v is not None}))
+    for k, v in updates.items():
+        if v is None:
+            values.pop(k, None)
+    CORE.write_json(settings_path(app), values)
+    return settings_get({"app": app})
+
+
+def scale_folder(scale):
+    return os.path.join(CORE.ROOT, "revive-scales", format(float(scale), "g"))
+
+
+def eye_variant(data, scale):
+    """Only the research Revive 3.2.0 eye-size site, with PE RVA translation. Never touch Oculus binaries.
+
+    Accept the stock eye-size load or the research divisor load. Refuse other instructions rather than guessing
+    at a new Revive build. Use a dedicated padding slot, leaving shared constants in the data section unchanged.
+    """
+    if data[:2] != b"MZ":
+        raise ValueError("Revive eye scale: invalid PE")
+    pe = struct.unpack_from("<I", data, 0x3c)[0]
+    n, opt = struct.unpack_from("<H", data, pe + 6)[0], struct.unpack_from("<H", data, pe + 20)[0]
+
+    def offset(rva):
+        for i in range(n):
+            size, va, rawsize, raw = struct.unpack_from("<IIII", data, pe + 24 + opt + i * 40 + 8)
+            if va <= rva < va + min(size, rawsize):
+                return raw + rva - va
+        raise ValueError("Revive eye scale: RVA outside sections")
+    ins, slot = offset(0x12eab), offset(0x12e9c)
+    # Original movss xmm4,[1.0], or the research patch's load of the existing 1.5 at RVA 0x4eaa4.
+    # Put our divisor in verified function-alignment padding: changing a shared rdata constant affects other code.
+    old = data[ins:ins + 8]
+    original = bytes.fromhex("f30f102515bb0400")
+    research = b"\xf3\x0f\x10\x25" + struct.pack("<i", 0x4eaa4 - 0x12eb3)
+    if old not in (original, research) or data[offset(0x12e91)] != 0xc3 or data[slot:slot + 4] != b"\xcc" * 4:
+        raise ValueError("Revive eye scale: unexpected 3.2.0 eye-size instruction/padding")
+    out = bytearray(data)
+    struct.pack_into("<f", out, slot, scale)
+    out[ins:ins + 8] = b"\xf3\x0f\x10\x25" + struct.pack("<i", 0x12e9c - 0x12eb3)
+    return bytes(out)
+
+
+def prepare_scales():
+    src = Path(CORE.REVIVE)
+    data = (src / "LibRevive64.dll").read_bytes()
+    # PC setup validates stock 3.2.0 and applies REVIVE_PATCHES (src/frameport/fexrift.py): the visibility fixes and
+    # the eye-size redirect to the 1.5 constant. Accept only that upload, or the same without the eye-size redirect.
+    uploaded = {"eda2a449d230832c95734a03e8c83eeb531668ce676693f636e19c315765af4e",    # all six patches
+                "0a3a6733f5decec74abb16b85c1f72783a6f421160753f600ddae4e8cb6482c6"}    # visibility fixes only
+    if hashlib.sha256(data).hexdigest() not in uploaded:
+        raise ValueError("Revive eye scale: needs FramePort's patched Revive 3.2.0 upload")
+    for scale in (1.0, 1.25, 1.5):
+        patched = eye_variant(data, scale)  # validate before replacing any directory
+        dest = Path(scale_folder(scale))
+        tmp = dest.with_name(dest.name + ".new")
+        shutil.rmtree(tmp, ignore_errors=True)
+        shutil.copytree(src, tmp, copy_function=os.link)
+        # Break the hard link before changing the DLL: shared base and other variants stay intact.
+        dll = tmp / "LibRevive64.dll"
+        dll.unlink()
+        dll.write_bytes(patched)
+        shutil.rmtree(dest, ignore_errors=True)
+        os.replace(tmp, dest)
+
+
+def perf_prepare(args):
+    app = app_name(args["app"])
+    s = settings_get({"app": app})["settings"]
+    config = os.path.join(CORE.ROOT, "settings", app + ".dxvk.conf")
+    os.makedirs(os.path.dirname(config), exist_ok=True)   # first launch of a game nobody changed settings for
+    managed = ("d3d11.disableMsaa", "dxgi.syncInterval", "dxgi.maxFrameLatency")   # these settings win
+    profile = [str(line) for line in args.get("dxvk", []) if "\n" not in str(line)
+               and str(line).split("=", 1)[0].strip() not in managed]
+    lines = profile + [f"{k} = {s[key]}" for k, key, default in (
+        ("d3d11.disableMsaa", "dxvk_disable_msaa", False), ("dxgi.syncInterval", "dxgi_sync_interval", -1),
+        ("dxgi.maxFrameLatency", "dxgi_max_frame_latency", 0)) if s[key] != default]
+    # Defaults = exactly the launch verified in the headset (First Contact, 2026-10-10): no dxvk.conf, the uploaded
+    # Revive (its eye-size patch is 1.5), no large-address-aware flag; only a changed setting adds something.
+    if lines:
+        CORE.put_text(config, "\n".join(lines + [""]))
+    elif os.path.lexists(config):
+        os.remove(config)
+    if s["eye_scale"] == 1.5:
+        revive = CORE.REVIVE
+    else:
+        revive = scale_folder(s["eye_scale"])
+        if not os.path.isfile(os.path.join(revive, "LibRevive64.dll")):
+            prepare_scales()
+    exports = {"FP_CORES": s["cores"], "FP_REVIVE_DIR": revive,
+               "FP_MEM": "1" if s["fp_mem"] else "", "FP_BIGCACHE_MB": str(s["bigcache_mb"]),
+               "FP_MEM_ZERO": "1" if s["fp_mem_zero"] else "0", "PROTON_NO_NTSYNC": "0" if s["ntsync"] else "1",
+               "FP_MOTION_SMOOTHING": json.dumps({"section": f"steam.app.{CORE.GAME_ID}",
+                                                 "key": "motionSmoothingOverride", "kind": "i",
+                                                 "value": s["motion_smoothing"]})}
+    exports.update({k: str(s["fex"].get(k, "0" if "TSO" in k else "1" if k == "FEX_MULTIBLOCK" else "0"))
+                    for k in FEX_KEYS})
+    if lines:
+        exports["DXVK_CONFIG_FILE"] = config
+    if s["wine_large_address_aware"]:
+        exports["WINE_LARGE_ADDRESS_AWARE"] = "1"
+    shell = "\n".join(f"export {k}={shlex.quote(v)}" for k, v in exports.items())
+    if s["ntsync"]:
+        shell += "\nunset PROTON_NO_NTSYNC"
+    return {"shell": shell, "settings": s}
+
+
+def launcher_env(app, info):
+    # stdout is an isolated helper's JSON, then a tiny decoder emits only validated exports. Failure aborts launch:
+    # continuing with an old config would give misleading experimental results (and could enable stale fp_mem).
+    # the compat profile's dxvk.conf lines (stream C) go into the same per-game config as these settings
+    dxvk = [str(line) for line in info.get("dxvk", []) if "\n" not in str(line) and "\r" not in str(line)]
+    arg = shlex.quote(json.dumps({"app": app_name(app), "dxvk": dxvk}))
+    decode = 'import json,sys; print(json.load(sys.stdin)["result"]["shell"])'
+    return [f'FP_PERF=$(python3 -I "$R/artifacts/fexrift.py" perf_prepare {arg}) || exit 1',
+            f'eval "$(printf \'%s\' "$FP_PERF" | python3 -I -c {shlex.quote(decode)})"']
+
+
+# OpenVR IVRCompositor_022 Compositor_FrameTiming, including its 80-byte TrackedDevicePose_t. Keeping the tail
+# prevents GetFrameTimings overwriting a truncated ctypes structure. Versions are pinned, never probed by index.
+class FrameTiming(C.Structure):
+    _fields_ = [(n, C.c_uint32) for n in ("size", "index", "presents", "mis_presents", "dropped", "reprojection")]
+    _fields_ += [("system_time", C.c_double)]
+    _fields_ += [(n, C.c_float) for n in ("pre_gpu", "post_gpu", "gpu_ms", "compositor_gpu", "compositor_cpu",
+                                         "compositor_idle", "client_interval", "present_call", "wait_present",
+                                         "submit", "poses_called", "poses_ready", "frame_ready", "update_start",
+                                         "update_end", "render_start")]
+    _fields_ += [("pose", C.c_byte * 80), ("vsyncs_ready", C.c_uint32), ("vsyncs_first", C.c_uint32)]
+
+
+class VR:
+    def __init__(self):
+        self.core, self.method, self.settings = CORE.vr_settings()
+        try:
+            self.compositor = self.interface(b"IVRCompositor_022")
+            self.system = self.interface(b"IVRSystem_022")
+        except BaseException:
+            self.close()
+            raise
+
+    def interface(self, name):
+        err = C.c_int()
+        obj = self.method(self.core, 3, C.c_void_p, C.c_char_p, C.POINTER(C.c_int))(name, C.byref(err))
+        if not obj or err.value:
+            raise ValueError("benchmark needs " + name.decode())
+        return obj
+
+    def activity(self):
+        # IVRSystem_022::GetTrackedDeviceActivityLevel(HMD=0). UserInteraction (1) and its timeout (2) refuse.
+        return self.method(self.system, 15, C.c_int, C.c_uint32)(0)
+
+    def screen_timeout(self):
+        err = C.c_int()
+        value = self.method(self.settings, 7, C.c_float, C.c_char_p, C.c_char_p, C.POINTER(C.c_int))(
+            b"power", b"turnOffScreensTimeout", C.byref(err))
+        if err.value or not math.isfinite(value) or value <= 0:
+            raise ValueError("cannot read screen timeout; benchmark refused")
+        return value
+
+    def timings(self):
+        rows = (FrameTiming * 128)()
+        for row in rows:
+            row.size = C.sizeof(FrameTiming)
+        n = self.method(self.compositor, 9, C.c_uint32, C.POINTER(FrameTiming), C.c_uint32)(rows, 128)
+        return [{"index": r.index, "presents": r.presents, "gpu_ms": r.gpu_ms,
+                 "cpu_ms": r.client_interval, "system_time": r.system_time} for r in rows[:min(n, 128)]]
+
+    def scene_pid(self):
+        return self.method(self.compositor, 22, C.c_uint32)()  # GetCurrentSceneFocusProcess
+
+    def close(self):
+        self.method(self.core, 1, None)()
+
+
+def drm_engines(text):
+    """DRM fdinfo nanoseconds, deduplicated by drm-client-id by the caller (dup fds share one client)."""
+    out = {}
+    for line in text.splitlines():
+        m = re.fullmatch(r"drm-engine-([\w-]+):\s*(\d+)\s+ns", line.strip())
+        if m:
+            out[m[1]] = int(m[2])
+    return out
+
+
+def process_sample(pids, proc="/proc"):
+    engines, waits, seen = {}, collections.Counter(), set()
+    for pid in pids:
+        base = Path(proc) / str(pid)
+        for fd in (base / "fdinfo").glob("*"):
+            try:
+                text = fd.read_text()
+            except OSError:
+                continue
+            client = re.search(r"^drm-client-id:\s*(\d+)", text, re.M)
+            device = re.search(r"^drm-pdev:\s*(.+)", text, re.M)
+            if not client:
+                continue
+            identity = (device[1] if device else "", client[1])
+            if identity in seen:
+                continue
+            seen.add(identity)
+            for engine, ns in drm_engines(text).items():
+                engines[(identity, engine)] = ns
+        for task in (base / "task").glob("*"):
+            try:
+                waits[task.joinpath("wchan").read_text().strip()] += 1
+            except OSError:
+                pass
+    return engines, waits
+
+
+def gpu_delta(before, after):
+    # Clients that open during the interval have no baseline; do not attribute their lifetime counters to one tick.
+    return sum(max(0, v - before[k]) for k, v in after.items() if k in before)
+
+
+def processes(proc="/proc"):
+    out = {}
+    for p in Path(proc).glob("[0-9]*"):
+        try:
+            if p.stat().st_uid != os.getuid():
+                continue
+            cmd = p.joinpath("cmdline").read_bytes().replace(b"\0", b" ").decode(errors="replace")
+            comm = p.joinpath("comm").read_text().strip()
+            out[int(p.name)] = (comm, cmd)
+        except OSError:
+            pass
+    return out
+
+
+def busy_processes(rows):
+    # Do not print cmdlines: another stream may be handling an Oculus browser sign-in.
+    return [pid for pid, (comm, cmd) in rows.items() if
+            (re.search(r"(?i)(\.exe(?: |$)|(?:^|/)(?:proton|wine(?:64)?(?:-preloader)?)(?: |$)|lepton-steamlaunch-)",
+                       cmd)
+             or (comm == "reaper" and not re.search(r"\bAppId=250820\b", cmd))
+             or comm.startswith("wineserver") or comm in ("FEXInterpreter", "FEXLoader", "pressure-vessel"))]
+
+
+def recent_steam_input(steam, now=None):
+    """Steam input log is a supplementary guard, HMD activity is the authoritative one. Never read login logs."""
+    now = time.time() if now is None else now
+    path = Path(steam) / "logs/controller.txt"
+    try:
+        # A recent controller log write can be a device reconnection, so conservatively refuse it too.
+        return now - path.stat().st_mtime < 60
+    except FileNotFoundError:
+        return False
+
+
+def vr_set(section, key, kind, value):
+    # In its own process: cmd_vrsetting in the process that holds VR()'s SteamVR connection segfaulted on the
+    # second call (reproduced on the Frame 2026-10-16) after the first had turned the display's standby pause off.
+    result = vrsetting_subprocess(section, key, kind, value)
+    if result.get("error"):
+        raise ValueError(f"SteamVR refused {section}/{key}")
+
+
+def stop_launcher(child):
+    # The shared prefix was verified idle before launch, so -k cannot interrupt an earlier game or login.
+    try:
+        subprocess.run([os.path.join(CORE.GEF, "files/bin/wineserver"), "-k"], env=CORE.wine_env(),
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5)
+    finally:
+        if child is not None:
+            try:
+                os.killpg(child.pid, signal.SIGTERM)
+                child.wait(timeout=5)
+            except ProcessLookupError:
+                pass
+            except subprocess.TimeoutExpired:
+                os.killpg(child.pid, signal.SIGKILL)
+                child.wait(timeout=5)
+
+
+START_WAIT = 180   # seconds the bench waits for the game's process after starting its launcher
+
+
+def bench_run(args, launcher, vr):
+    seconds = args.get("seconds", 120)
+    if type(seconds) is not int or not 1 <= seconds <= 120:
+        raise ValueError("seconds must be an integer in 1..120")
+    if busy_processes(processes()) or recent_steam_input(CORE.STEAM) or vr.activity() != 3:
+        raise ValueError("benchmark refused: game, Wine, container, HMD activity or recent Steam input")
+    screen = vr.screen_timeout()  # no setting is changed until both safety checks and this read succeed
+    vrserver_log = os.path.join(CORE.STEAM, "logs", "vrserver.txt")
+    log_start = os.path.getsize(vrserver_log) if os.path.isfile(vrserver_log) else 0
+    guard_write(screen=screen)    # before any change: the parent restores from it if this process dies
+    child, old_handler = None, None
+    settings = settings_get(args)["settings"]
+    frames, waits, gpu, gpu_seconds = {}, collections.Counter(), 0, 0.0
+    started = time.monotonic()
+
+    def interrupted(signum, frame):
+        raise ValueError("benchmark interrupted")
+    try:
+        old_handler = signal.signal(signal.SIGTERM, interrupted)
+        vr_set("power", "pauseCompositorOnStandby", "b", False)
+        vr_set("power", "turnOffScreensTimeout", "f", float(seconds + START_WAIT + 10))
+        # Save the initial frame index so stale scene frames in the compositor ring are excluded.
+        initial = {r["index"] for r in vr.timings()}
+        with open(os.devnull, "wb") as sink:
+            child = subprocess.Popen([launcher], stdin=subprocess.DEVNULL, stdout=sink, stderr=sink,
+                                     start_new_session=True, close_fds=True)
+        guard_write(screen=screen, pgid=getattr(child, "pid", None))
+        # The launcher starts Meta's runtime and waits for it (60-100 s under FEX) before the game: the window
+        # starts when the game's process appears, not at the launch.
+        wait_end = time.monotonic() + START_WAIT
+        while not [q for q, (_, cmd) in processes().items() if args["exe"].lower() in cmd.lower()]:
+            if time.monotonic() > wait_end:
+                raise ValueError(f"benchmark: the game didn't start within {START_WAIT} s; inspect launch.log")
+            if child.poll() is not None:
+                raise ValueError("benchmark launcher exited before the game started; inspect launch.log")
+            level = vr.activity()
+            if level == 1:   # controller.txt isn't a signal here: the starting game loads its input bindings
+                raise ValueError(f"benchmark stopped: owner interaction (activity {level})")
+            time.sleep(1)
+        before, previous = {}, time.monotonic()
+        deadline = time.monotonic() + seconds
+        while time.monotonic() < deadline:
+            # Before the launch the headset must be in standby (3); the game itself then wakes the compositor
+            # (activity leaves standby), so during the run only real use stops it: 1 = user interaction (worn or
+            # moved), or new controller input.
+            level = vr.activity()
+            if level == 1:   # controller.txt isn't a signal here: the starting game loads its input bindings
+                raise ValueError(f"benchmark stopped: owner interaction (activity {level})")
+            if child.poll() is not None:
+                raise ValueError("benchmark launcher exited before the sampling window ended; inspect launch.log")
+            rows = processes()
+            # Only the actual game's exe (or FEX's argv containing it), not the runtime/compositor GPU client.
+            pids = [p for p, (_, cmd) in rows.items() if args["exe"].lower() in cmd.lower()]
+            after, w = process_sample(pids)
+            now = time.monotonic()
+            if before.keys() & after.keys():
+                gpu += gpu_delta(before, after)
+                gpu_seconds += now - previous
+            before, previous = after, now
+            waits.update(w)
+            focus = vr.scene_pid()
+            for r in vr.timings():
+                if focus in pids and r["index"] not in initial:
+                    frames[r["index"]] = r  # ring revisits update presents, not another frame
+            time.sleep(min(0.5, max(0, deadline - time.monotonic())))
+    finally:
+        # Each cleanup is attempted even when the preceding one fails. Display safety outranks benchmark success.
+        try:
+            stop_launcher(child)
+        finally:
+            try:
+                vr_set("power", "pauseCompositorOnStandby", "b", True)
+            finally:
+                try:
+                    vr_set("power", "turnOffScreensTimeout", "f", screen)
+                finally:
+                    if old_handler is not None:
+                        signal.signal(signal.SIGTERM, old_handler)
+    records = list(frames.values())
+    # Without a tracking universe (IMU fallback, e.g. after a boot without the headset worn) Rift games wait at
+    # startup forever: SteamVR's own frames are all a run then counts (seen 2026-10-16, ~1.9/s, game GPU ~0 %).
+    imu_fallback = False
+    try:
+        with open(vrserver_log, errors="replace") as f:
+            f.seek(log_start if os.path.getsize(vrserver_log) >= log_start else 0)
+            imu_fallback = "IMU fallback is active" in f.read(8 << 20)
+    except OSError:
+        pass
+    duration = max(0.001, time.monotonic() - started)
+    times = [r["system_time"] for r in records]
+    span = max(times) - min(times) if len(times) > 1 else 0
+    return {"app": args["app"], "seconds": seconds, "elapsed_s": round(duration, 3), "frames": len(records),
+            "imu_fallback": imu_fallback,   # true: the result says nothing about the game (put the headset on once)
+            "valid": len(records) >= 2 and span > 0 and not imu_fallback, "sample_span_s": round(span, 3),
+            "fps": round((len(records) - 1) / span, 2) if span > 0 else None,
+            "hitches": sum(r["presents"] >= 3 for r in records),
+            "hitches_per_20s": round(20 * sum(r["presents"] >= 3 for r in records) / span, 2) if span > 0 else None,
+            "game_gpu_busy_pct": round(100 * gpu / (gpu_seconds * 1e9), 2) if gpu_seconds else None,
+            "render_gpu_ms": round(sum(r["gpu_ms"] for r in records) / len(records), 3) if records else None,
+            "client_interval_ms": round(sum(r["cpu_ms"] for r in records) / len(records), 3) if records else None,
+            "thread_wchan_samples": dict(waits), "settings": settings}
+
+
+def bench(args):
+    app = app_name(args["app"])
+    # Launcher path is supplied by the owning agent's deployment record, not an arbitrary remote shell command.
+    launcher = args["launcher"]
+    if not os.path.isfile(launcher) or os.path.basename(launcher) != "launch.sh":
+        raise ValueError("install the game before benchmarking")
+    info, _ = CORE.game_info(app)
+    exe = os.path.basename(info["exe"].replace("\\", "/"))
+    os.makedirs(CORE.ROOT, exist_ok=True)
+    with open(os.path.join(CORE.ROOT, ".bench.lock"), "w") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return bench_guarded(dict(args, app=app, exe=exe), launcher)
+
+
+# The measurement talks to SteamVR through ctypes (vrclient.so). A native crash there kills the process without
+# running bench_run's finally, which once left pauseCompositorOnStandby=false (display kept on) on the Frame
+# (2026-10-16). So it runs in a forked child, and the parent restores the display settings and stops the game from
+# a guard file when the child returns no result, each restore in its own process (another crash can't skip it).
+def guard_path():
+    return os.path.join(CORE.ROOT, ".bench.guard.json")
+
+
+def guard_write(**kw):
+    CORE.write_json(guard_path(), kw)
+
+
+def vrsetting_subprocess(section, key, kind, value):
+    """fexrift.py vrsetting in a fresh process: {"error": code} from SteamVR, or {"error": "..."} if it failed."""
+    arg = json.dumps({"section": section, "key": key, "kind": kind, "value": value})
+    p = subprocess.run([sys.executable, "-I", os.path.join(CORE.HERE, "fexrift.py"), "vrsetting", arg],
+                       capture_output=True, text=True, timeout=60)
+    try:
+        out = json.loads(p.stdout.strip().splitlines()[-1])
+    except (ValueError, IndexError):
+        return {"error": f"vrsetting exited {p.returncode}"}
+    return out.get("result", {}) if out.get("ok") else {"error": out.get("error", "failed")}
+
+
+def crash_cleanup():
+    guard = CORE.read_json(guard_path(), {}) or {}
+    try:
+        if guard.get("pgid"):
+            try:
+                os.killpg(int(guard["pgid"]), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+        subprocess.run([os.path.join(CORE.GEF, "files/bin/wineserver"), "-k"], env=CORE.wine_env(),
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=10)
+    finally:
+        vrsetting_subprocess("power", "pauseCompositorOnStandby", "b", True)
+        if guard.get("screen") is not None:
+            vrsetting_subprocess("power", "turnOffScreensTimeout", "f", float(guard["screen"]))
+
+
+def bench_guarded(args, launcher):
+    read_fd, write_fd = os.pipe()
+    pid = os.fork()
+    if pid == 0:                                   # child: measure, report through the pipe
+        os.close(read_fd)
+        code = 0
+        try:
+            vr = VR()
+            try:
+                out = {"ok": True, "result": bench_run(args, launcher, vr)}
+            finally:
+                vr.close()
+        except Exception as e:  # noqa: BLE001 - reported to the parent as the command's error
+            out, code = {"ok": False, "error": f"{type(e).__name__}: {e}"}, 1
+        with os.fdopen(write_fd, "w") as w:
+            w.write(json.dumps(out))
+        os._exit(code)
+    os.close(write_fd)
+    try:
+        with os.fdopen(read_fd) as r:
+            raw = r.read()
+        _, status = os.waitpid(pid, 0)
+        out = json.loads(raw) if raw.strip() else None
+        if out is None:                             # crashed or killed: bench_run's own cleanup didn't run
+            crash_cleanup()
+            raise ValueError(f"benchmark process died ({'signal ' + str(-os.waitstatus_to_exitcode(status)) if os.WIFSIGNALED(status) else 'no result'}); display settings restored, game stopped")
+        if not out["ok"]:
+            raise ValueError(out["error"])
+        return out["result"]
+    finally:
+        try:
+            os.remove(guard_path())
+        except FileNotFoundError:
+            pass
+
+
+def register(core):
+    global CORE
+    CORE = core
+    core.COMMANDS.update(settings_get=settings_get, settings_set=settings_set, perf_prepare=perf_prepare, bench=bench)
+    core.LAUNCHER_ENV_HOOKS.append(launcher_env)
+    # Use the existing setup step so --steps revive prepares the variants too, without another download.
+    def revive():
+        result = core.step_revive()
+        prepare_scales()
+        return result
+    core.STEPS = [(name, revive if name == "revive" else fn) for name, fn in core.STEPS]

announcements/README.md

@@ -1,40 +0,0 @@
-# Announcements
-
-`current.md` is the one announcement FramePort shows as a pop-up in the app. Edit it on `main`: the app reads it
-from GitHub `main` (raw.githubusercontent.com) at most every 6 hours, so a push reaches everyone without a release.
-
-## Who sees it
-
-- **Only people who already used FramePort before the announcement's `date`.** A new install never shows one, and
-  nor does an announcement published before FramePort was installed.
-- **Once.** Closing it in any way (the X, a click outside it, Escape, or its button) dismisses it for good. The app
-  remembers dismissals in its settings (`announce.dismissed`).
-- **A new announcement = a new `id`.** Fixing a typo with the same `id` doesn't show it again to anyone who closed it.
-  A new `id` shows to everyone who used FramePort before its `date`, whether they closed the earlier one or not.
-
-## The file
-
-```markdown
----
-active: true                    # false = nothing is shown (the fields are still checked)
-id: meetup-2026-11             # letters, digits, . _ -  — change it for every new announcement
-title: Steam Frame meetup on Discord  # required
-date: 2026-11-02T18:00:00Z      # required: when it was published (UTC; a bare date = midnight UTC)
-image: announcements/meetup.png # optional: a file in this folder, or an https URL (PNG, JPEG, WebP, GIF; ≤ 5 MiB)
-image_alt: The meetup poster    # optional: what the picture shows (screen readers)
-button: Join the meetup         # optional: an action button, with url
-url: https://example.com/meetup
-expires: 2026-11-30             # optional: not shown after this day (UTC, inclusive)
----
-The body, in Markdown: **bold**, *italic*, `code`, [links](https://frameport.app/), lists, headings.
-```
-
-The body is Markdown (no HTML). A `date` in the future works as a schedule: nobody sees it before then.
-
-Images look best at about 2:1 (e.g. 1200×600). The pop-up is 600 px wide and shows between 140 and 320 px of the
-picture's height.
-
-`pytest tests/test_announcements.py` checks this file, so a broken announcement fails CI instead of silently showing
-nothing.
-
-To turn announcements off for testing: `FRAMEPORT_NO_ANNOUNCEMENTS=1`.

announcements/current.md

@@ -1,16 +0,0 @@
----
-# The announcement FramePort shows once (announcements/README.md). Switched off: set active: true.
-active: false
-id: example-2026-10
-title: Example announcement
-date: 2026-10-15T12:00:00Z
-# image: announcements/example.png
-# image_alt: What the picture shows
-# button: Read more
-# url: https://frameport.app/changelog/
-# expires: 2026-11-30
----
-This is where the text goes, in **Markdown**: *emphasis*, `code`, [links](https://frameport.app/) and lists.
-
-- Keep it short: one or two paragraphs.
-- Change `id` for every new announcement.

artifacts/SHA256SUMS

@@ -1,6 +1,6 @@
 1a4dce5c4a6d0dfc5f20e55ac29e70c73cc2cc124c21ca6a7e1b316e6afb1c79  ./arm64-v8a/libVkLayer_fdm_darken.so
 5becb96ee86fbda0ce98c0e0fd064f8ba092314aceaa400e3dcc785705dc3c23  ./arm64-v8a/libVkLayer_fp_shaderfix.so
-222727ddabf7eaee08c92e86c64f02edc6639667e9041ab2629032b885c9ae3a  ./arm64-v8a/liba32bridge.so
+fbc3b0238462d976d234fee6740db92b873c85d6bb22a6b01428e64e9058ed83  ./arm64-v8a/liba32bridge.so
 c9c3da5cac224c38e2210b781bd12b7f97e02bd6b0ebb0ef85543e4ea4b76671  ./arm64-v8a/liba32rt.so
 18d8d917e83a6d87008f41908eb478dff635e798844e125abd1e8a5cf31805e2  ./arm64-v8a/liba32stub.so
 d6337034fb0bdcca7ef9b7063d85b7586b8508b63b435959e8fffaba0691091c  ./arm64-v8a/libfp_langpack.so
@@ -8,16 +8,16 @@ d6337034fb0bdcca7ef9b7063d85b7586b8508b63b435959e8fffaba0691091c  ./arm64-v8a/li
 321da502e0f8f46f0880aad39fe6b84bdef88f925164568814cf704a1b31a577  ./arm64-v8a/libfp_ovrp.so
 40defdaddcda53bd2649eb48076fae1622bfc2bfc88e9e03c94fc8b45af2a4f2  ./arm64-v8a/libfp_ovrtrace.so
 0167c2fde5dfde62897f9d85afc4fc8e97784e988b5b8df6cea8c407240b3424  ./arm64-v8a/libfp_tkeys.so
-468b97ee3c36481d939a87425b15880c7a801d16732350e1e2832b385d63f20a  ./arm64-v8a/libfp_vk.so
+e8c0965c188665a4e565e4a3af983ef1866d1cf9225665cc90d8df286bc96ef3  ./arm64-v8a/libfp_vk.so
 383054f8b3b41dde76d062c71856cd3163655e50009c08454bc1793f393ead65  ./arm64-v8a/libfpg.so
-4a13a33e112c9e4e3c5ff4337ed6e988a9e5b3602f48d654df148ef5fafbf426  ./arm64-v8a/libfpglmv.so
-36400eae4ba3807bcfcd54463daa217347032b07218792faa448d8cbbd086a0e  ./arm64-v8a/libframe_xrshim.so
+5432674a59d02f411cd853a5dc57e3fa547d1ac518f25bf433fc54c43677177a  ./arm64-v8a/libfpglmv.so
+8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-2d1726aaa8ee0ce788df1b8727bd55ab72efae749e7652f38f67e5e317b74b2f  ./arm64-v8a/libopenxr_loader_generic.so
+0f058921e9c1f5b9ef5847cc9e6b80a23e75028c76c1d3bb02d1610b535f81c9  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi_foveation.so
-eba4e9ed8563fa0de00d88bb85f960e79f13a6f60eddd437b203c8d3b7d308af  ./armeabi-v7a/libopenxr_loader_generic.so
+9e8a7ce599b62a7c607b0d3637e4ec1b1ea1974c3373a7af3f5920ad2adc5e00  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so

artifacts/fexrift/SHA256SUMS

@@ -0,0 +1,9 @@
+3e9099b5015e8f486c00bcea9d111ee721faba355a89bcf1df69561e3dc6325c  ./digicert-assured-id-root-ca.der
+e04db8044185c1c77941252e61794e84af7156c449fedcda4a826d7a9fc91989  ./dlls/crypt32.dll
+ec1387fad1f9b65503077e5aa24e3a3b60b3b04b85fd9412e0f2c451772f9b25  ./dlls/dnsapi.dll
+00ebfab0f3a066d9c85820332e0ec91cf4040797e580516dcafa048dfe758aa7  ./dlls/sechost.dll
+41584c41db41991f20a0b55011efa94618e0817ab351579f793ca01dbb488a0e  ./dlls/windows.devices.enumeration.dll
+420b21045ddc4f166733bf6d2d7227f0131e20f161c4568accb2b9c15a6d8e86  ./fp_mem.so
+f8d6aaaa123337c47837d0be5852f7f6687bb9c4bfaaa108aaab3f04af1ad5b9  ./fp_pipesend.exe
+13d455b700b08f40eb3e3452ab264bf535cb3d176c92ec9a3324a635ce4f8588  ./windows.devices.wifi.dll
+941a65274007db76b1c40880117fe7d881db32c5394ad09f80ccc44a08213a75  ./wineserver.arm64

bootstrap/bootstrap.sh

@@ -34,11 +34,7 @@ say "Letting FramePort log in"
 key=$(curl -fsS "$PC_URL/key?code=$PAIR_CODE")
 [[ "$key" == ssh-ed25519\ * ]] || { echo "Couldn't reach FramePort at $PC_URL. Is it still open?"; exit 1; }
 mkdir -p ~/.ssh && chmod 700 ~/.ssh && touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
-# a file without a final newline would glue our key onto its last line, where sshd never matches it (GitHub #242)
-grep -qxF "$key" ~/.ssh/authorized_keys || {
-  [ -n "$(tail -c1 ~/.ssh/authorized_keys)" ] && echo >> ~/.ssh/authorized_keys
-  echo "$key" >> ~/.ssh/authorized_keys
-}
+grep -qxF "$key" ~/.ssh/authorized_keys || echo "$key" >> ~/.ssh/authorized_keys
 
 say "Setting up Lepton's containers"
 # rootless podman leaks one kernel keyring per container start; ~200 game launches would exhaust the quota

catalog/games/ScaredBySquares.Game.yaml

@@ -1,19 +0,0 @@
-package: ScaredBySquares.Game
-title: Scared By Squares
-status: unknown
-notes: 'Showed black and dropped back to the home environment while the game kept running (sound only, GitHub 323).
-  Fixed in FramePort 1.2.1 and checked on the Frame without the headset (the game runs at 72 fps and SteamVR keeps it
-  as the running game); not yet confirmed in the headset. Rebuild and reinstall the game after updating FramePort.'
-details: 'The game (Unreal 4.27, OpenXR) creates two controller actions named "turn" (an action mapping and an axis
-  mapping called Turn). The Frame''s runtime accepts the duplicate, then fails to load the input manifest it builds
-  from the actions ("SetXrInputConfig failed. Failed to load manifest") and treats the game as closed. FrameBridge''s
-  action_dedup (on by default) creates the second one as "turn_2".'
-tested_version: '2'
-engine: Unreal
-xr: OpenXR
-frame:
-- frame.hw_video_decode
-- frame.unreal_skip_obb_check
-updated: '2026-10-16'
-min_app: 1.2.1
-source_hint: Scared By Squares

catalog/games/com.Astrea.Gundam.yaml

@@ -7,14 +7,8 @@ xr: OpenXR
 status: works
 notes: Uses Meta XR Audio via FMOD (not covered by patch_meta_xr_audio); if audio is missing, that is the likely
   cause.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 63fff470777f2753d55ad50f8355573ced8fa48bcaee0f5e6a0c10369f951a38
-updated: '2026-10-15'

catalog/games/com.BithellGames.Arcsmith.yaml

@@ -6,15 +6,9 @@ engine: Unity
 xr: VrApi
 status: issues
 notes: Right eye distorts during movement (unresolved; swap, tracking, Valve layers, depth and pacing ruled out).
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: Legacy VrApi via OVRPlugin; overport swaps in an OpenXR OVRPlugin. Do not remove VrApi.
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 192ff250f5fbec38b9c4e898f0b8408edc25901f46bb4b227f7ca60bbd9f0bba
-updated: '2026-10-15'

catalog/games/com.BolverkGames.GenotypeGame.yaml

@@ -6,15 +6,9 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Needed the GLES/sRGB swapchain fallback.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: Also available as a native PC SteamVR title.
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 158f7c4f5e8558029dc8cc5e8dcb4e67e846b261bf34e3e448fee7f657c74597
-updated: '2026-10-15'

catalog/games/com.CreaTeam.Sclerosis.yaml

@@ -1,20 +0,0 @@
-package: com.CreaTeam.Sclerosis
-title: Sclerosis
-status: works
-notes: Copy the "Amnesia The Dark Descent" folder from a Windows/Proton install to "FramePort/com.CreaTeam.Sclerosis/lepton-data/external".
-  Default hand positions are rather askew and should be amended via VR Controller Mappings in Steam itself. FOV
-  warping effects are EXTREMELY disorienting in VR, beware. Otherwise seems to work without issue.
-tested_version: 1.10.7
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
-verified:
-  date: '2026-10-16'
-  known_good_sha256: e17421ad9894f5e57fb9b1b8110544715166756ef924b5a86831f6f20e70a6d5
-  app: 1.2.0
-  overport_cli: 1.2.5
-  issue: 339
-source_hint: Sclerosis_v1.10.7

catalog/games/com.Curve.LawnMowingSimulatorVR.yaml

@@ -1,24 +0,0 @@
-package: com.Curve.LawnMowingSimulatorVR
-title: Lawn Mowing Simulator VR
-status: issues
-notes: Left eye textures flicker only when mowing in specific areas.
-tested_version: 1.0.50
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  pose_consistency: 1
-  hide_space_warp: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 2653e9b1dfbd11d607b5dd17b9c07ab19d9e98e1004ef9b14cb52867b5f959dc
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 344
-source_hint: com.Curve.LawnMowingSimulatorVR

catalog/games/com.CyDream.BattleTalent.yaml

@@ -1,29 +0,0 @@
-package: com.CyDream.BattleTalent
-title: BattleTalent
-status: issues
-notes: "Plays normally. The mixed-reality mode doesn't appear in the start menu (also with an APK from a Quest 3); MR
-  progress in #355. Multiplayer not tested yet."
-tested_version: '4.7'
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-- frame.hw_video_decode
-- frame.luajit_pointers
-- frame.unity_runtime_msaa_off
-- frame.meta_permissions
-- frame.unity_multipass
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scene_emul: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 17bbf8d7fc0f24d61986a0c5e1e9175cfe1239de6f8bcb2f588a57f80d83a1d3
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 381
-source_hint: com.CyDream.BattleTalent

catalog/games/com.FlatHeadStudio.DeadlyDelivery.yaml

@@ -1,10 +0,0 @@
-package: com.FlatHeadStudio.DeadlyDelivery
-title: Deadly Delivery
-status: unsupported
-notes: "Quits after Meta's entitlement check fails: it needs Meta's online services."
-tested_version: 1.0.30
-engine: Unity
-xr: OpenXR
-verified:
-  date: '2026-10-15'
-  issue: 322

catalog/games/com.FuturLab.PowerWashSimulator.yaml

@@ -6,14 +6,8 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Recommended pilot title.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 2300f628ce04c1da60b52fed18335d6a31b88cc88313fd6d2c0e1a8e7785126f
-updated: '2026-10-15'

catalog/games/com.HypetrainDigitalLtd.Breathedge.yaml

@@ -1,22 +0,0 @@
-package: com.HypetrainDigitalLtd.Breathedge
-title: Breathedge VR
-status: works
-notes: Loading fade is broken and only shows a small square but the game works!
-tested_version: 1.0.7
-engine: Unreal
-xr: VrApi
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.hw_video_decode
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 4975a32fbf36b4d417142a944bf7d771c18a184dc0320b5937ac2c67bd013575
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 347
-source_hint: Breathadge

catalog/games/com.JustAddWater.SniperEliteVR_EN.yaml

@@ -5,14 +5,9 @@ source_hint: 'Sniper Elite VR- Winter Warrior'
 engine: Unity
 xr: OpenXR
 status: works
-notes: frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
+notes: ''
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 6b8170da5826b9a35326a20967a0e5a242d46fb569a0a3c669e1cbd368102dd3
-updated: '2026-10-15'

catalog/games/com.Miragesoft.RealVrFishingQ.yaml

@@ -1,28 +0,0 @@
-package: com.Miragesoft.RealVrFishingQ
-title: Real VR Fishing
-status: issues
-notes: Seems to be almost 100% functional with meta permissions enabled.  In the new Mixed Reality mode, the room
-  scan doesn't seem to do anything and I can't seem to manually place anything either.
-tested_version: '3.06096'
-engine: Unity
-xr: OpenXR
-frame:
-- frame.vivox_audio_route
-- frame.unity_text_input
-- frame.oculusos
-- frame.meta_permissions
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scene_emul: 1
-  controller_models: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 8b17dd26ef0486618ec006f9d948a60dabea4d7763bbe6061db07ee8aad27c76
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 333
-source_hint: Real VR Fishing

catalog/games/com.Novelab.Demeter.yaml

@@ -6,14 +6,11 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Passthrough + Meta scene/room emulated from the Steam guardian (scene_emul=1).
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: Mixed-reality-only; builds its level from the room model, which the adapter emulates from the Steam guardian.
 overport_extra:
 - patch_force_passthrough
 adapter:
   scene_emul: 1
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
@@ -21,5 +18,3 @@ verified:
   known_good_sha256: 9f900fc86fbb2663abe83c82ab79cc72bbf1f93fea54f7583fd274dd07e3d09c
 frame:
 - frame.meta_permissions
-- frame.unity_text_input
-updated: '2026-10-15'

catalog/games/com.RealitiesIO.puzzlingPlaces.yaml

@@ -1,25 +0,0 @@
-package: com.RealitiesIO.puzzlingPlaces
-title: Puzzling Places
-status: issues
-notes: Works fine, but pointers dont show well on main menu, easy to work around.
-tested_version: '2.14'
-engine: Unreal
-xr: OpenXR
-overport_extra:
-- patch_disable_space_warp
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.unreal_skip_obb_check
-- frame.unreal_ovrp_entrypoints
-- frame.hw_video_decode
-adapter:
-  equirect_emul: 1
-  haptic_fix: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 8d9bb64b0af4c34269fffb64c5ef7515d6ba4715f5234f95517975b8e2b56c00
-  app: 1.2.0
-  overport_cli: 1.2.5
-  issue: 359
-source_hint: Puzzling Places

catalog/games/com.SDI.TWD.yaml

@@ -1,22 +0,0 @@
-package: com.SDI.TWD
-title: 'The Walking Dead: Saints & Sinners'
-status: works
-tested_version: Shipping / 2024.01.19 / build 400355 - STAGECH1
-engine: Unreal
-xr: VrApi
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.ovr_microphone
-- frame.hw_video_decode
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 4b172a5abba0901c75278fb55b867f344120c658c26ae07c8558d90e0c38cec3
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 376
-source_hint: The Walking Dead- Saints & Sinners

catalog/games/com.SchellGames.LostRecipes.yaml

@@ -1,22 +0,0 @@
-package: com.SchellGames.LostRecipes
-title: Lost Recipes
-status: works
-tested_version: 1.0.1+273175
-engine: Unreal
-xr: VrApi
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.unreal_skip_obb_check
-- frame.hw_video_decode
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: f071a1deea3e3b6dce0c3a923127f540a48b88532106536c1838f496e9d3e6c9
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 340
-source_hint: Lost Recipes

catalog/games/com.TeamPanoptes.SilhouetteVR.yaml

@@ -6,18 +6,12 @@ engine: Unity
 xr: OpenXR
 status: issues
 notes: Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: Hand-tracking-only game; Steam Frame has no optical hand tracking. Built with controller_fix=0 so hand
   data passes through if the runtime ever provides it.
 adapter:
   controller_fix: 0
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: a19b80db0c300d422cbba35a4924ab59211b39bcb6485e200d310e3e1372ddb7
-updated: '2026-10-15'

catalog/games/com.TriangleFactory.Breachers.yaml

@@ -1,11 +0,0 @@
-package: com.TriangleFactory.Breachers
-title: Breachers
-status: unsupported
-notes: Online-only multiplayer that needs Meta's online services, which aren't available on the Frame. The game's own
-  copy of Meta's platform library (libovr_custom.so) quits at start ("Failed to launch SystemActivities").
-tested_version: 40.0.23
-engine: Unity
-xr: OpenXR
-verified:
-  date: '2026-10-17'
-  issue: 357

catalog/games/com.UNIVRS.Freedom.yaml

@@ -1,24 +1,22 @@
 package: com.UNIVRS.Freedom
-title: 'Attack on Titan VR: Unbreakable'
-status: works
-notes: Keep the extra files that come with the APK and OBB next to the OBB (they hold the audio). Cutscenes are
-  detached from the head but still viewable.
+title: Freedom
+status: issues
+notes: Volume can't be changed in the game.
 tested_version: 1.0.2950
 engine: Unity
 xr: OpenXR
 frame:
 - frame.unity_text_input
-- frame.asset_files
 device:
 - device.text_input_window
 adapter:
   haptic_fix: 1
 verified:
-  date: '2026-10-16'
-  known_good_sha256: 1b3ced1a24b3b708f66aba6aa879863b667c0e502ef153d8a8cfa03e529d21fd
-  app: 1.2.0
+  date: '2026-10-10'
+  known_good_sha256: 24662272c4cbe5dc7c4f3c803bdb9dead9661ac3d59bf80cca2e260256acc4bc
+  app: 0.12.0
   overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 337
-source_hint: Aot
+  frame_build: '20261007.6125817'
+  agent: 59
+  issue: 132
+source_hint: AOT VR

catalog/games/com.Ubisoft.ACNexusVR.yaml

@@ -7,15 +7,10 @@ xr: OpenXR
 status: works
 notes: FrameBridge turns its upside-down UI panels upright (flip emulation, in place since FramePort 1.2.0). Ubisoft
   login may not work.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 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:
 - patch_ac_nexus_no_appsw_90
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
@@ -23,5 +18,5 @@ verified:
   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-15'
+updated: '2026-10-14'
 min_app: 1.2.0

catalog/games/com.VertigoGames.The7thGuestVR.yaml

@@ -1,27 +0,0 @@
-package: com.VertigoGames.The7thGuestVR
-title: The 7th Guest VR
-status: issues
-notes: Runs and is playable. Foveated rendering (fixed and eye-tracked) sits offset toward the bottom right, and
-  changing the foveated region size has no visible effect.
-tested_version: 1.1.3.12072
-engine: Unreal
-xr: OpenXR
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.unreal_skip_obb_check
-- frame.hw_video_decode
-adapter:
-  haptic_fix: 1
-  scale: 2.0
-foveation: fixed
-foveation_radius: 0.1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 11a1208888adedf4aa48a672b2af5535f0e8f11e5bb1ce0a28bafe5d272bb672
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 363
-source_hint: Guest

catalog/games/com.asg.clockworkdev.yaml

@@ -1,5 +1,5 @@
 package: com.asg.clockworkdev
-title: The Last Clockwinder
+title: Clockwork
 status: works
 tested_version: '1.29'
 engine: Unity

catalog/games/com.baywilly.crazytaxivr.yaml

@@ -1,17 +0,0 @@
-package: com.baywilly.crazytaxivr
-title: CrazyTaxiVR
-status: works
-tested_version: CrazyTaxiVR-42
-engine: Other
-xr: OpenXR
-adapter:
-  scale: 0.85
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 6801a09fec435776457dd2abd1c60d7db240be26cb846699946303aa94f53b04
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 380
-source_hint: CrazyTaxiVR

catalog/games/com.camouflaj.manta.yaml

@@ -2,7 +2,6 @@ package: com.camouflaj.manta
 title: 'Batman: Arkham Shadow'
 status: works
 notes: Large data set (~27 GiB) incl. all language packs.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: 'Uses Meta XR Audio (Wwise), handled by patch_meta_xr_audio. Cutscenes are 8K HEVC panoramas: frame.hw_video_decode
   decodes them on the Frame''s hardware, adapter.surface_native shows them in stereo (PRs #96, #128). Includes all
   language packs (~28 GB). sync_guard (to test, GitHub #102) - a reporter''s game quit to Steam''s waiting screen
@@ -14,18 +13,15 @@ overport_extra:
 - patch_disable_space_warp
 frame:
 - frame.hw_video_decode
-- frame.unity_text_input
 adapter:
   sync_guard: 1
   surface_native: 1
   fade_quad: 1
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 796d1cab08f614d72c50d9702974c719c0908f5de91183cfe02d1fd5eb09551a
-updated: '2026-10-15'
+updated: '2026-10-13'
 min_app: 1.1.0
 source_hint: Batman- Arkham Shadow

catalog/games/com.com.spectralgames.Medieval.yaml

@@ -6,15 +6,9 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Co-op unavailable.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: 'Release notes: for DLC use an older version. Co-op likely unavailable.'
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 06428a6328a49b3ca769e070dd0d2bb55c2122c8fba5d07a69b1b206a532c212
-updated: '2026-10-15'

catalog/games/com.crytek.climb.yaml

@@ -1,21 +0,0 @@
-package: com.crytek.climb
-title: The Climb
-status: works
-tested_version: '666.0'
-engine: CryEngine
-xr: VrApi
-frame:
-- frame.vrapi_bridge
-device_files:
-  user.cfg: 'r_vr_foveated = 0
-
-    '
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 3899967dd6d3ee0ce3409e94d543405c779e9c282ead29536abe93b3531ca285
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 341
-source_hint: TheClimb

catalog/games/com.fasttravelgames.lollipop.yaml

@@ -1,26 +0,0 @@
-package: com.fasttravelgames.lollipop
-title: 'Vampire: The Masquerade - Justice'
-status: issues
-notes: Game runs fine and playable, on loading there's a random sphere in the middle of the sceen. Also control
-  input images are missing so you get text like press <img>wmr.Rstick...
-tested_version: 1.00.1653
-engine: Unreal
-xr: OpenXR
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.bhaptics_permission
-- frame.hw_video_decode
-adapter:
-  haptic_fix: 1
-  scale: 2.0
-foveation: tracked
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 5669f8e9c52e4fa00a3bbce79d323c7f521e098b08dacaf330db0083c7993dee
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 377
-source_hint: vampire

catalog/games/com.fasttravelgames.mascot.yaml

@@ -1,22 +0,0 @@
-package: com.fasttravelgames.mascot
-title: 'Cities: VR'
-status: works
-notes: Loading screen Cities VR Logo doesn't load right.
-tested_version: 1.00.502
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 5537e4e9333a04eda8c1b2f96cdc9572c1bbed52a9d3af42269ba442ce9ba801
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 345
-source_hint: CitiesSkylines

catalog/games/com.fgovr.quest.yaml

@@ -1,16 +0,0 @@
-package: com.fgovr.quest
-title: FGO VR
-status: issues
-notes: Audio stuttering and popping sounds
-tested_version: 0.2.0-fgo-resolution
-engine: Other
-xr: OpenXR
-adapter:
-  scale: 1.2
-verified:
-  date: '2026-10-17'
-  known_good_sha256: e26a0755297961e5131fe4bd404cbd956e18aef01bed71a79114805f6d805032
-  app: 1.2.1.dev433
-  overport_cli: 1.2.5
-  issue: 364
-source_hint: com.fgovr.quest

catalog/games/com.iillusions.bamgame.yaml

@@ -6,17 +6,11 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Passthrough emulated with the Frame cameras (greyscale).
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: Mixed-reality-only title; relies on passthrough (emulated).
 overport_extra:
 - patch_force_passthrough
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 65ca3a8f46cc9acfd268949418f9adeecb0cf9f59d11591ba95fe2ba9ea966d8
-updated: '2026-10-15'

catalog/games/com.ilmxlab.tales.yaml

@@ -4,8 +4,6 @@ status: works
 notes: >-
   Headset tested for GitHub issue 61: full view, loading into gameplay, both eyes, controller input and sound
   work with the splash bypass and multiview depth-size fix. Keep the main OBB and all three content/sound-bank PAKs.
-  GitHub issue 369 (headset, Lepton 3.0.5): the GPU hang at a later loading screen is fixed by zink_shader_fix;
-  played ~28 min at 72 fps.
 details: Unreal Engine 4 (GLES) by ILMxLAB, like Vader Immortal, but a different engine build - it has none of Vader's
   Quest-only branches (no GetQuestShaderPrecompilePercent or RPOC key map; it precompiles shaders through Unreal's
   own pipeline cache), so frame.unreal_quest_precompile/_keymap don't apply. Its seasons and Wwise banks are Meta
@@ -19,10 +17,6 @@ details: Unreal Engine 4 (GLES) by ILMxLAB, like Vader Immortal, but a different
   frame.unreal_multiview_depth refreshes both cached dimensions from the current eye render size; multiview and
   multisampling remain enabled. The two engine fixes check exported symbols, function sizes and instruction bytes
   before changing one instruction each; unrecognized engine builds are left unchanged.
-  A fragment shader (module 16800_8dbab031..., as Zink compiles it) reads 12 int loop counters/accumulators before
-  setting them and hangs the GPU (kernel hangcheck) at a loading screen, the same bug as Vader Immortal's lightspeed
-  shaders; the Vulkan layer under Zink inserts stores of 0 (frame.zink_shader_fix, zink_shader_fix). Captured with
-  Lepton 3.0.5, so a Frame update that changes Zink's output stops it matching (the layer logs that).
 tested_version: 1.1.9+734762.cl.439699
 engine: Unreal
 xr: VrApi
@@ -33,12 +27,10 @@ frame:
 - frame.unreal_thumb_touch
 - frame.unreal_splash_bypass
 - frame.unreal_multiview_depth
-- frame.zink_shader_fix
 adapter:
   pose_time_fix: 1
-  zink_shader_fix: 16800:8dbab031be7975e23452e333fe63afe44d5c8f4fd2b096aa21ed300426747757:4008:0x0003003e,219,102,0x0003003e,229,102,0x0003003e,235,102,0x0003003e,241,102,0x0003003e,302,102,0x0003003e,312,102,0x0003003e,318,102,0x0003003e,324,102,0x0003003e,369,102,0x0003003e,379,102,0x0003003e,385,102,0x0003003e,391,102
 verified:
-  issue: 369
-updated: '2026-10-17'
+  issue: 61
+updated: '2026-10-12'
 min_app: 1.0.4
 source_hint: Star Wars- Tales from the Galaxys Edge

catalog/games/com.nexxr.nexplayer.yaml

@@ -2,17 +2,10 @@ package: com.nexxr.nexplayer
 title: NEX Player
 status: works
 notes: 'Confirmed in the headset by the owner (2026-10-01): 72 fps, local 2D/360/3D videos play (it browses /sdcard/Movies
-  itself). USB-drive browsing can''t work in Lepton. Typing (frame.unity_text_input + device.text_input_window,
-  owner in the headset 2026-10-15): SteamVR''s keyboard button works and typed text reaches the fields; the keyboard
-  doesn''t open by itself when a field is selected.'
+  itself). USB-drive browsing can''t work in Lepton.'
 tested_version: 1.3.1.0
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 engine: Unity
 xr: OpenXR
 verified:
   date: '2026-10-01'
 source_hint: NEX - NEXt-Gen Video Player
-updated: '2026-10-15'

catalog/games/com.orbusvr.OrbusVRCommunity.yaml

@@ -1,26 +0,0 @@
-package: com.orbusvr.OrbusVRCommunity
-title: OrbusVR
-status: works
-tested_version: '31.01'
-engine: Unity
-xr: VrApi
-frame:
-- frame.unity_oculus_check
-- frame.unity_text_input
-- frame.unity_runtime_msaa_off
-- frame.hw_video_decode
-- frame.unity_gl_shim
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  pose_time_fix: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: fe569ffe52ca73f2384162ce80769f05f7cf177edbf26d8e429ca0e9b4aa27e8
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 378
-source_hint: OrbusVR

catalog/games/com.s3d.ExplodingKittensVR.TestRelease.yaml

@@ -1,22 +0,0 @@
-package: com.s3d.ExplodingKittensVR.TestRelease
-title: Exploding Kittens VR
-status: issues
-notes: Requires online for most modes. Practice lobby does work though.
-tested_version: 1.4.25779
-engine: Unreal
-xr: OpenXR
-alt_overport:
-- patch_remove_unreal_force_quit
-frame:
-- frame.hw_video_decode
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: 4b0a2348a5553851dcec820835e02c93a1a64927a30533d554943a9b81b3baa0
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 343
-source_hint: com.s3d.ExplodingKittensVR.TestRelease

catalog/games/com.schellgames.ieytd2.yaml

@@ -1,27 +0,0 @@
-package: com.schellgames.ieytd2
-title: I Expect You To Die 2
-status: works
-notes: loaded up and played 5 minutes looks fine.
-tested_version: 1.0.1.171177 (ReleaseCandidate_1.0.1_QuestStore)
-engine: Unity
-xr: VrApi
-frame:
-- frame.unity_no_msaa
-- frame.unity_oculus_check
-- frame.unity_text_input
-- frame.unity_runtime_msaa_off
-- frame.unity_gl_shim
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scale: 2.0
-verified:
-  date: '2026-10-16'
-  known_good_sha256: fc626ec62e49e19210a188d90f94c370e956d0de729cbd04cbe8866430d77730
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 358
-source_hint: Expect

catalog/games/com.sigtrapgames.undercover.yaml

@@ -6,14 +6,8 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Layers with failed swapchains are dropped by the adapter.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: c3f8cba1c22762231b6a6fbd881668db859d83224884ebeae0c1a3ba716f298c
-updated: '2026-10-15'

catalog/games/com.smtrandom.toytrain.yaml

@@ -1,22 +0,0 @@
-package: com.smtrandom.toytrain
-title: ToyTrains
-status: works
-tested_version: 01.008.009
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-- frame.hw_video_decode
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: f8665ccd5ce9907164e0700c6924e78821918df550154f3b869cb9907aa50ede
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 96
-  issue: 384
-source_hint: Toy Trains

catalog/games/com.thunderful.legobricktales.yaml

@@ -6,15 +6,9 @@ engine: Unity
 xr: OpenXR
 status: works
 notes: Use VR mode.
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
 details: Has VR and MR modes; use VR mode (passthrough not forced).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: 5ba09a2bc0046c8cb587272ab81e8d32739334fef523b10ab26531a733d54f12
-updated: '2026-10-15'

catalog/games/jp.co.hit_point.vneko.yaml

@@ -1,24 +0,0 @@
-package: jp.co.hit_point.vneko
-title: Neko Atsume Purrfect
-status: works
-tested_version: 2.3.0
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-- frame.oculusos
-device:
-- device.text_input_window
-adapter:
-  controller_models: 1
-  haptic_fix: 1
-  scene_emul: 1
-verified:
-  date: '2026-10-16'
-  known_good_sha256: da0196efa495d6ea7b34be2cea5b279acf23489134bb1dd1acef7cf54aa57da6
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 91
-  issue: 338
-source_hint: jp.co.hit_point.vneko

catalog/games/org.crisiszone.vr.yaml

@@ -1,18 +0,0 @@
-package: org.crisiszone.vr
-title: Crisis Zone VR
-status: works
-notes: Played the beginning of the first mission without issues.
-tested_version: 0.1.4
-engine: Other
-xr: OpenXR
-frame:
-- frame.sdl_clipboard
-verified:
-  date: '2026-10-15'
-  known_good_sha256: 747d1e6613ae443ef03e509b509e4ec89039eec1aecf3689643db4057e53266a
-  app: 1.2.1.dev433
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 331
-source_hint: CrisisZoneVR-v0.1.4-quest3

catalog/games/org.godotengine.endoparasitic_vr.yaml

@@ -1,19 +0,0 @@
-package: org.godotengine.endoparasitic_vr
-title: EndoparasiticVR
-status: works
-tested_version: '1.3'
-engine: Other
-xr: OpenXR
-frame:
-- frame.godot_clipboard
-adapter:
-  equirect_emul: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 89ed0e940c0285b1284a22d8eb5b35966dda79dd57a602c475be3cf1b758fa35
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 375
-source_hint: Endoparasitic

catalog/games/org.smarttube.stable.yaml

@@ -1,18 +0,0 @@
-package: org.smarttube.stable
-title: SmartTube
-status: issues
-notes: Android's home screen shows for a few seconds while the app starts (normal for flat Android apps; longest on the
-  first start after an install). Froze once in the reporter's session.
-tested_version: '32.56'
-engine: Other
-xr: '?'
-as_is: true
-frame:
-- frame.hw_video_decode
-verified:
-  date: '2026-10-16'
-  known_good_sha256: cc53f1aedac52ea0d4e77803acd580e32e7e5179adc96b55db7267b63a16c864
-  app: 1.2.0
-  overport_cli: 1.2.5
-  issue: 350
-source_hint: SmartTube_stable_arm64-v8a

catalog/games/studio.NewFolderGames.ToyMaster.yaml

@@ -5,14 +5,9 @@ source_hint: Toy Master
 engine: Unity
 xr: OpenXR
 status: works
-notes: frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
+notes: ''
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: e951595c67b6e448f3fb4afd07e6b83e98e589094bb3b73374cfb28aa01e96ee
-updated: '2026-10-15'

catalog/games/us.lighthaus.nanocellx.yaml

@@ -7,9 +7,6 @@ xr: OpenXR
 status: works
 notes: Needs Oculus OS telemetry class stubs and the no-ForceQuit build (the normal build quits right after
   starting).
-  frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-device:
-- device.text_input_window
 verified:
   date: '2026-10-02'  # owner-confirmed with the no-ForceQuit build
   overport_cli: 1.2.3
@@ -17,8 +14,6 @@ verified:
   known_good_sha256: 31469d50b8ee292597291db7cc3bc3eca8e851f533cd92bba0d64214893580cc
 frame:
 - frame.oculusos
-- frame.unity_text_input
 alt_overport:
 - patch_remove_unreal_force_quit
 use_alt: true
-updated: '2026-10-15'

catalog/games/xyz.TheAviary.Vermillion.yaml

@@ -1,9 +1,9 @@
 package: xyz.TheAviary.Vermillion
 title: Vermillion
-status: works
-notes: "The canvas used to hide the hand and brush while painting (the Frame draws the game's canvas layer in front
-  of everything); the recipe makes the game draw canvases in the scene instead (fix found by Klownicle, GitHub #200).
-  Confirmed in the headset by Klownicle."
+status: issues
+notes: Runs. The canvas used to hide the hand and brush while painting (the Frame draws the game's canvas layer in
+  front of everything); the recipe makes the game draw canvases in the scene instead (fix found by Klownicle, GitHub
+  #200). Not yet confirmed in the headset with this patch.
 tested_version: 1.7.2
 engine: Unity
 xr: OpenXR
@@ -16,10 +16,10 @@ adapter:
   haptic_fix: 1
   scene_emul: 1
 verified:
-  date: '2026-10-15'
+  date: '2026-10-11'
   app: 1.0.1
   frame_build: '20261007.6125817'
   agent: 79
   issue: 200
-updated: '2026-10-15'
+updated: '2026-10-12'
 source_hint: Vermillion - VR Painting

catalog/games/xyz.muware.hunt.vr.yaml

@@ -5,14 +5,9 @@ source_hint: H.U.N.T
 engine: Unity
 xr: OpenXR
 status: works
-notes: frame.unity_text_input and device.text_input_window added from detection (not headset-verified).
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
+notes: ''
 verified:
   date: '2026-09-28'
   overport_cli: 1.2.3
   overport_runtime: 3.4.3-23204ea
   known_good_sha256: c35373d0f7c870ade148e3259abcc74098b6bc89fe2c2f3a2e55168df642e391
-updated: '2026-10-15'

catalog/triage.yaml

@@ -6,47 +6,55 @@
 # 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: quest2-headset-identity
-    pattern: 'venderId[^\r\n]*systemName Oculus Quest2'
+  # FEX Rift compatibility (stream C): PC runtime/renderer failures; never suggest entitlement workarounds.
+  - id: fex-missing-entitlement
+    kind: pcvr
+    pattern: '(?i:Missing entitlement)'
     severity: info
-    diagnosis: OVRPlugin sees OVRPort's Quest 2 identity. Quest 3-only graphics options may stay hidden (e.g. Asgard's Wrath 2). Choose Quest 3 under Headset model and rebuild; both the dispatcher name and XR_META_headset_id UUID must change. An intentional Quest 2 selection preserves the original identity.
-    suggest: [device.headset_model]
+    diagnosis: Meta reports that the signed-in account does not own this game. This is not a FramePort bug. Use an account that owns it; entitlement and Platform SDK checks remain intact.
+    suggest: []
+  - id: fex-registration-missing
+    kind: pcvr
+    pattern: '(?i:OVRServer[^\r\n]*install_available|install_available[^\r\n]*OVRServer)'
+    severity: error
+    diagnosis: Meta's runtime sees the app as available to install rather than registered as installed. Reinstall or register the game through the FEX install flow with its matching Meta manifest, then retry.
+    suggest: []
+  - id: fex-imu-fallback
+    kind: pcvr
+    pattern: 'Rejecting new committed universe since IMU fallback is active'
+    severity: warning
+    diagnosis: SteamVR has not acquired headset tracking since boot. Put the headset on once, wait for tracking, then retry the FEX game. A headless launch before that can wait forever.
+    suggest: []
+  - id: fex-librarian-stuck
+    kind: pcvr
+    pattern: '(?s)\A(?=.*(?i:Service invocation completed))(?=.*OVRLibrarian[^\r\n]*(?i:still running|did not exit))'
+    severity: warning
+    diagnosis: OVRLibrarian completed its work but remains alive under FEX and blocks later client registration. End only OVRLibrarian.exe after completion, then retry; the FEX launcher normally performs this cleanup.
+    suggest: []
+  - id: fex-vkd3d-init
+    kind: pcvr
+    pattern: '(?i:vkd3d[^\r\n]*(?:failed to (?:create|initialize)|could not (?:create|initialize)|no (?:suitable|compatible).*(?:device|adapter)))'
+    severity: error
+    diagnosis: The D3D12 route could not initialize vkd3d-proton or a Vulkan device. Check GE's shipped vkd3d-proton DLLs, clear PROTON_NO_D3D12 and PROTON_USE_WINED3D, and verify the FEX Vulkan thunk reaches Turnip. This route still needs a device test.
+    suggest: []
+  - id: fex-wined3d-init
+    kind: pcvr
+    pattern: '(?i:wined3d[^\r\n]*(?:failed to (?:create|initialize|find)|could not (?:create|initialize)|OpenGL support is disabled))'
+    severity: error
+    diagnosis: Wine's OpenGL renderer could not initialize. The FEX route has no configured GL thunk; verify the guest rootfs GL driver and display access. A Vulkan thunk alone does not provide host OpenGL. Prefer the game's D3D9 or D3D11 route when available.
+    suggest: []
+  - id: fex-revive-injector
+    kind: pcvr
+    pattern: '(?i:ReviveInjector[^\r\n]*(?:failed|unable|error (?:code|inject)))'
+    severity: error
+    diagnosis: ReviveInjector could not start or inject the game. Check the game executable and x86_64 Revive files in the shared GE-Proton prefix, and use OpenVR mode (without /openxr). An OpenVR-only game can launch directly. Do not change entitlement or Platform SDK checks.
+    suggest: []
+  # End FEX Rift compatibility (stream C).
   - 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: meta-entitlement
-    # Quest games (the pcvr oculus-entitlement signature covers Rift games). Only explicit failure results: a bare
-    # ovr_PlatformInitialize error isn't matched. `error`, not fatal: offline games may log it and play on; an online
-    # game that then quits (e.g. Deadly Delivery, GitHub #322) fails the test through its exit.
-    pattern: '(?i)entitlement check failed|\bnot entitled to (use|play)|ovrPlatformInitialize_(NotEntitled|UnableToVerify|FileInvalid|SignatureInvalid)'
-    severity: error
-    diagnosis: The game's Meta licence check (entitlement) failed. It needs Meta's online login and licence check,
-      which the Frame doesn't have; games that depend on it (often online games) quit or stay offline. FramePort
-      doesn't get around such checks.
-    suggest: []
-  - id: meta-request-failed
-    # Unity's Oculus.Platform wrapper logs this when a Meta platform call gets no usable answer: OVRPort's platform
-    # library answers some calls without Meta's services (request id 0), so the game's callback never runs and it
-    # can wait forever (e.g. Thief Simulator, Eleven, Spectre; GitHub #346, #360, #368).
-    pattern: 'An unknown error occurred\. Request failed\.[\s\S]{0,400}?Oculus\.Platform\.Request'
-    severity: warning
-    diagnosis: A Meta platform request made by the game failed (it needs Meta's online services, which the Frame
-      doesn't have). If the game then stays on a loading screen or doesn't go on, it is waiting for that answer;
-      some games have a per-game fix that skips the call. A problem report with diagnostics shows which call it is.
-    suggest: []
-    report: true
-  - id: meta-system-activities
-    # The game ships its own (renamed) copy of Meta's platform loader instead of going through OVRPort's, which
-    # tries to open Meta's system activities (Horizon OS) and aborts when Android can't start them (Breachers, #357).
-    pattern: 'DisplayErrorAndExit: Failed to launch SystemActivities'
-    severity: fatal
-    diagnosis: The game's own Meta platform library tried to open Meta's system screens (Horizon OS), which the
-      Frame doesn't have, and quit on purpose. Games built this way are usually online games that depend on Meta's
-      services; FramePort can't provide those.
-    suggest: []
-    supersedes: [native-crash]
   - id: lua-lightuserdata-pointer
     pattern: 'bad light userdata pointer'
     severity: fatal
@@ -87,13 +95,6 @@ signatures:
     severity: fatal
     diagnosis: 32-bit-only APK (e.g. a Gear VR or Oculus Go game). The Steam Frame has no 32-bit ARM support; FramePort's 32-bit bridge translates the game (experimental).
     suggest: [frame.a32_bridge]
-  - id: a32-jit-overflow
-    pattern: 'a32: block at 0x[0-9a-f]+ overflowed the code buffer'
-    severity: fatal
-    diagnosis: The 32-bit bridge's translator stopped the game on a long run of instructions it hands to its
-      interpreter, for example OpenSSL's ARMv8 SHA-1 code in Pinball FX2 VR. Fixed in newer FramePort versions;
-      update FramePort and rebuild the game ("Update on Frame").
-    suggest: [frame.a32_bridge]
   - id: android-too-new
     pattern: '(NoClassDefFoundError|ClassNotFoundException|NoSuchMethodError)\b.*(Landroid/window/|android\.window\.|(storeStoreFence|loadLoadFence)\(\)V in class Ljava/lang/invoke/VarHandle)'
     severity: fatal
@@ -104,13 +105,6 @@ signatures:
     severity: fatal
     diagnosis: This app is a website, not a game, and it can't open on the Frame. It is a Trusted Web Activity that opens Meta's browser (com.oculus.browser), which the Frame doesn't have; open the website (TWALauncherActivity's "Using URL" line) in a browser instead.
     suggest: []
-  - id: gvr-not-supported
-    # GitHub #335 (Blade Runner: Revelations, Daydream, Unity 2017.4): Unity's "Google VR Error [Daydream]", the GVR
-    # library's Java side missing on the 32-bit bridge, or a bind to Daydream's VrCore service
-    pattern: 'Google VR Error \[(Daydream|Cardboard)\]|Google VR had a fatal issue while loading|class com/google/vr/sdk/base/CardboardViewNativeImpl not found|act=com\.google\.vr\.vrcore\.\S+ pkg=com\.google\.vr\.vrcore'
-    severity: fatal
-    diagnosis: This is a Google Daydream / Cardboard VR build (Google VR SDK), and its VR can't reach the Frame's headset. Daydream needs Google's VR services (VrCore) and Cardboard draws for a phone in a viewer; FramePort has no translation for either, so the game runs as a flat window at best, usually without working controls. An Oculus build of the same game (Meta Quest, Oculus Go or Gear VR) goes through FramePort's normal path.
-    suggest: []
   - id: unity-render-crash
     pattern: 'CRASH\s*:.*#\d+\s+pc [0-9a-f]+\s+\S*libgallium_dri\.so'
     severity: fatal
@@ -147,17 +141,12 @@ signatures:
   - id: swapchain-rect-invalid
     pattern: 'xrEndFrame failed -25\b'
     severity: fatal
-    diagnosis: The runtime rejects the game's frames, so it stops drawing (for example stuck at a "Waiting" box). An image rect reaches a few pixels past its swapchain on some Frames (FrameBridge from FramePort 0.11.0 clamps the rects), or is empty (0x0, for example BattleTalent's first frames right after Unity switches its MSAA level; a newer FrameBridge shows the whole swapchain image instead), so rebuild and reinstall the game.
+    diagnosis: The runtime rejects the game's frames, so it stops drawing (for example stuck at a "Waiting" box). An image rect reaches a few pixels past its swapchain on some Frames; FrameBridge from FramePort 0.11.0 clamps the rects, so rebuild and reinstall the game.
     suggest: [frame.adapter]
   - id: cylinder-menu-layers-rejected
     pattern: 'xrEndFrame failed -16\b'
-    severity: info
-    # PreyVR (GitHub #306): one rejected frame at the start of every session (its space isn't locatable yet); the black
-    # menu there had another cause (a 0 Hz refresh rate stopped the game clock), so this alone is no error
-    diagnosis: The runtime rejected a frame's layers once (XR_ERROR_LAYER_INVALID). At the start of a session that is
-      harmless. If it repeats every frame the picture stays black; FrameBridge shows a curved (cylinder) screen drawn
-      to each eye separately (for example the Doom3Quest / PreyVR menu) as one set of flat strips for both eyes to stay
-      within the runtime's layer limit, so rebuild and reinstall the game with the current FrameBridge.
+    severity: error
+    diagnosis: The game draws a curved (cylinder) screen to each eye separately (for example the Doom3Quest / PreyVR menu). The Frame's runtime has no cylinder layers, so FrameBridge shows each as flat quad strips; a per-eye pair makes too many quad layers for one frame and the runtime rejects the whole frame (XR_ERROR_LAYER_INVALID), leaving the menu black while the game runs. FrameBridge from this build shows the left eye's strips to both eyes to halve the count; rebuild and reinstall the game to try it.
     suggest: [frame.adapter]
   - id: missing-ovr-symbol
     pattern: '(UnsatisfiedLinkError|cannot locate symbol) .*"?(ovr_[A-Za-z0-9_]+|ovr[A-Z][A-Za-z0-9]*_ToString)'
@@ -218,8 +207,7 @@ signatures:
     suggest: [adapter.vk_shader_dump, adapter.zink_shader_dump]
     report: true
   - id: space-warp-used
-    # space warp's motion vectors (97 = R16G16B16A16_SFLOAT); its depth (129) is also what eye depth layers use (#323)
-    pattern: 'xrCreateSwapchain \d+x\d+ format=97 '
+    pattern: 'xrCreateSwapchain \d+x\d+ format=(97|129) '
     unless: 'per-game: hide_space_warp=1'
     severity: info
     diagnosis: The game uses Meta's space warp (it renders half of its frames plus motion vectors, and the runtime makes
@@ -227,13 +215,6 @@ signatures:
       Metro Awakening). Turning it off makes the game render every frame itself.
     question: Did textures flicker, jump or smear while you moved?
     suggest: [adapter.hide_space_warp]
-  - id: duplicate-action-renamed
-    pattern: 'action_dedup: action .* already exists in its set'
-    severity: info
-    diagnosis: The game creates two controller actions with the same name (for example an Unreal action and axis both
-      called Turn). The Frame's runtime then can't load the game's controller setup and drops the game back to the home
-      environment while it keeps running. FramePort renamed the second one, so this is handled.
-    suggest: []
   - id: unity-runtime-msaa
     pattern: 'recommended MSAA level is [248]\. Switching to the recommended level'
     severity: info
@@ -296,23 +277,6 @@ signatures:
     severity: error
     diagnosis: The screen stays black because the game submits a layer the VrApi bridge can't show. Whole frames with that VrApi layer type are dropped.
     suggest: []
-  - id: unreal-reserve-refused
-    # GitHub #349: Unreal's out-of-memory handler dereferences its not yet created log while libUnreal.so's static
-    # constructors run (System.loadLibrary), after the Binned3 allocator's up-front reservation failed
-    pattern: '(?s)fault addr 0x10\b(?:(?!Fatal signal).){0,8000}?#00 pc [0-9a-f]+\s+\S*lib(?:Unreal|UE4)\.so(?:(?!Fatal signal).){0,8000}?soinfo17call_constructors'
-    severity: fatal
-    diagnosis: The game crashed while Unreal was still loading, before its first frame. Its memory allocator (Binned3)
-      reserves tens of gigabytes of address space at once, which Quest allows and the Frame's kernel refuses in one
-      piece (for example Transformers Beyond Reality). Rebuild with the reservation marked as not committed.
-    suggest: [frame.unreal_noreserve]
-    supersedes: [native-crash]
-  - id: color-space-missing
-    # GitHub #336: OutRun Quest VR requires XR_FB_color_space (Rec.709) and quits before xrCreateSession
-    pattern: 'Rec\.709 color space unavailable'
-    severity: fatal
-    diagnosis: The game needs Meta's colour-space extension, which the Frame's runtime doesn't offer, and quits before
-      it starts VR (for example OutRun Quest VR). FrameBridge can offer it.
-    suggest: [adapter.fb_color_space]
   - id: graphics-requirements-missing
     pattern: '(XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING|Failed to create XR session: -50\b|xrCreateSession[^\n]*-50\b)'
     severity: fatal
@@ -389,13 +353,6 @@ signatures:
     diagnosis: 'The Frame''s Vulkan driver crashed on a call from Unreal. Unreal 5 passes things Quest''s driver ignores: a depth resolve in a subpass without a depth attachment (handled by the Vulkan shim), and image barriers and views for a missing image when it expects fragment density maps (foveation) from the headset (for example Metro Awakening).'
     suggest: [frame.vk_sanitize, adapter.vk_spec_fixes, adapter.vk_hide_fdm]
     supersedes: [native-crash]
-  - id: quest-foveation-image-missing
-    pattern: 'foveationImage = 0x0, width = 0, height = 0'
-    unless: 'hide_fb_foveation: filtering dispatcher extensions'
-    severity: info
-    question: Did the Vulkan game stop on its first frames?
-    diagnosis: OVRPlugin enabled Quest Vulkan foveation but received no density image. For a first-frame failure, compare with Quest foveation suppressed. This message alone does not prove the crash cause; a null Unreal graphics pipeline can also follow an earlier fatal error.
-    suggest: [adapter.hide_fb_foveation]
   - id: unreal-fdm-missing
     pattern: 'vk shim: left out \d+ image barrier\(s\) without an image \(first: layout \d+ -> 1000218000'
     unless: 'vk shim: fragment density map extensions hidden'
@@ -424,13 +381,6 @@ signatures:
     diagnosis: The game crashed creating a very large image (over 4096 px, for example in video players). OVRPort's OpenXR dispatcher aborts on such swapchains.
     suggest: [frame.swapchain_limit]
     supersedes: [native-crash]
-  - id: cortopia-org-id-wait
-    # Meta's C# wrapper logs this when the native call returned request id 0 (no callback ever follows); Cortopia's
-    # start-up awaits it forever (GitHub #360)
-    pattern: 'An unknown error occurred\. Request failed\.[\s\S]{0,600}?Cortopia\.Scripts\.Platform\.Meta'
-    severity: error
-    diagnosis: The game waits forever on its loading screen for an answer from Meta's platform (an org-scoped user id, used as its analytics id) that OVRPort's platform library doesn't give. The patch makes the game skip that one request, as it does without Wi-Fi.
-    suggest: [frame.cortopia_org_id]
   - id: ovr-microphone-crash
     pattern: 'ovr_Microphone_GetOutputBufferMaxSize\+'
     severity: fatal
@@ -444,22 +394,10 @@ signatures:
     suggest: [frame.slz_vulkan_hooks]
     supersedes: [java-crash, native-crash]
   - id: vivox-api31
-    pattern: 'NoSuchMethodError: No virtual method \w*CommunicationDevice\w*\(.*Landroid/media/AudioManager[^\n]*(?:\n[^\n]*\sat [^\n]*){0,12}?\n[^\n]*\sat com\.vivox\.'
+    pattern: 'NoSuchMethodError: No virtual method \w*CommunicationDevice\w*\(.*Landroid/media/AudioManager'
     severity: fatal
     diagnosis: The game's Vivox voice-chat SDK calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes (for example Green Hell VR). The patch makes Vivox's audio-route check return early (voice chat keeps the default route).
     suggest: [frame.vivox_audio_route]
-    supersedes: [java-crash, audio-api31]
-  - id: photon-voice-api31
-    pattern: 'NoSuchMethodError: No virtual method \w*CommunicationDevice\w*\(.*Landroid/media/AudioManager[^\n]*(?:\n[^\n]*\sat [^\n]*){0,12}?\n[^\n]*\sat com\.exitgames\.photon\.'
-    severity: fatal
-    diagnosis: The game's Photon Voice microphone plugin calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes when voice chat starts (for example Table Troopers at the tutorial). The patch makes Photon's audio-device pick return early (the microphone keeps the default route).
-    suggest: [frame.photon_voice_audio_route]
-    supersedes: [java-crash, audio-api31]
-  - id: audio-api31
-    pattern: 'NoSuchMethodError: No virtual method \w*CommunicationDevice\w*\(.*Landroid/media/AudioManager'
-    severity: fatal
-    diagnosis: Code in the game (often a voice-chat SDK) calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes. FramePort has fixes for Vivox and Photon Voice; this one comes from another library, so please report it with the log.
-    report: true
     supersedes: [java-crash]
   - id: lepton-data-link-failed
     pattern: "ln: cannot create symbolic link from '[^']*' to '/data/data/|Couldn't create directory for SharedPreferences file /data/user/0/"
@@ -467,24 +405,6 @@ signatures:
     diagnosis: The game has no internal storage (saves, settings) inside Lepton. Usually its folder's path has a space (a microSD card named for example "Steam Frame 512g"), which Lepton's own scripts can't handle; FramePort's launcher (agent 83 and newer) gives Lepton a path without spaces. Connect FramePort once so the launcher is updated, then start the game again.
     report: true
     supersedes: [java-crash, native-crash]
-  - id: gms-android12-call
-    pattern: 'No virtual method permitUnsafeIntentLaunch\(\)'
-    severity: fatal
-    diagnosis: Google Play services' code in the game called an Android 12 method (the game was built for Android 12 and newer, so its version checks were built in as "always true") and Lepton runs Android 11; the game crashes on its GoogleApiHandler thread at start (for example Titan Isles). The patch makes those checks answer "no" again; Play services themselves aren't on the Frame, so sign-in and other Google features stay off.
-    suggest: [frame.gms_platform_version]
-    supersedes: [java-crash]
-  - id: usb-midi-watcher
-    pattern: 'UsbManager\.getDeviceList\(\)'' on a null object reference|at jp\.kshoji\.driver\.midi\.device\.MidiDeviceConnectionWatcher\$MidiDeviceConnectionWatchThread\.checkConnectedDevices'
-    severity: fatal
-    diagnosis: The app's USB MIDI driver (kshoji's, used by Unity MIDI plugins, for example PianoVision) asked Android's USB service for MIDI devices; the Frame's Android has no USB service, so the app crashed. The patch stops that poll; USB MIDI devices can't reach the app on the Frame anyway.
-    suggest: [frame.usb_midi_watcher]
-    supersedes: [java-crash]
-  - id: unity-appui-vibrator
-    pattern: 'NoClassDefFoundError: Failed resolution of: Landroid/os/VibratorManager;'
-    severity: fatal
-    diagnosis: The game's start activity uses Android 12's VibratorManager (Unity's App UI package, for example PianoVision) and Lepton runs Android 11, so it quits before the game starts. The patch starts the activity without a vibrator; its UI haptic feedback then does nothing.
-    suggest: [frame.unity_appui_vibrator]
-    supersedes: [java-crash]
   - id: bhaptics-permission-prompt
     pattern: 'GrantPermissionsActivity: Permission grant result .*permission=android\.permission\.BLUETOOTH_CONNECT'
     severity: error

docs/DEVICE_NOTES.md

@@ -1,720 +0,0 @@
-# Device notes
-
-Detailed device findings per game and issue, moved verbatim from CLAUDE.md (which keeps a one-line pointer
-with the key fact and the patch/setting names for each). Read the matching section before debugging a game;
-general runtime facts are in docs/FRAME_RUNTIME.md and symptom → fix rows in docs/PLAYBOOK.md.
-
-## Per-game language (GitHub #354, 2026-10-17)
-
-Asgard's Wrath 2 starts in English with no in-game language choice. Headless verification used Transformers:
-`LEPTON_GFXRECON_FP_LOCALE="0\npersist.sys.locale=de-DE"` gave container
-`getprop persist.sys.locale = de-DE`, while `ro.product.locale` remained `en-US`. The game's VM started with
-`user.locale=de-DE`, Android configuration was `[de_DE]`, and Unreal logged `Locale=de_DE`.
-Patch `device.language` sets this boot property independently of `device.hide_navbar`.
-Text/voice switching in individual games, including Asgard's Wrath 2, still needs headset verification.
-
-Recipes store the selection as `patches: {device.language: {tag: de-DE}}`. The catalog's `device` field is a
-list of patch IDs, with dedicated fields for some parameterized device settings (files, environment, config sync,
-foveation); it has no field for a language tag. Catalog import/export cannot currently preserve this selection.
-
-## a32 bridge: games, lessons, debugging aids, profiling
-
-Learned: Unity 2019 contexts
-have no EGLConfig (EGL_KHR_no_config_context: the VrApi bridge takes the window's or an RGBA8 ES3 config); Unity's
-floor origin = vrapi_SetTrackingSpace(1) (the VrApi bridge now honours LOCAL_FLOOR/STAGE); mapped GL buffers are
-per buffer object (a per-target guest copy leaked ~10 MB/s and garbled vertices); the guest runtime's own scudo
-names its maps `[anon:scudo:*]` below 4 GiB (watch them for guest leaks). The Go controller = the right Frame
-controller (stick = touchpad touch, sideways > 0.6 or press = click). Gunjack (CCP, UE 4.10 NativeActivity, Gear VR,
-2026-10-10): needed the native_app_glue imports (ALooper/AInputQueue/AConfiguration/AAsset*, imports.txt), an arm64
-libvrapi.so for Java's System.loadLibrary("vrapi") and MOUNTED under OVP_HEADLESS_TEST; it then loads its map and
-quit on purpose: AndroidMain compares AndroidThunkCpp_GetSignature() with an obfuscated copy. **Works since
-2026-10-11 (owner-verified in the headset):** GameActivity.AndroidThunkJava_GetSignature() = Base64.DEFAULT(SHA-1(
-signing certificate DER)) (jadx); `a32_bridge.original_signature` computes it from the original APK's
-META-INF/*.RSA|DSA|EC, `convert()` stores it as `assets/fp_a32_signature.txt` for libUE4.so games, the bridge loads
-it at activity creation (native_activity.c) and jni.c answers Call*Method on the method ID of
-`AndroidThunkJava_GetSignature()Ljava/lang/String;` with it. After loading, Unreal leaves VR mode and enters it again on
-the same GL context; a second OpenXR session there aborted in vrclient (CSharedSemaphoreLinux::WaitFromGPU from the GL
-binding's PreBeginFrame, also with OVP_HEADLESS_TEST) → the VrApi bridge keeps a running GLES session across
-LeaveVrMode and reuses it for an EnterVrMode with the same context (upstream-patches/runtime.cpp.patch).
-Debugging aids added: A32_BREAK=<guest addr>[,..] (stack of the first hits; guest libs load at fixed addresses, e.g.
-libUE4 0xf25d5000), A32_STRACE in bridge mode = path/exit calls to logcat, activity lifecycle + LeaveVrMode caller
-logs. Lepton's logcat mirror often dies for these games: read `podman exec <container> logcat` instead. Gunjack input
-(2026-10-11): it imports no vrapi input functions and reads the Gear VR touchpad/back as AInputEvents from its
-AInputQueue (native_app_glue), so dispatchKeyEvent never reached it (no control at all) → input.c queues synthetic
-events there (ALooper_poll* return the queue's ident while one waits; AInputQueue_getEvent/finishEvent and the
-AInputEvent/AKeyEvent/AMotionEvent getters are hand-written "!" imports that know them; touch positions scaled to the
-window size). Same mapping as AFFECTED: trigger = hold touchpad, A = tap, right stick = swipe, B = back; for NativeActivity games the stick's up/down = swipe forward/back (touchpad X: Gunjack's OnFlick = reload at ~0°, special weapon at ~180°). Not yet
-headset-verified. Quest builds on the bridge (2026-10-13, Sports Scramble = a 32-bit Santa Cruz build,
-UE 4.21 + OVRPlugin on VrApi 1.21): manifest requires `android.hardware.vr.headtracking` version 1
-(`detect.requires_6dof`, headset "quest", ANALYSIS_VERSION 16) → convert writes `assets/fp_a32_headset.txt`
-= "quest" → vrapi.c `quest_touch` (read in vrapi_Initialize via the activity's AssetManager; A32_TOUCH=1/0
-overrides) passes the 64-bit bridge's Touch controllers through (enumerate/caps/state/tracking/haptics, struct
-tails per VrApi minor) and starts no synthetic input. It also needed AAsset_getBuffer (guest copy, freed in
-AAsset_close), AKeyEvent_getFlags and the other AConfiguration getters. Headset (owner, 2026-10-13): plays,
-both controllers work. Recenter (holding the Frame's menu button) turned VrApi games ~90-120 degrees aside: the bridge's app space is LOCAL + the start yaw and the runtime moves LOCAL to the head → the bridge now takes the origin from the head again on XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING (LOCAL) and on vrapi_RecenterPose (owner-verified with Gunjack, 2026-10-13). Next: the other 32-bit catalog games (Journey of the Gods, Shadow Point: still "unsupported" until
-tested), translator speed. Profiled on the Frame
-(2026-10-12, `A32_PERFMAP` + perf): FPCR switches are negligible (8 of 86k samples); the cost was the run loop
-(a mutex + hash-chain walk on every dispatch, a contended counter, inline-lookup slots never refilled: Gunjack
-~45 % of its CPU) and `jit_invalidate` scanning every block on each Mono `cacheflush` (72 % of Spunky Dungeon's
-main thread). Now lock-free lookups, ltab refill, per-thread flags, per-page block lists: Gunjack's dispatcher
-23.6 % -> 1.6 %, CPU in the same phase about -55 %, still 72 fps.
-
-## Upload speed
-
-**Upload speed (measured 2026-09-29):** via the home router (PC Wi-Fi → router → Frame wlan0) only 15-18 MB/s, the
-same for paramiko, OpenSSH and 4 parallel streams, so the network path is the limit, not the SSH code. Direct to the
-Frame's hotspot (`wlanap` 10.35.78.1; the owner's PC has Valve's USB Wi-Fi dongle on it) 83 MB/s OpenSSH / 97 MB/s
-paramiko; reading dumps from D: via WSL drvfs is then the cap (~82 MB/s). `Frame.fast_link()` (installer
-`transfer_link`, uploads ≥64 MiB) uses usb0 > wlanap when reachable **and** the host key matches the paired Frame.
-
-## Revive under Proton arm64 (Lone Echo)
-
-**Revive under Proton arm64 (Lone Echo, 2026-09-29):** Revive's Detours hooks (LoadLibraryW/ExW, OpenEventW, the
-signature check) don't take effect: Wine's kernelbase is ARM64EC. The LibOVR shim in the game then does a plain
-`LoadLibrary("LibOVRRT64_1.dll")` search (exe dir, cwd, system32, windows, PATH — no registry, `OculusBase` or
-`LIBOVR_DLL_DIR` used by this build) → `Failed to initialize Oculus API (-3001)` (= Lies Beneath's "Unable to load
-LibOVRRT DLL"). A symlink `pfx/drive_c/windows/system32/LibOVRRT64_1.dll -> <base>/revive/LibReviveXR64.dll` (Wine
-maps a symlink to the already-loaded module) gets past it to **-3021 = ovrError_LibSignCheck**: the shim only accepts
-an Oculus-signed runtime. Next step (not done): make the runtime check pass without Detours, e.g. an injected helper
-that patches the game's import table (IAT) for LoadLibrary*/WinVerifyTrust, or a prefix-level override. This is
-runtime interop (what Revive does), not the Platform SDK licence check (which FramePort never touches).
-Uninstall (Quest, saves kept) used to leave `deployment.json` → still "installed"; fixed (agent v16).
-
-
-## OVRPort 1.2.5
-
-**OVRPort 1.2.5 (2026-10-01, the fork's first release; CLI-only):** same commands (`patches [--json]`, `patch`, `help`,
-`install`), but `patch` rejects unknown/duplicate args, unknown patch ids and an empty `--patches=`
-(`tools/overport.patch` refuses empty lists). After patching it adds `libovrplatformcompat.so` itself when the platform
-loader lacks `ovrMessageType_ToString` (our `frame.ovrplatformcompat` then skips: same library). New patches (all off;
-`patches/overport.py`): `patch_ac_nexus_no_appsw_72/_90` (AC Nexus build 207706 only, exclusive),
-`patch_disable_meta_xr_audio_telemetry` (x86_64 emulators: hidden), `patch_vrapi_openxr` = OVRPort's VrApi adapter =
-the **unpatched** upstream of our `frame.vrapi_bridge` (`native/vrapi` unchanged since our 5e7df52), only usable with an
-experimental CLI built with `-PwithVrApi=true` (stable jars list it but fail). The owner prefers OVRPort's fixes over
-ours where they work as well (less to maintain): compare in the headset before switching a default.
-`frameport install <pkg> --apk <file>` installs a specific (test) build signed with the game's key.
-Headset results (2026-10-02, `PATCHED/_test-ovrport-1.2.5/TESTING.md`): OVRPort's own VrApi translator fails on the
-Frame (Climb 2: requests VkFormat 37 → crash; POTW: no GLES path, missing `vrapi_GetTextureSwapChainHandle`) → keep
-`frame.vrapi_bridge`; those two changes are upstream candidates. 1.2.5 builds (its platform compat, new permissions)
-work. AC Nexus: `patch_ac_nexus_no_appsw_90` is the catalog default (owner preferred 90 Hz); `STRICT` patches are only
-taken from a catalog recipe where `applies()` holds (the AC Nexus ones need build MAIN.450412.207706.final, else the
-whole overport run fails).
-
-
-## Steam Frame controller models
-
-**Steam Frame controller models (2026-09-30, not yet seen in a game):** adapter setting `controller_models`
-(`native/adapter/render_model.c`) emulates XR_FB_render_model and serves `files/framebridge/controller_{left,right}.glb`;
-agent v20 (`install_controller_models`, command `controller_models`) converts the Frame's SteamVR render models
-(folder name matching "frame" + left/right, OBJ+PNG, `openxr_grip` component → grip space) at finalize/set_settings.
-Valve's models are never committed or copied off the Frame. Only games that use Meta's runtime controller models
-benefit (manifest `RENDER_MODEL` permission/feature → suggested); **none of the 34 catalog games do** (they ship their
-own meshes: that would need per-game asset replacement). Model discovery and conversion
-checked on the device 2026-09-30: `/opt/steamvr/drivers/frame_controller/resources/rendermodels/frame_controller_{left,right}`
-(component OBJs in model space = the whole `<name>.obj`, one `_color.png` 2048² near-black, `openxr_grip` rotates about
-X only; hidden-by-default components like `status` are skipped) → ~2 MB glb each, ~1 s. Not yet seen in a game (none
-of the installed builds has the new adapter, and none requests runtime models), so whether Meta's SDK attaches runtime models at the grip pose is unverified.
-
-## Crash backtraces, Fossilize, swapchain limit, cylinder and equirect layers
-
-**Crash backtraces (2026-09-30):** Lepton writes tombstones only to `lepton-logcats/steamlaunch-<appid>/logcat-crash.log` (after "Dumping logcat"), not launch.log; agent v23 launch tests wait for it and return `crash_log`, triage gets it via `triage(..., crash=)` (not pid-filtered: tombstones come from crash_dump's pid). The guest is `userdebug` (`ro.debuggable=1`), so Lepton's Fossilize layer loads into every app whatever the APK's debuggable flag; it has no off switch. Fossilize crashed Deadpool VR on uninitialized attachment-reference pNexts (several, in FVulkanRenderPass and the render-target layout) → `frame.vk_sanitize` = `native/vkshim` (engine's `dlopen("libvulkan.so")` string → `libfp_vk.so`, wraps vkCreateRenderPass2/KHR, drops unreadable/wrong-sType pNexts; verified: game runs). overport's dispatcher aborts on swapchains > 4096 px (`cmp wN,#4096` in xrCreateSwapchain) → `frame.swapchain_limit` (verified with 4XVR, 7680×3840 accepted by the runtime). Both are default-on (parity classifies their rewrites as
-"expected"; library migration `quest_binary_fixes_v2`). The adapter shows cylinder layers (4XVR's movie screen) as ~15° quad strips (`cylinder_strips`, setting
-`cylinder_strips`); the runtime composites them at full resolution. Equirect (360°) layers are dropped: drawing
-them ourselves (GLES renderer in xrEndFrame: stutter, never showed 4XVR's VR video; Vulkan renderer: hung the
-Frame's GPU in AC Nexus; reading the newest *released* image broke 4XVR's theatre) was removed again on the owner's
-request — don't retry without a new approach. Converted layers must count as "swapped" or the original layer list
-is submitted (runtime returns -2 for every frame). A focus debounce (hiding the Frame's brief
-FOCUSED→VISIBLE→SYNCHRONIZED dips, which make 4XVR recenter) was also removed: AC Nexus stayed black with it (it
-hid 521 ms focus changes at start). The new approach (below) is per-game, off the app's render thread, GLES-only.
-
-
-## 360° layers / 4XVR
-
-**360° layers / 4XVR (2026-09-30):** the Frame's Android SteamVR runtime (`/opt/steamvr/bin/androidarm64/vrclient.so`,
-mounted in Lepton as `/data/steamvr/runtime`) only composites quad + projection layers (cube/cylinder/equirect(2)
-are enum names only) — nothing to unlock. Per-game adapter settings (off by default, hooks installed only when on):
-`equirect_emul` (GLES only: a worker thread with a shared EGL context converts each 360° image to a cube map when it
-changes and draws one adapter projection layer from it for every frame with exactly that frame's views (the app's own
-projection views, else xrLocateViews at displayTime); xrEndFrame waits ≤6 ms for the worker's CPU submit, never the
-GPU. Learned in the headset: quads can't be a background (the Frame draws quad layers above all projection layers
-whatever the order: hid 4XVR's balcony/controllers), and the Frame doesn't reproject a projection layer from its own
-pose (images drawn only after head turns, or ahead from xrWaitFrame and sometimes late, wobbled);
-`equirect_flip/face/res/fps/stereo`), `stable_local`, `focus_hold` (only after 3 s FOCUSED, dips <600 ms),
-`aim_pitch/aim_yaw/aim_forward`, `refresh_rate`, `layer_debug` (diagnostics); focus_hold is default-on since 2026-10-05. 4XVR re-creates LOCAL spaces every 2–4 s
-(menu recentring suspect); its theatres are baked 7680×3840 equirect2 images (`assets/100.png` …). Test 360° videos
-(NASA, public domain) are in the Frame's ~/Videos; copies in `~/Downloads/frameport-360`. 4XVR's "Internal Storage"
-lists its own `/sdcard/4XPlayer`, not Movies: agent v25 `link_media` hard-links sent files into an app's own top-level
-folder (`app_media_dirs`), `frameport frame send --app <pkg>`, GUI game page "Add videos" (players) / "Add videos &
-files…". A 4XVR webm stereo swapchain was refused with XR_ERROR_LIMIT_REACHED (-10) → right eye grey; our projection
-swapchain was halved (1536/eye) in case memory is the limit (unverified). Frame data snapshot
-(SteamVR runtimes, Lepton scripts, logs; never commit Valve binaries): `~/frameport-research/frame-data-2026-09-30/`.
-Not yet verified in the headset.
-
-
-## Companion apps / intents (Stremio + 4XVR)
-
-**Companion apps / intents (2026-10-03, tested with Stremio + 4XVR):** a second APK can be installed into a running
-Lepton container (`podman exec -i lepton-steamlaunch-<appid> pm install -g -S <size> < apk`) and runs there, VR
-included (4XVR in Stremio's flatscreen container: FrameBridge 72 fps, settings via LEPTON_ENV_FRAMEBRIDGE_CONFIG). But
-Lepton's services.jar (`ActivityStarter.execute`) intercepts **every** `android.intent.action.VIEW` with data (any
-scheme, explicit component or not, no property to disable): it writes `steam://openurl/<uri>` to `/lepton/steam.pipe`
-(= the host Steam client's `~/.steam/steam.pipe`) and starts nothing. So "open in external player" hand-offs (Stremio
-→ 4XVR) can't work inside Lepton; don't retry without Valve changing it. Lepton installs exactly one `*.apk` per app
-folder (two break `get_apk_path`).
-
-## Text input (Stremio VR)
-
-**Text input (2026-10-03, verified in the headset with Stremio VR):** Lepton's Android has no IME (`ime list` empty)
-and runs VR apps headless (`lepton.headless=true`): no Android window has input focus (`dumpsys input` FocusedWindows
-empty), so neither `input text`, a USB keyboard nor Steam's keyboard reach the app. `lepton-show-flatscreen` on a VR
-app keeps VR working (FrameBridge 72 fps) and gives the window focus; Steam's on-screen keyboard then opens for text
-fields. Unity's TMP_InputField on non-Quest Android waits for the system keyboard (`TouchScreenKeyboardShouldBeUsed`)
-and deselects a frame later unless `isKeyboardUsingEvents` (Android: `InPlaceEditing() && m_HideSoftKeyboard`);
-uGUI InputField's LateUpdate keeps the field when `InPlaceEditing()`. Patch `frame.unity_text_input` rewrites them
-(`mov w0,#0|#1; ret`) at Cpp2IL's **Offset** (= file offset; RVA differs by 0x4000 in Stremio's lib), Cpp2IL
-2022.1 pre-release (Unity 6 / metadata v31; Il2CppDumper can't), cached per libil2cpp sha. `/dev/uinput` has an ACL
-for steamos (Steam Input) → agent v33 `_keyboard` uinput keyboard ("Type on Frame") reaches everything with focus.
-Installing a second APK into a container with `pm install` re-runs Lepton's post-install hook on the **main** app
-(`lepton.active_app_id`; moves its files to /data/steam_app) and corrupts it on the next start (fix: touch the APK →
-re-bake); `cmd_real package install` skips the hook.
-
-## User reports 2026-10-04 (issues #4-#10)
-
-**User reports (2026-10-04, issues #4-#10):** Steam shortcuts go to the signed-in account (`loginusers.vdf`
-MostRecent) else every account (agent v35 `library_users`; it used to refuse with >1 account → Play gave Steam's "Game
-configuration unavailable"); `launch` uses the shortcut's own appid and errors `NOT_IN_LIBRARY`, the app then adds it
-and plays. Unity IL2CPP fixes share one Cpp2IL run (`unity_text_input.Il2cppReturnPatch`, `ALL_TARGETS`, cache keyed by
-global-metadata.dat): `frame.unity_runtime_msaa_off` (OVRManager raises MSAA to 4x at runtime: "Switching to the
-recommended level" → Lucky's Tale restarted the headset; `OVRDisplay.get_recommendedMSAALevel` → 0) and
-`frame.unity_multipass` (Oculus XR Plugin multiview → MultiPass via `OculusSettings.GetStereoRenderingMode`; I Am Cat's
-right eye grey). Both checked against Toy Master's Cpp2IL output, not yet in a headset. VR4 quits itself (System.exit
-after the intro movie) → catalog `use_alt`. **Catalog changes reach existing games** without hardcoded migrations:
-recipes store `catalog_rev` (= `CatalogEntry.rev()`), `library._follow_catalog` re-derives non-user recipes whose entry
-changed; a maintained entry beats the user's shared copy when its `updated`/verified date is later (`catalog._newer`).
-
-## Round 2 of reports, headset rounds 2-3 (2026-10-04)
-
-**Round 2 of reports (2026-10-04):** VR4's campaign hang = one fragment shader reading an uninitialized loop counter
-(reporter's capture): vkshim `vk_shader_fix` setting (`<size>:<sha256>:<offset>:<words>`, from the recipe's `adapter:`;
-matched by size + SHA-256, words inserted into a copy) — on the device the module is fixed at load ("fixed shader
-module (6488 -> 6512 bytes)"); campaign itself not yet seen in a headset by us. Text settings (kind "str") stay out of
-the Game settings dialog (saving it dropped them). I Am Cat: `GetStereoRenderingMode` is inlined (no call sites) →
-`Il2cppReturnPatch.field_loads` rewrites the field read in `OculusLoader.Initialize` (Cpp2IL gives the field offset,
-`field:<name>`); verified with Toy Master: eye swapchains array=1 ×2 instead of array=2. Builds record `recipe_fp`
-(`patches/base.recipe_fingerprint`, `Patch.revision`): a changed recipe or revised patch shows "Update on Frame".
-Remembered Frames are found again after an address change (`Frame.relocate`: scan, same SSH host key, before
-login). Packaged apps show artwork by file path (`thumbs.use_file_paths`, #16). Diagnostics: this boot's kernel log.
-Device tests of requested games (2026-10-04, headless): I Am Cat, Myst 3.3.0, BattleGlide, Blade & Sorcery: Nomad
-start (RUNNING, frames). Roblox: SIGSEGV in je_free from libroblox.so ~3 s in (likely its anti-tamper vs the re-signed
-APK). BONELAB (Unity 2021.3 Vulkan, OVRPlugin 1.94): SIGSEGV with pc == fault addr in vkCreateInstance, called from
-libSLZQuestNative.so's Vulkan hooks into an unmapped (unloaded) library right after OVRPlugin's pre-init
-xrDestroyInstance; pinning openxr/vrclient libraries (RTLD_NODELETE) did NOT help — find the unloaded library with the
-linker's dlopen/dlclose logging next. Accounting+ (Unity 2017.4 built-in Oculus, libOVRPlugin + libvrapi): Unity
-never starts VR on the Frame (no OVRPlugin/OpenXR lines; runs as a 2D app), which is why its "controller setup"
-screen can't be passed — Unity 2017's Oculus device check, not the controller profiles. Cpp2IL can't read Unity 2017.
-The Frame's Android runtime (vrclient.so) knows oculus/touch_controller but not Meta's Touch Plus/Pro profiles
-(OVRPlugin suggests those too, routinely) → adapter `profile_remap`.
-Headset round 2 (2026-10-04): the Frame drops focus often (ms to 7 s; only some are presence/standby) → games pause
-or recentre (B&S Player.OnVRPresence → Teleport, BattleGlide/Unreal pauses); focus_hold now 1 s focused / 1 s max dip
-(longer must still pause). Myst crash = vrclient xrSyncActions race after FOCUSED → `sync_guard` (confirmed); its
-object glitches: app space warp suspected (FB_space_warp is advertised and used) → recipe `patch_disable_space_warp`.
-I Am Cat multipass: poses/times consistent, but every frame is submitted after the next xrWaitFrame (one period late;
-Zink + doubled draws) and the game clamps its physics step to 10 ms → judder while still; testing scale 0.8. Roblox's
-newest crash is on Fossilize's recording thread → vk_sanitize extended to own-engine libs (engine "Other").
-Accounting+: unity_oculus_check + native/ovrpshim (libfp_ovrp.so waits via ovrp_WaitToBeginFrame before Unity
-2017's ovrp_Update2) → VR in the headset at ~72 fps (2026-10-04), but stuck at "press any button" although input
-reaches its OVRInput cleanly (probe: both Touch connected 0x63, individual buttons, input focus 1) → works with issues.
-"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`); 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
-the header checksum/signature; verified with LÖVE for Android 11.5, GitHub #24 Dramatic Shape). Godot 4.2-4.4 (Kotlin `as ClipboardManager`,
-GitHub #134 EndoparasiticVR) → `frame.godot_clipboard` (nops the `Intrinsics.checkNotNull` before that check-cast; Godot's
-clipboard methods return at once; analysis `godot_clipboard`, ANALYSIS_VERSION 10; checked on real godot-lib/templates
-4.2.2-4.4.1, not on the device; 4.1 and 4.5+ don't throw). 2D apps (vr_kind none)
-keep every suggested patch that isn't about VR (`needs_vr = False`), not a fixed list. FramePort on the Frame:
-`frame/local.py` (127.0.0.1, own key authorized; "This Frame (experimental)"; app data in
-~/.local/share/frameport-app because ~/.local/share/frameport is the agent's) and Steam library changes wait while
-Desktop Mode is open. Verified on the device 2026-10-04 (install + launch test from the Frame). Library updates on the
-Frame run one at a time (agent v40 flock): two quick uninstalls used to bring a removed shortcut back (Roblox).
-Headset round 3 (owner's verdicts, 2026-10-04): Blade & Sorcery works — its freezes were the headset's wear sensor
-flickering off while worn (vrserver.txt "HMD off/on" 0.5-2 s) → per-game `focus_hold_ms=2500` (only this game reacts;
-not a default). BattleGlide works (focus_hold). Myst works with issues (object glitches; space warp ruled out, its
-recipe keeps it on). I Am Cat works with issues (judder; scale 0.8 no help). Roblox unsupported (je_free in
-libroblox, also with the Vulkan shim). Installs skip the Steam restart when the shortcut is unchanged and wait while a
-game runs (agent v37). New default fixes in FramePort's code reach games already in a library: after every app update
-`library._follow_catalog` re-derives each non-user recipe once (setting `recipes.app_version`; tests switch it off via
-`library.REFRESH_ON_UPDATE`). Analysis fields added later: **bump `analysis/detect.ANALYSIS_VERSION`** (stored as `analysis.extra.analysis_version`); older entries whose APK is still there are analysed again at the GUI's start (background thread, not a job: ~8 s per 900 MB APK) and before a build (`pipeline.refresh_analyses`, GitHub #104); only `analysis`/`suggested` change, user recipes stay; an unreadable APK gets `analysis_failed` = the version (not retried until the next bump). Troubleshooting techniques: docs/PLAYBOOK.md "Debugging techniques". Unity `boot.config` "vulkan" substring mislabels GLES games as Vulkan
-(I Am Cat ran GLES); OVRPlugin's "Unavailable OpenXR extension: XR_FB_scene" is routine (no longer triaged).
-
-## Round 4 (2026-10-04): surface swapchains, save-folder permissions
-
-**Round 4 (2026-10-04):** XR_KHR_android_surface_swapchain is listed by the Frame's runtime but returns
-FUNCTION_UNSUPPORTED → adapter `surface_emul` (default on, `native/adapter/surface_swapchain.c`): an ordinary runtime
-swapchain is returned, the game gets a Surface from a SurfaceTexture on a worker thread (own EGL context, JavaVM from
-XrInstanceCreateInfoAndroidKHR), frames are read back (glReadPixels) and uploaded in xrEndFrame (Vulkan: own command
-buffer + fence per panel, never waits; GLES: glTexSubImage2D). I Am Monkey's intro works (owner-confirmed). SUPERHOT
-(Quest) quit at start: its cloud save folder was mode 1700 and Lepton's app writes through the folder's group →
-launch.sh `fix_perms` adds u+rwx,g+rwx (agent v41). Lucky's Tale: Unity's Loading.PreloadManager thread grows the
-native heap ~1 GB/s until the OOM killer (Frame freezes); no fix. `perf` works as steamos (paranoid 2; ptrace_scope 1
-blocks gdb/eu-stack/debuggerd) — see PLAYBOOK "Debugging techniques". QuestCraft downloads its JRE at first run into
-`files/runtimes/JRE` (Pojlib Installer); on the Frame it was missing (unpacked by hand, unverified). WiiCompiled: its launcher shows
-(lepton-show-flatscreen) but imports .wcgame files through Android's document picker (OPEN_DOCUMENT), which Lepton
-lacks (ActivityNotFoundException) → imported by hand: libmain.so + game.json → internal files/game/<profile>,
-DATA/ → external files/WiiCompiledOpenXRVR/DATA, MOD/ → .../RetroRewind6 (decompiled with jadx). Lepton has no
-picker at all: a FramePort fix would be an injected picker activity. Generated cover/banner art used to suppress the
-Steam placeholder set (no Steam art at all) → fixed in artwork/steam.py.
-
-## Steam library failures and the devkit fallback (GitHub #21/#30/#41/#42)
-
-**Steam library failures (GitHub #21/#30):** on some Frames Steam never loads FramePort's shortcuts.vdf entries (same SteamOS build and arm64 beta client as the dev Frame; IDs correct; file written before Steam starts): Play → console_log `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` (= "Game configuration unavailable", Steam treats the id as a store app). Cause unknown; agent v42/43 diagnostics: `launch` returns `steam` (started / error + code / silent from console_log), `collect_diag` adds `steam_library` (real Steam dir, beta, Steam start vs vdf write time, entries per account, devkit games) + `steam-console.txt` (incl. Steam's `logs/shortcuts.previous.txt` if present; steamclient.so has "LoadShortcuts: rejecting attempt to load shortcuts: invalid account ID"). **Fallback (agent v43):** when Play gets AppError_9 the agent registers the game through Steam's devkit interface (what Valve's Devkit Management Tool does, MIT: `devkit-1 steam://devkit-1/<~/.steam/steam.token>/create-shortcut?response=<file>&gameid=<id>&directory=~/devkit-game` written to ~/.steam/steam.pipe; answer file / `.error`; `~/devkit-game/<id>/launch.sh` = link to the game's launch.sh, `<id>-argv.json` ["launch.sh"] (relative to the folder), `<id>-settings.json` {steam_play 0, compat_tool ""}). Steam adds it live (no restart), picks its own appid (read back from shortcuts.vdf by DevkitGameID), shows it as a normal non-Steam game named "Devkit Game: <id>" (OpenVR 0, but VR works: owner-verified 2026-10-04), art copied to grid/<appid>*. Ids: letter first, then letters/digits/_ only (spaces, '-', leading digit → "missing/invalid arguments"). Later Plays use the devkit entry; uninstall (`devkit_unregister`, `delete-shortcut` live) and purge remove it. Verified on the dev Frame: register/launch/unregister; the AppError_9 trigger itself only in unit tests. GitHub #42 (two Steam accounts, neither MostRecent): Steam rewrote the active account's shortcuts.vdf without FramePort's entries right after starting, and added the devkit entry live without saving it, so `devkit_appid` (vdf only) failed ("Steam added the devkit entry but didn't save it"); agent v55 `devkit_appid_from_log` reads Steam's `sanitize shortcut app id "~/devkit-game/<id>/launch.sh": replacing 0 with N` console line. GitHub #41 (one account): same Steam behaviour, and every install restarts Steam, which forgets the never-saved devkit entry. Agent v56: the log fallback reads only the current session's console_log.txt; Play re-registers a devkit entry that gets AppError_9; art updates also write the devkit entry's grid art (`copy_grid_art`). Open: why some Frames' Steam never loads or saves shortcuts.vdf (single account too).
-
-## Exit game (GitHub #36)
-
-**Exit game (GitHub #36, 2026-10-04):** `Apps.TerminateApp` (what Exit game calls; reachable for tests through Steam's CEF devtools on 127.0.0.1:8080, SharedJSContext, `Runtime.evaluate` — a stdlib websocket client is enough) closed both a normal shortcut and a devkit entry on the dev Frame within 1-3 s. SIGTERM to Steam's `reaper` alone left launch.sh + Lepton (setsid) + the container running (an earlier headset launch ran on for 87 min); SIGTERM to launch.sh cleans up in ~4 s. Agent v44: launch.sh's 2 s loop ends the game when its parent (the reaper) is gone; `upgrade_launchers` (from ensure_host_fixes) adds that to existing launchers in place. Which in-headset exit path fails is still unknown. Screenshots on the Frame: all under SteamVR's appid 250820 (`760/remote/250820/screenshots`, screenshots.vdf has creation time, no game).
-
-## SteamVR dashboard at game start
-
-**SteamVR dashboard at game start (2026-10-04):** the dashboard (Resume game / controller / VR options) was open whenever a FramePort game started (also over Lepton's 2D launcher). Steam's UI exposes `SteamClient.OpenVR.VROverlay.{IsDashboardVisible,HideDashboard,ShowDashboard}` (CEF devtools, `steam_js` in the agent). Agent v44: launch.sh starts `_dashboard_worker` (waits for FrameBridge's first `pacing:` line in launch.log, then hides a visible dashboard for 25 s, at most 3 times; log `<base>/dashboard.log`; opt out with env FRAMEPORT_KEEP_DASHBOARD=1). Verified on the dev Frame (dashboard shown → 4XVR launched via Steam → hidden ~5 s after the first frames); not yet seen in the headset. **Headset (ITR2, 2026-10-05): too late** — Steam shows its frame menu (`valve.steam.gamepadui.frame.menu`, vrwebhelper_systemui.txt `[PooledPopups] Showing`) ~0.3 s after the game's first submitted frame (FrameBridge `new layer:`), but the first `pacing:` summary comes ~8 s later; the owner had pressed Resume (`[HideDashboard] return_to_game`) before the worker looked. Agent v52: watches from the first `new layer:` line (incremental log reads, 0.5 s polls, 30 s window). Agent v59: watches 120 s and hides up to 10 times (the menu came back after 30 s in the owner's sessions). Agent v53: stops for good once the player opens the dashboard with the controller (`toggle_dashboard_action` in vrwebhelper_systemui.txt since the worker started): v52 closed it 60 ms after each press, and the game, paused for it, stayed paused.
-
-## Space warp / ITR2
-
-**Space warp / ITR2 (2026-10-04):** Into The Radius 2 (UE5, `libUnreal.so` + OVRPlugin, Vulkan) uses Application SpaceWarp (extra swapchains `376x376 format=97` motion vectors + `format=129` depth); #35 reports flickering textures. OVRPort's `patch_disable_space_warp` has no effect on UE5, and hiding XR_FB_space_warp in FrameBridge's enumerate doesn't reach the game either: **OVRPort's dispatcher offers/enables XR_FB_space_warp itself**. FrameBridge `hide_space_warp` (per game, off) hides it and strips `XrCompositionLayerSpaceWarpInfoFB` (1000171000) from the projection views (log `hide_space_warp: removed space warp info`); the game still renders its MV swapchains. Test build installed on the dev Frame; flicker not yet checked in a headset. Heuristic: UE5 + OVRPlugin shows it as an option (off). `equirect_emul` is suggested for Unreal games whose graphics API isn't detected ("GLES or unknown"); on Vulkan it switches itself off (Myst/Riven/ITR2): harmless, but Unreal Vulkan detection is a known gap.
-
-## PR #34: Meta XR Audio metadata (Batman)
-
-**PR #34 (merged 2026-10-04, Lucas-Mathieu):** `native/adapter/audio_metadata.h` patches Meta XR Audio Wwise (only build ID e1619e7f…, Batman: Arkham Shadow 1.4.1) so queued audio metadata isn't freed while the current audio frame references it (smoke-bomb crash). Verified headless: installs ("metadata reclamation follows …"), 72 fps; we added a once-per-second scan limit. Outside PRs: review source, rebuild `artifacts/` ourselves, merge locally (contributor's commit kept), push main.
-
-## Heuristics eval (2026-10-04)
-
-**Heuristics eval (2026-10-04):** `scripts/eval_heuristics.py "<VR CyberDeck Portable>"` → 19/44 recipes exact, 322/352 fields (most diffs: `frame.unity_text_input` suggested where older catalog recipes lack it; the rest are runtime-only findings: use_alt, vk_shader_fix, focus_hold, sync_guard, multipass). `PATCHED/` copies aren't scored (already converted).
-
-## Proton default (stable vs Experimental)
-
-**Proton default (agent v51, owner's choice 2026-10-05):** the newest **stable** ARM64 Proton is the default for PC VR games (`pick_proton`: asked-for name/alias, else newest installed stable, else any stable). Agent v49-50 defaulted to Experimental; the owner's headset A/B with Rick and Morty (Experimental 69 % reprojected frames, stable felt much smoother) reverted it. The game page's Customize shows `pcvr.proton_tool` as a dropdown (Stable (default) / Experimental = alias `proton-experimental`); `ensure_proton` installs a chosen one (it asks once more for the runtime Steam only names after Proton is installed; Experimental installed unattended on the device in 53 s). A PC VR launch test that fails on stable suggests Experimental (`pipeline.PROTON_TOOL`, `proton_alternative_worth_trying`, button "Try Proton Experimental and reinstall"). Remaining Rick and Morty stutter on head turns = the game rendering below the refresh rate (reprojection), not Proton.
-
-## USB cable link
-
-**USB cable link (verified 2026-10-05, cabled to the dev PC):** `usb0` is a USB **NCM** gadget (configfs g1: `ncm.usb0` + `ffs.adb`, Valve 28de:2460) set up by `usb-ncm-gadget@usb0.service`, which only runs with `ConditionPathExists=|/etc/systemd/system/adbd.service.d/steamos-devkit-enabled` = **Developer Mode only**. `usb-ncm-dnsmasq@usb0` serves DHCP with fixed `dhcp-host` entries: Frame 10.86.200.233, PC **10.86.200.234** (`frame/usb.py` FRAME_USB_IP/PC_USB_IP). Windows 11 binds its built-in "UsbNcm Host Device" (no driver); WSL mirrored sees eth 10.86.200.234. USB is high-speed (USB 2.0): upload 36.9 MB/s vs 11.3 MB/s home Wi-Fi. Frame→PC over the cable worked without a firewall change. `scripts/usb_autotest.py` (Windows via powershell.exe from WSL), `frameport frame usb-check`. Wizard "Set up with a USB cable" (`PairingServer(host=PC_USB_IP)`; the real bootstrap ran end to end over USB). Discovery dedupes by SSH host key and prefers USB > Frame hotspot > network (`discovery.dedupe`); a lost address is re-found by key (`Frame.relocate`, tested with a dead saved address).
-
-## Start activity / QuestCraft / ITR2 pop-in
-
-**Start activity / QuestCraft / ITR2 pop-in (2026-10-05):** WiiCompiled's VR part (`QuestActivity`, SDL, process `:game`) stays behind Lepton's flat window when the launcher is shown (`device.text_input_window`). `frame.start_activity` (opt-in; analysis `extra.vr_activity` = the original APK's activity with Meta's VR category when it isn't the launcher) gives that activity's filter LAUNCHER and every other LAUNCHER becomes INFO, per element (`axml.set_start_activity`); Lepton's own `apk-info-extractor --print-activity-name` (on the Frame under Lepton/liblepton/apk_extractor) then answers QuestActivity. **OVRPort gives every MAIN activity LAUNCHER + VR categories**, so the VR activity must come from the original APK's analysis, not the converted manifest. Lepton has no activity override (`APP_ACTIVITY` is reset when app_metadata.sh is sourced). QuestCraft reaches Minecraft 1.21.5 (Fabric, Vivecraft, Sodium; LTW "Large Thin Wrapper" GL 3.0 on the Frame's Zink) and stops at `OpenGL error 1282` in `WindowFramebuffer` createTexture (Minecraft's crash report in `files/instances/1.21.5/crash-reports/`, Pojlib's `files/latestlog.txt`); the vrclient SIGSEGV / "pthread_mutex_lock called on a destroyed mutex" afterwards is only the shutdown (Unity's render thread still in vrclient while the instance is destroyed). ITR2 "models popping in and out" in game: Unreal reads user config from **internal** storage (`lepton-data/internal/<pkg>/files/UnrealGame/<Project>/<Project>/Saved/Config/Android/Engine.ini`, not external); `r.AllowOcclusionQueries=0` there broke its menus (removed again). Vulkan shim `vk_query_slots` (two slots per occlusion query) never saw ITR2 create an occlusion query pool, and the run with it crashed (Unreal RenderThread SIGSEGV, caught by sentry-native: no tombstone; the backtrace is in `cache/sentry/*/.sentry-native/*.run/*.envelope` with module offsets) - left off. Next suspect: Unreal 5 mobile HZB occlusion reading depth stored with Valve's FDM injection layer; test = launcher `VK_INSTANCE_LAYERS=''` (Lepton then loads neither VALVE_rpo nor VALVE_fdm_injection, Fossilize still). QuestCraft: LTW overrides glGetError and returns 0 with `LIBGL_NOERROR` set; Lepton passes `LEPTON_ENV_<NAME>` to the app as `<NAME>`, so catalog `lepton_env: {LEPTON_ENV_LIBGL_NOERROR: '1'}` gets Minecraft past the GL error 1282; then black picture (see the catalog entry). FrameBridge logs `new layer` once per layer type per process and projection views only for the first frames, so a second session in the same process (Vivecraft after Unity) needs `layer_debug=1`.
-
-## Vulkan validation / ITR2 solved
-
-**Vulkan validation / ITR2 solved (2026-10-05):** Khronos' validation layer can't come from Lepton (its layer dir is in the read-only guest image; the Linux copies on the Frame are glibc) and a global `debug.vulkan.layers` property (via the LEPTON_GFXRECON_FP_PROPS trick) kills the container at boot. Working recipe: bundle `libVkLayer_khronos_validation.so` (Khronos android-binaries release, arm64-v8a, stored uncompressed) into a test APK re-signed with the game's key (`apk.sign.sign`), install with `frameport install <pkg> --apk`, and set the Vulkan shim's `vk_validation=1` (it adds the layer at vkCreateInstance; findings under the logcat tag VALIDATION in launch.log, each message ID capped at 10). ITR2's flicker + windows behind models = Unreal's Qualcomm shader-resolve subpasses with a depth resolve of a single-sampled depth attachment (VUID-04908/-03179); `vk_spec_fixes=1` drops that resolve (its TRANSFER_DST half never applies to ITR2: the main depth is transient). Valve's VALVE_rpo layer removed ITR2's fog (catalog `lepton_env: VK_INSTANCE_LAYERS: VK_LAYER_VALVE_fdm_injection`). `r.ViewDistanceScale=2` in the internal Saved/Config/Android/Engine.ini only exists on the owner's Frame (the catalog can't write internal storage yet). Launch tests: Lepton prints a transient "is not a running context" on the first start after an APK change (agent v54 `not_started` waits 30 s for "Boot complete!").
-
-## GitHub #38/#39: PowerWash Simulator, The Room VR
-
-**GitHub #38/#39 (2026-10-05):** PowerWash Simulator stuck at "Waiting.." on a reporter's Frame = Unity sized the right-eye image rect past its swapchain (rect 268+1656 on a 1920-wide swapchain; the runtime's recommended size differs per Frame) and SteamVR rejected every frame (`xrEndFrame failed -25`, XR_ERROR_SWAPCHAIN_RECT_INVALID), after which the game stopped calling xrEndFrame. FrameBridge `rect_clamp` (default on; sizes noted in xrCreateSwapchain; clamped layers count as swapped) keeps projection/quad rects inside their swapchain; triage `swapchain-rect-invalid`. Not reproducible on the dev Frame with `scale` (Unity's eye sizing isn't just the recommended width); no regression there (72 fps). The adapter's revision was NOT bumped (that would mark every installed game outdated): affected users rebuild. The Room VR (#38) = Unity's render thread SIGSEGV in libgallium_dri.so ~30 ms after the game recreates its eye swapchain with samples=4 (FrameBridge retries samples=1); the game's own code turns MSAA on (not OVRManager); candidate fix: hide GL_EXT_multisampled_render_to_texture (GL shim) - needs the APK to test. The launch test passed both (render thread dead / no frames): triage gap.
-
-## Headset round 2026-10-05 (evening)
-
-**Headset round 2026-10-05 (evening):** I Am Cat's judder = repeated xrLocateViews of one display time returning
-slightly different poses → FrameBridge `pose_consistency` (owner-verified, works). Lucky's Tale freeze on touching a
-save slot = OVRPort's OpenXR dispatcher converting XR_FB_haptic_amplitude_envelope with ns read as s (GitHub #9) →
-xrshim `haptic_fix` (owner-verified); its remaining short pauses were the wear sensor ("HMD off/on" 0.5-1 s in
-`logs/eyetracking.txt`, not vrserver.txt) → **`focus_hold` is on by default with 5 s** (owner's choice; C defaults
-too). The Room VR works (`unity_no_overlay_copy`). BattleSisters (Unity 2019.4 built-in VR, no libOculusXRPlugin.so)
-flooded "outside of frame bounds" ~2400/s and hung the GPU (kernel hangcheck, zink DEVICE LOST) → the ovrpshim frame
-wait now also applies to Unity 2019 without the Oculus XR Plugin (`UnityOculusCheck.legacy_loop`). Vader Immortal
-(UE4, stuck on the loading image after the intro, GitHub #49): VRP repacks carry a Frida gadget (`libfrda.so`,
-config `hijack_responses`), but OVRPort's `patch_clean_up_frida` removes its loadLibrary call, so it never runs on
-the Frame; `frame.ovr_trace` (opt-in, `native/ovrtrace`: 1138 exported ovr_* stubs → real loader functions, logcat
-tag `fp_ovrtrace`: calls, PopMessage answers, unanswered requests every 10 s) is the next diagnostic.
-
-## Unity built-in VR input (Accounting+, BattleSisters)
-
-**Unity built-in VR input (2026-10-05):** probe builds (`FRAMEPORT_INPUT_PROBE=1 frameport build …`; it logs
-trigger/grip crossings too) showed OVRPlugin returns the full Touch state for every controller mask (also Go masks);
-presses reach the games' OVRInput. Accounting+ (Il2CppDumper v6.7.46 reads its Unity 2017 metadata v24, run on Windows)
-passes stance selection (NewtonVR grip/trigger) but its motion warning waits for `Input.GetMouseButtonDown(0/1)`,
-which Lepton never delivers (no focused Android window) → ovrpshim registers its own
-`UnityEngine.Input::GetMouseButtonDown(System.Int32)` icall (il2cpp_add_internal_call, after Unity's: resolve first)
-that adds a click in the frame a Touch trigger or A/B/X/Y is newly pressed (`unity_oculus_check` revision 3).
-BattleSisters (Unity 2019 InputSystem/XR InputDevices via `VrHandInput`): libunity's Oculus module (OVRPlugin
-function table: a global pointer at 0x16b57c0 in this build, slots filled by name, e.g. +0x160 GetControllerState,
-+0x168 State2, +0xe8 GetNodePresent) only reports controllers when `strncmp(deviceModel, "Oculus", 6) == 0` (next to
-the Go check `deviceModel == "Oculus Pacific"`); Lepton's model is "Valve Lepton" → Go/unknown → only Go masks polled,
-buttons dead. `unity_oculus_check` revision 4 (`oculus_model_checks`, Unity 2019 only) turns the 17 compares' length
-into 0 (`orr w2, wzr, #6` → `mov w2, #0` after the adrp/add of the "Oculus" literal; the string stays: it is also
-Unity's VR device name). Device result: libunity now polls `ovrp_GetControllerState(0x3)` (Touch); owner-confirmed
-2026-10-06: buttons work. Its first controller vibration then hit OVRPort's haptic-envelope bug (11 GB, OOM kill) →
-`haptic_fix` is now suggested for every game with libOVRPlugin.so (settings detect), BattleSisters works. Ruled out before: ProductName, GetNodePresent, the device-model string itself, exports.
-Accounting+ works (owner, 2026-10-06).
-
-## Vader Immortal (headless investigation)
-
-**Vader Immortal (UE4, GitHub #49, 2026-10-06, headless):** stuck after the intro on an in-game image (the splash
-quad ends ~6 s in; then the game's own projection frames, 72 fps, balanced xrBeginFrame/xrEndFrame). Not the Platform
-SDK (`frame.ovr_trace`: only user + entitlement, both answered) and not the repack's Frida gadget (OVRPort's
-`patch_clean_up_frida` removes its loadLibrary). It **leaks ~430 GPU mappings (/dev/dri/renderD128) and ~20 MB a
-second** (6.5 GB + swap after 5 min, then 26 fps): page-fault stacks (perf -e page-faults, offsets resolved with the
-process maps + vrclient.so's own symbols; its text segment is at file offset + 0x4000) end in SteamVR's runtime:
-`xrBeginFrame → CSxrCompositorOpenVR::BeginFrame → SubmitExplicitTimingData → CVRCompositorSharedTextures::
-BeginGPUTimingCommandBuffer` and `xrEndFrame → CVRCompositorClient::SubmitWithArrayIndexAndTime`. Ruled out: the
-layer color scale/bias + image layout structs (FrameBridge `strip_color_bias` 1/2, diagnostic), Valve's Vulkan
-layers (VK_INSTANCE_LAYERS=""), array swapchains in general (Lucky's Tale/I Am Cat flat). Kernel tracepoints aren't
-allowed for steamos. FrameBridge: `layer_debug` logs xrDestroySwapchain and per-5 s xrBeginFrame/xrEndFrame counts;
-`frame_balance` (ends an open frame before the next begin) exists but Vader never leaves one open. Next (built,
-not yet run: the Frame slept): `layer_debug` also counts xrAcquire/Wait/ReleaseSwapchainImage per 5 s (hooked only
-with layer_debug, after the other conditional hooks) to see whether Vader skips a wait or release: it doesn't (361/361/361 per 5 s).
-FrameBridge `snapshot=N` (`snapshot_gl.c`, GLES): every N s the left-eye image the game submits is read back on its
-own context and saved as `files/fb_snap_0-7.ppm` (quarter size) — headless launches show a black headset view, this
-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
-
-**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
-
-**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).
-
-## Unreal's self-restart
-
-**Unreal's self-restart (agent v90, 2026-10-13):** UE 4.21+ restarts the app once after its first-run shader
-precompile ("optimizing" screen; `r.ProgramBinaryCache.RestartAndroidAfterPrecompile`): it starts its own LAUNCHER
-activity and calls System.exit(0); Lepton ends the container with the first process (the restarted one with it).
-Skipping `AndroidThunkJava_RestartApplication` or the cvar = 0 (accepted via UE4CommandLine.txt `-ini:`) left Sports
-Scramble on that level for good. launch.sh (RESTART_BLOCK, `upgrade_launchers` adds it) starts Lepton once more when
-`_restart_requested` sees the app's own LAUNCHER start (system log, uid >= 10000) <= 5 s before its exit; first run
-kept as `launch-before-restart.log`; `FRAMEPORT_NO_RESTART=1` off. Owner-verified with Sports Scramble's first start (2026-10-13).
-
-## xrWaitFrame runs ahead (Journey of the Gods)
-
-**xrWaitFrame runs ahead (Journey of the Gods, 2026-10-14, owner-verified):** with real frames (headset on) the
-Frame's runtime sometimes returns from xrWaitFrame at once with a display time less than one refresh after the frame
-just submitted, and then rejects the second submission for that refresh (`VRCompositorError_AlreadySubmitted` in
-Steam's `logs/xrclient_<pkg>.txt`; FrameBridge pacing above the display rate). VrApi games that render faster than
-the display ran ahead (~120 submits/s at 90 Hz) and the scene slid and snapped back. The VrApi bridge re-waits when
-the new display time is under half a period after the last submitted one (`pacing 2s:` counters). Headless runs only
-submit empty frames and never show it. Lepton's logcat mirror also missed the whole verifying session (launch.log =
-Lepton's own lines only): the keeper now catches a silent mirror too (agent v91).
-
-## Lepton's logcat mirror dies
-
-**Lepton's logcat mirror dies (agent v67, 2026-10-09; v91 2026-10-14):** Lepton's mirror (`podman exec -it <container> logcat -v threadtime,color`) fails three ways: `logcat: Unexpected EOF!` right after the game starts, `Logcat read failure`, or running and writing nothing at all (Lepton 3.0.5: seen twice on 2026-10-14, once in the owner's session, once headless). launch.sh's `_logcat_keeper` reads `podman exec <container> logcat -v threadtime -T <epoch>` itself into launch.log after a failure line or 20 s without a logcat line (from the launcher's start when the mirror never wrote, else from just before its last line), restarts it from where it ended (≤5), stops it when Lepton's coloured lines come back, sets the container's log buffer to 16 MiB (`logcat -G`), and logs every decision to `<base>/logcat-keeper.log`. Checked on the dev Frame: a mirror killed mid-game (hand-over without a gap) and a silent mirror (the whole session recovered).
-
-## Double launch
-
-**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
-"(starting)", "Clearing baked app data due to early exit") and both died (Vader, BattleSisters). launch.sh now takes
-`flock` on `<base>/.launch.lock` (fd 9, inherited by Lepton; the watchdog and dashboard helpers close it with
-`9>&-`); a second launch exits 0 and logs to `<base>/launch-dup.log`. `upgrade_launchers` adds it to existing
-launchers. Verified on the device (second launch during boot: ignored, the first kept running). Vader on its loading
-card ignores input too (owner pressed/held every button: presses reach the runtime, the card never changes).
-
-## Issue triage round (2026-10-06)
-
-**Issue triage round (2026-10-06, owner's headset):** vibration in OVRPlugin games = 2 s vibrations updated per frame and
-stopped with amplitude 0; FrameBridge turns amplitude 0 into xrStopHapticFeedback (else each buzz ran 2 s), haptic_fix
-uses the envelope RMS (was its peak), per-game `haptic_scale` → Creed/The Boys/Jurassic World fine. Lambda1VR (TBXR):
-loader named by Build.MANUFACTURER (`frame.tbxr_vendor`), no graphics extension enabled (FrameBridge adds
-XR_KHR_opengl_es_enable + asks for the requirements on -50), always multisampled render-to-texture (GL shim gives
-single-sampled stand-ins when GL_EXT_multisampled_render_to_texture is hidden) + its xash/ data → works. Jurassic World:
-`frame.vrapi_stub`. Metro Awakening: contributor's vkshim fixes + hide_space_warp + no VALVE_rpo (jumping polygons like
-ITR2). Pinball FX VR: hide_space_warp (stutters). Eleven: a Meta online request fails after platform init → needs Meta
-services. Star Wars Tales: top half black + freeze after loading; ruled out: asset-file paks (never requested), Valve
-foveation (off: no change), GL errors (MESA_DEBUG=1: none), EGL_BAD_ACCESS once in OVRPlugin init (harmless); the game's
-eye image reads back black. BlazeRush: VrApi bridge exports + ovr*_ToString stubs + avatar stub get it to the menu room
-at 72 fps, full input reaches it (diagnostics `input 5s`: Touch type only, sticks 1.0, buttons, poses 0x8f), but the room
-draws no controllers and ignores input; avatar loader forced to its "Failed" path (no logged-in user) changed nothing.
-`frame.ovr_trace` can't trace Unity games (P/Invoke dlsym; nothing imports ovr_*). Headless: the VrApi bridge's 30 s
-head-pose deadline ends VR mode without a worn headset (not a game bug).
-
-## Lepton storage
-
-**Lepton storage (2026-09-30):** each app's /sdcard (= /storage/emulated/0 → `<base>/lepton-data/external`) has `Movies`/`Download`/`Documents` symlinked to the Frame's `~/Videos`/`~/Downloads`/`~/Documents` (liblepton/mounting.sh, only if they exist at start); agent v24 `storage_targets` reads that mapping. Android's MediaProvider canonicalises paths to /home/steamos/... and rejects every file ("doesn't appear under [/system/media...]"), `sm list-volumes` is empty: the media index never works, apps must browse folders. Lepton installs with `adb install -g` (runtime permissions granted, MANAGE_EXTERNAL_STORAGE too). Files: `install/files.py`, `frameport frame send|storage`, GUI Files tab (formerly Frame → Send files).
-
-## SteamVR per-app settings
-
-**SteamVR per-app settings (2026-09-30):** editing steamvr.vrsettings while SteamVR runs is lost; the web API (127.0.0.1:27062 /app/setsettings) needs `x-steamvr-secret`. `native/vrsettings` = `fp_vrsettings.exe` (freestanding, OpenVR `FnTable:IVRSettings_003` as a Utility app, loads SteamVR's bin/win64/openvr_api.dll) sets them live and SteamVR persists them: section `steam.app.<shortcut appid>`, keys `preferredRefreshRate` (float) and `motionSmoothingOverride` (0 global, 1 on, 2 off, 3 always). Steam Link (vrlink) lists the Frame's rates 72/80/90/96/108/120/144 in vrserver.txt and follows the per-app preference ("host preferred N Hz"; whether the key is honoured is unverified in-headset yet). Judder metric: vrcompositor.txt session summary dropped + "Timed out. N total" (Stormland: 0 dropped but 313 timeouts in 2 min); fpsVR (`%LOCALAPPDATA%\fpsVR\*.json`, 0.1 ms histograms) gives p99 CPU/GPU ms. `pcvr.steamvr_tuning` (default on, PC only) applies on Play: highest rate whose budget ≥ p99×1.05, at least one step down, smoothing on.
-
-
-## Language packs
-
-**Language packs (merged from PR #20, 2026-10-04):** overport's `libovrplatformloader.so` is a dispatcher that `dlopen`s Meta's own loader (`libovrplatformloader_meta.so` / `_meta_q1.so`, also `libpxrplatformloader.so`) and keeps its own message queue; `ovr_LanguagePack_GetCurrent/SetCurrent` are 8-byte `return 0` stubs in it, `ovr_AssetFile_GetList` forwards to Meta's loader. `frame.langpacks` (opt-in, `native/langpack`) serves `<tag>.lang` files from the game's data; `elf.hide_exports` marks the loader's exports STB_LOCAL (bionic and glibc only match GLOBAL/WEAK; verified for glibc, bionic's `is_symbol_global_and_defined` is from memory). `libfp_langpack.so` is built here (`python native/build.py --only langpack`) and committed. Owner-verified 2026-10-04: Deadpool VR with only `en.lang` and the patch on plays English dialogue and runs normally (headless launch tests show 2-6 fps while it loads: not a regression sign). A dispatcher answer that arrives after we answered the timed-out GetList is dropped (one answer per request); games already in a library get `lang_packs` filled after an app update (`library._refresh_data_fields`). The library logs to logcat under the tag `fp_langpack` (dirs looked in, packs found, every language-pack call), so it shows up in the game's `launch.log`; an `ovr_AssetFile_GetList` the dispatcher leaves unanswered for 1.5 s is answered with our packs alone. Deadpool VR (Unreal) accepts a pack only when its `Metadata` equals the game's own version string (`ULanguagePacksSubsystem` compares it with `%s.%s.%s.%s.%s` built from the build info, e.g. `1.0.40.356975.Quest` = versionName; found by disassembling `libUE4.so`): the patch writes the APK's versionName into the library (`@FPMETA@` slot, `with_metadata`), `FRAMEPORT_LANGPACK_META` overrides it. Deadpool VR (2026-10-04, headset): German became selectable with that Metadata, but dialogue stayed silent (even English once reported as a pack) while the path was spelled `/sdcard/Android/obb/<pkg>/x.lang`; with the `/storage/emulated/0/Android/obb/<pkg>/x.lang` spelling (Unreal's own, now listed first in `scan_dirs`) German dialogue plays. `FRAMEPORT_LANGPACK_SKIP=<tags>` or a file `fp_langpack_skip` in the obb folder leaves packs out of the list (experiments).
-
-
-## Cube swapchains
-
-**Cube swapchains (GitHub #107, 2026-10-09):** the Frame's runtime refuses `faceCount=6` swapchains (-2,
-XR_ERROR_RUNTIME_FAILURE); OVRPlugin ignores that ("CreateSwapchain for eye 0: 0x0, 0 stages") and crashes in
-ovrp_EndFrame4 (memset). FrameBridge `cube_standin` (default on, `native/adapter/cube_standin.c`) serves a refused cube
-swapchain as one GL cube-map texture in the app's context (GLES only) and drops its layers. Verified headless with
-Budget Cuts Ultimate (2048² sRGB, 12 mips; runs on at ~70 fps); what the cube layer showed is simply missing.
-
-## Hardware video decoding
-
-**Hardware video decoding (PR #96, PR #128 by Lucas-Mathieu, adapted 2026-10-10, agent v71):** `native/hevc` = one
-OMX plugin `OMX.frameport.{avc,hevc,vp9}.decoder` (FFmpeg v4l2m2m on Iris /dev/video-dec0, FFmpeg software decoders as
-fallback inside the component, Vulkan copy for big native surfaces). The connection installs it once per Frame
-(`ensure_video_codec` → agent `video_codec_status`/`install_video_codec`: `~/.local/share/frameport/video-codec/versions/
-<manifest sha>` + `current` symlink). A Frame keeps the same or a newer `revision` (no flip-flop between PCs) → **bump
-`revision` in native/hevc/build.py with every artifact change**; a failed install isn't retried during the connection.
-Per game: only launchers of games whose recipe has `frame.hw_video_decode` (install stage, no APK change; suggested
-from analysis `media_codec`, ANALYSIS_VERSION 8; deployment.json `hw_video_decode`) get the codec line → the Podman
-wrapper (native/hevc/podman.py) mounts the plugin into that container (merged media_codecs.xml in
-$XDG_RUNTIME_DIR/frameport-video). Off for every game: Settings → Installing (library `video.hw_decode` → agent
-`video_codec_switch` = video-codec/disabled); one game: `FRAMEPORT_NO_HW_VIDEO=1 %command%`. `upgrade_launchers`
-converts agent ≤70 launchers (Batman's `<base>/frameport-codec` → keeps the line, folder then removed). Batman: catalog
-+ migration `batman_video_patches` (`frame.hw_video_decode` + hidden adapter setting `surface_native`). Iris: 8K
-refused (ENOMEM) while any other decoder session is open; SteamVR's vrlinkrunthread holds one ~12 s at game start →
-refused opens retry until 20 s after the plugin loaded (else 2 s), then software; VP9 7680x3840 never returned a
-picture → VP9 ≤4096x2304; hidden VP9 frames come back as empty capture buffers (bytesused 0, no LAST):
-FFmpeg's wrapper ended the EOS drain at the first one (two-pass VP9 lost its last ~25 frames) → build.py requeues
-them (codec revision 8; drain ends at LAST, or 1 s after a skipped empty buffer; dev Frame 2026-10-10: 600/600 =
-OMX.google.vp9 Y hashes). Rebuilds are deterministic (ext4 + NTFS path
-with spaces, two NDK copies → same; rev 8 141de01f…; PR #128's own sources → its 27a2d749…). Not yet run on the device.
-
-## Vulkan shader dump
-
-**Vulkan shader dump (GitHub #140, 2026-10-10):** adapter `vk_shader_dump=1` (Vulkan shim, `native/vkshim/shader_dump.h`;
-applies where vk_sanitize can: Unreal/Other arm64) writes each distinct SPIR-V module once to
-`files/fp_vk_shaders/<size>_<sha256>.spv` (tmp + rename) and one `index.txt` line per vkCreateShaderModule (`<seq> <ms>
-<unix ms> <name> new|known|again|failed`, O_APPEND) to find the module behind a GPU hang. Agent v72 `collect_diag`
-returns `shaders` (newest modules of fp_vk_shaders + fp_spirv, ≤4 MB each, base64) → bundle
-`games/<pkg>/target/shaders/`. Triage `gpu-hang` suggests both dumps; `triage.graphics_api` (FrameBridge's
-xrCreateSwapchain formats: <0x1000 Vulkan, else GL) keeps only the session's API's (`API_ONLY`). Host-tested only.
-Agent v74: a reporter's hang came ~10 s after the last new module, so the culprit wasn't among the newest written →
-with an index naming modules, `shader_dumps` sends every module of the index's **newest session** (after the last
-`# start`), deduplicated, last used first, each ≤4 MB, ≤30 MB in all (`session` = how many it names) + that session's
-index lines; no index (fp_spirv) = the old newest-by-mtime 4 MB. One JSON line (~40 MB base64) over the SSH channel
-is read whole by `Frame.agent` (fine at that size); `_Writer.fit` drops the least recently used modules last, after
-cutting logs, to stay under the 24 MB zip limit.
-
-## Unreal OBB check
-
-**Unreal OBB check (GitHub #159, 2026-10-10):** Epic's DownloaderActivity checks OBB name+size (OBBData), then with `bVerifyOBBOnStartUp=true` CRCs the whole OBB; its screens are invisible in Lepton (stuck at `Displayed …/.DownloaderActivity`, triage `unreal-obb-check-stuck`) → `frame.unreal_skip_obb_check` (analysis `unreal_verify_obb`, ANALYSIS_VERSION 11) flips the manifest boolean (`axml.set_meta_data_bool`); skips only the CRC pass. Host-tested only.
-
-## Issue round 2026-10-12
-
-**Issue round 2026-10-12 (agent v83):** Lepton pastes STEAM_COMPAT_DATA_PATH unquoted into `sh -c "ln -s …/internal/<pkg>
-/data/data/<pkg>"` (mounting.sh): a game on a card named "Steam Frame 512g" got no internal storage (no saves/prefs;
-Beyond Sandbox's EOS then looped `createKeychain→resetKeychain` forever, 1.85 GB log). Quest launchers with an unsafe
-path now `ln -sfn <base> ~/.local/share/frameport/lepton-paths/<pkg>` at every start and give Lepton that path
-(`app_dir_lines`/`set_app_dir`/`launcher_base`; upgrade_launchers converts; deployment.json keeps the real base).
-Verified on the device with a spaced copy of Stremio (old: the `ln` error; new: /data/data link, shared_prefs
-writable). `frame.eos_keychain_loop` (opt-in, triage `eos-keychain-loop`) returns from EOSSDK.resetKeychain. Wander
-0.3570 (Unity 6.5, Firebase, Gecko) ran out of bionic's 128 pthread keys → `frame.unity_tls_key_pool` (Klownicle's
-approach, #198: libunity's 4 key imports renamed `fp_tkey_*` via `elf.rename_imports`, `libfp_tkeys.so` pools
-destructor-less keys behind one real key); device: past Firestore, 72 fps. Cpp2IL releases can't read metadata v107
-(Unity 6.5) → `tools/cpp2il.py` falls back to the development CI build (nightly.link) on that error, and since #293 on any release failure (BattleTalent, Unity 2021.3: the release dies exit 134 in CsFileUtils.GetTypeName after making the folders, no .cs; `il2cpp._run` = non-zero exit or no .cs is unreadable; never with FRAMEPORT_CPP2IL; caches holding "every class missing" are re-run). Vermillion's canvas
-is an OVROverlay quad (drawn above the hand) → `frame.vermillion_scene_canvas` (PaintableMesh getters → false;
-installed build checked, 72 fps headless; headset not yet). Linux apps: `desktop_icon` switch, a deleted desktop copy
-stays deleted (#212). Findings: OLAR (#201) RHIThread null deref in libUnreal (`ldr x8,[x19,#792]`, x19=0) not fixed by
-hide_space_warp / vk_hide_fdm / no Valve layers; FNAF HW (#135) "freeze" = first-start GL program-binary-cache compile
-on Zink (threads busy in zink/disk cache), not a hang; VR4 (#199) reporter's patch.203 OBB truncated. Upload benchmark
-(`scripts/upload_bench.py`, #242): home Wi-Fi caps every method at ~11 MB/s; paramiko uses ~3x OpenSSH's CPU; Windows
-OpenSSH refuses FramePort's key file (ACL "bad permissions") until its permissions are tightened.
-
-## OpenSSH uploads
-
-**OpenSSH uploads (2026-10-15, #324/#242):** sftp escapes `* ? [` inside double quotes itself (and undoes it for
-put's destination), so `native_upload.quote` escapes only `\\`/`"`; Win32 sftp turns every local backslash into `/`
-(escapes too) → local paths go as `C:/…`. Logins: `Frame.auth` = the attempt that worked (app_key / user_key = a key
-file from Settings → Installing → SSH keys, library `ssh.extra_keys`, CLI `frame ssh-keys` / agent / password).
-OpenSSH strict (FramePort + Settings keys, IdentitiesOnly) unless auth was "agent"; a refused strict login retries
-relaxed (+ private copies of ~/.ssh/id_{rsa,dsa,ecdsa,ed25519}: OpenSSH skips its defaults once any -i is given, + the
-agent); `-v` key lines go into the error. FramePort doesn't add its key to the Frame for this. Windows-tested.
-
-## Meta user id
-
-**Meta user id (GitHub #182, 2026-10-11):** OVRPort's platform loader (runtimes 3.4.3-23204ea and -aa54c3f) answers
-`ovr_GetLoggedInUserID` (and two other callers) without a Meta account with a made-up id from a helper (`stp; mov x29,
-sp; bl random; …; mov/movk x9 = 0x53444835ec580000 (6e18); add x0, x8, x9; ldp; ret`), kept only in memory → a new id
-every start; Walkabout Mini Golf files saves under `Profiles/Oculus/<id>/` and lost all progress. `frame.ovr_stable_user`
-(default_on, detect = the game has libovrplatformloader.so) rewrites the helper to `mov x0, <6e18 + 32 bits of
-sha256(package, keystore)>; ret`: stable per game and per user (keystores are personal), so online games never see two
-FramePort users as one. Found in every PATCHED build checked. Host-tested only; upstream candidate.
-
-## Vivox API 31
-
-**Vivox API 31 (GitHub #101, 2026-10-09):** newer Vivox builds (Green Hell VR) call Android 12 AudioManager
-communication-device methods from `com.vivox.sdk.AudioChangeListener` with no SDK check → NoSuchMethodError on Lepton's
-Android 11. `frame.vivox_audio_route` (analysis `vivox_api31`, ANALYSIS_VERSION 4) makes every such method return at
-once (`Dex.return_early`: return-void / `const/4 v0,0; return v0`; nopping the invoke would leave a move-result the
-verifier rejects). Older Vivox (Eleven Table Tennis, BattleSisters) lacks that code and isn't matched. Verified
-headless: Vivox initialises, 150 s at ~65-70 fps.
-Photon Voice does the same (GitHub #362 Table Troopers, #325): `com.exitgames.photon.audioinaec.AudioInAEC.
-updateAudioDevice` (void; only caller of getAvailableCommunicationDevices/setCommunicationDevice, reached from the mic
-thread `AudioInAEC$1.run` via access$000; no SDK_INT check left) → sibling patch `frame.photon_voice_audio_route`
-(analysis `photon_voice_api31`, ANALYSIS_VERSION 21; shares `vivox_audio_route.patch_class`; Vivox's id, title and
-output unchanged, no revision bump). Triage: `vivox-api31` / `photon-voice-api31` now need the SDK's class in the
-stack; any other `*CommunicationDevice*` NoSuchMethodError = `audio-api31` (report). Host-tested on the real dex only.
-
-## Steam Input gamepad for 2D apps
-
-**Steam Input gamepad for 2D apps (GitHub #162, agent v72, 2026-10-10):** Lepton's Android only has the Wayland seat's `wayland_touch/keyboard/pointer`. Steam makes its virtual pad (uinput, `/devices/virtual/input`, 28de:11ff, "Microsoft X-Box 360 pad N", ACL for steamos) only while the Frame's controllers are on (controller.txt "Steam Controller reserving XInput slot 0"; gone when they sleep), also with no game running; steamos-manager's 28de:0000 keys device isn't a pad (no BTN_SOUTH). Lepton's container root (system_server too) = steamos (`keep-id:uid=0`), so a bind-mounted `/dev/input/eventN` opens. Opt-in `device.steam_gamepad` (vr_kind none; suggested for `android.hardware.gamepad`/`LEANBACK_LAUNCHER`, analysis `gamepad`, ANALYSIS_VERSION 9): deployment.json `steam_gamepad` → launcher `GAMEPAD_LINE` (after the codec line: exports FRAMEPORT_GAMEPAD + LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD, puts `agent/bin` first on PATH) → `PODMAN_WRAPPER` (written by ensure_host_fixes; non-`run` calls go straight on; `run` imports the agent's `podman_run_args`; hands on to the next Podman after its own PATH entry with itself removed from PATH, so it chains to the codec wrapper either way round) adds the pads + `Vendor_28de_Product_<pid>.kl` (Xbox 360 layout). Verified headless with a uinput stand-in pad (Stremio's container: EventHub `classes=0x80000141`, our key layout, KeyEvent BUTTON_A dispatched); with Steam's real pad and a game: not yet. Pads made after the start aren't seen until the next one.
-
-## Multiview programs on flat framebuffers (Doom3Quest)
-
-**Multiview programs on flat framebuffers (GitHub #77, Doom3Quest, 2026-10-09, prototype):** Mesa enforces OVR_multiview's
-"program num_views == draw framebuffer views" rule (`draw_validate.c`, the draw is dropped silently); Qualcomm doesn't.
-Doom3Quest compiles every VS with `layout(num_views=2) in;` and draws its HUD/PDA into 2D-texture FBOs → black. Opt-in
-`frame.gl_multiview_fbo` (analysis `gl_multiview_libs`, ANALYSIS_VERSION 6; own-engine GLES only): `native/glmv` =
-`libfpglmv.so` (12 chars = "libGLESv3.so": libdoom3.so's one `.rodata` dlopen string is rewritten in place, its qgl*
-table comes from dlsym on that handle; also first DT_NEEDED for its direct gl*/egl* imports). Such draws use a lazily
-built single-view twin (view 0, uniforms copied per draw); eglMakeCurrent resets the per-thread cache. Host-tested only
-(rewriter on all 19 Doom3Quest shaders + glmv.c against a stand-in GL, `tests/test_gl_multiview_fbo.py`); the host's
-Mesa 23.2 llvmpipe has no OVR_multiview. Headset-verified by Xandrix1987 (2026-10-09: HUD/PDA shown, no fps drop) -> in the Doom3Quest catalog recipe.
-
-## BlazeRush
-
-**BlazeRush (GitHub #57, Klownicle's verified guide, 2026-10-10; FramePort's version headless-tested only):**
-`frame.blazerush` (1.0.349 only: exec-segment SHA + every word checked, offsets from PT_LOAD) NOPs the avatar-readiness
-wait (0x4b2dbc), RETs the avatar renderer (0x4b2adc), renames `cache/shader_cache` → `cache/br_shader_v1`. GL shim
-(now also exports glShaderSource/glLinkProgram/glProgramBinary/glDeleteProgram/glDraw*: pass-through unless a setting
-is on) `gl_int_attribs` (integer inputs fed via glVertexAttribPointer re-set with glVertexAttribIPointer per draw,
-reflection cached per EGL context + program, dropped on link/binary/delete) and `gl_highp_markers` (vertex shaders with
-every '|' marker: mediump→highp except on in/out/uniform lines); host test `tests/test_blazerush.py` with a stand-in
-GL. FOV: the game reads VrApi props 7/8 right after vrapi_Initialize (no session; the Frame has no
-XR_EPIC_view_configuration_fov) → the bridge saves the live FOV (also located before tracking, headless: 118.87×120.04
-on the dev Frame) in `files/framebridge-vrapi-fov.txt` and answers with it at the next start (log `FOV properties: …
-(saved by an earlier session)`). `device.config_sync` (catalog field `config_sync`, agent v78): user_config.xml
-r_3dwidth/height, r_width/height from the runtime eye size (FrameBridge logs `runtime recommended eye size`) × scale,
-written at finalize, set_settings and by launch.sh before Lepton starts (`_config_sync`). Headless runs at scale 1.7
-end in `zink: DEVICE LOST` right after the bridge's 30 s no-tracking deadline tears the session down (gpu fault at the
-teardown; not at scale 1.0): a headless-only artifact, the headset never hits that deadline. Launch tests count an exit/crash after
-such a line as a pass (triage.yaml `headless_end`, finding `headless-end`; GitHub #57 "Failed to launch" on install).
-
-## Session triage
-
-**Session triage (agent v70, 2026-10-09):** launch tests never reach FOCUSED, so real play sessions are triaged
-too. list_installed gives each game `last_play` {start, end, test} from `<anchor>/plays.log` (launch tests write a
-`test <unix>` line first → test sessions are only marked); `session_log` returns the newest session's launch.log
-(`<base>/session.log`, ≤4 MB: head + tail + FrameBridge/crash lines between) + that session's logcat-crash.log +
-`journalctl -k` GPU lines ("kernel: …"). The GUI's connection refresh (`app._check_sessions` → `pipeline.sessions_due`,
-background thread; sessions >7 days old are skipped) runs `pipeline.triage_session` = `validate/session.analyze`
-(triage.yaml signatures incl. `space-warp-used` (info, `question:`, never auto-applied), `gpu-hang` (`report: true`)
-+ computed `slow-frames` (pacing windows vs the nearest refresh rate) and `focus-dips` (FrameBridge always logs
-`focus: lost` / `focus: back after N ms`, session_fixes.c)) → library `last_session` / `last_session_checked` → game
-page "Last session" callout (Try this fix / Rebuild with this fix / Yes-No question / Report / Dismiss). Suggestions may
-be values (`adapter.scale=0.85`, `triage.split_suggestion`); adapter-only fixes are pushed live (`apply_suggestions_live`
-→ agent set_settings, like the Game settings dialog). CLI `frameport session <pkg> [--apply]`. PC VR (Proton) launchers
-log no session end, so they aren't triaged yet. pac_hints stays triage-only: a survey of all 68 dump APKs found unpaired
-PAC hints in 21 libraries of 18 games (OpenSSL's 38/40 in most UE4 libUE4.so and libEOSSDK.so, UE5 libUnreal.so ~400
-vs +2-3, libass, libopencv, …), most of them games that work, so default-on would rewrite many working builds.
-
-## Install links / FrameDrop button protocol
-
-**Install links / FrameDrop button protocol (2026-10-07, not yet clicked end to end from a browser):** FrameDrop
-(framedropvr.com, a closed-source Windows sideloader) defines "Install with FrameDrop" buttons:
-`https://framedropvr.com/install?manifest=<url>|url=<file>` → that page opens `framedrop://install?…` (1.6 s, else its
-home page); manifest `{"schema":"framedrop.install/v1","name","files":[{"url","sha256"}]}` (name = Steam title; .apk
-or Linux .zip). `deeplink.py` (no Flet) parses framedrop://, frameport:// and the pasted https link, enforces its
-rules (https; http only on loopback; no credentials; no LAN/loopback/link-local IPs, also after DNS and redirects; URL
-ends in a file name), caps manifests at 256 KiB, ignores non-hex sha256 (FrameDrop's own example has a placeholder),
-downloads into `<data>/downloads/<slug>-<hash>/` (OBBs → `obb/` next to the APK, `.part` removed on cancel/mismatch);
-`pipeline.add_from_link` routes APK / Linux / exe and sets `title` + `title_locked` + `link` (a bare file link keeps
-FramePort's title). GUI: `views/link_dialog.py` (always asks first), Add games → "Install from a link…", CLI
-`frameport open-link [--yes --no-install --gui]`. **A `flet build` bundle can't take a URL argument** (the Flutter
-host treats any argv as a developer page URL), so `urlhandler.py` registers a script, not FramePort.exe: Windows
-HKCU `Software\Classes\{framedrop,frameport}` → hidden PowerShell `frameport-link-handler.ps1`; WSL (source runs)
-the same keys → `wsl.exe -d <distro> -e sh frameport-link-handler.sh`; Linux `frameport-links.desktop` +
-`xdg-mime`; macOS unsupported (Apple Events, paste instead). The script drops the link into `<data>/links/*.link`
-and starts FramePort unless `<data>/gui.alive` is < 10 s old (`gui.starting` stops double starts); the GUI's
-`_watch_links` thread touches the heartbeat and opens links (newest window session). Settings → Install links: one
-switch per scheme (`links.framedrop`, `links.frameport`, default on); a scheme another program owns (FrameDrop) is
-only taken with "Use FramePort for these links" (`register([s], force=True)`); off removes only FramePort's own
-registration (`MARK` in the command). Never registered with FRAMEPORT_HOME/FRAMEPORT_NO_LINK_HANDLER (tests,
-screenshots). Same round: files dropped on the Library (`ui/dropped.py`, bundles only like the Files tab), "Add a
-Windows program (.exe)…" (`pipeline.add_windows_exe`: exe in Downloads/home/drive root copied alone into
-`<data>/windows-apps/<slug>/`), patch `device.display_mode` (Automatic / VR / Flat window → `InstallContext.display`,
-`installer.show_window`). FramePort-only manifest extension `"frameport": {"description", "icon"}` (bad values ignored; icon: same URL rules,
-≤2 MiB, Pillow-checked, ≥32 px, saved as PNG in `<data>/downloads/icons/`, shown in the question by asset URL, then
-`sources.apply_custom(pkg, "icon")` unless `.picked` exists; description fills `details.description` only when
-empty). Bare file links get a title guessed from the file name (`title_from_filename`: version/arch dropped, package
-names → last part). Windows test of 0.12.1.dev191 (2026-10-07): a button click opened the dialog; but a click right
-after closing FramePort did nothing (the closed window's heartbeat was < 10 s old) → the handler scripts now wait
-up to 4 s for the link file to be taken before trusting the heartbeat, the window's CLOSE event / atexit delete
-`gui.alive`, and the Windows command runs under `conhost.exe --headless` (plain `-WindowStyle Hidden` flashed a
-console). Screens: `scripts/ui_smoke.py --links --fake-frame --game <pkg>` (tall pages: `--viewport
-1280x7000`; Flutter's popup menu ignores Escape).
-Demo link: the homepage's example button = `deeplink.DEMO_MANIFEST` (https://frameport.app/demo/cool-game.json, published
-from site/public/demo/); every form (https button page, frameport://, framedrop://, pasted) → `InstallRequest.demo`,
-no network (fetch_manifest returns `demo_manifest()`, download refuses), `link_dialog.show_demo` (Install =
-`easter.demo_install`: Cool Game's cover out of the portal; eggs off → "Nice, it works!"), CLI just says so.
-Link updates (2026-10-17): manifest `version` (top level, or `frameport.version`, which wins; ≤64 chars) is stored in
-the entry's `link` record (+ `direct`); `pipeline.check_link_updates` (GUI start via `app._check_link_updates`, every
-6 h: setting `links.last_update_check`, off with `links.check_updates`) re-fetches web manifests that named a version
-(`deeplink.can_check_updates`: not bare file links, local manifests or the demo) and sets/clears `link_update`
-{version, checked}; versions compare with `deeplink.compare_versions` (numbers, then release > suffix). UI: Library
-`link_bar` + game page callout → `link_dialog.update_from_link` (fetch again, one confirmation, `download_and_install`
-per game; add_from_link clears the offer and keeps a name the user gave). CLI `frameport link-updates [--install]`.
-
-
-## XR_FB_color_space (#336)
-
-OutRun Quest VR (`org.outrun.quest.vr`, its own Khronos loader, no OVRPlugin) logs "Rec.709 color space unavailable" right after xrCreateInstance and quits ~20 s later without a session: the Frame's runtime (and OVRPort's dispatcher) list no XR_FB_color_space. Adapter setting `fb_color_space` (off by default, `native/adapter/color_space.c`) offers the extension when the runtime lacks it, strips it from the runtime's create info, fills XrSystemColorSpacePropertiesFB with Rec.709 and answers xrEnumerateColorSpacesFB / xrSetColorSpaceFB (no conversion: the runtime has no API for it). The functions are reachable through FrameBridge's xrGetInstanceProcAddr and `framebridge_extension_proc` (xrshim); OVRPort's fixed dispatcher table can't forward them, hence off by default. Not yet tried on the device (the build was not downloaded: it ships Sega's game data). Log: `color_space: emulating XR_FB_color_space`.
-
-## Per-game headset identity (#373, 2026-10-17)
-
-Owner decision: all Quest / OVRPort conversions default to Quest 3; Customize → Headset model offers Quest 3,
-Quest 3S, Quest Pro and Quest 2. Rebuild and reinstall after changing it. Rift, Linux and 2D apps are excluded.
-Target: Asgard's Wrath 2's **Enhanced Rendering Features** and **90 Hz Mode**. This implementation has static and
-host tests; unlocking those options and actual 90 Hz presentation still need an owner headset check.
-
-Device evidence supplied by the owner (headless Transformers, OVRPort runtime 3.4.3-aa54c3f): Lepton's image already
-sets `ro.product.model=Lepton`, manufacturer `Valve`, device `lepton_arm64_only`. A `LEPTON_GFXRECON_*` boot-property
-line cannot replace existing write-once `ro.*` values. Removed the WIP headset property injection. Android
-`Build.MODEL` stays Lepton. A general app-start dex/reflection override is follow-up: the existing `Dex.return_early`
-tooling replaces method bodies, but does not supply a universal early startup hook that safely sets Build fields.
-
-OVRPlugin logged `venderId 10291, systemName Oculus Quest2` even with FrameBridge rewriting the name. The APK's
-`lib/arm64-v8a/libopenxr_loader.so` dispatcher sits above FrameBridge: `xrGetSystemProperties` at VA `0x18554`
-overwrites the name (`0x18620`–`0x18638`, string at file/VA `0x6034`) and returns its own
-`XR_META_headset_id` (`0x186e8` loads address `0x29338`, `0x18778`–`0x1877c` copies 16 bytes;
-UUID file offset `0x21338`). Vendor id remains 10291. A lower-layer-only override cannot fix those answers.
-
-Disassembly of the supplied Unreal `libOVRPlugin.so`:
-
-- `ovrp_GetSystemHeadsetType` at `0x251730` calls `ovrp_GetSystemHeadsetType2` at `0x247bb0`, which calls the
-  `0x2590b0` thunk → `0x292f80`.
-- System properties' name is copied to the global std::string `0x62d328` at `0x261b30`–`0x261b3c`.
-  `0x261b9c`–`0x261bb4` stores the headset-id-present flag (`0x62d2c0`) and UUID (`0x62d2c1`).
-- `0x292f80` checks that flag. When present it compares the UUID, in inline 64-bit constants, returning
-  Quest 1 = 8 (`0x293134`), Quest 2 = 9 (`0x2931ac`), Pro = 10 (`0x2931b8`),
-  Quest 3 = 11 (`0x2931c4`), Quest 3S = 12 (`0x293060`–`0x29309c`). Unknown UUID → 9.
-- Only without the UUID does `0x2930a8` fall back to systemName (older Quest/Pro names, default 9).
-  `0x292d60` is a separate product-name normalizer: it recognizes newer Meta names but returns the generic
-  `Meta Quest` for known Quest products. It is not the headset-type selector. Android Build is not consulted
-  in the traced headset-type path.
-- Cross-check: the available armv7 OVRPlugin's Thumb entry `0x120c5c` → thunk `0x12bc38` → `0x148ac8`
-  likewise tests UUID first (16-byte comparisons), then name at `0x148b1a`. This older build recognizes through
-  Quest 3 (return 11 at `0x148b14`), not Quest 3S. It is consistent with the Unreal mapping for Quest 2/Pro/3.
-
-Raw XrUuidEXT byte order (hyphens just group sequential bytes; do not swap GUID fields):
-
-| Model | UUID | Unreal headset type |
-| --- | --- | --- |
-| Quest 2 | `3064f239-15ed-4722-a659-5ea1ecd899c2` | 9 |
-| Quest Pro | `b58443c9-df86-40cd-8918-2a278e18ab71` | 10 |
-| Quest 3 | `082746ba-a071-4cf7-8f87-bade5cce43ce` | 11 |
-| Quest 3S | `9510492b-0d42-4872-bcf4-fb1a8def6f0e` | 12 |
-
-`device.headset_model` now applies at APK stage after FrameBridge. It verifies original name, UUID and the
-instructions loading both in the known dispatcher before writing either. Unknown builds fail with an explicit
-unsupported-dispatcher message and a Quest 2 escape hatch. Same-size data edits only: NUL-padded 14-byte name and
-16-byte UUID. Quest Pro uses the short dispatcher label `Quest Pro` because `Meta Quest Pro` plus NUL needs 15 bytes;
-its UUID selects type 10. Quest 2 changes no dispatcher bytes and adds no embedded headset setting (native default preserves the old name).
-FrameBridge retains the full standard name override
-for apps calling it directly; setting 2 preserves its original result. No UUID extension is invented in FrameBridge.
-
-Owner verification: rebuild/reinstall Asgard's Wrath 2 with Quest 3 selected. Capture the OVRPlugin line containing
-`venderId 10291, systemName Meta Quest 3`, and its `HeadsetId:` line (16 hex bytes matching Quest 3 above).
-Capture any game/OVRPlugin headset-type line: expect `Meta_Quest_3` / `Quest_3` / numeric 11 if the build logs it;
-absence of such a line is not proof of failure. In the headset check both named graphics options become available,
-can be enabled and persist after restart. Check actual runtime refresh/pacing separately when selecting 90 Hz;
-identity alone does not implement refresh-rate support. Rebuild with Quest 2 for the control: original `Oculus Quest2`,
-original Quest 2 UUID, type 9 if logged, and previous option visibility. Also smoke-test a Unity OVRPlugin game
-with the default Quest 3 choice for regressions. No device access was used during implementation.

docs/FAQ.md

@@ -26,25 +26,6 @@ Games/                                  ← scan this folder (Add games → Scan
 Not sure of the package name? It's in the OBB file names (`main.<version>.<package name>.obb`), and the game's page
 shows it under **Details**.
 
-## I moved my games to another folder or drive. How do I update the library?
-
-Scan the new folder (**Add games → Scan a folder…**, or **Settings → Library folders → Add folder…**). A game whose
-files are gone from their old place and that FramePort finds again in the new folder keeps its library entry: only
-where its files are changes. Its name, tags, artwork, your own recipe and what's installed on the Frame stay; you don't
-have to remove it from the library first. **Rescan folders** in the Library does the same for every library folder.
-
-- **Removing a folder:** **Settings → Library folders** lists every folder FramePort scans, with how many library games
-  come from it and whether it's there now (a folder on an unplugged drive shows as not found). The bin icon stops
-  scanning a folder; its games stay in the library. `frameport folders [--add DIR] [--remove DIR]` does the same on the
-  command line, `frameport rescan` rescans.
-- **Another version in the new folder** (a different APK or game build): **Scan a folder…** on that folder takes it, as
-  **Update with a newer APK…** would (name, tags, art and your own recipe stay). **Rescan folders** leaves such games
-  alone and says so; use the game's **Update with a newer APK…** / **…version…** to switch.
-- **Two copies** (the old folder is still there): the library keeps the copy it has. To use the other one, delete or
-  rename the old copy and rescan.
-- PC VR games are recognised by their folder name, or a renamed folder by its program file. Linux apps aren't part of
-  folder scans: add the moved app again with **Add a Linux app…** (it keeps its name, art and switches).
-
 ## Can I scan SideQuest backups or AXRB downloads directly?
 
 Yes. Scan the folder as it is; FramePort finds the APK and its OBB files in both layouts:
@@ -86,7 +67,7 @@ AXRB/                                   ← AXRB's download folder (Downloads/AX
 
 Every game has three places; the answers below refer to them.
 
-- **Game settings:** right-click the game in the **Library** → **Game settings…**. Render resolution (supersampling), refresh rate,
+- **Game settings:** right-click the game in the **Library** → **Game settings…**. Sharpness, refresh rate,
   controllers, menus and more, in plain words. Changes apply the next time the game starts.
 - **Patches:** click the game in the **Library** to open its page, then **Customize** (in the **Patches** section).
   Turn a patch on or off, then click **Update on Frame** at the top of the page.
@@ -94,10 +75,7 @@ Every game has three places; the answers below refer to them.
   It has **Reset to suggested recipe…** and **Report a problem…**, among others.
 
 The sidebar has two tabs for troubleshooting: **Monitor** (the running game's frame rate, CPU and graphics) and
-**Files** (each installed game's storage on the Frame, under **Game storage**). Quest games expose their Android
-storage; PC VR and Linux games expose their install folders, including installations on another drive.
-SD cards, USB drives and other Steam library drives appear under **Drives**, with free space when available.
-Read-only drives can be browsed and downloaded from, but cannot be changed.
+**Files** (each installed game's storage on the Frame, under **Game storage**).
 
 ## A game doesn't work right. Where do I start?
 
@@ -154,7 +132,7 @@ need **Update on Frame**).
 | One eye shimmers while menus look steady | Game page → **Customize** → **Eye-tracked foveation (Valve)**: **Fixed**, else **Off** |
 | Menus or screens upside down | **Game settings…** → **Fix upside-down menus** |
 | Curved menus or video screens missing | **Game settings…** → **Show curved menus and screens** |
-| Blurry | **Game settings…** → raise **Render resolution (supersampling)** (costs frame rate) |
+| Blurry | **Game settings…** → raise **Sharpness** (costs frame rate) |
 
 The [patch reference](PATCHES.md) lists every patch with what it does. If nothing helps, report it with a short
 description of what you see.
@@ -164,7 +142,7 @@ description of what you see.
 How to tell: open **Monitor** in the sidebar while you play. Smooth play needs the game's frame rate at the refresh
 rate (for example 72 or 90 fps).
 
-- **Below the refresh rate:** right-click the game → **Game settings…** → lower **Render resolution (supersampling)** (for example to 0.8×) or
+- **Below the refresh rate:** right-click the game → **Game settings…** → lower **Sharpness** (for example to 0.8×) or
   pick a lower **Refresh rate**. After a session, the game's page may suggest a value.
 - **At the refresh rate but it still judders:** report it; that points to timing, not speed.
 
@@ -187,7 +165,7 @@ Right-click the game → **Game settings…**:
 How to tell: if it only happens on battery and never while plugged in, it's power, not FramePort. Heavy games can
 draw more than the battery delivers, especially at lower charge, and the Frame then turns off without an error.
 
-- Play plugged in, or right-click the game → **Game settings…** → lower **Render resolution (supersampling)** to reduce the load.
+- Play plugged in, or right-click the game → **Game settings…** → lower **Sharpness** to reduce the load.
 - It also turns off while plugged in: report it. The diagnostics include the log of the boot that ended.
 
 ## My progress isn't saved
@@ -200,19 +178,6 @@ draw more than the battery delivers, especially at lower charge, and the Frame t
 
 Saves stay on the Frame when you update or reinstall a game.
 
-## Can I back up a game's saves?
-
-Yes. Steam doesn't sync Quest games' saves, so FramePort copies them to your PC: the game's menu (**…** on its page) →
-**Saves** → **Back up saves**, or **Back up all saves** on the Steam Frame page (Installed games). Close the game
-first. A backup holds the game's own storage (`/data/data/<package>` and `/sdcard/Android/data/<package>`), without
-caches, shader caches and large downloaded content (videos, OBBs, files over 64 MB); the job says when something was
-left out. FramePort keeps the 10 newest backups per game (Settings → Data). They're in FramePort's data folder under
-`save-backups/<package>/` (**Open backups folder** in the game's menu).
-
-**Restore saves…** puts one back: it replaces the game's saves on the Frame. The Frame keeps a copy of the saves it
-had, so **Undo last restore** in the same window takes you back. When you uninstall a game and tick *Also delete its
-saves*, FramePort backs them up first. Command line: `frameport saves backup|list|restore|undo <game>`.
-
 ## A game with mods crashes
 
 How to tell: play once without mods and custom content. If it then works, a mod is the cause; the diagnostics zip

docs/FRAME_RUNTIME.md

@@ -43,12 +43,6 @@
   work on Android 11: `policy_control` is gone, `cmd statusbar send-disable-flag home recents` has no `back` and
   moves the back button onto the app's controls, the `sysui_nav_bar` layout and disabling SystemUI had no effect.
 
-- **Per-game language** (verified 2026-10-17): `device.language` uses the same unescaped
-  `LEPTON_GFXRECON_*` boot-property path: `LEPTON_GFXRECON_FP_LOCALE="0\npersist.sys.locale=<tag>"`.
-  Android reports the selected locale to the game at startup; `ro.product.locale` stays `en-US`.
-  Choose Game language under Customize and apply with Update on Frame. English (US) removes the override.
-  Games need to include and use the requested language; text and voice still need headset verification.
-
 ## Where FramePort keeps games (internal storage, microSD)
 - Every game has an **anchor** on internal storage: `~/Applications/quest-frame/<pkg>/` with `launch.sh`,
   `deployment.json`, `artwork/` and `plays.log`. Steam's shortcut points at the anchor's `launch.sh`, so it never
@@ -66,32 +60,6 @@
   `launch.sh` at the new folder and only then deletes the old copy; on the same filesystem it renames instead.
   Moving a game whose Lepton data holds absolute paths, or a PC VR prefix, is not yet verified on the device.
 
-## Save backups (Quest games, agent v95, discussion #352)
-- A Lepton game's saves are two folders of `<base>/lepton-data`: `internal/<pkg>` (= `/data/data/<pkg>`:
-  `shared_prefs/`, `files/`, `databases/`; Unreal's `files/UE4Game|UnrealGame/.../Saved` often lives here) and
-  `external/Android/data/<pkg>` (= `/sdcard/Android/data/<pkg>`: Unity's `files/`, Unreal's external `Saved`). On the
-  dev Frame (2026-10-16) every file in them belongs to `steamos` (Lepton's `keep-id:uid=0`: the container's root and
-  app = steamos), mostly mode 600/660 in 700/771/775/2771 folders; Lepton's links (`Android/obb/<pkg>`, `Movies`,
-  `Download`, `Documents`) sit outside these two folders.
-- Agent `_backup_saves '<json>'` streams a tar.gz of both (members `internal/…`, `external/…`, PAX, numeric owners and
-  modes; last member `frameport-saves.json` = manifest with size + sha256 per file and what was left out) on the SSH
-  exec channel's stdout, the result JSON on stderr. Left out: folders named cache/code_cache/no_backup/il2cpp/
-  UnityShaderCache/(Vulkan)ProgramBinaryCache/GPUCache/… at any depth, Unreal `Saved/Logs|Crashes`, FrameBridge's
-  `fb_snap_*`/`framebridge*` files, `.obb/.apk/.foz/.mp4/.mkv/.webm/.mov`, symlinks and special files, and files over
-  64 MiB (big downloaded content; e.g. BattleTalent's `files/Video`). More than 4 GiB of saves is refused.
-- `_restore_saves '<json>'` reads the archive from stdin and treats it as untrusted: only regular files and folders
-  under `internal/`/`external/` (no `..`, absolute paths, links, devices, duplicates), ≤1 GiB per file / 8 GiB in all,
-  each file's sha256 must match the manifest, the manifest's package must be the game. Everything is staged in
-  `<base>/.saves-restore-*` first, a path that would pass through a link on the Frame is refused, then the current
-  saves are written to `<base>/saves-before-restore.tar.gz` (one copy; `rollback: true` restores it and keeps the
-  replaced saves as the new copy) and each file is renamed into place. Existing files keep their owner and mode, new
-  ones get their folder's owner and the backup's mode (at least u+rw); save files the backup doesn't have are removed
-  (left-out files stay). A failure while swapping puts the rollback copy back.
-- Both run their file work in `podman unshare` (the agent re-runs itself as `_saves_ns <op>` with stdio inherited) so
-  files owned by mapped ids are readable and keep their ids, take the game's launch lock (`<base>/.launch.lock`, a
-  Play meanwhile is ignored as a double launch) and refuse while its container runs. `saves_info` sizes a backup and
-  reports the rollback copy, `saves_rollback_delete` removes it.
-
 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
   KHR_vulkan_enable(2), KHR_opengl_es_enable, KHR_composition_layer_depth, FB_display_refresh_rate, EXT_hand_tracking
@@ -112,8 +80,6 @@
 - Swapchain formats: GLES `GL_SRGB8_ALPHA8` (35907) / `GL_SRGB8` (35905) only, samples = 1. Vulkan: 43 (R8G8B8A8_SRGB)
   and 50, not 37/44 (UNORM).
 - Environment blend: ALPHA_BLEND available (grayscale passthrough cameras).
-- XR_FB_composition_layer_alpha_blend and XR_KHR_composition_layer_color_scale_bias are not the runtime's (OVRPort's
-  dispatcher lists alpha_blend): their structs are ignored, so FrameBridge emulates inverse alpha (`alpha_blend_emul`).
 - Reference spaces: STAGE bounds are reported as 1×1 m.
 - Display 72 Hz by default in tests. Head pose is only tracked while the headset is worn; otherwise flags 0x3 and
   the session stays below FOCUSED.
@@ -396,8 +362,7 @@ over Quest games.
 
 ## Shared foveation controls (tested 2026-10-12)
 
-Under a Quest game's **Game settings → Picture**, choose **Foveated rendering → Eye-tracked**, then **Save**.
-Changes apply at the next game start.
+Under a Quest game's Advanced patches, choose **Foveated rendering → Eye-tracked**, then **Update on Frame**.
 The full-resolution area selector defaults to **Default (30% radius)**: no radius override, preserving the
 runtime profile used in the headset experiments. Larger radii retain more detail and save less shading work.
 Custom radii set `FOVE_INNER`; `FOVE_OUTER` is twice that value, matching the runtime's profile proportions.
@@ -405,7 +370,7 @@ The inspected runtime's built-in inner/outer pairs are 0.30/0.60, 0.25/0.50 and
 The shared-texture injection path selects profile 1: 0.30 inner radius and 0.60 outer radius.
 
 `device.foveation` enables Valve's shared Vulkan injection and suppresses competing native foveation through
-`foveation_fix=1`. Game settings stores mode, radius and test selection as a per-game library preference, outside shared recipes. This remains
+`foveation_fix=1`. Recipes and shared catalog entries preserve mode, radius and test selection. This remains
 experimental: complete images were confirmed in RE4, Batman, Deadpool, The Climb 2 and Asgard's Wrath 2,
 not all Quest games or renderers. RE4 and Batman checks include title/calibration scenes; these are not
 equivalent to extended gameplay coverage. Asgard gameplay was visually confirmed, without an on/off benchmark.
@@ -421,14 +386,14 @@ installation. The runtime correction additionally checks the exact Valve library
 instructions before touching executable memory; unsupported libraries request injection be disabled and log
 the reason. No system library is changed. A SteamOS update requires revalidation of this compatibility path.
 Both-eye gaze following was confirmed in Climb's darkening diagnostic, but long-session stability remains
-experimental. Off disables injection through launcher exports; the private APK compatibility support remains installed.
+experimental. Off rebuilds from the source APK and removes this private support, including its visibility fix.
 
-**Darken coarse fragments (test)** enables the dormant Vulkan shader diagnostic. It dims RGB where the
+**Darken lower-resolution regions (test)** adds an optional Vulkan shader diagnostic. It dims RGB where the
 actual `FragSizeEXT` footprint exceeds one pixel; alpha is unchanged. Deadpool's shaded regions were confirmed
 to follow gaze in the headset. Unsupported shader output interfaces are skipped, and multiple passes may
 compound darkening, so this is a diagnostic rather than a precise composited mask. Do not benchmark with it on.
-Uncheck it and save Game settings to remove the launcher opt-in. The library stays installed and dormant;
-in Climb the same library also carries the compatibility correction.
+Uncheck it and update from the original source APK to remove the diagnostic library, except in Climb where
+the same library also carries the compatibility correction. Darkening stays dormant without its launcher opt-in.
 
 High-resolution Deadpool samples crossed from about 45 to 90 FPS with injection enabled, but temperatures and
 power rose as it rendered twice as many frames. Foveation does not guarantee lower temperature at uncapped FPS.
@@ -456,50 +421,3 @@ sighting, command lines checked once per process, render fds cached (rescanned e
 game processes without one), temperatures every 2 s, the CPU-cluster power rails every 5 s and the battery gauge every
 2-10 s, the stream measured ~10-13 ms CPU per 1 s tick on the device (idle clocks; idle or with 4XVR running) = about
 1 % of one core, ~0.15 % of the whole CPU. The I2C sensors (power monitors, battery gauge) are the slowest reads.
-
-### Foveation user preferences (discussion #365)
-
-Game settings → Picture provides Default / Eye-tracked / Fixed / Off, radius, and an advanced diagnostic switch.
-`set_settings` (agent 98) atomically rewrites just the managed launcher exports and records them in deployment.json;
-no APK rebuild, reinstall or live device intervention is needed. Changes apply at the next start. Default restores
-recipe/catalog launcher defaults; explicit preferences win. One-time library migration extracts old recipe choices
-and leaves internal APK compatibility support. Catalog defaults (including Climb 2 and Batman) still apply to new
-entries. Shared working configs omit `device.foveation` entirely.
-
-APK-side: adapter builds automatically prepare Batman's hash-verified allocation fix and Climb 2's
-renderer-guarded private bridge for verified builds, independently of the runtime choice. Unknown versions skip
-automatic compatibility edits; explicit catalog requests still fail validation rather than guessing offsets. FrameBridge
-builds include the dormant diagnostic layer (activated only by `FRAMEPORT_FOVEATION_TEST=1`), so future test toggles
-need only a launcher update. Existing builds need one normal update to acquire that support. Render resolution
-(supersampling) changes the game's render resolution: higher is sharper but slower. Climb 2 foveation still requires
-1.0 scale.
-
-## Steam library scheduling
-
-Agent v99 holds automatic shortcut restarts while the local app's
-`~/.local/share/frameport-app/gui.alive` heartbeat is under ten seconds old, as well as while a game or Desktop Mode
-is open. Closed/crashed GUIs expire; the existing twelve-hour hold limit still applies.
-
-`library_mode` accepts `now` (default), `later`, and `off`; FramePort stores its preference as
-`install.steam_library`. Later writes shortcuts and journals packages/removals in
-`~/.local/share/frameport/library-pending.json`. Steam rewrites shortcuts.vdf on exit, so a user drop-in
-`~/.config/systemd/user/steam.service.d/frameport-library.conf` reapplies the journal in ExecStartPre, after the
-previous session has exited. ExecStartPost verifies the entries and uses the existing live devkit fallback if Steam
-removed them. The journal is cleared only after success, and survives agent/app exit and reboot. The hooks share the
-shortcut worker lock; an active worker performs its own write/verification instead. Both hook lines start with
-`-` and run under `/usr/bin/timeout -k 5 20` (present on SteamOS; `-` ignores exit codes, including 127 for a missing
-interpreter or agent, but not a hook that hangs until the unit's 90 s start timeout); ExecStartPre also has its own
-SIGALRM deadline. ExecStartPost only starts the verification as the transient unit `frameport-library-verify`
-(`--no-block`, RuntimeMaxSec 300), so Steam's start never waits for its Steam/devkit waits. The pre hook leaves
-shortcuts.vdf alone when nothing is pending. The drop-in is removed (and the user manager reloaded) as soon as the
-mode isn't `later` and nothing is pending, and by purge; an otherwise empty `steam.service.d` goes with it.
-SteamOS 0.3.0 facts (checked 2026-10-16): Steam is the static user unit `/usr/lib/systemd/user/steam.service`
-(Type=simple, Restart=always, TimeoutStartSec 90 s, its own `-` ExecStartPre lines; `extra_args.conf` drop-ins are
-Valve's documented way to extend it), systemd 257; no user drop-ins exist by default.
-This automatic application targets SteamOS's `steam.service`; if Steam is started outside that service, use
-FramePort's Restart Steam now action to apply the journal safely.
-
-Off skips new shortcuts (existing entries remain). Play in Off, and Play for a pending Later entry, starts launch.sh
-in a detached user systemd unit, just as launch tests do, without adding a devkit entry. Steam/SteamVR must already
-be running. This loses Steam's per-game overlay/controller setup and Exit game integration; use FramePort Monitor
-to stop the game. This direct path has unit coverage; headset input/visual behaviour needs device validation.

docs/GAMES.md

@@ -13,14 +13,11 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Arkio | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
 | Assassin's Creed Nexus | Quest | ✅ Works |  |
-| Attack on Titan VR: Unbreakable | Quest | ✅ Works |  |
 | Audica | Quest | ✅ Works |  |
-| AugmentedEmpire | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
 | BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
 | Batman: Arkham Shadow | Quest | ✅ Works |  |
 | BattleGlide | Quest | ✅ Works |  |
-| Battlemarked | Quest | ✅ Works |  |
 | BattleSisters | Quest | ✅ Works |  |
 | Beat Saber | Quest | ✅ Works |  |
 | Beat Saber | Quest | ✅ Works |  |
@@ -30,20 +27,16 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | BlazeRush | Quest | ✅ Works |  |
 | BodyCombat | Quest | ✅ Works |  |
 | BONELAB | Quest | ✅ Works |  |
-| Breathedge VR | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Caves | Quest | ✅ Works |  |
-| Cities: VR | Quest | ✅ Works |  |
+| Clockwork | Quest | ✅ Works |  |
 | COMPOUND | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Cosmodread | Quest | ✅ Works |  |
-| CrazyTaxiVR | Quest | ✅ Works |  |
 | Creed | Quest | ✅ Works |  |
-| Crisis Zone VR | Quest | ✅ Works |  |
 | cubism | Quest | ✅ Works |  |
 | Dance Central | Quest | ✅ Works |  |
 | Deep Cuts | Quest | ✅ Works |  |
-| Demeo | Quest | ✅ Works |  |
 | Demeter | Quest | ✅ Works |  |
 | Dinosaur Island | Quest | ✅ Works |  |
 | Doom3Quest | Quest | ✅ Works |  |
@@ -52,14 +45,11 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Drunkn Bar Fight 2 - Early Access | Quest | ✅ Works |  |
 | Eleven Table Tennis | Quest | ✅ Works |  |
 | Eleven: Table Tennis VR | PC VR | ✅ Works |  |
-| EndoparasiticVR | Quest | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
-| Eye of the Temple | Quest | ✅ Works |  |
 | FrenzyVR | Quest | ✅ Works |  |
 | Fruit Ninja | Quest | ✅ Works |  |
 | Fruit Salon | Quest | ✅ Works |  |
 | Genotype | Quest | ✅ Works |  |
-| Ghost Town | Quest | ✅ Works |  |
 | Ghostbusters: Rise of the Ghost Lord | Quest | ✅ Works |  |
 | GORN2 | Quest | ✅ Works |  |
 | Gravity Lab | Quest | ✅ Works |  |
@@ -67,39 +57,29 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | H.U.N.T | Quest | ✅ Works |  |
 | I Am Cat | Quest | ✅ Works |  |
 | I Am Monkey | Quest | ✅ Works |  |
-| I Expect You To Die 2 | Quest | ✅ Works |  |
 | IEYTD3 | Quest | ✅ Works |  |
 | In Death: Unchained | Quest | ✅ Works |  |
 | Into The Radius 2 | Quest | ✅ Works |  |
 | Job Simulator | Quest | ✅ Works |  |
-| Journey of the Gods | Quest | ✅ Works |  |
 | Jurassic World Aftermath Collection | Quest | ✅ Works |  |
 | Keep Talking and Nobody Explodes | Quest | ✅ Works |  |
 | Kill It With Fire VR | Quest | ✅ Works |  |
 | Ladder | Quest | ✅ Works |  |
 | Lambda1VR | Quest | ✅ Works |  |
 | LEGO® Bricktales | Quest | ✅ Works |  |
-| Lost Recipes | Quest | ✅ Works |  |
 | Lucky's Tale | Quest | ✅ Works |  |
-| Maestro | Quest | ✅ Works |  |
 | Marvel's Deadpool VR | Quest | ✅ Works |  |
 | Marvel's Iron Man VR | Quest | ✅ Works |  |
 | Max Mustard | Quest | ✅ Works |  |
 | Medieval Dynasty New Settlement | Quest | ✅ Works |  |
 | Metro Awakening | Quest | ✅ Works |  |
-| Mini Motor Racing X | Quest | ✅ Works |  |
 | Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
-| Moss | Quest | ✅ Works |  |
 | Moss: Book II | Quest | ✅ Works |  |
 | Munkr Funkr (The Legacy Days) | Quest | ✅ Works |  |
 | Nano | Quest | ✅ Works |  |
-| Neko Atsume Purrfect | Quest | ✅ Works |  |
 | NEX Player | Quest | ✅ Works |  |
 | NFL PRO ERA II | Quest | ✅ Works |  |
 | NOPE CHALLENGE | Quest | ✅ Works |  |
-| Ocean Rift | Quest | ✅ Works |  |
-| Operation Wolf Returns: First Mission VR | Quest | ✅ Works |  |
-| OrbusVR | Quest | ✅ Works |  |
 | palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
 | Pistol Whip | Quest | ✅ Works |  |
@@ -117,12 +97,9 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Riven | Quest | ✅ Works |  |
 | Robo Recall | Quest | ✅ Works |  |
 | RUINSMAGUS | Quest | ✅ Works |  |
-| Sclerosis | Quest | ✅ Works |  |
-| Shadow Point | Quest | ✅ Works |  |
 | Shoot The Zombirds VR | Quest | ✅ Works |  |
 | Shores of Loci | Quest | ✅ Works |  |
 | SilentSlayer | Quest | ✅ Works |  |
-| Smash Drums | Quest | ✅ Works |  |
 | Sniper Elite VR | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
@@ -135,20 +112,15 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | SUPERHOT VR | Quest | ✅ Works |  |
 | SynthRiders | Quest | ✅ Works |  |
 | Taskmaster | Quest | ✅ Works |  |
-| Tea For God | Quest | ✅ Works |  |
 | TetrisEffect | Quest | ✅ Works |  |
 | The Boys VR | Quest | ✅ Works |  |
-| The Climb | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
-| The Last Clockwinder | Quest | ✅ Works |  |
 | The Room VR | Quest | ✅ Works |  |
 | The Tale of Onogoro | Quest | ✅ Works |  |
-| The Walking Dead: Saints & Sinners | Quest | ✅ Works |  |
 | Time Crisis II VR (Test) | Quest | ✅ Works |  |
 | Time Crisis VR (Experimental) | Quest | ✅ Works |  |
 | Totally Baseball | Quest | ✅ Works |  |
 | Toy Master | Quest | ✅ Works |  |
-| ToyTrains | Quest | ✅ Works |  |
 | TRIANGLE STRATEGY | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
 | Vacation Simulator | Quest | ✅ Works |  |
@@ -156,8 +128,6 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Vader Immortal: Episode II | Quest | ✅ Works |  |
 | Vader Immortal: Episode III | Quest | ✅ Works |  |
 | Vampire Survivors | Quest | ✅ Works |  |
-| Vendetta Forever | Quest | ✅ Works |  |
-| Vermillion | Quest | ✅ Works |  |
 | VR HOT Quest | Quest | ✅ Works |  |
 | VR4 | Quest | ✅ Works |  |
 | Walkabout Mini Golf | Quest | ✅ Works |  |
@@ -168,39 +138,29 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | AFFECTED: The Manor | Quest | ⚠️ Works with issues | Gear VR game (32-bit only), runs through FramePort's 32-bit bridge (experimental). |
 | 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). |
-| BattleTalent | Quest | ⚠️ Works with issues | Plays normally. |
 | 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. |
-| Exploding Kittens VR | Quest | ⚠️ Works with issues | Requires online for most modes. |
 | ExploreVR | Quest | ⚠️ Works with issues | The 3D world warps and shifts with head movement (wrong perspective). |
-| FGO VR | Quest | ⚠️ Works with issues | Audio stuttering and popping sounds |
 | Fisherman | Quest | ⚠️ Works with issues | Loading screens have corruption, but everything works otherwise. |
-| Homeworld: Vast Reaches | Quest | ⚠️ Works with issues | The game starts but after selecting to start a new game it seems to crash. |
-| Lawn Mowing Simulator VR | Quest | ⚠️ Works with issues | Left eye textures flicker only when mowing in specific areas. |
+| 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. |
-| Puzzling Places | Quest | ⚠️ Works with issues | Works fine, but pointers dont show well on main menu, easy to work around. |
-| Quantum Void | Quest | ⚠️ Works with issues | no hands |
-| Ragnarock | Quest | ⚠️ Works with issues |  |
-| Real VR Fishing | Quest | ⚠️ Works with issues | Seems to be almost 100% functional with meta permissions enabled. |
 | Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
-| SmartTube | Quest | ⚠️ Works with issues | Android's home screen shows for a few seconds while the app starts (normal for flat Android apps; longest on the first start after an install). |
 | Spunky Dungeon | Quest | ⚠️ Works with issues | Gear VR / Oculus Go game (32-bit only), runs through FramePort's 32-bit bridge (experimental). |
 | Swarm 2 | Quest | ⚠️ Works with issues | MSAA creates visible seams around edge geometry and also the skybox edge |
-| The 7th Guest VR | Quest | ⚠️ Works with issues | Runs and is playable. |
 | The Light Brigade | Quest | ⚠️ Works with issues | Judder in weapons |
 | The Thrill Of The Fight | Quest | ⚠️ Works with issues | Right eye doesn't draw the opponent or the referee. |
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
-| Vampire: The Masquerade - Justice | Quest | ⚠️ Works with issues | Game runs fine and playable, on loading there's a random sphere in the middle of the sceen. |
+| 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… |
-| Breachers | Quest | ❌ Doesn't run | Online-only multiplayer that needs Meta's online services, which aren't available on the Frame. |
-| Deadly Delivery | Quest | ❌ Doesn't run | Quits after Meta's entitlement check fails: it needs Meta's online services. |
 | 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. |
+| Journey of the Gods | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |
 | Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
+| Shadow Point | Quest | ❌ Doesn't run | 32-bit only; the Frame has no AArch32. |

docs/HEURISTICS_EVAL.md

@@ -1,83 +0,0 @@
-# Evaluating patch heuristics
-
-`scripts/eval_heuristics.py` compares `engine.suggest(analysis, use_catalog=False)` with the bundled
-`catalog/games/*.yaml` entries. It does not merge personal or remote catalog recipes into the benchmark.
-It supports the original dumps command, or a precomputed `scripts/heuristics_snapshot.py` snapshot:
-
-```sh
-.venv/bin/python scripts/eval_heuristics.py '<dumps folder>' --verbose
-.venv/bin/python scripts/eval_heuristics.py --snapshot analyses.json --split all --json baseline.json
-.venv/bin/python scripts/eval_heuristics.py --snapshot analyses.json --fit-report --out fit-report.md
-```
-
-Use a scratch `FRAMEPORT_HOME`, `FRAMEPORT_NO_CATALOG_UPDATE=1`, and an empty `FRAMEPORT_WINDOWS_DATA` for offline
-measurement. Snapshot mode reads no APKs or game data. Each snapshot read copies the source to a temporary file,
-then parses the copy, retrying incomplete JSON. To compare multiple splits against an actively growing snapshot,
-freeze one valid copy first and use that file for every run.
-
-The default split is `dev`. `split_packages({package: analysis_engine})` sorts packages by SHA-256 within Unity,
-Unreal, and Other strata, then holds out the nearest 20% (half rounded up). Pass only packages with both an analysis
-and a catalog entry. The same input set always yields the same split regardless of iteration order; adding packages
-can move the cutoff. Very small strata can have no holdout. Unsupported entries participate in splitting.
-
-## What is scored
-
-Ground truth contains catalog choices and patch registry defaults, with no inherited heuristic adapter settings.
-Default expectations are determined per analysis, using each default patch's own detection in the same way as the
-engine's initial heuristic pass. Thus a conditional default that is not detected (e.g. LTW on a game without LTW)
-is not expected. Explicit catalog `overport_remove` and `frame_remove` entries remove expected defaults. An absent
-expected default is represented as `remove:<patch id>`; enabled defaults do not inflate patch scores.
-
-Opt-in overport/frame/device/PC VR IDs, default removals, adapter values, device-file names, foveation parameters,
-and alternate-build patch IDs are compared. Alternate-build identities use `alt:<patch id>` so choosing one in a
-fallback is distinct from choosing it in the primary build. Device-file content is not compared. Adapter values
-must match: a wrong value contributes both an FP and an FN for `adapter.<key>`. Patch precision, recall and F1 are
-micro-averaged across games; an empty denominator is reported as zero. Exact-game accuracy also compares the
-unsupported status flag. Fields report matching games, including empty-field matches.
-
-`RUNTIME_ONLY` lists choices excluded from the headline: `use_alt`, selected runtime adapter settings, Lepton
-environment variables, and config-sync settings. They have their own exact, field and patch metrics. Catalog
-entries with status `unsupported` are excluded from both headline and runtime supported-game metrics, and have
-separate metrics and per-game diffs. Converted analyses are included and marked. JSON contains all metrics per
-engine, all game signatures, split assignments, and missing/extra decisions.
-
-## Dated score: catalog gaps vs. detection errors
-
-The strict score treats the catalog as complete, but older entries were verified before many patches existed, and
-a catalog recipe inherits every heuristic adapter setting and device patch (except `device.text_input_window`)
-without listing them (`engine.suggest`), so the verified build had those. The dated score (`headline_dated`, printed
-under "Dated") sets aside, on both sides:
-
-- patches first committed after the entry's `verified.date` (the verifier couldn't have chosen them), and
-- inherited adapter/device picks (`inherited_decisions`).
-
-What remains are real disagreements: an extra on an entry verified after the patch existed, or a catalog choice
-the heuristics don't make. Gaps are counted per patch ("Catalog gaps by patch"). The dated score needs the intro
-date cache that `--fit-report` writes; without it only inherited picks are set aside.
-
-Before tuning a rule to remove an "extra", check which kind it is: a gap on an old entry is a candidate for the
-catalog (fit report), not a detection error. Before adding a patch to a working entry, weigh its benefit (does it
-fix something the game hits?) against a rebuild prompt for everyone who installed it; adapter settings never need
-adding (inherited). Results 2026-10-15: strict 5/65 exact, F1 73.8%; dated 39/65, F1 88.6% (dev 90.5%, holdout
-79.5%). Remaining misses are one-game fixes found at runtime (e.g. Vader's gl_error_clear, BlazeRush's GL settings).
-
-An evaluation writes JSON even when its headline has differences, then exits 1 for compatibility with the original
-script. It exits 0 when exact, or after producing a fit report.
-
-## New patch fit
-
-The fit report covers all catalog entries, independently of `--split`. Candidates come from the final heuristic
-recipe, preserving platform, flat-app, dependency, and 32-bit normalization rules. A candidate must also be opt-in,
-applicable and recommended by its own `detect()`. Entries already listing or explicitly removing the patch are
-excluded; a listed adapter key is excluded regardless of its value. This report proposes additions, not value edits.
-
-Each candidate includes its reason, experimental/strict flags, first local git introduction date, catalog entry
-date (`verified.date`; `updated` only without one, since it also moves for unrelated edits), and whether the
-patch is newer. Unknown dates are marked unknown. Warnings
-come from the full catalog recipe plus that one candidate; they may include pre-existing conflicts. Missing-analysis
-entries appear as metadata-only rows. Intro dates, including unknown results, are cached in
-`patch-intro-dates.json` beside the snapshot (or dumps folder); subsequent runs only query uncached patch IDs.
-
-`tests/test_eval_heuristics.py` uses synthetic data. The opt-in real-dump test in `tests/test_games.py` ratchets the
-supported all-split exact ratio and patch F1 against measured, rounded-down baseline constants. Machine-local
-`.eval-home/` and `.eval-results/` scratch outputs are ignored by git.

docs/INSTALL.md

@@ -86,24 +86,8 @@ FramePort can run on the Frame itself, without a PC:
 2. In Desktop Mode, download `FramePort-linux-arm64.tar.gz`, unpack it (`tar xzf FramePort-linux-arm64.tar.gz`) and
    start `FramePort/FramePort`.
 
-With the default **Steam library: Now**, games appear after you close FramePort and return to Gaming Mode.
-FramePort also waits while its window is open in Gaming Mode, so you can install several games in one session.
-Please report anything odd with **Report a problem…**.
-
-Settings → Installing → **Steam library** controls future installs:
-
-- **Now** (default): restart Steam after adding shortcuts, waiting while a game, Desktop Mode, or FramePort's local
-  window is open (up to 12 hours). Unchanged shortcuts need no restart.
-- **Later**: save shortcuts without restarting Steam. Keep installing; changes are applied at the next Steam
-  service start, including after a reboot. **Restart Steam now** applies them immediately. It closes Desktop Mode
-  and FramePort running on the Frame, and asks again if a game is running.
-- **Off**: skip new Steam shortcuts; existing entries stay. FramePort's **Play** runs the installed launcher directly.
-  Steam and SteamVR must already be running. Steam's per-game overlay, controller setup, and Exit game integration
-  are unavailable; stop the game from FramePort's Monitor. Pending games in Later also use this direct Play path.
-
-CLI: `frameport frame steam-library now|later|off` saves the setting and applies it to the connected Frame.
-`frameport frame restart-steam` applies pending entries now; `--yes` confirms ending a running game.
-These settings concern game shortcuts; installing a missing Steam runtime such as Proton can still require a restart.
+Games appear in the Steam library when you go back to Gaming Mode. Please report anything odd with **Report a
+problem…**.
 
 ## Installing games
 
@@ -183,11 +167,6 @@ FramePort downloads it, checks it, restarts and keeps your games and settings. *
 - Settings → **Updates** turns the check off or turns on **Install updates automatically**.
 - **Recipes** (the tested patches and settings for each game) update by themselves. A game whose recipe changed shows
   **Update on Frame**.
-- **Moved your games?** Scan the new folder (or **Rescan folders**): games found there whose old files are gone keep their library entry, name, artwork, tags and settings, and only their location changes. **Settings → Library folders** lists the folders FramePort scans; remove the old one there (the games stay). See the [FAQ](FAQ.md#i-moved-my-games-to-another-folder-or-drive-how-do-i-update-the-library).
-- **A newer version of a game:** right-click it (or use **…** on its page) → **Update with a newer APK…** (Quest and
-  Android games) or **Update with a newer version…** (Linux apps: the new AppImage, archive or folder; PC VR games:
-  the new game folder). Its name, artwork, tags and your settings stay. Then click **Update on Frame** (or **on this
-  PC**).
 - **Dev builds:** if you're asked to test a change before its release, use Settings → Updates → **Install the latest
   dev build…**. The next release then arrives as a normal update.
 
@@ -237,14 +216,6 @@ The **Files** tab copies files between your PC and the Frame: videos, documents,
   `/sdcard/Download`, `/sdcard/Documents`).
 - **Game storage** holds each game's own files. A game's menu → **Add videos and files…** opens it.
 
-## Backing up saves
-
-Steam doesn't sync Quest games' saves. A game's menu (**…** on its page) → **Saves** → **Back up saves** copies them
-to your PC (close the game first); **Back up all saves** on the Steam Frame page does every installed Quest game.
-**Restore saves…** puts a backup back on the Frame and keeps a copy of the replaced saves there (**Undo last
-restore**). Backups live in FramePort's data folder under `save-backups/`; the 10 newest per game are kept (Settings →
-Data). Caches and large downloaded content stay out. More in the [FAQ](FAQ.md#can-i-back-up-a-games-saves).
-
 ## Share a recipe or report a problem
 
 - **Share working recipe…** (in the game's menu) opens a GitHub issue with the game's recipe filled in. Accepted
@@ -283,15 +254,12 @@ option. The main ones:
 | Command | What it does |
 |---|---|
 | `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's patches |
-| `folders [--add <folder>] [--remove <folder>]` / `rescan` | list the library folders, add or remove one (its games stay); scan them again for new and moved games |
 | `add-linux <path> [--exe <program>]` | add a Linux app (AppImage, folder or archive) |
-| `new-version <game> <path>` | point a game at its newer version (APK, Linux app file/folder, PC VR game folder) |
 | `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
 | `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for this PC), launch test |
 | `frame discover` / `frame connect` / `frame info` | find, connect to and describe the Frame |
 | `frame send <files> --dest videos` / `frame storage` / `frame cleanup` | copy files to the Frame, list where they can go, free space |
 | `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | list the Frame's drives, move a game, install to a drive |
-| `saves backup <game>\|--all` / `saves list <game>` / `saves restore <game> [n]` / `saves undo <game>` | back up Quest games' saves to this PC, restore one, undo the last restore |
 | `tools status` / `tools install` | the tools FramePort downloads |
 | `open-link "<link>"` | install from an install button's address or a download link (`--yes`, `--no-install`) |
 | `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |

docs/INSTALL_BUTTON.md

@@ -45,7 +45,6 @@ The manifest:
 {
   "schema": "framedrop.install/v1",
   "name": "My Game",
-  "version": "1.4.2",
   "files": [{ "url": "https://example.com/my-game.apk", "sha256": "<64 hex digits>" }],
   "frameport": { "description": "One sentence about the game.", "icon": "https://example.com/icon.png" }
 }
@@ -55,13 +54,6 @@ The manifest:
 against it. The `frameport` object is optional; its icon and description are shown in the
 install question. Only public `https://` addresses are accepted.
 
-`version` is optional (it can also go inside the `frameport` object) and makes updates possible: FramePort remembers
-the manifest's address and version, fetches the manifest again at start (at most every 6 hours) and, when its
-`version` is newer, offers to download and install the update (Library bar and the game's page; CLI
-`frameport link-updates [--install]`). Keep the manifest at the same address and raise `version` with every build.
-Versions compare number by number (`1.10` > `1.9`), and a suffix sorts before the plain release (`1.2.0-beta2` <
-`1.2.0`). Bare file links (`?url=…`) and manifests without a version are never checked.
-
 To build a link from Python: `frameport.deeplink.make_link(manifest_url="https://…/my-game.json")`.
 
 ## On a website

docs/PATCHES.md

@@ -2,7 +2,7 @@
 
 # Patches
 
-Every patch and game setting FramePort knows: 182 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: 169 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,9 +11,9 @@ 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) (61)
-- [Game settings](#group-adapter) (73)
-- [Files and settings on the Frame](#group-device) (10)
+- [Steam Frame patches](#group-frame) (55)
+- [Game settings](#group-adapter) (68)
+- [Files and settings on the Frame](#group-device) (8)
 - [PC VR (Proton and Revive)](#group-pcvr) (13)
 
 ## Index
@@ -27,7 +27,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Copy OVRPlugin if VrApi is present](#patch_copy_ovrplugin_vrapi) | `patch_copy_ovrplugin_vrapi` | Patches from OVRPort | default |
 | [Disable controller tracking offset](#patch_disable_controller_offset) | `patch_disable_controller_offset` | Patches from OVRPort |  |
 | [Disable Meta XR Audio telemetry](#patch_disable_meta_xr_audio_telemetry) | `patch_disable_meta_xr_audio_telemetry` | Patches from OVRPort |  |
-| [Disable application space warp if used](#patch_disable_space_warp) | `patch_disable_space_warp` | Patches from OVRPort | 4 |
+| [Disable application space warp if used](#patch_disable_space_warp) | `patch_disable_space_warp` | Patches from OVRPort | 3 |
 | [Fix minimal Android SDK](#patch_fix_min_android_sdk) | `patch_fix_min_android_sdk` | Patches from OVRPort | default |
 | [Fix UE4 crash with Unity stub](#patch_fix_unreal_crash) | `patch_fix_unreal_crash` | Patches from OVRPort | default |
 | [Force enable passthrough](#patch_force_passthrough) | `patch_force_passthrough` | Patches from OVRPort | 3 |
@@ -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 | 45 |
+| [Remove Unreal's ForceQuit](#patch_remove_unreal_force_quit) | `patch_remove_unreal_force_quit` | Patches from OVRPort | 38 |
 | [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,75 +47,67 @@ 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 |  |
 | [32-bit ARM bridge (Gear VR / Go games)](#frame-a32_bridge) | `frame.a32_bridge` | Steam Frame patches | 6 |
 | [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 | 2 |
+| [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 | 6 |
+| [bHaptics: skip the Bluetooth permission request](#frame-bhaptics_permission) | `frame.bhaptics_permission` | Steam Frame patches | 5 |
 | [BlazeRush: controllers without Meta avatars, own shader cache](#frame-blazerush) | `frame.blazerush` | Steam Frame patches | 1 |
-| [Cortopia games: don't wait for Meta's org-scoped id](#frame-cortopia_org_id) | `frame.cortopia_org_id` | Steam Frame patches |  |
 | [Epic Online Services: stop the keychain retry loop](#frame-eos_keychain_loop) | `frame.eos_keychain_loop` | Steam Frame patches |  |
 | [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 |
-| [Play services: Android 11 version checks](#frame-gms_platform_version) | `frame.gms_platform_version` | Steam Frame patches |  |
-| [Godot apps: start without a clipboard service](#frame-godot_clipboard) | `frame.godot_clipboard` | Steam Frame patches | 1 |
-| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 31 |
+| [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 | 19 |
 | [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 |
-| [Fix Lua startup crashes on Frame](#frame-luajit_pointers) | `frame.luajit_pointers` | Steam Frame patches | 1 |
-| [Declare Meta-only permissions](#frame-meta_permissions) | `frame.meta_permissions` | Steam Frame patches | 4 |
+| [Fix Lua startup crashes on Frame](#frame-luajit_pointers) | `frame.luajit_pointers` | Steam Frame patches |  |
+| [Declare Meta-only permissions](#frame-meta_permissions) | `frame.meta_permissions` | Steam Frame patches | 2 |
 | [Meta XR Audio: skip Quest telemetry class](#frame-metaxr_telemetry) | `frame.metaxr_telemetry` | Steam Frame patches | default |
 | [Clear android:debuggable](#frame-nodebug) | `frame.nodebug` | Steam Frame patches | 3 |
-| [Oculus OS telemetry class stubs](#frame-oculusos) | `frame.oculusos` | Steam Frame patches | 17 |
-| [Fix crash when the game prepares the microphone](#frame-ovr_microphone) | `frame.ovr_microphone` | Steam Frame patches | 1 |
+| [Oculus OS telemetry class stubs](#frame-oculusos) | `frame.oculusos` | Steam Frame patches | 15 |
+| [Fix crash when the game prepares the microphone](#frame-ovr_microphone) | `frame.ovr_microphone` | Steam Frame patches |  |
 | [Keep the same Meta user between starts](#frame-ovr_stable_user) | `frame.ovr_stable_user` | Steam Frame patches | default |
 | [Trace Meta platform requests (diagnostics)](#frame-ovr_trace) | `frame.ovr_trace` | Steam Frame patches |  |
 | [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 |
-| [Photon Voice: skip Android 12 audio routing](#frame-photon_voice_audio_route) | `frame.photon_voice_audio_route` | Steam Frame patches |  |
-| [SDL apps: start without a clipboard service](#frame-sdl_clipboard) | `frame.sdl_clipboard` | Steam Frame patches | 5 |
+| [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 |
 | [Team Beef ports: treat the Frame as a Meta headset](#frame-tbxr_vendor) | `frame.tbxr_vendor` | Steam Frame patches | 1 |
-| [Unity App UI: no Android 12 vibrator](#frame-unity_appui_vibrator) | `frame.unity_appui_vibrator` | Steam Frame patches |  |
-| [GL shim for Unity (no multisampled render-to-texture)](#frame-unity_gl_shim) | `frame.unity_gl_shim` | Steam Frame patches | 25 |
-| [Unity: render each eye separately (no multiview)](#frame-unity_multipass) | `frame.unity_multipass` | Steam Frame patches | 2 |
-| [Unity: disable MSAA](#frame-unity_no_msaa) | `frame.unity_no_msaa` | Steam Frame patches | 10 |
+| [GL shim for Unity (no multisampled render-to-texture)](#frame-unity_gl_shim) | `frame.unity_gl_shim` | Steam Frame patches | 23 |
+| [Unity: render each eye separately (no multiview)](#frame-unity_multipass) | `frame.unity_multipass` | Steam Frame patches | 1 |
+| [Unity: disable MSAA](#frame-unity_no_msaa) | `frame.unity_no_msaa` | Steam Frame patches | 9 |
 | [Unity: skip OVROverlay layers (fades, splash screens)](#frame-unity_no_overlay_copy) | `frame.unity_no_overlay_copy` | Steam Frame patches | 2 |
-| [Unity: start VR without Meta's system apps](#frame-unity_oculus_check) | `frame.unity_oculus_check` | Steam Frame patches | 14 |
-| [Unity: keep MSAA off at runtime (OVRManager)](#frame-unity_runtime_msaa_off) | `frame.unity_runtime_msaa_off` | Steam Frame patches | 31 |
-| [Make Unity text fields work](#frame-unity_text_input) | `frame.unity_text_input` | Steam Frame patches | 111 |
+| [Unity: start VR without Meta's system apps](#frame-unity_oculus_check) | `frame.unity_oculus_check` | Steam Frame patches | 12 |
+| [Unity: keep MSAA off at runtime (OVRManager)](#frame-unity_runtime_msaa_off) | `frame.unity_runtime_msaa_off` | Steam Frame patches | 28 |
+| [Make Unity text fields work](#frame-unity_text_input) | `frame.unity_text_input` | Steam Frame patches | 85 |
 | [Unity: share thread keys (games that run out of them)](#frame-unity_tls_key_pool) | `frame.unity_tls_key_pool` | Steam Frame patches | 1 |
 | [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: reserve memory like on Quest](#frame-unreal_noreserve) | `frame.unreal_noreserve` | Steam Frame patches |  |
-| [Unreal: stand-ins for OVRPlugin functions OVRPort lacks](#frame-unreal_ovrp_entrypoints) | `frame.unreal_ovrp_entrypoints` | Steam Frame patches | 3 |
+| [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 | 9 |
+| [Unreal: start without the OBB check](#frame-unreal_skip_obb_check) | `frame.unreal_skip_obb_check` | Steam Frame patches | 5 |
 | [Unreal: skip the OBB delivery check](#frame-unreal_skip_obb_delivery) | `frame.unreal_skip_obb_delivery` | Steam Frame patches | 1 |
 | [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 |
-| [USB MIDI: don't poll for USB devices](#frame-usb_midi_watcher) | `frame.usb_midi_watcher` | Steam Frame patches |  |
 | [Vermillion: paint canvases in the scene](#frame-vermillion_scene_canvas) | `frame.vermillion_scene_canvas` | Steam Frame patches | 1 |
-| [Vivox voice chat: skip Android 12 audio routing](#frame-vivox_audio_route) | `frame.vivox_audio_route` | Steam Frame patches | 2 |
+| [Vivox voice chat: skip Android 12 audio routing](#frame-vivox_audio_route) | `frame.vivox_audio_route` | Steam Frame patches | 1 |
 | [Vulkan: drop invalid render-pass pointers](#frame-vk_sanitize) | `frame.vk_sanitize` | Steam Frame patches | default · 1 |
-| [VrApi → OpenXR bridge](#frame-vrapi_bridge) | `frame.vrapi_bridge` | Steam Frame patches | 4 |
+| [VrApi → OpenXR bridge](#frame-vrapi_bridge) | `frame.vrapi_bridge` | Steam Frame patches | 3 |
 | [Quiet Meta's VrApi loader (OpenXR games)](#frame-vrapi_stub) | `frame.vrapi_stub` | Steam Frame patches | 2 |
-| [OpenGL ES: shader fixes (Vulkan layer under Zink)](#frame-zink_shader_fix) | `frame.zink_shader_fix` | Steam Frame patches | 2 |
-| [Unique controller action names](#adapter-action_dedup) | `adapter.action_dedup` | Game settings |  |
+| [OpenGL ES: shader fixes (Vulkan layer under Zink)](#frame-zink_shader_fix) | `frame.zink_shader_fix` | Steam Frame patches | 1 |
 | [Pointer start](#adapter-aim_forward) | `adapter.aim_forward` | Game settings |  |
 | [Pointer angle](#adapter-aim_pitch) | `adapter.aim_pitch` | Game settings |  |
 | [Pointer turn](#adapter-aim_yaw) | `adapter.aim_yaw` | Game settings |  |
-| [Fix inside-out mixed reality](#adapter-alpha_blend_emul) | `adapter.alpha_blend_emul` | Game settings |  |
 | [Use controllers](#adapter-controller_fix) | `adapter.controller_fix` | Game settings | 1 |
-| [Show Steam Frame controllers](#adapter-controller_models) | `adapter.controller_models` | Game settings | 6 |
+| [Show Steam Frame controllers](#adapter-controller_models) | `adapter.controller_models` | Game settings | 4 |
 | [Stand in for cube layers](#adapter-cube_standin) | `adapter.cube_standin` | Game settings |  |
 | [Show curved menus and screens](#adapter-cylinder_strips) | `adapter.cylinder_strips` | Game settings |  |
-| [Show 360° backgrounds and videos](#adapter-equirect_emul) | `adapter.equirect_emul` | Game settings | 7 |
+| [Show 360° backgrounds and videos](#adapter-equirect_emul) | `adapter.equirect_emul` | Game settings | 5 |
 | [360° detail](#adapter-equirect_face) | `adapter.equirect_face` | Game settings |  |
 | [360° picture orientation](#adapter-equirect_flip) | `adapter.equirect_flip` | Game settings |  |
 | [360° video frame rate limit](#adapter-equirect_fps) | `adapter.equirect_fps` | Game settings |  |
@@ -123,7 +115,6 @@ 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 |
-| [Colour space support](#adapter-fb_color_space) | `adapter.fb_color_space` | Game settings |  |
 | [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 |  |
@@ -136,10 +127,9 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [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 | 96 |
+| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 81 |
 | [Vibration strength](#adapter-haptic_scale) | `adapter.haptic_scale` | Game settings |  |
-| [Turn off Quest Vulkan foveation](#adapter-hide_fb_foveation) | `adapter.hide_fb_foveation` | Game settings |  |
-| [Turn off space warp](#adapter-hide_space_warp) | `adapter.hide_space_warp` | Game settings | 5 |
+| [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 |  |
 | [Extra diagnostics (log)](#adapter-layer_debug) | `adapter.layer_debug` | Game settings |  |
 | [Drop broken layers](#adapter-layer_fix) | `adapter.layer_fix` | Game settings |  |
@@ -147,18 +137,18 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Unity frame loop: wait for skipped frames](#adapter-ovrp_begin_gate) | `adapter.ovrp_begin_gate` | Game settings | 1 |
 | [Steadier hands (older Unity)](#adapter-ovrp_hold_physics) | `adapter.ovrp_hold_physics` | Game settings | 1 |
 | [See your room](#adapter-passthrough_emul) | `adapter.passthrough_emul` | Game settings |  |
-| [Steadier head tracking](#adapter-pose_consistency) | `adapter.pose_consistency` | Game settings | 2 |
+| [Steadier head tracking](#adapter-pose_consistency) | `adapter.pose_consistency` | Game settings | 1 |
 | [Pose timing diagnostics (log)](#adapter-pose_debug) | `adapter.pose_debug` | Game settings |  |
-| [Fix hands lagging behind controllers](#adapter-pose_time_fix) | `adapter.pose_time_fix` | Game settings | 15 |
+| [Fix hands lagging behind controllers](#adapter-pose_time_fix) | `adapter.pose_time_fix` | Game settings | 14 |
 | [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 | 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 |  |
-| [Render resolution (supersampling)](#adapter-scale) | `adapter.scale` | Game settings | 9 |
+| [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 | 12 |
+| [Pretend room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 9 |
 | [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 |  |
@@ -171,24 +161,21 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Retry refused picture formats](#adapter-swapchain_fix) | `adapter.swapchain_fix` | Game settings |  |
 | [Steady controller input after focus](#adapter-sync_guard) | `adapter.sync_guard` | Game settings | 3 |
 | [Hide Vulkan foveation](#adapter-vk_hide_fdm) | `adapter.vk_hide_fdm` | Game settings | 1 |
-| [Vulkan pipeline failures (log)](#adapter-vk_pipeline_log) | `adapter.vk_pipeline_log` | Game settings |  |
 | [Stop objects popping in and out](#adapter-vk_query_slots) | `adapter.vk_query_slots` | Game settings |  |
 | [Vulkan shader dump (diagnostics)](#adapter-vk_shader_dump) | `adapter.vk_shader_dump` | Game settings |  |
 | [Vulkan shader fixes](#adapter-vk_shader_fix) | `adapter.vk_shader_fix` | Game settings | 1 |
 | [Fix depth flicker (Unreal Vulkan)](#adapter-vk_spec_fixes) | `adapter.vk_spec_fixes` | Game settings | 2 |
 | [Vulkan error checks (log)](#adapter-vk_validation) | `adapter.vk_validation` | Game settings |  |
 | [OpenGL ES shader dump (diagnostics)](#adapter-zink_shader_dump) | `adapter.zink_shader_dump` | Game settings |  |
-| [OpenGL ES shader fixes](#adapter-zink_shader_fix) | `adapter.zink_shader_fix` | Game settings | 2 |
+| [OpenGL ES shader fixes](#adapter-zink_shader_fix) | `adapter.zink_shader_fix` | Game settings | 1 |
 | [Keep the game's saved resolution in step](#device-config_sync) | `device.config_sync` | Files and settings on the Frame | 1 |
 | [Show as VR or as a flat window](#device-display_mode) | `device.display_mode` | Files and settings on the Frame |  |
-| [Settings files for the game](#device-files) | `device.files` | Files and settings on the Frame | 3 |
-| [Foveated rendering (Valve)](#device-foveation) | `device.foveation` | Files and settings on the Frame | 5 |
-| [Headset model](#device-headset_model) | `device.headset_model` | Files and settings on the Frame | default |
+| [Settings files for the game](#device-files) | `device.files` | Files and settings on the Frame | 2 |
+| [Foveated rendering (Valve)](#device-foveation) | `device.foveation` | Files and settings on the Frame | 3 |
 | [Hide Android's navigation bar](#device-hide_navbar) | `device.hide_navbar` | Files and settings on the Frame |  |
-| [Game language](#device-language) | `device.language` | Files and settings on the Frame |  |
 | [Extra Lepton settings](#device-lepton_env) | `device.lepton_env` | Files and settings on the Frame | 3 |
 | [Controllers as a gamepad (Steam Input)](#device-steam_gamepad) | `device.steam_gamepad` | Files and settings on the Frame |  |
-| [Show the app's Android window (for typing)](#device-text_input_window) | `device.text_input_window` | Files and settings on the Frame | 114 |
+| [Show the app's Android window (for typing)](#device-text_input_window) | `device.text_input_window` | Files and settings on the Frame | 88 |
 | [Launch options (SteamVR or OpenXR)](#pcvr-launch_args) | `pcvr.launch_args` | PC VR (Proton and Revive) | 2 |
 | [Provide the Oculus runtime from Revive (Frame)](#pcvr-libovr_redirect) | `pcvr.libovr_redirect` | PC VR (Proton and Revive) |  |
 | [No Unreal crash reporter](#pcvr-no_crash_reporter) | `pcvr.no_crash_reporter` | PC VR (Proton and Revive) |  |
@@ -297,7 +284,7 @@ Turns off Meta's frame-rate trick, which causes glitches or hangs outside Quest
 - **Changes:** Changes the APK (during the OVRPort conversion).
 - **Suggested (on):** Very heavy game (… GiB) using OVRPlugin: application space warp causes artifacts/hangs off-Quest.
 - **Offered (off):** Enable if the game shows warping artifacts or hangs (uses OVRPlugin space warp).
-- **Catalog games (4):** Asgard's Wrath 2, Batman: Arkham Shadow, Marvel's Deadpool VR, Puzzling Places.
+- **Catalog games (3):** Asgard's Wrath 2, Batman: Arkham Shadow, Marvel's Deadpool VR.
 - **Source:** [patches/overport.py](../src/frameport/patches/overport.py)
 
 > 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).
@@ -433,7 +420,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 (45):** Asgard's Wrath 2, BARTENDER VR SIMULATOR, Breathedge VR, Carve Snowboarding, Creed, Dance Central, Espire 1: VR Operative (Quest Edition), Espire 2 and 37 more.
+- **Catalog games (38):** Asgard's Wrath 2, BARTENDER VR SIMULATOR, Carve Snowboarding, Creed, Dance Central, Espire 1: VR Operative (Quest Edition), Espire 2, ExploreVR and 30 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)
@@ -510,7 +497,6 @@ Runs a 32-bit game (Gear VR, Oculus Go, early Quest) on the Frame, which only ru
 - **Suggested (on):** 32-bit-only game: the Frame can't run 32-bit ARM code, the bridge translates it.
 - **Catalog games (6):** AFFECTED: The Manor, Gunjack, Journey of the Gods, Shadow Point, Sports Scramble (Santa Cruz), Spunky Dungeon.
 - **Suggested by launch-test signatures:**
-  - `a32-jit-overflow` (fatal): The 32-bit bridge's translator stopped the game on a long run of instructions it hands to its interpreter, for example OpenSSL's ARMv8 SHA-1 code in Pinball FX2 VR.
   - `no-arm64` (fatal): 32-bit-only APK (e.g. a Gear VR or Oculus Go game).
 - **Source:** [patches/frame/a32_bridge.py](../src/frameport/patches/frame/a32_bridge.py)
 
@@ -520,12 +506,12 @@ Runs a 32-bit game (Gear VR, Oculus Go, early Quest) on the Frame, which only ru
 
 FramePort's layer between the game and the Steam Frame: fills in what the Frame lacks (controllers, room, passthrough). Needed for every converted game.
 
-- `frame.adapter` · on by default · revision 2
+- `frame.adapter` · on by default
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Required for every OpenXR/overport build on the Frame.
 - **Suggested by launch-test signatures:**
   - `cube-swapchain-refused` (fatal): The game asked for a cube-map swapchain (for example an OVROverlay skybox or loading cube), which the Frame's runtime doesn't have.
-  - `cylinder-menu-layers-rejected` (info): The runtime rejected a frame's layers once (XR_ERROR_LAYER_INVALID).
+  - `cylinder-menu-layers-rejected` (error): The game draws a curved (cylinder) screen to each eye separately (for example the Doom3Quest / PreyVR menu).
   - `graphics-requirements-missing` (fatal): The game can't start VR on the Frame; rebuild it with the current FramePort.
   - `swapchain-rect-invalid` (fatal): The runtime rejects the game's frames, so it stops drawing (for example stuck at a "Waiting" box).
   - `time-conversion` (warning): The Frame's runtime lacks timespec time conversion; the current adapter build emulates it.
@@ -540,7 +526,7 @@ Lets the game find extra content it keeps next to its data (for example Star War
 - `frame.asset_files`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** The game asks Meta's platform for asset files and its data has … content file(s) (*.pak) that OVRPort's loader doesn't report.
-- **Catalog games (2):** Attack on Titan VR: Unbreakable, Star Wars: Tales from the Galaxy's Edge.
+- **Catalog games (1):** Star Wars: Tales from the Galaxy's Edge.
 - **Source:** [patches/frame/langpack.py](../src/frameport/patches/frame/langpack.py)
 
 > 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.
@@ -579,7 +565,7 @@ Stops bHaptics from asking for a Bluetooth permission the Frame doesn't have (th
 - `frame.bhaptics_permission` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** bHaptics asks for an Android 12 Bluetooth permission at start; the permission screen interrupts the game on the Frame.
-- **Catalog games (6):** Quantum Void, Ragnarock, Smash Drums, Tea For God, Vampire: The Masquerade - Justice, Vendetta Forever.
+- **Catalog games (5):** Quantum Void, Ragnarock, Smash Drums, Tea For God, Vendetta Forever.
 - **Suggested by launch-test signatures:**
   - `bhaptics-permission-prompt` (error): The game asked for Android 12's Bluetooth permission (bHaptics' vest SDK, for example Yupitergrad).
 - **Source:** [patches/frame/bhaptics_permission.py](../src/frameport/patches/frame/bhaptics_permission.py)
@@ -599,19 +585,6 @@ Makes BlazeRush's menus and controllers work without Meta's avatars, and lets it
 
 > BlazeRush 1.0.349 only (Klownicle's guide, GitHub #57). Its menus wait for Meta's avatar, which never comes on the Frame, before they create the game's own controllers: the second menu ignored all input. Two instructions in libtargemapp.so skip that wait and the avatar mesh drawing; the game's shader cache gets a new folder name (cache/br_shader_v1), so programs compiled before the GL shim's shader fixes aren't reused. Only this exact build is changed (code fingerprint and every instruction checked); anything else is left as it is.
 
-### <a id="frame-cortopia_org_id"></a>Cortopia games: don't wait for Meta's org-scoped id
-
-Gets Cortopia games (for example Escaping Wonderland) past their loading screen.
-
-- `frame.cortopia_org_id`
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Cortopia's Meta platform start-up waits for an org-scoped user id that OVRPort's platform library never answers (stuck loading screen).
-- **Suggested by launch-test signatures:**
-  - `cortopia-org-id-wait` (error): The game waits forever on its loading screen for an answer from Meta's platform (an org-scoped user id, used as its analytics id) that OVRPort's platform library doesn't give.
-- **Source:** [patches/frame/cortopia_org_id.py](../src/frameport/patches/frame/cortopia_org_id.py)
-
-> Cortopia Studios' games (e.g. Escaping Wonderland) ask Meta's platform for an org-scoped user id at start when on Wi-Fi, only to use it as their analytics id. OVRPort's platform library doesn't answer that request ("An unknown error occurred. Request failed."), so the game waits forever on its loading screen. Makes the game take its own offline path for that one request (the analytics id stays empty); the licence check and the logged-in user before it are unchanged. Found with Cpp2IL in libil2cpp.so.
-
 ### <a id="frame-eos_keychain_loop"></a>Epic Online Services: stop the keychain retry loop
 
 Stops Epic Online Services from retrying its login keychain forever (the game would never finish starting).
@@ -652,19 +625,6 @@ Corrects graphics code the Frame's drivers reject (black screen with sound).
 
 > Loads libglshim.so ahead of libEGL in every engine library that fetches GL through eglGetProcAddress. Fixes Quest-only leniency that Mesa/Zink rejects: #pragma before #extension, implicit int/float conversions (enables GL_EXT_shader_implicit_conversions), and multiview shaders used on single-view framebuffers (hides GL_OVR_multiview; gl_hide_multiview=0 turns that off). Logs every failed shader with its source lines (logcat tag GLShim). Symptom: black screen with working audio in a GLES game.
 
-### <a id="frame-gms_platform_version"></a>Play services: Android 11 version checks
-
-Lets games with Google Play services code start on the Frame (they'd crash at start on an Android 12 call).
-
-- `frame.gms_platform_version` · also for 2D apps
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Google Play services' Android 12 checks were built in as 'always true'; on Lepton (Android 11) the game would crash at start.
-- **Suggested by launch-test signatures:**
-  - `gms-android12-call` (fatal): Google Play services' code in the game called an Android 12 method (the game was built for Android 12 and newer, so its version checks were built in as "always true") and Lepton runs Android 11; the game crashes on its GoogleApiHandler thread at start (for example Titan Isles).
-- **Source:** [patches/frame/gms_platform_version.py](../src/frameport/patches/frame/gms_platform_version.py)
-
-> Google Play services' libraries in games built for Android 12+ only (for example Titan Isles) had their Android 12 checks folded into 'always true' when the game was built; on Lepton's Android 11 they then call an Android 12 method and the game crashes at start (FATAL EXCEPTION: GoogleApiHandler). Those checks answer 'no' again (an in-place edit of classes.dex).
-
 ### <a id="frame-godot_clipboard"></a>Godot apps: start without a clipboard service
 
 Lets Godot games start on the Frame (they'd crash looking for a clipboard).
@@ -672,7 +632,6 @@ Lets Godot games start on the Frame (they'd crash looking for a clipboard).
 - `frame.godot_clipboard` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Godot 4 app: it crashes at start in Lepton, which has no clipboard service.
-- **Catalog games (1):** EndoparasiticVR.
 - **Suggested by launch-test signatures:**
   - `godot-no-clipboard` (fatal): The app crashed at start because the Frame's Android has no clipboard.
 - **Source:** [patches/frame/godot_clipboard.py](../src/frameport/patches/frame/godot_clipboard.py)
@@ -686,7 +645,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 (31):** 4XVR Video Player, AugmentedEmpire, Batman: Arkham Shadow, Battlemarked, BattleTalent, Breathedge VR, Dance Central, Exploding Kittens VR and 23 more.
+- **Catalog games (19):** 4XVR Video Player, AugmentedEmpire, Batman: Arkham Shadow, Battlemarked, Dance Central, Eye of the Temple, Fruit Ninja, Ghost Town and 11 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.
@@ -734,7 +693,6 @@ Lets games with a verified older Lua engine get past a startup crash on the Fram
 - `frame.luajit_pointers`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** The bundled Lua engine rejects Frame's wider native pointers; use the compatible full-pointer engine while retaining the game's bindings.
-- **Catalog games (1):** BattleTalent.
 - **Suggested by launch-test signatures:**
   - `lua-lightuserdata-pointer` (fatal): The Lua runtime rejected a pointer outside its supported address range.
 - **Source:** [patches/frame/luajit_pointers.py](../src/frameport/patches/frame/luajit_pointers.py)
@@ -748,7 +706,7 @@ Declares Meta's permissions some mixed-reality games ask for, so they don't stop
 - `frame.meta_permissions`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Mixed-reality game that needs the room model: its 'use spatial data' permission must be granted (for example Demeter).
-- **Catalog games (4):** Arkio, BattleTalent, Demeter, Real VR Fishing.
+- **Catalog games (2):** Arkio, Demeter.
 - **Source:** [patches/frame/manifest_fixes.py](../src/frameport/patches/frame/manifest_fixes.py)
 
 > Declares com.oculus.permission.* / horizonos.permission.* that the app uses, so Android grants them at install (for example the 'use spatial data' permission of mixed-reality games like Demeter).
@@ -791,7 +749,7 @@ Provides stand-ins for Quest system calls some games make at start.
 - **Suggested (on):** The Unreal build of Meta XR Audio looks up com.oculus.os.AnalyticsEvent and aborts without it (for example NOPE Challenge).
 - **Suggested (on):** Several Meta SDK libraries look up com.oculus.os.AnalyticsEvent (…); games like this abort without the stub (for example Nano).
 - **Offered (off):** … references com.oculus.os.AnalyticsEvent; usually harmless (for example Batman: Arkham Shadow and LEGO Bricktales run without it). Enable if the game aborts with ClassNotFoundException.
-- **Catalog games (17):** AgeOfJoy, AllInOneSports, Caves, Deep Cuts, Does it Stack?, Nano, Neko Atsume Purrfect, NOPE CHALLENGE and 9 more.
+- **Catalog games (15):** AgeOfJoy, AllInOneSports, Caves, Deep Cuts, Does it Stack?, Nano, NOPE CHALLENGE, RC Pilot Trainer and 7 more.
 - **Suggested by launch-test signatures:**
   - `oculus-os-class` (fatal): The game looks up a Quest-only system class and aborts.
 - **Source:** [patches/frame/telemetry.py](../src/frameport/patches/frame/telemetry.py)
@@ -805,7 +763,6 @@ Stops a crash a few seconds after the logo in games with voice chat.
 - `frame.ovr_microphone`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** The game uses Meta's microphone API (ovr_Microphone_GetOutputBufferMaxSize), which crashes in OVRPort's library before the microphone is started.
-- **Catalog games (1):** The Walking Dead: Saints & Sinners.
 - **Suggested by launch-test signatures:**
   - `ovr-microphone-crash` (fatal): The game crashed while setting up the microphone (for example Unreal's Oculus voice chat a few seconds after the logo).
 - **Source:** [patches/frame/ovr_microphone.py](../src/frameport/patches/frame/ovr_microphone.py)
@@ -874,19 +831,6 @@ Stops a crash on the Frame's processor in games whose code the Quest runs more l
 
 > Some engines contain assembly (for example OpenSSL's) that checks a return-address signature it never made. The Quest's CPU ignores those checks, the Steam Frame's enforces them: the game crashes with SIGILL as soon as it uses that code, for example on its first network connection (Star Wars Pinball VR). In a library with unpaired checks, the signing and checking instructions become no-ops.
 
-### <a id="frame-photon_voice_audio_route"></a>Photon Voice: skip Android 12 audio routing
-
-Stops games with Photon Voice chat from crashing on the Frame when voice chat starts (an Android 12 audio call).
-
-- `frame.photon_voice_audio_route` · also for 2D apps
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Photon Voice calls Android 12 audio methods, which Lepton (Android 11) lacks, and crashes when voice chat starts.
-- **Suggested by launch-test signatures:**
-  - `photon-voice-api31` (fatal): The game's Photon Voice microphone plugin calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes when voice chat starts (for example Table Troopers at the tutorial).
-- **Source:** [patches/frame/photon_voice_audio_route.py](../src/frameport/patches/frame/photon_voice_audio_route.py)
-
-> Photon Voice's microphone plugin (for example Table Troopers) picks the audio device with Android 12 methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the game crashes with a NoSuchMethodError when voice chat starts. That method returns at once instead (an in-place edit of classes.dex); the microphone keeps Android's default audio route.
-
 ### <a id="frame-sdl_clipboard"></a>SDL apps: start without a clipboard service
 
 Lets SDL and LÖVE games start on the Frame (they'd crash looking for a clipboard).
@@ -894,7 +838,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 (5):** Crisis Zone VR, Majora's Mask VR, 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)
@@ -953,19 +897,6 @@ Lets Team Beef ports (for example Lambda1VR) start on the Frame.
 
 > Team Beef's ports (for example Lambda1VR, RTCWQuest) load an OpenXR library named after the headset maker and pick their VR setup by maker; for "valve" they stop at start (libopenxr_loader_valve.so not found) or take the Pico path. Adds that library and lets them take the Meta path. Keeps GL4ES in charge of its desktop OpenGL draw calls so animated models don't turn into stretched triangles.
 
-### <a id="frame-unity_appui_vibrator"></a>Unity App UI: no Android 12 vibrator
-
-Lets games built with Unity's App UI start on the Frame (they'd quit at once on an Android 12 vibrator call).
-
-- `frame.unity_appui_vibrator` · also for 2D apps
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Unity App UI's activity uses Android 12's VibratorManager at start, which Lepton (Android 11) lacks: the game would quit at once.
-- **Suggested by launch-test signatures:**
-  - `unity-appui-vibrator` (fatal): The game's start activity uses Android 12's VibratorManager (Unity's App UI package, for example PianoVision) and Lepton runs Android 11, so it quits before the game starts.
-- **Source:** [patches/frame/unity_appui_vibrator.py](../src/frameport/patches/frame/unity_appui_vibrator.py)
-
-> The activity of Unity's App UI package (for example PianoVision) gets the vibrator through Android 12's VibratorManager without checking the Android version; on Lepton's Android 11 the game quits at start with a NoClassDefFoundError. The activity then starts without a vibrator and its UI haptic feedback does nothing (an in-place edit of classes.dex).
-
 ### <a id="frame-unity_gl_shim"></a>GL shim for Unity (no multisampled render-to-texture)
 
 Stops a gray or frozen screen in Unity games that turn on anti-aliasing while running (for example The Room VR).
@@ -973,7 +904,7 @@ Stops a gray or frozen screen in Unity games that turn on anti-aliasing while ru
 - `frame.unity_gl_shim`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity GLES game that may switch to MSAA at runtime: hide multisampled render-to-texture, which crashes the Frame's GL driver (for example The Room VR).
-- **Catalog games (25):** Audica, BattleSisters, Beat Saber, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight, End Space and 17 more.
+- **Catalog games (23):** Audica, BattleSisters, Beat Saber, Clockwork, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 15 more.
 - **Suggested by launch-test signatures:**
   - `unreal-msrtt-crash` (fatal): The game's graphics crashed a few seconds after start.
 - **Source:** [patches/frame/vrapi_bridge.py](../src/frameport/patches/frame/vrapi_bridge.py)
@@ -987,7 +918,7 @@ Draws each eye separately. Try it when one eye shows a gray or broken picture.
 - `frame.unity_multipass` · revision 2
 - **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.
-- **Catalog games (2):** BattleTalent, I Am Cat.
+- **Catalog games (1):** I Am Cat.
 - **Source:** [patches/frame/unity_runtime.py](../src/frameport/patches/frame/unity_runtime.py)
 
 > Oculus XR Plugin games render both eyes in one pass (multiview) on Android. If one eye shows only effects or gray (for example I Am Cat), rendering each eye in its own pass can fix it, at some GPU cost. Rewrites OculusSettings.GetStereoRenderingMode and its inlined read in OculusLoader.Initialize -&gt; MultiPass in libil2cpp.so (found with Cpp2IL). Try it when one eye is wrong.
@@ -1000,7 +931,7 @@ Turns off a smoothing setting that crashes some older Unity games on the Frame.
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Legacy VrApi Unity game on GLES with MSAA (… quality levels): multisampled render-to-texture hangs the Frame's GL driver (for example Sniper Elite VR).
 - **Offered (off):** GLES Unity game with MSAA on (… quality levels); enable if it hangs the GPU ('zink: DEVICE LOST').
-- **Catalog games (10):** Audica, BattleSisters, Eye of the Temple, I Expect You To Die 2, IEYTD3, Jurassic World Aftermath Collection, Mini Motor Racing X, Sniper Elite VR and 2 more.
+- **Catalog games (9):** Audica, BattleSisters, Eye of the Temple, IEYTD3, Jurassic World Aftermath Collection, Mini Motor Racing X, Sniper Elite VR, SUPERHOT VR and 1 more.
 - **Suggested by launch-test signatures:**
   - `zink-device-lost` (fatal): The GPU hung, so the game froze or closed.
 - **Source:** [patches/frame/unity_no_msaa.py](../src/frameport/patches/frame/unity_no_msaa.py)
@@ -1028,7 +959,7 @@ Lets older Unity games start VR without Meta's system apps (they'd stay on a 2D
 - `frame.unity_oculus_check` · revision 5
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity with built-in Oculus support: it checks for Meta's system apps before starting VR, else it runs as a 2D app (for example Accounting+, BattleSisters).
-- **Catalog games (14):** Accounting+, Audica, BattleSisters, Cosmodread, End Space, Eye of the Temple, I Expect You To Die 2, Jurassic World Aftermath Collection and 6 more.
+- **Catalog games (12):** Accounting+, Audica, BattleSisters, Cosmodread, End Space, Eye of the Temple, Jurassic World Aftermath Collection, Mini Motor Racing X and 4 more.
 - **Suggested by launch-test signatures:**
   - `unity-vr-device-none` (fatal): Unity didn't start VR, so the game runs as a hidden 2D app.
 - **Source:** [patches/frame/unity_oculus_check.py](../src/frameport/patches/frame/unity_oculus_check.py)
@@ -1042,7 +973,7 @@ Keeps a smoothing setting off that the game turns on itself and that can freeze
 - `frame.unity_runtime_msaa_off` · revision 2
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** GLES Unity game whose OVRManager turns 4x MSAA on at runtime: multisampled render-to-texture can hang the Frame's GPU.
-- **Catalog games (31):** Audica, BattleSisters, BattleTalent, Beat Saber, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 23 more.
+- **Catalog games (28):** Audica, BattleSisters, Beat Saber, Clockwork, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 20 more.
 - **Suggested by launch-test signatures:**
   - `unity-render-crash` (fatal): The game's graphics crashed, so the picture freezes or stays gray.
   - `unity-runtime-msaa` (info): The game turns MSAA on at runtime, which can hang the Frame's GPU.
@@ -1058,7 +989,7 @@ Lets you type into this app's text fields on the Frame (they'd close at once).
 - `frame.unity_text_input` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity app with text fields (…): they close at once on the Frame because it has no system keyboard.
-- **Catalog games (111):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arcsmith, Arkio, Assassin's Creed Nexus, Attack on Titan VR: Unbreakable, Audica and 103 more.
+- **Catalog games (85):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arkio, Audica, AugmentedEmpire, Battlemarked, BattleSisters and 77 more.
 - **Source:** [patches/frame/unity_text_input.py](../src/frameport/patches/frame/unity_text_input.py)
 
 > Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a frame later when there is none (Lepton has no on-screen keyboard; Meta's system keyboard does this on a Quest), so a selected text field only flashes a caret. Rewrites TouchScreenKeyboardShouldBeUsed -&gt; false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -&gt; true in libil2cpp.so, found per game with Cpp2IL (downloaded on first use), so fields stay selected and take key presses: Steam's keyboard (with "Show the app window") or Type on Frame from the PC.
@@ -1069,7 +1000,6 @@ Lets Unity 6 games with many native libraries start when they run out of thread
 
 - `frame.unity_tls_key_pool` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Unity 6 with Firebase Firestore and Gecko: these native runtimes can exhaust Android's 128 thread keys alongside the Frame's graphics and XR libraries. Pool Unity's keys to leave room for them.
 - **Offered (off):** Unity 6 with …: turn on if the game aborts at start with "cannot create thread specific key" (for example Wander).
 - **Catalog games (1):** Wander.
 - **Suggested by launch-test signatures:**
@@ -1118,19 +1048,6 @@ Shows the full environment when its upper part is clipped but menu panels look c
 
 > Some UE4 games keep the initial Android window size for their stereo depth buffer, clipping the upper part of the environment while menu panels look correct. Refreshes the cached depth dimensions from the current eye render target before allocation. Preserves multiview and multisampling. Verified in Tales from the Galaxy's Edge 1.1.9; changes one branch only when the function size and surrounding code match.
 
-### <a id="frame-unreal_noreserve"></a>Unreal: reserve memory like on Quest
-
-Lets the game load: it reserves more memory at start than the Frame grants in one piece and crashed before its first frame (for example Transformers Beyond Reality).
-
-- `frame.unreal_noreserve` · also for 2D apps
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Unreal's Binned3 allocator reserves more memory at start than the Frame's kernel allows in one piece; without this the game crashes while it loads.
-- **Suggested by launch-test signatures:**
-  - `unreal-reserve-refused` (fatal): The game crashed while Unreal was still loading, before its first frame.
-- **Source:** [patches/frame/unreal_noreserve.py](../src/frameport/patches/frame/unreal_noreserve.py)
-
-> Unreal reserves its memory ranges on Android with ordinary read/write mappings. Games built with Unreal's Binned3 allocator reserve tens of gigabytes at once while the engine loads (76 GiB in Transformers Beyond Reality); Quest allows that, the Frame's kernel refuses mappings larger than its memory, and the game crashes before its first frame (SIGSEGV at fault addr 0x10 in libUnreal.so, inside System.loadLibrary). This marks those mappings MAP_NORESERVE, as Quest effectively treats them: memory is still only used when the game touches it.
-
 ### <a id="frame-unreal_ovrp_entrypoints"></a>Unreal: stand-ins for OVRPlugin functions OVRPort lacks
 
 Lets older Unreal games start VR on the Frame (for example Star Wars Pinball VR).
@@ -1138,7 +1055,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 (3):** Ghostbusters: Rise of the Ghost Lord, Puzzling Places, 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.
@@ -1174,7 +1091,7 @@ Starts Unreal games without re-checking their data file (they'd seem to hang on
 - `frame.unreal_skip_obb_check` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unreal checks the OBB's contents before starting (bVerifyOBBOnStartUp); on the Frame a failed or slow check can't be seen and the game seems to hang.
-- **Catalog games (9):** Dance Central, Kill It With Fire VR, Lost Recipes, MacacoVR, Maestro, Puzzling Places, Ragnarock, Scared By Squares and 1 more.
+- **Catalog games (5):** Dance Central, Kill It With Fire VR, MacacoVR, Maestro, Ragnarock.
 - **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)
@@ -1221,19 +1138,6 @@ Makes the hands' thumbs follow what your thumb touches (they always pointed up:
 
 > Unreal 4's Oculus input sets the ThumbUp axis (games animate the hand's thumb with it) from Meta's near-touch sensing, which the Frame never reports: the thumb always points up. Uses the touches instead (left X/Y/stick/thumb rest, right A/B/stick/thumb rest). Changes three instructions in OculusInput::SendControllerEvents, only where the code matches exactly (UE4 Oculus games of one engine generation, for example Vader Immortal, Robo Recall). Found by Klownicle (GitHub #49).
 
-### <a id="frame-usb_midi_watcher"></a>USB MIDI: don't poll for USB devices
-
-Lets apps with a USB MIDI driver start on the Frame (they'd crash looking for USB devices); USB MIDI devices aren't available there.
-
-- `frame.usb_midi_watcher` · also for 2D apps
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** kshoji's USB MIDI driver polls Android's USB service, which the Frame's Android lacks: the app would crash a few seconds after start.
-- **Suggested by launch-test signatures:**
-  - `usb-midi-watcher` (fatal): The app's USB MIDI driver (kshoji's, used by Unity MIDI plugins, for example PianoVision) asked Android's USB service for MIDI devices; the Frame's Android has no USB service, so the app crashed.
-- **Source:** [patches/frame/usb_midi_watcher.py](../src/frameport/patches/frame/usb_midi_watcher.py)
-
-> kshoji's USB MIDI driver (Unity MIDI plugins, for example PianoVision) polls Android's USB service for MIDI devices; the Frame's Android has no USB service, so the app crashes a few seconds after start (NullPointerException on MidiDeviceConnectionWatchThread). The poll returns at once instead, so no USB MIDI device is ever found (an in-place edit of classes.dex).
-
 ### <a id="frame-vermillion_scene_canvas"></a>Vermillion: paint canvases in the scene
 
 Keeps the hand and brush visible over Vermillion's painting canvas (the canvas is drawn in the scene instead of as a layer in front).
@@ -1253,7 +1157,7 @@ Lets games with Vivox voice chat start on the Frame (they'd crash on an Android
 - `frame.vivox_audio_route` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Vivox voice chat: it calls Android 12 audio methods, which Lepton (Android 11) lacks, and crashes.
-- **Catalog games (2):** Dungeons of Eternity, Real VR Fishing.
+- **Catalog games (1):** Dungeons of Eternity.
 - **Suggested by launch-test signatures:**
   - `vivox-api31` (fatal): The game's Vivox voice-chat SDK calls Android 12 audio-routing methods (AudioManager communication devices) without checking the Android version; Lepton runs Android 11, so the app crashes (for example Green Hell VR).
 - **Source:** [patches/frame/vivox_audio_route.py](../src/frameport/patches/frame/vivox_audio_route.py)
@@ -1284,7 +1188,7 @@ Lets games built on Meta's oldest VR interface run on the Frame.
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** The engine calls libvrapi.so directly; OVRPort can't translate it.
 - **Conflicts with:** [`frame.vrapi_stub`](#frame-vrapi_stub)
-- **Catalog games (4):** BlazeRush, Path of the Warrior, The Climb, The Climb 2.
+- **Catalog games (3):** BlazeRush, Path of the Warrior, The Climb 2.
 - **Suggested by launch-test signatures:**
   - `direct-vrapi` (warning): The game uses Meta's VrApi directly and needs the VrApi bridge.
   - `vrapi-frame-rejected` (fatal): The VrApi bridge rejected the game's frame options, so no picture reaches the headset even though frame pacing can appear in the log.
@@ -1314,7 +1218,7 @@ Repairs shaders that hang the graphics chip at certain effects, from the game's
 - `frame.zink_shader_fix`
 - **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.
-- **Catalog games (2):** Star Wars: Tales from the Galaxy's Edge, Vader Immortal: Episode I.
+- **Catalog games (1):** Vader Immortal: Episode I.
 - **Source:** [patches/frame/zink_shader_fix.py](../src/frameport/patches/frame/zink_shader_fix.py)
 
 > Loads FramePort's shader-fix Vulkan layer into an OpenGL ES game. On the Frame, OpenGL ES runs on Zink (Mesa's GL on Vulkan); the layer sits between Zink and the driver and inserts the words of the adapter setting zink_shader_fix into the SPIR-V modules whose size and SHA-256 match (every other module is untouched), for example stores that set loop counters and accumulators a shader reads before writing, which hang the GPU (Vader Immortal's lightspeed jump; found by Klownicle, GitHub #49). Does nothing without zink_shader_fix (or zink_shader_dump) in the recipe. The layer adds itself to Android's Vulkan debug layer list for the game's process only.
@@ -1323,20 +1227,6 @@ Repairs shaders that hang the graphics chip at certain effects, from the game's
 
 Settings of FrameBridge, FramePort's OpenXR layer inside every converted Quest game. Most can be changed on the Frame later without a rebuild (game page → Game settings).
 
-### <a id="adapter-action_dedup"></a>Unique controller action names
-
-Stops games from dropping back to the home environment at start because two of their controller actions share a name (for example Scared By Squares). Leave it on.
-
-- `adapter.action_dedup`
-- **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 `1`.
-  - Game settings → Troubleshooting → "Unique controller action names" (advanced).
-- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
-
-> Gives a controller action whose name already exists in its action set a free name ("turn" -&gt; "turn_2"). The Frame's runtime accepts duplicate names but then can't load the game's input manifest and treats the game as closed: black, then the home environment while the game keeps running with sound (for example Scared By Squares, whose Unreal project has an action and an axis both called Turn; GitHub #323).
-
 ### <a id="adapter-aim_forward"></a>Pointer start
 
 Moves where the pointer starts, forward or back.
@@ -1379,20 +1269,6 @@ Turns the pointer left or right.
 
 > Turns the controllers' pointing ray left (+) or right (−).
 
-### <a id="adapter-alpha_blend_emul"></a>Fix inside-out mixed reality
-
-For games that show your room on their objects and darkness where your room should be.
-
-- `adapter.alpha_blend_emul`
-- **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 `1`.
-  - Game settings → Mixed reality → "Fix inside-out mixed reality" (advanced); shown while `adapter.passthrough_emul` is on.
-- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
-
-> With emulated passthrough, honours the eye layer's XR_FB_composition_layer_alpha_blend, which the Frame's runtime ignores: Unreal games keep inverted alpha and ask for inverse blending, so the room showed where the game drew and black where it should show the room (for example Star Wars: Beyond Victory). The alpha is inverted in the game's image before it is composited (Vulkan).
-
 ### <a id="adapter-controller_fix"></a>Use controllers
 
 Turn off only for games you play with your hands instead of controllers.
@@ -1418,7 +1294,7 @@ For games that show the headset's own controllers. Takes effect after a reinstal
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Controllers → "Show Steam Frame controllers".
-- **Catalog games (6):** Neko Atsume Purrfect, Ocean Rift, Real VR Fishing, SynthRiders, VR HOT Quest, Walkabout Mini Golf.
+- **Catalog games (4):** Ocean Rift, SynthRiders, VR HOT Quest, Walkabout Mini Golf.
 - **Suggested by launch-test signatures:**
   - `render-model-requested` (info): The game shows Quest controllers (or none) because the Frame doesn't provide controller models.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -1463,7 +1339,7 @@ Video players' virtual theaters and 360° videos would otherwise stay black.
 - **Options:**
   - Value: int, default `0`.
   - Game settings → 360° pictures and video → "Show 360° backgrounds and videos".
-- **Catalog games (7):** 4XVR Video Player, EndoparasiticVR, Into The Radius 2, Pinball FX VR, Puzzling Places, Riven, Tea For God.
+- **Catalog games (5):** 4XVR Video Player, Into The Radius 2, Pinball FX VR, Riven, Tea For God.
 - **Suggested by launch-test signatures:**
   - `equirect-layers-dropped` (warning): The game's 360° pictures (for example a video player's theater or 360° videos) are missing because the Frame's runtime can't show equirect layers.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -1569,22 +1445,6 @@ 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-fb_color_space"></a>Colour space support
-
-For games that stop at start because the headset reports no colour space (for example OutRun Quest VR).
-
-- `adapter.fb_color_space`
-- **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 → "Colour space support" (advanced).
-- **Suggested by launch-test signatures:**
-  - `color-space-missing` (fatal): The game needs Meta's colour-space extension, which the Frame's runtime doesn't offer, and quits before it starts VR (for example OutRun Quest VR).
-- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
-
-> Offers Meta's colour-space extension when the Frame's runtime lacks it: the game is told the headset uses Rec.709 and may choose any colour space (no conversion is done). For games that quit before their VR session with "Rec.709 color space unavailable" (for example OutRun Quest VR, GitHub #336). Only reaches games that use their own OpenXR loader; OVRPort's dispatcher can't forward the new functions.
-
 ### <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.
@@ -1760,7 +1620,7 @@ Logs details when flat panels stay black. No effect on the game.
   - Game settings → Troubleshooting → "Flat panel diagnostics (log)" (advanced).
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> 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). 2 (frameport settings) also checks every draw and logs the draw state, failed texture uploads and shader compiles and, for idTech 4 engines, the game clock.
+> 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).
 
 ### <a id="adapter-haptic_fix"></a>Fix freezes when controllers vibrate
 
@@ -1772,7 +1632,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 (96):** AgeOfJoy, Ancient_Dungeon, Attack on Titan VR: Unbreakable, Audica, AugmentedEmpire, Battlemarked, BattleSisters, BattleTalent and 88 more.
+- **Catalog games (81):** AgeOfJoy, Ancient_Dungeon, Audica, AugmentedEmpire, Battlemarked, BattleSisters, Beat Saber, Caves and 73 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.
@@ -1791,22 +1651,6 @@ Turn it down if controller vibrations are too strong.
 
 > Scales every controller vibration the game asks for (0-1): plain vibrations, Meta's amplitude envelopes and PCM buffers. For games whose vibrations feel much stronger than on a Quest.
 
-### <a id="adapter-hide_fb_foveation"></a>Turn off Quest Vulkan foveation
-
-Diagnostic for Vulkan games that fail on their first frames with missing Quest foveation images.
-
-- `adapter.hide_fb_foveation`
-- **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 → "Turn off Quest Vulkan foveation" (advanced).
-- **Suggested by launch-test signatures:**
-  - `quest-foveation-image-missing` (info): OVRPlugin enabled Quest Vulkan foveation but received no density image.
-- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
-
-> Hides Quest FB foveation extensions from the game and OVRPort, removes Vulkan foveation image/create chains, and refuses foveation profile updates. Diagnostic for first-frame failures with missing density images (for example Transformers Beyond Reality: Redux). Device verification pending; does not disable Valve foveation.
-
 ### <a id="adapter-hide_space_warp"></a>Turn off space warp
 
 For games whose picture flickers or smears (for example Into The Radius 2).
@@ -1817,7 +1661,7 @@ For games whose picture flickers or smears (for example Into The Radius 2).
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Troubleshooting → "Turn off space warp" (advanced).
-- **Catalog games (5):** Into The Radius 2, Lawn Mowing Simulator VR, Metro Awakening, Pinball FX VR, The Boys VR.
+- **Catalog games (4):** Into The Radius 2, Metro Awakening, Pinball FX VR, The Boys VR.
 - **Suggested by launch-test signatures:**
   - `space-warp-used` (info): The game uses Meta's space warp (it renders half of its frames plus motion vectors, and the runtime makes up the rest).
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -1936,7 +1780,7 @@ For games that judder or shimmer while you hold your head still (for example I A
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Picture → "Steadier head tracking" (advanced).
-- **Catalog games (2):** I Am Cat, Lawn Mowing Simulator VR.
+- **Catalog games (1):** I Am Cat.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Repeat xrLocateViews queries for the same display time get the first, fully tracked answer again. Games that ask several times per frame got slightly different poses and rendered parts of the frame with different heads: judder (for example I Am Cat; proposed by Klownicle, GitHub #8).
@@ -1966,7 +1810,7 @@ For games whose hands trail the controllers when you move them (for example Batt
 - **Options:**
   - Value: int, default `0`.
   - Game settings → Controllers → "Fix hands lagging behind controllers" (advanced).
-- **Catalog games (15):** Battlemarked, BattleSisters, Beat Saber, Dance Central, Dungeons of Eternity, Mini Motor Racing X, OrbusVR, Phantom: Covert Ops and 7 more.
+- **Catalog games (14):** Battlemarked, BattleSisters, Beat Saber, Dance Central, Dungeons of Eternity, Mini Motor Racing X, Phantom: Covert Ops, Quantum Void and 6 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Poses a game asks for at a CLOCK_MONOTONIC time, or more than 0.5 s before the frame's display time, are located at the same moment in the runtime's time (or now). Meta's OVRPlugin passes the monotonic clock on as the OpenXR time, which on the Frame runs seconds behind the runtime's clock, so its "now" poses (Unity's physics step, controller poses) came from the past: hands trailing the controllers (for example BattleSisters, Sniper Elite VR).
@@ -1983,7 +1827,7 @@ For apps that only know Quest 3/Pro controllers: without it they get no buttons.
   - Game settings → Controllers → "Treat newer Quest controllers as Touch" (advanced).
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped), and the runtime's answer for each hand is reported to them as their own profile (Unity's OpenXR input only connects controllers of a profile it knows). Meta's detached-controller paths (XR_META_detached_controllers, which the Frame lacks) are left out of the app's actions and bindings: one such path made Unity attach no controller input at all. Without it such apps get no controller input.
+> Apps that suggest controller bindings only for Meta's newer profiles (Touch Plus, Touch Pro), which the Frame's runtime rejects (XR_ERROR_PATH_UNSUPPORTED), get the same bindings as oculus/touch_controller instead (components Touch lacks are dropped). Without it such apps get no controller input.
 
 ### <a id="adapter-proximity_emul"></a>Animate fingers from touch
 
@@ -2001,7 +1845,7 @@ For games whose hands' thumbs never move when you touch the buttons or thumbstic
 
 ### <a id="adapter-rect_clamp"></a>Keep pictures in bounds
 
-Stops games from hanging when their eye picture is a little too big or empty (for example PowerWash Simulator). Leave it on.
+Stops games from hanging when their eye picture is a little too big (for example PowerWash Simulator). Leave it on.
 
 - `adapter.rect_clamp`
 - **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
@@ -2011,7 +1855,7 @@ Stops games from hanging when their eye picture is a little too big or empty (fo
   - Game settings → Troubleshooting → "Keep pictures in bounds" (advanced).
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game stops drawing (for example PowerWash Simulator stuck at "Waiting"). An empty rect (0x0, e.g. BattleTalent's first frames, GitHub #293) is rejected the same way and becomes the whole swapchain image.
+> Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game stops drawing (for example PowerWash Simulator stuck at "Waiting").
 
 ### <a id="adapter-refresh_rate"></a>Refresh rate
 
@@ -2026,7 +1870,7 @@ How often the picture updates. Higher is smoother if the game can keep up.
 - **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). Applied through SteamVR before the game starts. A video's frame rate that divides the refresh rate plays smoothest (for example 30 fps at 90 Hz, 24 fps at 72 Hz).
+> 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).
 
 ### <a id="adapter-release_wait"></a>Wait for the game's GPU
 
@@ -2056,17 +1900,17 @@ Re-creates the game's play space after the first frames. For testing.
 
 > Recreate spaces after the first frames (diagnostic).
 
-### <a id="adapter-scale"></a>Render resolution (supersampling)
+### <a id="adapter-scale"></a>Sharpness
 
-Changes the game's render resolution. Higher is sharper but slower; 1.0× is the game's own resolution.
+Higher looks sharper but needs more power; lower runs smoother. 1.0× is the game's own.
 
 - `adapter.scale`
 - **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: float, default `1.0` (always written).
-  - Game settings → Picture → "Render resolution (supersampling)": slider 0.5–2 in steps of 0.1.
-- **Catalog games (9):** 4XVR Video Player, BlazeRush, CrazyTaxiVR, cubism, FGO VR, I Expect You To Die 2, The 7th Guest VR, Vampire: The Masquerade - Justice and 1 more.
+  - Game settings → Picture → "Sharpness": slider 0.5–2 in steps of 0.1.
+- **Catalog games (4):** 4XVR Video Player, BlazeRush, cubism, Walkabout Mini Golf.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Multiplies the recommended eye-buffer width and height (0.5–2.0). 1.5 ≈ 2.25× pixels.
@@ -2096,7 +1940,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 (12):** Arkio, AugmentedEmpire, Battlemarked, BattleTalent, Demeo, Demeter, Ghostbusters: Rise of the Ghost Lord, Neko Atsume Purrfect and 4 more.
+- **Catalog games (9):** Arkio, AugmentedEmpire, Battlemarked, Demeo, Demeter, Ghostbusters: Rise of the Ghost Lord, Ocean Rift, Smash Drums and 1 more.
 - **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)
@@ -2282,20 +2126,6 @@ For Unreal Engine 5 games that crash on the Frame (for example Metro Awakening).
 
 > Vulkan shim (frame.vk_sanitize): the game doesn't see VK_EXT_fragment_density_map(2). Unreal Engine 5 turns on fragment-density-map foveation when the driver offers it and expects the density map from the headset, which the Frame doesn't provide: image views and barriers for a missing image, then a crash in the Frame's Vulkan driver (for example Metro Awakening). Valve's own foveation layer isn't affected.
 
-### <a id="adapter-vk_pipeline_log"></a>Vulkan pipeline failures (log)
-
-Logs graphics pipelines the Frame's driver refuses. No effect on the game.
-
-- `adapter.vk_pipeline_log`
-- **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 → "Vulkan pipeline failures (log)" (advanced).
-- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
-
-> Vulkan shim (frame.vk_sanitize): logs every failing graphics/compute pipeline creation with its shader stages (named like the vk_shader_dump files), structure types and any sampler Y'CbCr conversion involved, to find the pipeline behind Unreal's "Shader compilation failures are Fatal." No effect on the game.
-
 ### <a id="adapter-vk_query_slots"></a>Stop objects popping in and out
 
 For Vulkan games whose models flicker or vanish while you look at them (for example Into The Radius 2). Needs a rebuild.
@@ -2399,7 +2229,7 @@ Repairs OpenGL ES shaders that hang the graphics chip, from the game's recipe.
 - **Options:**
   - Value: str, default empty.
   - Not in the Game settings dialog (set by a recipe or the CLI).
-- **Catalog games (2):** Star Wars: Tales from the Galaxy's Edge, Vader Immortal: Episode I.
+- **Catalog games (1):** Vader Immortal: Episode I.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Shader-fix Vulkan layer (frame.zink_shader_fix) for OpenGL ES games, whose GLSL the Frame's GL driver (Zink) turns into SPIR-V: modules matching size + SHA-256 get words inserted at a byte offset, for example stores that set loop counters and accumulators a shader reads before writing (Vader Immortal's lightspeed jump hung the GPU; found by Klownicle, GitHub #49). Same format as vk_shader_fix. Comes from a game's recipe; the driver's output can change with a Frame update, then the fix no longer matches (logged).
@@ -2410,7 +2240,7 @@ Files, environment and window options written on the Frame when a Quest game or
 
 ### <a id="device-config_sync"></a>Keep the game's saved resolution in step
 
-Keeps the resolution the game saves in step with the headset's picture size (else the picture is shifted, with black borders, after a render resolution change).
+Keeps the resolution the game saves in step with the headset's picture size (else the picture is shifted, with black borders, after a sharpness change).
 
 - `device.config_sync`
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
@@ -2441,7 +2271,7 @@ Puts settings files next to the game on the Frame, for example to turn off an un
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
 - **Suggested (on):** CryEngine: variable-rate shading isn't supported on the Frame, so user.cfg turns it off (… = 0; The Climb / The Climb 2).
 - **Options:** `files`: text, default none — path relative to files/ -&gt; content
-- **Catalog games (3):** SUPERHOT VR, The Climb, The Climb 2.
+- **Catalog games (2):** SUPERHOT VR, The Climb 2.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Writes config files into the game's Android/data/&lt;package&gt;/files/ on the Frame, to turn off engine features the Frame doesn't support (for example a CryEngine user.cfg with r_variable_rate_shading = 0, as The Climb 2 needs).
@@ -2454,28 +2284,13 @@ Render less detail outside your gaze; adjust the full-resolution area or darken
 - **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.
 - **Options:**
-  - `support`: bool, default `False` — Internal APK compatibility support
-  - `mode`: str, default empty — Catalog default: tracked, fixed or off (empty = Valve's default)
+  - `mode`: str, default empty — tracked, fixed or off (empty = Valve's default)
   - `radius`: float, default `0.0`, 0–0.45 — Full-resolution radius; 0 keeps the current runtime default
   - `test`: bool, default `False` — Darken lower-resolution regions (diagnostic)
-- **Catalog games (5):** Ocean Rift, Quantum Void, Tea For God, The 7th Guest VR, Vampire: The Masquerade - Justice.
+- **Catalog games (3):** Ocean Rift, Quantum Void, Tea For God.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
-> Reduces shading away from the full-resolution area, following each eye's gaze. Default area size keeps the runtime's current profile unchanged. Custom radius is a fraction of the shorter eye-image dimension; the transition ends at twice that radius. Larger areas retain more detail but save less GPU work. Fixed stops the area following your eyes. The optional test darkens actual coarse-shaded fragments. Runtime choices are in Game settings. Tested on RE4, Deadpool and Asgard's Wrath 2. The Climb 2 gets a version-guarded private bridge at 1.0 scale; Batman gets its hash-verified allocation fix (unsupported OVRPlugin versions are refused). Other games may need additional fixes; turn this off if artifacts appear.
-
-### <a id="device-headset_model"></a>Headset model
-
-Choose the headset identity the game sees; Quest 3 is the default.
-
-- `device.headset_model` · on by default
-- **Changes:** Changes the APK (a rebuild and reinstall apply it).
-- **Suggested (on):** Quest 3 hardware is closest to Steam Frame: report Quest 3 by default.
-- **Options:** `model`: str, default empty — Headset model reported to the game.
-- **Suggested by launch-test signatures:**
-  - `quest2-headset-identity` (info): OVRPlugin sees OVRPort's Quest 2 identity.
-- **Source:** [patches/frame/headset_model.py](../src/frameport/patches/frame/headset_model.py)
-
-> Choose the OpenXR headset name and headset UUID reported to Quest games. Quest 3 is the default; Quest 2 preserves OVRPort's original answers. Requires a rebuild. Android Build.MODEL remains Lepton.
+> Reduces shading away from the full-resolution area, following each eye's gaze. Default area size keeps the runtime's current profile unchanged. Custom radius is a fraction of the shorter eye-image dimension; the transition ends at twice that radius. Larger areas retain more detail but save less GPU work. Fixed stops the area following your eyes. The optional test darkens actual coarse-shaded fragments; rebuild/reinstall to toggle it. Tested on RE4, Deadpool and Asgard's Wrath 2. The Climb 2 gets a version-guarded private bridge at 1.0 scale; Batman gets its hash-verified allocation fix (unsupported OVRPlugin versions are refused). Other games may need additional fixes; turn this off if artifacts appear.
 
 ### <a id="device-hide_navbar"></a>Hide Android's navigation bar
 
@@ -2488,18 +2303,6 @@ Hides Android's back, home and recents buttons, which cover the app's own button
 
 > Removes Android's back/home/recents buttons from a 2D app's window, where they cover the app's own controls. Turn it off for an app that needs the on-screen back button.
 
-### <a id="device-language"></a>Game language
-
-Choose the language for games that follow the system language. The game must include it. Apply with Update on Frame.
-
-- `device.language` · also for 2D apps
-- **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
-- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
-- **Options:** `tag`: str, default empty — Android language tag, e.g. de-DE (empty = English, US)
-- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
-
-> The language Android reports to the game. Lepton's Android is set to English (US), and games that follow the system language (most Unity and Unreal games) start in English. A language the game doesn't have still shows English. Applies with Update on Frame (the APK isn't changed).
-
 ### <a id="device-lepton_env"></a>Extra Lepton settings
 
 Extra settings for the Android container (for testing).
@@ -2531,7 +2334,7 @@ Lets typing reach this app from Steam's on-screen keyboard or your PC's keyboard
 - `device.text_input_window`
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
 - **Suggested (on):** App with text fields: key presses only reach a shown Android window.
-- **Catalog games (114):** AFFECTED: The Manor, AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arcsmith, Arkio, Assassin's Creed Nexus, Attack on Titan VR: Unbreakable and 106 more.
+- **Catalog games (88):** AFFECTED: The Manor, AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arkio, Audica, AugmentedEmpire, Battlemarked and 80 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
 
 > Lepton runs VR apps headless: their Android window is never shown, so it never gets keyboard focus and no key press (Steam's on-screen keyboard, a USB/Bluetooth keyboard, Type on Frame) reaches the app's text fields. With Lepton's lepton-show-flatscreen marker the window is shown (behind the VR view, which keeps working) and Steam's keyboard opens for a selected text field. Steam lists the shown window as "Gamescope" (the Frame's compositor). Pairs with "Make Unity text fields work without a system keyboard".

docs/PLAYBOOK.md

@@ -13,7 +13,6 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
 |---|---|---|
-| Quest 3-only options missing; OVRPlugin logs `venderId 10291, systemName Oculus Quest2` (#373, Asgard's Wrath 2) | OVRPort's dispatcher overwrites FrameBridge's name and supplies a Quest 2 `XR_META_headset_id`; OVRPlugin prioritizes that UUID | `device.headset_model`: Quest 3 by default, per-game Quest 3S / Quest Pro / Quest 2; rebuild the APK. Byte-checked dispatcher name + UUID edit; Quest 2 leaves the dispatcher unchanged. See DEVICE_NOTES 'Per-game headset identity' |
 | Startup exits through `libxlua.so (lj_err_throw)`, then Unity aborts in mutex cleanup; captured Lua error is `bad light userdata pointer` (GitHub #257, BattleTalent 4.7) | This older LuaJIT encodes lightuserdata in 47 bits; Frame supplies valid wider native pointers. Controlled tests with the unchanged library pass a real low-address allocation and fail its own high-address static pointer | `frame.luajit_pointers` automatically selects a full-pointer Lua engine only for the verified library SHA-256, retaining xLua bindings and custom helpers. The scoped patch reaches OpenXR startup for 60 s headless; rendering and gameplay remain unverified. A `lj_err_throw` cleanup stack without the original error message is insufficient to infer this cause |
 | A GL4ES Team Beef game draws stretched triangles or spikes across characters and the scene (GitHub #191, Lambda1VR) | The newer GL shim exports GLES draw functions that intercept GL4ES's desktop OpenGL calls, bypassing its client-array and immediate-mode translation | `frame.tbxr_vendor` keeps the shim's five draw symbols private when the APK bundles `libgl4es.so`. GL queries and single-sampled framebuffer fixes remain active; other games retain the draw hooks. A/B eye captures on SteamOS 0.4.5: old shim normal, current shim spikes, current shim with private draw symbols normal at ~72 fps. Worn-headset gameplay still needs confirmation |
 | A Team Beef game reports a crash after manually quitting: `fdm_injection_xrDestroySwapchain` → `TBXR_LeaveVR` (GitHub #191, Lambda1VR) | Valve's foveation layer dereferences a null pointer during swapchain cleanup | Triage `tbxr-fdm-shutdown-crash` identifies this as a teardown crash, separate from startup and distorted geometry. No verified cleanup fix yet |
@@ -21,15 +20,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Updating a flat Android app after saving its recipe fails with `no OVRPort patches selected` (GitHub #271, Plezy) | older FramePort loads the saved recipe without restoring its unchanged-install setting or applying the flat-app build rules, then tries an empty VR conversion | update FramePort: saved recipes keep `as_is`, and flat apps still skip OVRPort; existing catalog-derived recipes refresh at the next app update. Until then, enable "Install as is" for an app whose APK needs no fixes |
 | A launch test suggests a patch (for example triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analyzed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analyzed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
 | FDM layer loads but diagnostic logging reports `fdm_injection_CreateInstance: skipped` | Layer loading alone does not enable injection on the tested SteamOS 0.4.5 build; a skipped helper instance alone also does not establish game-wide inactivity | Opt-in `device.foveation` mode `tracked`: loads Valve's layer and sets `FDM_DEBUG=enable`. Batman probe reached foveated render passes with changing per-eye offsets. Validate graphics and matched gameplay GPU time; do not enable globally. Use `debug` only for brief diagnostics, preserving existing flags; never benchmark with debug spam. See FRAME_RUNTIME.md. |
-| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Game settings → Picture → "Foveated rendering (Valve)": **Fixed** (`FDM_DEBUG=disable_offsets`; verify injection remains active on the installed runtime) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
-| With `device.foveation` Eye-tracked/Fixed, the sharp area looks right but everything around it is black with scattered coloured blocks (menus on quads too); pacing fine (GitHub #303, Medieval Dynasty; Vampire Survivors reported the same) | Unity's Oculus XR plugin asks for SUBSAMPLED eye images (`XR_META_vulkan_swapchain_create_info`, `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`); under Valve's FDM their coarse areas stay in the compact subsampled layout, which the compositor reads as an ordinary image. `foveation_fix=1` only dropped the `XrSwapchainCreateInfoFoveationFB` nodes and passed the META node on. With `foveation_fix=0` + `foveation_storage_fix=1` the adapter logs `foveation_storage_fix: shared allocation SUBSAMPLED cleared` for the eye swapchains | `device.foveation` (tracked/fixed) now also sets `foveation_storage_fix=1`, which clears SUBSAMPLED whatever `foveation_fix` is (generic version of Batman's OVRPlugin allocation fix). Rebuild + reinstall (new adapter). Headless-checked only (72 fps, bit cleared); picture needs the headset |
+| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Customize → "Eye-tracked foveation (Valve)" (`device.foveation`): **Fixed** (`FDM_DEBUG=disable_offsets`; verify injection remains active on the installed runtime) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
 | 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`) |
-| A Quest game renders, then logs `Entitlement check failed` / `ovrPlatformInitialize_NotEntitled` (often with retries) and quits, e.g. `SIG: 9` after `[Photon] Disconnected` (GitHub #322, Deadly Delivery) | The game's Meta licence check (entitlement) needs Meta's online login, which the Frame doesn't have; online-only games quit (triage `meta-entitlement`) | None: FramePort doesn't get around entitlement checks. Offline games that log it and play on are fine |
 | 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 |
-| A Unity Quest game stays on a loading screen or doesn't go on; `An unknown error occurred. Request failed.` from `Oculus.Platform.Request`1:OnComplete` (GitHub #346 Eleven, #360 Spectre, #368 Thief Simulator; triage `meta-request-failed`) | A Meta platform call the game waits for got no usable answer: OVRPort's platform library answers some calls without Meta's services (request id 0) and Meta's Unity wrapper drops the callback | Find the call in the stack (the game's own coroutine after `OnComplete`); a per-game fix that skips it when it isn't needed to play (e.g. an analytics id request). Calls the game needs online stay unsupported |
-| Game aborts at start: `OVRPlatform-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after an `ActivityNotFoundException` stack (GitHub #357 Breachers; triage `meta-system-activities`) | The game ships its own renamed copy of Meta's platform loader (e.g. `libovr_custom.so`), which bypasses OVRPort's dispatcher and tries to open Meta's system activities (Horizon OS) | None in general: such games are online games built on Meta's services. Serving OVRPort's dispatcher under that name is possible but unlikely to make them playable |
 | 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 |
@@ -49,7 +44,6 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Launch test "failed" although the game runs in the headset: frames paced, then `OVRPortVrApi: EnterVrMode: no tracked head pose before deadline`, then a crash (e.g. `zink: DEVICE LOST` + SIGSEGV in a `gdrv` thread) (GitHub #57, BlazeRush) | the VrApi bridge ends the VR session after 30 s without head tracking, which only happens without a worn headset; the game's renderer then crashes while tearing down | none needed: launch tests (`triage(..., headless=True)`) treat an exit or crash after a `headless_end` line (catalog/triage.yaml) as a pass when frames were paced before it (info finding `headless-end`); play sessions ignore it. Add new such markers to `headless_end` |
 | Launch test EXITED, launch.log has `Target app (<pkg>) did not start` and no `Start proc …:<pkg>` (GitHub #179) | Lepton occasionally doesn't start the app on the first start after an APK change; Android's `WebViewLoader-: System.exit` at boot is not the game (triage `app-not-started`) | start it again |
 | A game keeps no progress between starts although it saves (its storage gets a new `Profiles/Oculus/<id>/`-style folder per start; Walkabout Mini Golf, GitHub #182) | OVRPort's platform loader answers `ovr_GetLoggedInUserID` with a made-up id (6e18 + `random()`), new at every start; games file saves under the user id | `frame.ovr_stable_user` (default for games with the platform library): a fixed id per game and keystore. Old progress: copy the newest old profile into the new id's folder |
-| A Cortopia game (Escaping Wonderland, GitHub #360) stays on its loading screen (frames paced); launch.log: `E Unity: An unknown error occurred. Request failed.` with `OculusPlatformExtension:ToUniTask` / `Cortopia.Scripts.Platform.Meta.<Initialize>d__13` | after the licence check and the logged-in user, the game asks for `Users.GetOrgScopedID` when on Wi-Fi (its analytics id); OVRPort's `ovr_User_GetOrgScopedID` returns request id 0, Meta's C# wrapper logs that line and never calls back, so the awaited start-up never finishes | `frame.cortopia_org_id` (suggested from the analysis, triage `cortopia-org-id-wait`): the `b.ne` after `cmp w0, #2` on `get_internetReachability` in `<Initialize>d__13.MoveNext` -> `b` (Cpp2IL), the game's own no-Wi-Fi path; the same "Request failed." line in another game = another request OVRPort doesn't implement |
 | A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (for example Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
 | FramePort's games disappear after Steam restarts, especially after a devkit registration (GitHub #263) | Steam saves `Shortcuts` / `AppName` with capital letters; older FramePort reads them case-sensitively and writes a second shortcut map that Steam ignores | agent v86 reads and updates keys case-insensitively, keeping Steam's spelling, appids and tags; update FramePort and add the missing games to the library again |
 | Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); see the casing fix above, other causes remain unconfirmed (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
@@ -68,8 +62,6 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 | 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) |
-| Log: `OpenSSH SFTP failed (255): … Permission denied (publickey,password)`, then Paramiko | OpenSSH offered keys the Frame doesn't authorize (GitHub #242) | The log lists the keys OpenSSH offered (`Offering public key`) and its warnings. A connection that logged in with the PC's own keys/agent makes OpenSSH use them too (copies of `~/.ssh/id_*` + the agent); a refused FramePort key is retried that way once. A Frame that accepts only another key file: Settings → Installing → SSH keys (CLI `frameport frame ssh-keys --add <file>`); passphrase keys go through the SSH agent |
-| Log: `OpenSSH SFTP failed (1): stat C://…/[…: No such file or directory` | sftp got glob escapes inside its quotes (GitHub #324, fixed): `[` in a local folder name | Update FramePort; the native_upload `quote()` passes only `\\` and `\"` escapes, Windows paths with `/` |
 | 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 |
@@ -85,7 +77,6 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 (Gear VR / Go / early Quest); Frame has no AArch32 | `frame.a32_bridge` (suggested for every 32-bit-only APK, experimental): the a32 translator runs the game's 32-bit libraries inside the 64-bit app (native/a32translator/bridge) |
 | a32 bridge faults at a low Thumb PC while loading a library, with the same unrelocated pointer in `.init_array` (e.g. Journey of the Gods: `0x1259e9` in OVRPlugin) | The guest loader ignored the older `DT_ANDROID_RELR` / `DT_ANDROID_RELRSZ` tags, leaving relative pointers at their link addresses | Fixed in the guest loader: both Android and standard RELR tags use the existing RELR decoder. Rebuild the a32 runtime and APK; host regression tests cover both tag families, but game startup still needs a Frame run |
-| 32-bit game on the bridge quits right after its loading screen with `a32: block at 0x… overflowed the code buffer` (exit 127; Pinball FX2 VR, GitHub #342: OpenSSL's `sha1_block_data_order_armv8`, ~60 SHA-1 crypto instructions in a row, reached from `RAND_poll`) | Every instruction the JIT hands to the interpreter needs an exit stub; the translator only ended a block at 96 instructions or half its code buffer, so a dense run of such instructions overflowed the 64-entry stub table and `fatal()` ended the process | Fixed in the translator (jit.c `STUB_RESERVE`: a block ends while 8 stubs are left); rebuild the game. Find the code with the logged address minus the library's load address (`a32rt: loaded …`) and `A32_BREAK=<addr>` for its caller; `tests/programs/sha1ce.c` covers it |
 | 32-bit game on the bridge: framerate falls over minutes, purple/garbled geometry, then `Could not allocate memory: System out of memory!` (Spunky Dungeon) | The bridge's guest copies of mapped GL buffers were tracked per buffer target: a second buffer mapped on the same target lost the first one's copy (never written back: garbage vertices; never freed: ~10 MB/s until the guest's 4 GiB were full) | Fixed in the bridge (gl.c: mappings per buffer object). Check: the guest's `[anon:scudo:*]` maps below 4 GiB in /proc/<pid>/maps must stay flat |
 | 32-bit game on the bridge loads, leaves VR and its engine threads end, no crash, no finish() (Gunjack) | The game checks its own APK signature (UE4 `AndroidThunkJava_GetSignature` = Base64 of the signing certificate's SHA-1, compared in AndroidMain): every FramePort build is re-signed | `frame.a32_bridge` stores the original APK's value in `assets/fp_a32_signature.txt` (Unreal games) and the bridge answers the guest's call with it (log `AndroidThunkJava_GetSignature: original signature returned`). Find other such checks with `A32_BREAK` on the game's exit path (vrapi_LeaveVrMode logs its caller) |
 | 32-bit NativeActivity game on the bridge ignores every controller (Gunjack, UE 4.10 Gear VR: no vrapi input functions, it reads the Gear VR touchpad/back button as Android input events from its AInputQueue) | The bridge sent its controller events through `Activity.dispatchKeyEvent`, which a NativeActivity never passes to native code | input.c puts synthetic touchpad (motion, touchscreen source) and back-key events in front of the game's AInputQueue: `ALooper_pollAll/pollOnce` return the queue's ident while one waits, `AInputQueue_getEvent` hands it out, the AInputEvent/AKeyEvent/AMotionEvent imports answer for it. Right trigger = hold the touchpad, A = tap, right stick = swipe (up/down = swipe forward/back along the touchpad's X axis: Gunjack's `OnFlick` takes flick angles <45°/>315° as reload, 135-225° as special weapon), B/left menu = back (log `controllers: the game reads its AInputQueue`) |
@@ -93,7 +84,6 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 32-bit Unity game on the bridge: player stands in the floor (Spunky Dungeon) | Unity's floor-level tracking origin: `vrapi_SetTrackingSpace(1)` (LOCAL_FLOOR) was ignored | The VrApi bridge puts the origin on the STAGE floor for LOCAL_FLOOR/STAGE |
 | 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) |
-| A flat window, no VR and no way to interact; `Google VR Error [Daydream]: Google VR had a fatal issue while loading`, `class com/google/vr/sdk/base/CardboardViewNativeImpl not found` (32-bit bridge), `Unable to start service Intent { act=com.google.vr.vrcore.… }` (GitHub #335 Blade Runner: Revelations, triage `gvr-not-supported`) | A Google Daydream / Cardboard build: Google's VR SDK (GVR, `libgvr.so`) or the Cardboard SDK. Daydream needs Google's VrCore service, Cardboard draws a distorted side-by-side image for a phone screen; neither reaches OpenXR, the Frame's only way into the headset | None: get the game's Oculus build (Quest, Go or Gear VR), which goes through the normal path. Analysis `extra.google_vr` (`daydream`/`cardboard`: manifest categories `com.google.intent.category.DAYDREAM`/`CARDBOARD`, `enableVrMode="com.google.vr.vrcore/…"`, `libgvr.so`/Cardboard SDK libraries, GVR Java classes, Unity `vr-device-list`; not `libgvraudio.so`, which Quest games ship too) → a warning on the game page/CLI and in the recipe notes, only when the APK has no Oculus support; never unsupported from the manifest alone. A GVR → OpenXR shim (like the VrApi bridge) is possible in principle but not built |
 | `UnsatisfiedLinkError` / `cannot locate symbol "ovr_…"` | overport's platform loader lacks Meta platform functions | `frame.ovrstubs` (automatic, generated stubs) |
 | missing `ovrMessageType_ToString` | same, but the game needs a real string | `frame.ovrplatformcompat` (automatic) |
 | The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, for example `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) gray out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
@@ -118,14 +108,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Menu/screen jumps to where you look (for example 4XVR) | the app re-creates LOCAL spaces (4XVR: every 2–4 s) and the Frame places them at the current head yaw, or the app recenters after the Frame's brief focus dips | turn on `adapter.layer_debug`, check `that LOCAL space sits at … deg` vs `focus_hold: hid a … ms focus dip`; patches: `adapter.stable_local` (new LOCAL spaces line up with the first) / `adapter.focus_hold` (on by default: hides dips up to `focus_hold_ms` once the game has been focused for a second; never at start-up: a global debounce broke AC Nexus) |
 | Pointer misses menu items | the Frame's aim pose differs from Touch's | `adapter.layer_debug` logs `aim in grip … pitch/yaw`; correct with `aim_pitch`/`aim_yaw`/`aim_forward` (`frameport settings`, no rebuild) |
 | Video stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (for example 90 for 30 fps, 72 for 24 fps); `layer_debug` logs the offered rates and the app's own requests |
-| A saved 90 Hz refresh setting still launches at 72 Hz (for example Jurassic World Aftermath); FrameBridge reads `refresh_rate=90` but logs result `-1000101000` | The Frame's OpenXR runtime only enumerates its current rate and rejects requests for another mode (`XR_ERROR_DISPLAY_REFRESH_RATE_UNSUPPORTED_FB`) | Agent v92 applies `adapter.refresh_rate` to SteamVR's per-game `preferredRefreshRate` through IVRSettings, on save/install and before Lepton starts (existing launchers upgrade on connection). `0` clears the override; unavailable SteamVR is retried at launch. Device-tested: Aftermath selected 90 Hz and sustained 90.2 fps |
 | PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (for example 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | adapter `focus_hold` (on by default; an earlier global debounce made AC Nexus stay black and was removed) |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
 | Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (for example PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
-| Black from the start, `projection view 0: ... rect=0,0 0x0` then `xrEndFrame failed -25` twice and OVRPlugin "Unable to submit Oculus frame" (BattleTalent, GitHub #293; right after Unity's "Switching to the recommended level" MSAA line) | The game submits its first projection views with an empty image rect; SteamVR rejects them and OVRPlugin gives up submitting | `rect_clamp` replaces an empty rect with the whole swapchain image (log `rect_clamp: view N empty image rect -> full swapchain WxH`): rebuild + reinstall. Check the build output for a WARN from the Unity IL2CPP fixes (`frame.unity_runtime_msaa_off` etc. "code not found in this game"): turned on, they may still change nothing |
-| Black flash, then the SteamVR home environment while the game keeps running (sound plays); vrserver.txt `[OpenXR] SetXrInputConfig failed. Failed to load manifest provided by SetXrInputConfig`, then the app "has exited" and reconnects as `VRApplication_OpenXRInstance`; headless launch tests pace at 10 fps (for example Scared By Squares, GitHub #323) | Two controller actions in one action set share a name (Unreal: an action mapping and an axis mapping both called "Turn"). The Frame's runtime accepts the duplicate but can't load the input manifest it builds and drops the app as a scene app | FrameBridge gives the later duplicate a free name (`action_dedup`, default on; log `action_dedup: action "turn" ("Turn") already exists in its set: created as "turn_2"`): rebuild + reinstall the game. `input_diag=1` logs every action set and action the game creates |
 | Unity game (OVRPlugin, GLES or Vulkan) crashes ~10 s in: `FrameBridge: xrCreateSwapchain … faces=6 … result=-2`, OVRPlugin `CreateSwapchain for eye 0: 0x0, 0 stages`, then render-thread SIGSEGV in memset ← libOVRPlugin ← `ovrp_EndFrame4` (libgallium/ANR follow; for example Budget Cuts Ultimate, GitHub #107); triage `cube-swapchain-refused` | The game shows a cube-map layer (OVROverlay cubemap); the Frame's runtime has no cube layers and refuses cube swapchains (XR_ERROR_RUNTIME_FAILURE); OVRPlugin doesn't check and writes into the image list it never got | FrameBridge `cube_standin` (default on): a refused cube swapchain is served as a GL cube map in the game's context or a device-local Vulkan cube image transitioned to COLOR_ATTACHMENT_OPTIMAL, and its layers are dropped (log `cube_standin: runtime refused …`): rebuild + reinstall. Vulkan path covers UNDERDOGS (GitHub #296); host-tested, headset verification pending |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
@@ -146,17 +133,11 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | SDL / LÖVE app crashes at start: `NullPointerException … ClipboardManager.addPrimaryClipChangedListener` in `SDLClipboardHandler.<init>` (for example Dramatic Shape) | Lepton's Android has no clipboard service (`service check clipboard`: not found) | `frame.sdl_clipboard` (that call → nops in classes.dex, in place, `apk/dex.py`); reproduced and verified with LÖVE for Android 11.5 |
 | Godot 4 app crashes at start: `java.lang.NullPointerException: null cannot be cast to non-null type android.content.ClipboardManager` at `org.godotengine.godot.Godot.<init>` (Godot 4.3/4.4; 4.2 when the clipboard is first used, in `Godot$mClipboard$2.invoke`) (for example EndoparasiticVR, GitHub #134); triage `godot-no-clipboard` | Lepton's Android has no clipboard service and Godot's Kotlin code casts it with a non-null `as ClipboardManager` (`Intrinsics.checkNotNull` before the check-cast). Godot 4.1 (Java) and 4.5+ (`as?`) don't throw | `frame.godot_clipboard` (suggested by analysis `godot_clipboard`): that checkNotNull call → nops in classes.dex (check-cast accepts null), and Godot's getClipboard/hasClipboard/setClipboard return at once ("" / false / nothing; `Dex.return_early`), in place; matched exactly, other dex files untouched. Checked against the Maven godot-lib 4.2.2/4.3.0/4.4.1 and the 4.3/4.4.1 release export templates (D8 re-reads the result); not yet run on the device |
 | Game crashes at start: `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.vivox.sdk.AudioChangeListener.checkAudioRouteAndApplyChanges` (for example Green Hell VR, GitHub #101); triage `vivox-api31` | Newer Vivox (voice chat) builds call Android 12 audio-routing methods without a version check; Lepton is Android 11. Older Vivox builds (Eleven Table Tennis, BattleSisters) don't have that code | `frame.vivox_audio_route` (suggested by analysis `vivox_api31`): every AudioChangeListener method that calls one of them returns at once (`Dex.return_early`: return-void / `const/4 v0, 0; return v0`, in place); voice chat keeps the default audio route |
-| Game crashes when voice chat starts (Table Troopers: at the tutorial's start): `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.exitgames.photon.audioinaec.AudioInAEC.updateAudioDevice` ← `AudioInAEC$1.run` (GitHub #362/#325); triage `photon-voice-api31` (the same error from another library: `audio-api31`, report it) | Photon Voice's Android microphone plugin picks the audio device with Android 12 methods (getAvailableCommunicationDevices / setCommunicationDevice) and has no version check (it logs "Start: SDK >= 31, using BroadcastReceiver" on every Android); Lepton is Android 11. `frame.vivox_audio_route` only edits Vivox's class, so it can't help here | `frame.photon_voice_audio_route` (suggested by analysis `photon_voice_api31`): AudioInAEC.updateAudioDevice (void, the only caller) returns at once (`Dex.return_early`, in place); the microphone thread goes on (communication mode, echo canceller, AudioRecord) on the default route. Checked against Table Troopers' classes.dex; not yet run on the device |
 | A game on a microSD card or another drive doesn't start, loses its saves or loops at start; launch.log has `ln: cannot create symbolic link from 'Frame' to '/data/data/<pkg>'` or `Couldn't create directory for SharedPreferences file /data/user/0/<pkg>/…` (GitHub #213/#214/#215/#221: a card named "Steam Frame 512g"); triage `lepton-data-link-failed` | Valve's Lepton pastes `STEAM_COMPAT_DATA_PATH` unquoted into `sh -c "ln -s …/internal/<pkg> /data/data/<pkg>"` (liblepton mounting.sh) and APK paths into unquoted substitutions, so a path with a space never gets the app's internal storage | agent v83: the Quest launcher links the game folder to `~/.local/share/frameport/lepton-paths/<pkg>` at every start and gives Lepton that path (`app_dir_lines`); `upgrade_launchers` converts existing launchers at the next connection; deployment.json keeps the real path |
 | Start never finishes, 100 % CPU, launch.log of gigabytes repeating `EOSSDK.createKeychain` / `resetKeychain` (Beyond Sandbox, GitHub #214); triage `eos-keychain-loop` | Epic Online Services' Java keychain can't write its SharedPreferences and resets/creates without end (seen when the app had no internal storage, row above) | fix the storage first; `frame.eos_keychain_loop` (opt-in, offered by triage; analysis `eos_keychain`) makes `EOSSDK.resetKeychain` return at once (`Dex.return_early`) |
-| Game quits ~20 s after start (Titan Isles, GitHub #310); launch.log has `FATAL EXCEPTION: GoogleApiHandler` `java.lang.NoSuchMethodError: No virtual method permitUnsafeIntentLaunch()` at `com.google.android.gms.common.internal.zzp` (play-services-basement); triage `gms-android12-call` | Not the missing Play services: the APK was built for minSdk 32, so R8 folded Play services' `PlatformVersion.isAtLeastS()`/`isAtLeastSv2()` to `return true`; OVRPort lowers minSdk, the folded checks stay, and Lepton (Android 11) lacks the Android 12 method | `frame.gms_platform_version` (suggested by analysis `gms_folded_sdk_checks`): those constant checks return false again (in-place dex edit) |
-| App quits a few seconds after OpenXR starts (PianoVision, GitHub #297, after `frame.unity_appui_vibrator`); launch.log has `FATAL EXCEPTION: MidiDeviceConnectionWatchThread` `NullPointerException: … UsbManager.getDeviceList()' on a null object reference` at `jp.kshoji.driver.midi.device.MidiDeviceConnectionWatcher$MidiDeviceConnectionWatchThread.checkConnectedDevices`; triage `usb-midi-watcher` | Lepton's Android has no USB service (`getSystemService("usb")` is null); kshoji's USB MIDI driver polls it | `frame.usb_midi_watcher` (suggested by analysis `usb_midi_watcher`): the poll returns at once; no USB MIDI on the Frame |
-| Unity app quits ~1 s after start, before any OpenXR line (PianoVision, GitHub #297); launch.log has `FATAL EXCEPTION: main` `java.lang.NoClassDefFoundError: Failed resolution of: Landroid/os/VibratorManager;` at `com.unity3d.player.appui.AppUIGameActivity.onCreate`; triage `unity-appui-vibrator` | Unity's App UI package (its own GameActivity) gets the vibrator through Android 12's VibratorManager without a version check; Lepton runs Android 11 | `frame.unity_appui_vibrator` (suggested by analysis `unity_appui_vibrator`): that sequence leaves the vibrator null and the activity's vibrate methods return at once (in-place dex edit) |
 | Unity game freezes on its loading screen ~10-15 s in (Yupitergrad, GitHub #235); launch.log has `GrantPermissionsActivity: Permission grant result … permission=android.permission.BLUETOOTH_CONNECT`, then OVRPlugin `SetupDisplayObjects(): Unable to find EGLConfig for configId 0` and no more frames; triage `bhaptics-permission-prompt` | bHaptics' vest SDK (`com.bhaptics.commons.PermissionUtils.requestBluetoothPermission`) asks for Android 12's BLUETOOTH_CONNECT; on Lepton's Android 11 it can't be granted at install, so Android's permission screen takes the foreground for a moment, the game pauses/resumes and OVRPlugin's GLES compositor stops drawing | `frame.bhaptics_permission` (suggested by analysis `bhaptics_permission`): the request returns at once (`Dex.return_early`) |
 | Unity game aborts at start: `Abort message: 'cannot create thread specific key for __cxa_get_globals()'` (SIGABRT in a library such as `libFirebaseCppApp-*.so`, for example Wander 0.3570, GitHub #198); triage `pthread-keys-exhausted` | Bionic allows 128 pthread keys per process; Unity 6 takes ~40 (most without a destructor), large native libraries (Gecko `libxul.so`, Firebase, avatar SDKs) and the Frame's own libraries (Mesa/Zink, FrameBridge, OVRPort, Valve's Vulkan layers) take the rest | `frame.unity_tls_key_pool` (opt-in; suggested for Unity 6 with Firebase C++ or Gecko): libunity.so's `pthread_key_*`/`pthread_get/setspecific` imports are renamed to `fp_tkey_*` (`elf.rename_imports`, versions set global) and `libfp_tkeys.so` (`native/tlskeys`) is added to its DT_NEEDED; destructor-less keys become slots behind one real key (logs `fp_tkeys: pooling Unity's thread keys`). Approach by Klownicle (#198) |
 | Controllers do nothing (for example stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
-| Controllers "don't sync": virtual hands/controllers lie on the floor below you, no buttons (Unity OpenXR games that only suggest Touch Plus/Pro, e.g. Hotel Infinity #327); log with `input_diag=1`: only `meta/touch_controller_plus` (or Pro) suggested, `controller profile … -> oculus/touch_controller` | the runtime then reports `oculus/touch_controller` for each hand, a profile the game never suggested: Unity's OpenXR input creates no device for it | adapter `profile_remap` (default on) reports the game's own profile for such hands (log: `profile_remap: /user/hand/left reported as meta/touch_controller_plus`) |
-| Controllers "don't sync": hands on the floor below you, no buttons, in a Unity OpenXR game with Meta's OpenXR features (e.g. Spatial Zombies #328); log: `xrCreateAction: XR_ERROR_PATH_UNSUPPORTED` (input_diag: `xrCreateAction -> XR_ERROR_PATH_UNSUPPORTED (thumbstick)`), then `xrGetCurrentInteractionProfile: XR_ERROR_ACTIONSET_NOT_ATTACHED` | Meta's "Detached … Controller" devices add `/user/detached_controller_meta/left|right` to Unity's merged actions; the Frame has no XR_META_detached_controllers, the action fails and Unity attaches no action set (OVRPlugin's input goes with it) | adapter `profile_remap` (default on) leaves those paths out of actions and bindings (log: `profile_remap: action thumbstick without 2 detached-controller path(s)`) |
 | Some buttons do nothing or the wrong thing (for example a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | turn on adapter `input_diag` (diagnostics, off by default; `frameport settings <pkg> input_diag=1`) and look for `input_diag:` lines: `bindings: <profile> accepted` or `unsupported: interaction profile <profile> -> <result>` with the rejected paths, `bindings: /user/hand/<hand> uses <profile>`, `unsupported: function <name>`, `unsupported: xrCreateAction -> <result> (<action>)` |
 | Unity game hangs or the whole Frame restarts (for example in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (for example Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
 | Unity game: one eye shows only effects or gray, the other is fine (for example I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
@@ -182,17 +163,14 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | 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 |
 | An install button opens another program (or nothing) instead of FramePort | another program owns the link type, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
 | 2D Android game ignores the controllers: they only move a pointer, an SDL game keeps its touch controls ("no controller attached"); Android's log lists only `wayland_touch`/`wayland_keyboard`/`wayland_pointer` (GitHub #162, Skate 3) | Lepton's Android gets keyboard, pointer and touch from the Wayland seat only: no gamepad device | patch `device.steam_gamepad` (2D apps; suggested when the manifest declares `android.hardware.gamepad` or `LEANBACK_LAUNCHER`; no APK change, reinstall): the launcher puts FramePort's Podman wrapper (`~/.local/share/frameport/agent/bin/podman`) first on PATH, which binds the host's `/dev/input` at `/dev/fp-input` plus an Xbox 360 key layout (Vendor_28de_Product_11ff.kl, incl. D-pad buttons), and exports `LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1`; the launcher's `_gamepad_links` worker (agent v85) keeps `/dev/input/eventN` links to Steam Input's virtual pads (uinput, 28de, "Microsoft X-Box 360 pad N") in step while the game runs, so a pad Steam makes later (controllers woke up, reconnected) is added and a gone one removed (Android's EventHub follows through inotify). Check: `<base>/gamepad.log` (`pads: event5` / `pads: none`), launch.log `EventHub: New device … pad`, `podman exec lepton-steamlaunch-<appid> dumpsys input` lists the pad. Steam Input must be on for the shortcut; Steam activates the shortcut's own layout while the game has focus (controller.txt `Queueing activation for controller: 0 app: <shortcut appid as signed int>`), and Steam's UI layout (app 769) while the dashboard is open. Off for one start: `FRAMEPORT_NO_GAMEPAD=1 %command%` |
-| Game starts in English and has no in-game language choice | Game follows Lepton's English Android locale | Choose Game language under Customize (`device.language`), then Update on Frame; the game must include the selected language |
 | 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
 | Black screen, audio works, GLES engine with direct VrApi | Mesa rejects Quest-style GLSL | `frame.gl_shim` (logs `GLShim: SHADER COMPILE FAILED` + source lines) |
 | Black screen, audio works, log `Unsupported VrApi layer type N` | bridge drops frames containing that layer | extend the bridge (cylinder=3 is converted to a quad already) |
 | Only some draws visible (for example controllers) + `glGetError 0x502` | multiview shaders used on single-view FBOs | GL shim `gl_hide_multiview=1` (default) |
 | Own GLES engine (OpenXR, not VrApi): eye view fine, but HUD / menu / PDA panels black (for example Doom3Quest, GitHub #77; no error in the log) | every shader declares `layout(num_views=2) in;`, also the ones drawn into the engine's single-layer offscreen framebuffers (2D textures/renderbuffers); OVR_multiview makes such draws INVALID_OPERATION and Mesa drops them (`draw_validate.c`), Quest's driver doesn't | `frame.gl_multiview_fbo` (opt-in, experimental: `libfpglmv.so` interposes GLES and draws those cases with a single-view twin of the program; logs `GLMV: twin built: program N -> M`, per-5-s `single-view draws` counters; `gl_mv_debug=1` adds glGetError checks; triage `gl-multiview-twin-failed`). Alternative: the game's own fix (two-layer multiview pool, Xandrix's patch in #77) |
-| Team Beef idTech 4 port (PreyVR, GitHub #306): main menu black except the mouse cursor, loading screen fine, 72 fps, no GL error; one game thread at 100 % CPU | the game clock runs 1000 / refresh ms per tic (`USERCMD_MSEC`, from xrGetDisplayRefreshRateFB). The Frame's runtime lacks XR_FB_display_refresh_rate and OVRPort's dispatcher answered 0 Hz: 0 ms tics, the async thread spins (millions of tics/s) and `com_frameTime` stays 0, so the menu GUI stays at its first animation step (everything hidden) | FrameBridge (default, no setting) answers xrGetDisplayRefreshRateFB with the measured rate (1 / predictedDisplayPeriod, else 72 Hz); log `refresh rate: runtime reported 0.0 Hz (result -7), reporting 72.0 Hz`. Found with `gl_mv_debug=2` (`frameport settings <pkg> gl_mv_debug=2`, needs `frame.gl_multiview_fbo`): only 2 draws per frame (backdrop + cursor) and `trace clocks: com_frameTime=0` |
 | Upside-down image in a GL bridge game | GL images start at the bottom row | fixed in the bridge (swap angleUp/Down for GL chains) |
 | UI panels upside down (AC Nexus) | XrCompositionLayerImageLayoutFB VERTICAL_FLIP unsupported | adapter `flip_emul=1` (default); rotating quads makes them vanish |
 | Passthrough black (BAM) | XR_FB_passthrough missing | adapter `passthrough_emul=1` (default) + `patch_force_passthrough` for MR-only games |
-| Mixed reality inside out: the room shows on the game's objects, black where the room should be (Unreal, for example Star Wars: Beyond Victory, GitHub #329) | Unreal keeps 1 - coverage in the scene alpha and OVRPlugin chains XrCompositionLayerAlphaBlendFB (colour factors ONE_MINUS_SRC_ALPHA / SRC_ALPHA, `layer_debug` shows `n=1000041001(3,2/3,2)`) to the eye layer; the Frame's runtime ignores it | adapter `alpha_blend_emul=1` (default, Vulkan): inverts the alpha of the eye images in place while passthrough is emulated; logs `alpha_blend: inverting the alpha of swapchain=…` |
 | Quest Touch controllers (or none) shown in a game that uses Meta's runtime controller models | XR_FB_render_model missing on the Frame | adapter `controller_models=1`: the agent converts the Frame's SteamVR controller models to glb at install, the adapter serves them. Games with their own controller meshes aren't affected (none of the 34 catalog games use runtime models) |
 | `overportOXR: Unknown proc addr: xr…` for a function the adapter emulates | overport's dispatcher only forwards functions in its own table | route the plugin's lookups through `native/xrshim` (done for XR_FB_render_model when `controller_models=1`) |
 | MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
@@ -206,8 +184,6 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Unity game crashes or hangs right as Vulkan starts, after `SLZ Graphics plugin loading!` and OVRPlugin's pre-init `xrDestroyInstance`: SIGSEGV with pc 0 (or pc == fault address in an unloaded library), x16/x23 in `libSLZQuestNative.so` (BONELAB 1.2974) | Stress Level Zero's graphics plugin hooks Unity's Vulkan start-up (IUnityGraphicsVulkanV2 interception: vkCreateInstance/vkCreateDevice) and vkCreateSampler; its vkCreateInstance wrapper calls an invalid pointer on the Frame | `frame.slz_vulkan_hooks` (its two registrations become no-ops; Unity starts Vulkan itself; ~35 s of shader prewarming without its pipeline cache) |
 | Unity game shows a picture but the player body is frozen: no head tracking, the controllers stay on the model, no buttons, although OpenXR input works (BONELAB 1.2068, Oculus XR Plugin) | OVRPlugin reports the headset as not worn (`ovrp_GetUserPresent2` → 0) a few seconds after start, and the game's rig only follows a present user (Marrow `XRHMD.IsUserPresent` = Unity's HMD `UserPresence`) | `frame.unity_user_presence` (the Oculus XR Plugin's lookup → `libfp_ovrp.so`, reports present; log `user presence: OVRPlugin 0 …`) |
 | Unreal 5 game crashes at its first render pass, backtrace `vulkan.freedreno.so` ← `libVkLayer_fossilize.so` ← `libfp_vk.so (create_render_pass2)` (Metro Awakening) | a subpass without a depth attachment names a depth/stencil resolve attachment; the Frame's Turnip reads the missing depth attachment (NULL) | the Vulkan shim drops that resolve (always, FramePort after 0.11.0; log `dropped the depth resolve of subpass N (no depth attachment)`); triage `unreal-vulkan-driver-crash` |
-| Unreal game crashes before its first frame: SIGSEGV `fault addr 0x10` on the main thread, backtrace all `libUnreal.so` above the linker's `soinfo::call_constructors` (inside `System.loadLibrary`), right after `Parsing commandline` (GitHub #349, Transformers Beyond Reality) | The game is built with Unreal's Binned3 allocator, which reserves its whole range while the library loads: one `mmap(NULL, 76 GiB, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS)`. Quest grants it; the Frame's kernel (heuristic overcommit, mode 0) refuses a writable private mapping larger than RAM + swap, and Unreal's out-of-memory handler ("Ran out of memory allocating ...") dereferences its not-yet-created log | `frame.unreal_noreserve` (suggested from analysis `unreal_binned3`): every such anonymous read/write mmap in the engine library gets `MAP_NORESERVE` (one instruction each: `mov w3, #0x22` → `#0x4022`); triage `unreal-reserve-refused`. Found by disassembling the crash pc (the OOM handler; its UTF-16 format string) and the caller's `mov x0, #0x1300000000` |
-| Unreal Vulkan game fails on its first frames and OVRPlugin reports `foveationImage = 0x0, width = 0, height = 0` (for example Transformers Beyond Reality: Redux, #349) | Quest FB foveation remains advertised by OVRPort's dispatcher despite `foveation_fix=1`. This is a hypothesis for the failure, not a confirmed cause: Redux's alternate no-ForceQuit build dereferences a null graphics-pipeline-state object during Vulkan pipeline binding, not a density image | Diagnostic `adapter.hide_fb_foveation=1` (off by default, Vulkan): filters the dispatcher and runtime extension lists/instance requests, removes foveation create/image chains and refuses profile creation/updates. Rebuild with the adapter **and xrshim** artifacts, then compare first-frame survival and Unreal's original fatal log. Does not disable Valve FDM injection. Device verification pending |
 | Unreal 5 game crashes in `vulkan.freedreno.so` called straight from `libUnreal.so` right after its swapchains, or a few seconds into the first frames (Metro Awakening) | Unreal turns on fragment-density-map foveation because Turnip offers VK_EXT_fragment_density_map, then records barriers (to `FRAGMENT_DENSITY_MAP_OPTIMAL`) and image views (2D array R8G8) for a density map the Frame never provides (VK_NULL_HANDLE); Turnip dereferences it | adapter `vk_hide_fdm=1` (the game doesn't see the extension) + `vk_spec_fixes=1` (leaves out null-image barriers, refuses null-image views); triage `unreal-fdm-missing`. Found by disassembling the driver at the crash pc: the struct offsets (0x58 = VkSubpassDescription2, 0x48/0x60 = image barriers, viewType/format in registers) name the call |
 | Own-engine game crashes in `je_free` from its own library on the first frames (Roblox) | the game frees memory it doesn't own; not the Vulkan shim or the format fallback | unsupported |
 
@@ -291,10 +267,19 @@ Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they
 | Proton game hangs at start in a headless/SSH launch; log `no driver could be loaded` / `explorer process failed to start` | no display session (DISPLAY/GAMESCOPE_WAYLAND_DISPLAY) | the Proton launch.sh takes them from the running Steam (built in) |
 | Unreal game starts (window created) then `CrashReportClient` runs | the game crashed under Proton; often no VR runtime reached it (Revive off) | keep `pcvr.revive` on (repacks' bundled LibRevive64.dll isn't loaded by itself); read the game log + crash summary in the launch log |
 | `VK_ERROR_DEVICE_LOST` under DXVK | freedreno GPU hang | `pcvr.proton_log` to capture; PC mode |
-| Game page shows another game's description or screenshots, or they stay wrong after Rename (GitHub #377: "Lollipop" matched an adult Steam game) | Store details were looked up by title and kept after a rename; Steam exact-title matches had no content check | Rename/reset drops title-matched details and screenshots and fetches them again under the new name (package-matched details and custom art stay); Steam matches with sexual-content descriptors are rejected for details and artwork |
-| `Rec.709 color space unavailable`, the game quits before xrCreateSession (GitHub #336, OutRun Quest VR) | The Frame's runtime has no XR_FB_color_space | Adapter setting `fb_color_space=1` (triage `color-space-missing` suggests it): FrameBridge offers the extension (v3), reports Rec.709 and accepts any colour space without converting. Reaches games with their own OpenXR loader; OVRPort's dispatcher can't forward the new functions. Device-unverified |
 
-Foveation mode, radius and diagnostic test are per-game user preferences (discussion #365), excluded from
-shared working recipes. Saving Game settings rewrites launcher exports through `set_settings`; changes apply
-at the next game start without rebuilding or reinstalling. Existing builds need one update for dormant diagnostic
-support. Catalog `device.foveation` defaults and the guarded Batman/Climb 2 APK compatibility work remain supported.
+## Experimental Rift through FEX
+
+These signatures apply to PC VR logs (`kind: pcvr`). Compatibility profiles describe static evidence until a
+headset test verifies them. Meta's entitlement and runtime signature checks remain intact.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Meta runtime says `Missing entitlement` | The signed-in Meta account does not own the game | Informational, not a FramePort bug; use an account that owns it. No bypass or patch is offered (`fex-missing-entitlement`) |
+| `OVRServer` reports `install_available` | The matching app is not registered as installed | Reinstall/register through the FEX install flow with the matching Meta manifest (`fex-registration-missing`) |
+| `Rejecting new committed universe since IMU fallback is active` | SteamVR has not acquired headset tracking since boot | Wear the headset once and wait for tracking before retrying (`fex-imu-fallback`) |
+| `Service invocation completed`, followed by confirmation `OVRLibrarian still running` | Wine Mono's OVRLibrarian never exits under FEX and blocks later clients | End only OVRLibrarian.exe after completion; check that the FEX launcher's cleanup runs. Completion alone is healthy (`fex-librarian-stuck`) |
+| `vkd3d` fails to create/initialize a device | D3D12 renderer initialization failed | Check GE's bundled vkd3d-proton, clear inherited wined3d/no-D3D12 flags, verify FEX Vulkan thunk to Turnip (`fex-vkd3d-init`) |
+| `wined3d` fails to initialize OpenGL | No working guest GL/display route; the Vulkan thunk does not provide a GL thunk | Inspect guest Mesa renderer and display access; prefer the game's D3D9/11 route if available (`fex-wined3d-init`) |
+| `ReviveInjector` reports failure to start/inject | Wrong exe, missing x64 Revive files or injection failure | Check executable and shared GE prefix; use OpenVR mode, without `/openxr`. OpenVR-only games can run directly (`fex-revive-injector`) |
+| Robo Recall has no IME CVar in ApplicationCore or Slate | Older modular Unreal keeps FWindowsApplication in Core | Search `*-Core-Win64-Shipping.dll` with the same anchored CVar finder; this surveyed build has the constructor default at RVA `0x15ffe5`. Never patch an unanchored boolean based on an assumed member offset |

docs/rift-fex/compat.md

@@ -0,0 +1,276 @@
+# Rift through FEX: compatibility stream C
+
+Compatibility is static evidence until a headset test verifies a build. First Contact remains the only verified
+profile. No game entitlement, Platform SDK or Oculus signature checks are changed. A Meta account without ownership
+must receive **Missing entitlement**; this is an informational result, not a bug to work around.
+
+## Implementation and profile schema
+
+`agent/fexrift_compat.py` registers a `GAME_INFO_HOOKS` handler, launcher environment handler and install-check
+handler. `game_info()` obtains the exe and launch arguments from Meta's manifest, then applies a matching profile.
+The helper reports `verified: false` for likely/untested builds. Likely profiles install with a warning (also in
+`checks.profile_warnings`, which the parent agent forwards); untested builds need `force_unverified`; blocked
+profiles are refused even with force. `checks` records the selected profile, status, route, cache eligibility and
+32-bit warning. No agent version bump is included.
+
+`agent/fexrift_games.json` is data, not executable configuration. Its `_comment` describes these fields:
+
+| Field | Meaning |
+|---|---|
+| `match.canonical_names` | List of exact Meta canonical app names; no fuzzy title matching |
+| `match.sha256` | List of exact executable SHA-256 strings |
+| `match.executables` | List of `{name, size}` objects: case-insensitive basename **and** exact byte size must match |
+| `status` | `verified`, `likely`, `untested`, `blocked` |
+| `graphics` | `d3d11` (default), `d3d9`, `d3d12`, `opengl`, `vulkan` |
+| `env` | String environment values |
+| `ime_patch` | Optional fallback `{rva, old, new}`, with integer/hex RVA; null means no fallback |
+| `fp_mem` | `off`, `candidate` (informational, no preload), `enabled` (verified per-game opt-in) |
+| `bigcache_mb` | Cache size when enabled, default 256 |
+| `dxvk` | List of dxvk.conf lines; launcher writes `$A/dxvk.conf` and exports `DXVK_CONFIG_FILE` |
+| `args` | Optional argument list override; omit to preserve manifest arguments |
+| `notes` | Evidence and first-launch cautions |
+| `revive` | Optional, defaults true; false launches an OpenVR-only game directly |
+
+Match alternatives are OR, while basename and size within an executable match are AND. Multiple matching profiles
+are refused. With no `match`, the profile key is the exact canonical name (legacy First Contact compatibility).
+The surveyed profiles use basename+size because the owner's folders do not establish authoritative Meta canonical
+names; their keys identify profiles, **not** presumed Meta app IDs. They preserve the manifest's exe and arguments.
+A different store build/size needs a new survey or an explicit untested install; do not guess its identity.
+
+A SHA-only identity should be rechecked against the original executable after any game-byte patch: patching changes
+its hash. Prefer canonical names or basename+size for profiles that need the IME fix. Size matches choose launch
+settings only; the anchored finder independently verifies the bytes before patching.
+
+`fp_mem: candidate` is set only when the surveyed lower bound of the UE version is >=4.18 (Binned2 big-block path).
+It never enables the unzeroed cache. Every other game needs evidence that it fully overwrites reused memory before
+an opt-in. First Contact's existing explicit environment/cache settings remain enabled.
+
+## Older Unreal: Robo Recall
+
+The premise that Robo Recall lacks `Slate.DeferWindowsMessageProcessing` was a search-location error. Its modular
+`RoboRecall-Core-Win64-Shipping.dll` contains the UTF-16 CVar at file offset `0x1e1bb0`; the existing anchored finder
+returns RVA `0x15ffe5`, old `c7860002000001000000`, new `c7860002000000000000`. This changes the constructor's
+`mov dword ptr [rsi+0x200],1` immediate to zero, with the existing expected-byte guard and `.orig` backup.
+
+Older Unreal placed `FWindowsApplication` in Runtime/Core; newer trees split it into Runtime/ApplicationCore.
+`bAllowedToDeferMessageProcessing` and `GetDeferMessages` control the same Windows message deferral path, so an old
+engine is not exempt from the IME deadlock merely because ApplicationCore/Slate lack the marker. The extension
+extends `find_ime_target()` to search `*-Core-Win64-Shipping.dll` (and Win32/Core.dll forms), using the unchanged
+CVar/xref/storage finder. It never patches a guessed member offset. Synthetic tests cover successful Core discovery,
+repeat installs, and a CVar name without an anchored reference. No Unreal source checkout was available offline;
+the observed binary is the evidence for this build, rather than an inferred engine-version exemption.
+
+## Graphics and remaining device questions
+
+DXVK handles D3D9/11; D3D12 uses GE's own vkd3d-proton selection. The launcher clears inherited
+`PROTON_USE_WINED3D`, `PROTON_NO_D3D12` and `PROTON_NO_D3D11`, keeps `FP_VKTHUNK=1`, and lets Proton select/copy its
+shipped DLLs. It makes no renderer DLL edits in a game. `checks.vkd3d_dlls` reports installed d3d12 DLLs under
+`files/{lib,lib64}/wine/vkd3d-proton/{,x86_64-windows/,i386-windows/}`. These are discovery candidates, not a hardcoded
+installation prerequisite. GE-Proton's script/archive was not available locally, and network/device access was
+prohibited: verify the exact 11-7 layout and its script logic on the device before claiming D3D12 support.
+
+The `opengl` profile exports `PROTON_USE_WINED3D=1`. A native OpenGL game still calls OpenGL directly; this flag
+selects Wine's GL renderer for any D3D calls. There is **no configured FEX GL thunk**. Host acceleration would need
+FEX's matching guest libGL/libEGL thunk libraries, host counterparts and enabled GL thunk configuration, with a
+working display/GLX/EGL bridge. Guest rootfs Mesa might instead use software rendering or Zink through Vulkan;
+inspect the actual renderer before attributing a game failure to Wine or promising hardware acceleration.
+The Climb prefers its imported D3D9 route; imports alone do not prove which renderer its config selects.
+
+A 32-bit exe is flagged in the survey and install checks. GE WoW64 under FEX still needs working 32-bit graphics
+and SteamVR's 32-bit vrclient bridge; it is not promoted to likely based on engine alone. XAudio2 and Bink are facts
+to watch; Media Foundation is flagged for a real movie-playback check. Anti-cheat detected by filenames/imports
+makes a generated profile blocked. Absence of a static marker is not proof that runtime-loaded middleware is absent.
+
+## Reproduce the offline survey
+
+Use an isolated `FRAMEPORT_HOME`; never set `FRAMEPORT_WINDOWS_DATA`. No program in a dump is executed, no archive
+is extracted, and no file in a game folder is written. The report contains local paths and must stay uncommitted.
+
+```bash
+export FRAMEPORT_HOME="$PWD/.home"
+uv run python - <<'PY'
+import subprocess, sys
+from pathlib import Path
+root = Path('/mnt/d/Backup Data/Misc/emus/VR_META_QUEST/ARMGDDN_PCVR_OCULUS')
+cmd = [sys.executable, 'scripts/rift_fex_survey.py', '--out', '.home/survey']
+for folder in sorted(root.iterdir()):
+    if folder.is_dir():
+        cmd += ['--folder', str(folder)]
+subprocess.run(cmd, check=True)
+PY
+```
+
+Outputs: `.home/survey/survey.json`, `survey.md`, and `profiles.json` (ready to paste, but review argument overrides
+and direct OpenVR routing). The Unreal pak/ini reader is deliberately left in place for stream B's extraction.
+
+## Owner's library: static results
+
+All 19 selected game exes are x86_64; no selected 32-bit client was found. Eighteen use the Platform SDK; Rick and
+Morty is the exception. The table contains **10** likely titles (including Robo Recall and all three Vader episodes),
+plus nine untested titles. Profile IDs below are data keys matched by exe basename+size, not canonical app names.
+`candidate` means cache eligibility only; it is off at launch. No surveyed game is promoted to verified.
+
+| Game / profile ID | Route | Status | Platform SDK | fp_mem | Watch at first launch |
+|---|---|---|---|---|---|
+| Arktika 1 / `arktika-1` | d3d11 trial; API undetected | untested | yes | off | Establish actual renderer and custom-engine startup; do not infer D3D11 from this default |
+| Asgard's Wrath / `asgards-wrath` | d3d11 | likely | yes | candidate | Large-block stalls/memory, Media Foundation movies, entitlement |
+| Brass Tactics / `brass-tactics` | d3d11 | likely | yes | off | Media Foundation movies, tracking and IME startup |
+| Chronos / `chronos` | d3d11 | likely | yes | off | Older UE D3D11 path, movies and controller input |
+| Defector / `defector` | d3d11 | untested | yes | off | Custom-engine startup and Bink cutscenes |
+| Hubris / `hubris` | d3d11 | likely | yes | candidate | XAudio2 sound, Media Foundation movies, shader/GPU cost |
+| Lies Beneath / `lies-beneath` | d3d11 | likely | yes | candidate | Platform SDK delay load/entitlement; IME fix and movies |
+| Lone Echo / `lone-echo` | d3d11 (also imports d3d9) | untested | yes | off | Runtime tracks client, entitlement; custom-engine startup and allocator stalls |
+| Lone Echo II / `lone-echo-2` | d3d12 | untested | yes | off | vkd3d-proton DLL layout and Vulkan device creation on Turnip |
+| Rick and Morty / `rick-and-morty-virtual-rick-ality` | opengl; direct OpenVR | untested | **no** | off | Actual GL renderer/acceleration; SteamVR bridge; speech WinRT; never inject Revive |
+| Robo Recall / `robo-recall` | d3d11 | likely | yes | off | Core DLL IME fix at `0x15ffe5`; Meta entitlement and tracking |
+| Skydance's Behemoth / `skydances-behemoth` | d3d11 | likely | yes | candidate | XAudio2 sound, Media Foundation movies and heavy GPU/memory use |
+| Stormland / `stormland` | d3d11 | untested | yes | off | Custom engine, Media Foundation and Bink cutscenes |
+| The Climb / `the-climb` | d3d9 preferred; also imports GL | untested | yes | off | Confirm CryEngine selects D3D9 and DXVK; GL import alone is not a selected renderer |
+| The Unspoken / `the-unspoken` | d3d11 | untested | yes | off | Custom engine, Media Foundation and Bink cutscenes |
+| Vader Immortal I / `vader-immortal-episode-i` | d3d11 | likely | yes | off (UE range starts at 4.16) | Movies, controller input, startup IME; leave MSAA at its game default |
+| Vader Immortal II / `vader-immortal-episode-ii` | d3d11 | likely | yes | off (UE range starts at 4.16) | Movies, controller input, startup IME; leave MSAA at its game default |
+| Vader Immortal III / `vader-immortal-episode-iii` | d3d11 | likely | yes | off (UE range starts at 4.16) | Movies, controller input, startup IME; leave MSAA at its game default |
+| Wilson's Heart / `wilsons-heart` | d3d11 | untested | yes | off | Custom-engine startup and Bink cutscenes |
+
+## Exact maintainer device checks (not executed here)
+
+Only run one FEX game at a time: they share the Wine prefix and wineserver. The following uses the existing CLI;
+stream A/B may add a direct login/install path at integration. Set `FRAMEPORT_HOME` to the development data folder
+with the paired Frame configuration, then keep using that folder. The example `.home` is isolated from normal app
+data and needs a paired Frame first. Never set `FRAMEPORT_WINDOWS_DATA`.
+
+1. On the development PC, upload the integrated helper/extensions/profiles and verify setup:
+
+   ```bash
+   export FRAMEPORT_HOME="$PWD/.home"
+   export FRAMEPORT_EXPERIMENTAL_FEX=1
+   uv run frameport fex setup
+   uv run frameport fex status
+   ```
+
+   Wait for setup to finish. Expect `proton`, `prefix` and `fex` true; `apps` lists Meta canonical names. No token or
+   sign-in URL is needed in the output. If importing from an already signed-in PC Wine prefix, use the exact app
+   name from its Meta manifest filename (replace both example values):
+
+   ```bash
+   app='actual-meta-canonical-name'
+   prefix='/path/to/signed-in/wine-prefix'
+   uv run frameport fex import-login "$prefix" --app "$app"
+   uv run frameport fex install "$app"
+   ```
+
+   For a matching likely profile, expect `verified: false`, `checks.profile_status: likely`, a profile ID and
+   `checks.profile_warnings`; no `--force-unverified` should be needed. If the downloaded build differs from the
+   surveyed basename+size, expect refusal and review its own survey before forcing. An explicitly blocked profile
+   must still refuse with `--force-unverified`. An untested game needs that switch. The PC reporter also warns
+   that the game has not been verified on the Frame.
+
+2. On the Frame, wear the headset once after boot and wait for tracking. Launch from the Steam shortcut. For these
+   checks in a Frame terminal, replace `app` with the same canonical name:
+
+   ```bash
+   app='actual-meta-canonical-name'
+   pkg="rift.${app//-/_}"
+   anchor="$HOME/Applications/quest-frame/$pkg"
+   python3 - "$anchor/deployment.json" <<'PY'
+   import json, sys
+   d = json.load(open(sys.argv[1]))
+   for key in ('profile', 'profile_status', 'profile_warnings', 'graphics', 'fp_mem', 'exe_32bit', 'wow64', 'vkd3d_dlls'):
+       if key in d.get('checks', {}):
+           print(key, d['checks'][key])
+   PY
+   rg 'FramePort FEX: graphics=' "$anchor/launch.log"
+   rg 'PROTON_USE_WINED3D|PROTON_NO_D3D12|DXVK_CONFIG_FILE|export FP_MEM' "$anchor/launch.sh"
+   ```
+
+   Expect the profile route. Candidate caches must have no `export FP_MEM=1`. For Rick and Morty also run
+   `rg 'taskset.*proton' "$anchor/launch.sh"`: the command must invoke the game directly with no ReviveInjector.
+   A graphics route marker proves selection of launcher settings, not successful rendering. Check both eyes,
+   tracking/controllers, sound and a movie in the headset before changing a profile to verified.
+
+3. For Robo Recall, `checks.ime.file` should name `RoboRecall-Core-Win64-Shipping.dll` and `fixes.ime_patch` should be
+   `patched` on first install and `already` on repeat. On the Frame, verify the original backup exists and the
+   constructor immediate is zero (only the installed copy is read):
+
+   ```bash
+   python3 - "$anchor/deployment.json" <<'PY'
+   import importlib.util, json, os, sys
+   d = json.load(open(sys.argv[1]))
+   path = os.path.join(os.path.dirname(d['exe']), d['checks']['ime']['file'])
+   helper = os.path.expanduser('~/.local/share/frameport/fexrift/artifacts/fexrift.py')
+   spec = importlib.util.spec_from_file_location('fx', helper)
+   fx = importlib.util.module_from_spec(spec)
+   spec.loader.exec_module(fx)
+   b = open(path, 'rb').read()
+   p, reason = fx.find_ime_patch(b)
+   assert p and b[fx.pe_offset(b, p['rva']):fx.pe_offset(b, p['rva']) + len(bytes.fromhex(p['new']))] == bytes.fromhex(p['new']), reason
+   assert os.path.isfile(path + '.orig')
+   print('Core IME default zero; original backup present')
+   PY
+   ```
+
+4. For Lone Echo II (untested), install with `--force-unverified`. In a Frame terminal inspect only GE's files and
+   script; no network fetch is needed:
+
+   ```bash
+   r="$HOME/.local/share/frameport/fexrift"
+   rg --files "$r/ge/files" | rg '/vkd3d-proton/.*/?d3d12(core)?\.dll$|/vkd3d-proton/d3d12(core)?\.dll$'
+   rg -n 'PROTON_USE_WINED3D|PROTON_NO_D3D12|vkd3d-proton|dxvk' "$r/ge/proton"
+   ```
+
+   Expect bundled vkd3d-proton and script selection when wined3d/no-D3D12 are unset. `checks.vkd3d_dlls` should name
+   the installed layout. A vkd3d initialization failure is triaged `fex-vkd3d-init`; a successful Vulkan device plus
+   frames in both eyes is the first actual evidence of this route. If the file layout differs, update discovery
+   candidates without copying DLLs into the game. For GL, inspect the active **guest** renderer; an installed host
+   Mesa library or the Vulkan thunk does not establish guest GL acceleration.
+
+5. Exercise each triage signature offline on the PC with
+   `uv run pytest -q tests/test_fexrift_compat.py -k triage`. On-device expected strings are `Missing entitlement`,
+   `OVRServer ... install_available`, SteamVR's IMU-fallback message, vkd3d/wined3d initialization failure, or a
+   ReviveInjector failure. Do not dump entire Meta log files: they may carry sign-in data. A Librarian completion
+   line alone must not diagnose a hang. After completion, confirm persistence using `pgrep -f '[O]VRLibrarian.exe'`;
+   only if it remains alive, record the safe diagnostic `OVRLibrarian still running` alongside the completion
+   marker. The launcher now emits the fixed combined marker itself if Librarian persists after cleanup and
+   completion is present; it never mirrors the log. The combined trace matches `fex-librarian-stuck`. Stop only that process after completion with
+   `pkill -9 -f '[O]VRLibrarian.exe'`; the normal launcher already does this. For an unowned title, accept Meta's
+   Missing entitlement result and stop that game test.
+
+Undo: exit the game in Steam before touching files. Remove the selected profile from the device copy of
+`artifacts/fexrift_games.json` and rerun install with `--force-unverified` to regenerate the default D3D11/Revive
+launcher. For an OpenVR-only game, retain `revive: false` in an untested profile when comparing graphics routes.
+Remove the anchor's `dxvk.conf` when no longer used. To undo the IME fix, restore **only the installed binary**
+from its `.orig` copy after stopping the game; for example, on the Frame:
+
+```bash
+python3 - "$anchor/deployment.json" <<'PY'
+import json, os, shutil, sys
+record = json.load(open(sys.argv[1]))
+path = os.path.join(os.path.dirname(record['exe']), record['checks']['ime']['file'])
+shutil.copy2(path + '.orig', path)
+print('Installed IME binary restored')
+PY
+```
+
+Do not delete the shared prefix to undo a profile: it holds Meta's runtime and the owner's login/saves. Game dumps
+are never modified. Re-running install reapplies the anchored IME fix; to compare launches, restore after install
+and before Play.
+
+## Validation in this worktree
+
+- Offline survey completed for all 19 folders with no per-game errors. Every surveyed executable matched exactly
+  its intended committed profile through the compatibility hook. Ten profiles are likely, nine untested; the
+  separate First Contact profile stays verified. No selected or alternate candidate exe was 32-bit. No static
+  anti-cheat marker was found; this does not rule out runtime-loaded middleware.
+- Focused FEX/survey/triage tests: **96 passed, 1 skipped**. Ruff passed for the new extension, survey and their tests.
+- `uv run python scripts/patch_docs.py` was run; `--check` passes and generated patch docs needed no committed change.
+- Final whole-suite run: **1,646 passed, 43 skipped, 11 failed, 16 setup errors**. All 27 unsuccessful cases failed
+  at local `socket()` creation with `PermissionError: [Errno 1] Operation not permitted`. They are existing local
+  HTTP/pairing/stream tests in `test_deeplink`, `test_devkit`, `test_install_links_extra`, `test_livestream`,
+  `test_setup_url`, and `test_ui_state`. They need a runner allowing loopback sockets; no application or test code
+  was changed to hide this restriction. Re-run the full suite there before integration.
+- The prebuilt virtual environment was used with `UV_CACHE_DIR=/tmp/frameport-rift-uv UV_NO_SYNC=1` because the default
+  uv cache is read-only and offline metadata resolution cannot install hatchling. For example:
+  `UV_CACHE_DIR=/tmp/frameport-rift-uv UV_NO_SYNC=1 uv run pytest -q`.
+- No device or external network access was attempted. D3D12, guest OpenGL acceleration, WoW64 and gameplay remain
+  device questions; the steps above specify the evidence needed. The GE script and Unreal source-history checkout
+  were unavailable locally; Robo Recall's actual Core DLL supplies direct evidence for the IME fix instead.

docs/rift-fex/install.md

@@ -0,0 +1,228 @@
+# Stream B: unchanged local Rift copies and Meta library registration
+
+Implemented on `rift/install`. Device validation is pending: this workspace cannot reach the Frame or create local
+network sockets. No entitlement, Platform SDK, runtime signature check, sign-in data or repack crack is changed by
+this work. A Meta **Missing entitlement** response remains a failure to report to the owner.
+
+## Implementation
+
+`frameport fex install --from-library rift.<slug>` takes the Rift entry's `game_dir`, selected `exe`, title and
+`launch_args` (also supported in `analysis.extra`). `--folder DIR [--title T]` uses the existing Rift analyzer to pick
+the exe; ambiguous choices must first be resolved in the library. Optional positional `APP` overrides the generated
+canonical name. Otherwise use the analysis's `canonical_name`, then a lowercase title slug. Local unverified games
+require `--force-unverified` **before** any upload. Existing prefix-game installs still work without either option.
+
+`src/frameport/fexinstall.py` stats the folder and reuses `installer.transfer_link()` and `upload_files()` unchanged:
+fast link, SFTP `.part` append, tar batches, progress and Reporter cancellation all follow the existing install path.
+Finished files are skipped by source size/mtime plus remote size; changed sources discard old completed/partial
+bytes before retry. The source is statted again after transfer. This avoids hashing all source files over NTFS;
+it cannot detect an edit that deliberately preserves both size and mtime. Do not edit the source during an install.
+The free-space check reserves 1 GiB in addition to all pending bytes (conservative when `.part` files already exist).
+
+Skipped, logged and recorded: case-insensitive `*.7z`, `*.7z.0*` split volumes (including backup suffixes), `Data.bin`,
+`AGRepackInstaller.exe`, `VD.bat`, and `*.AG`. Nothing is extracted or executed on the PC. Every included file's bytes
+are uploaded as supplied. Existing install-time generic fixes, including the Unreal IME fix, still run on the Frame
+after registration; they may change the **Frame** executable. The source folder stays unchanged. Symlinks, path
+escapes, duplicate Windows filenames and collisions with Meta-managed copies are refused.
+
+App ID precedence:
+
+1. `[OnlineSubsystemOculus]` in unencrypted pak `Config/DefaultEngine.ini`, then loose `DefaultEngine.ini`,
+   `Oculus.ini` or `OculusConfig.ini`; keys `RiftAppId`, `OculusAppId`, `AppId` in that order. Also checks only the
+   known JSON names `OculusConfig.json` / `oculus-platform-config.json` for `RiftAppId`, `OculusAppId`, `AppId`,
+   `app_id`. IDs must be positive numbers. No binary-string guessing or archive decryption.
+2. Already cached OculusDB data: `details.store_url` (`fetch_details()` retains the ID in this URL, not an explicit
+   Rift-ID field). No lookup/network request is introduced. A Quest-linked details record can name its Quest store
+   product: check this fallback manually before testing a game with no config ID.
+3. `--app-id ID`, used only if no earlier source supplies one.
+
+`app_id_source` records the selected origin. `store_app_id` independently retains the cached store ID when present,
+so a game ID such as First Contact's `1184903171584429` is not lost to store product `1217155751659625`. Manifest
+`appId` uses the selected ID; device tests must establish whether Meta instead requires the store product ID for
+particular builds. The version comes from a version-like folder name, then the exe's PE `.rsrc` FileVersion, else
+`0.0.0`; versionCode is 1. The shared reader moved to `analysis/unreal_pak.py`; the survey re-exports it via imports
+so its existing callers and tests keep working. Stream C should keep these imports when merging its survey edits.
+
+`agent/fexrift_install.py` registers `prepare_local`, `register_local`, `local_info`, `unregister_local` and
+`runtime_state`. Reservations/metadata live in `fexrift/local-games/<app>.json`, with no login information. They also
+allow interrupted pre-registration uploads to resume. Registration hashes each file **on the Frame**, writes
+`<library>/Manifests/<app>.json` and `.json.mini`, and imports the library registry entry through Wine. The extension
+supplies the library manifest to `manifest_launch` / `game_info`; the existing static checks, IME patch and launcher
+then run normally. The install check hook marks `local_copy: true`.
+
+Manifest JSON matches the supplied real First Contact app fixtures: property order (derived properties first),
+types, CRLF, two-space indentation, backslash `files` keys, forward-slash `launchFile`, and mini containing exe
+records only. App packageType `APP`, isCore false, launchFile2D null, launchParameters2D empty string,
+redistributables empty; other defaults come from `MANIFEST_DEFAULTS`. Launch parameters use Windows argv quoting;
+the launcher preserves the original argv list (a small shared launcher hook avoids splitting local-copy arguments
+while retaining the existing profiles' shell-fragment parsing).
+
+Each file has its actual size and whole-file SHA-256, `segmentSize: 10000000`, and one segment per **decimal 10 MB**
+chunk. Each triple is `[0, chunk_sha256, len(zlib.compress(chunk))]`. The fixture's third number is compressed length,
+not uncompressed size. We do not know Meta's opaque first value and use 0 as an explicit placeholder; no fabricated
+CDN identifiers or download URLs are written. Empty files have zero segments. **These manifests describe local
+bytes, not a working Meta CDN repair recipe. Whether Meta accepts the placeholder without scheduling repair is an
+open device question.** Do not initiate an update/repair from Meta's app to validate this.
+
+Internal games: `<PFX>/drive_c/Program Files/Meta Horizon/Software/Software/<app>`, using Meta's existing default
+library registration. `--dest <mount>` must exactly match an available external mount returned by the existing
+`drives` command; existing `resolve_dest()` rejects unusable filesystems. No fallback on a missing card.
+
+External games: `<mount>/FramePort/fexrift-games/<app>`. Their Meta library root is the sibling
+`<mount>/FramePort/fexrift-library`, containing `Manifests/` and a `Software` symlink to `fexrift-games/`. A stable
+UUID5 from the mount path identifies the registry library. A prefix `dosdevices/volume{GUID}` links to the mount,
+and the first unused D:–Y: letter links there too (an existing letter for the same mount is reused). Registry
+`Path` uses `\\?\Volume{GUID}\FramePort\fexrift-library`, `OriginalPath` uses the letter. The default library stays
+default. Mount-path changes require uninstall/reinstall; moving these games through the general Move action has
+not been implemented by this stream. Wine volume discovery and external-library scans need device validation.
+
+Deployment kind stays `frame_fex`, with `source: local_copy`, `app_id`, `app_id_source`, `store_app_id`, `skipped`,
+`dest`, and the existing launcher/check fields. Local-copy uninstall removes its files and both manifests. The last
+game on an external library also removes that library's registry key; the shared default key, shared prefix, saves,
+login and reusable drive/volume links remain. Imported Meta-managed games still keep their files on uninstall.
+There is no agent-version bump; integration must bump it so updated agent commands reach existing devices.
+
+The only other shared-agent helper change sends helper JSON on stdin, avoiding Linux's single-argument size limit
+for large inventories. The extension files are already included by `artifact_files()` and need no packaging change.
+
+## Runtime probe
+
+`--runtime-check` calls the separate bounded `fex_runtime_state` command after install (helper `runtime_state`). It
+reuses an existing OVRServer or starts it with the shared prefix's Wine environment. It examines only newly appended
+Service/OVRServer log text, returning `runtime_state: ready`, `install_available` or `timeout` plus `reused_server`.
+It never returns raw runtime log lines. If it started the server, it kills OVRLibrarian after a fresh invocation
+completion and stops its Wine server at exit; a reused runtime is left running. The polling budget is 95 seconds,
+with bounded process start/probe/cleanup, and the agent imposes a 120-second limit. A reused idle runtime may emit no
+new state line and return `timeout`; that result is inconclusive. The probe does not start the game or prove account
+ownership. The actual log naming/state-line format remains a device question.
+
+## Offline validation
+
+Use a writable UV cache in this sandbox (the default cache is read-only):
+
+```sh
+UV_CACHE_DIR=/tmp/frameport-uv-cache uv run --offline --no-sync pytest -q
+UV_CACHE_DIR=/tmp/frameport-uv-cache uv run --offline --no-sync pytest -q \
+  tests/test_fex_install.py tests/test_fexrift.py tests/test_fexrift_ext.py tests/test_rift_fex_survey.py
+```
+
+The full run reached 1,654 passed, 43 skipped; 11 failures + 16 setup errors all tried to create network sockets
+for existing localhost HTTP/streaming/pairing tests, which this sandbox forbids (`PermissionError: Operation not
+permitted`). Rerun the whole suite without that sandbox restriction at integration. No socket tests were changed
+to conceal this limitation. Triage/patch catalog files were not touched, so `patch_docs.py --check` is not required.
+
+Final follow-up: 1,658 passed, 43 skipped, 27 deselected when excluding precisely those socket-dependent tests.
+The final install/FEX/survey run (including an additional split-volume suffix case) passed 68 tests, 1 skipped.
+Ruff passed for the new modules/tests and the survey; `git diff --check` passed.
+
+## Exact maintainer device test
+
+Run these only on the maintainer's connected PC. Keep `FRAMEPORT_HOME` pointing to this worktree's `.home`, with
+its paired Frame target and Rift library entries. Do not point at the Windows FramePort data directory. Ensure the
+maintainer's integration agent version includes this branch. Wear the headset once after boot; stop any running
+FEX game before the runtime probe (all use one prefix).
+
+```sh
+export FRAMEPORT_HOME="$PWD/.home"
+export FRAMEPORT_EXPERIMENTAL_FEX=1
+uv run frameport fex setup
+uv run frameport fex status
+uv run frameport list
+```
+
+Setup uploads this extension and binaries; it may fetch the signed Meta runtime on the device. Use the login stream
+to sign in with the owner's account first. `status` should show prefix/meta installed and `login: true` without
+printing any session content. Do not copy session files, CoreData or sign-in URL queries into a report.
+
+Pick a library ID the account owns; example (substitute the exact ID from `frameport list`):
+
+```sh
+uv run frameport fex install --from-library rift.robo_recall --force-unverified --runtime-check
+```
+
+Expect `Skipped repack leftover: ...` entries, `Meta app ID ... (config:...)` or the cached/CLI fallback, upload
+progress, `Hash and register the game on the Frame`, then generic checks/Steam registration. Final JSON should
+have `checks.local_copy: true`, with `checks.runtime_state: ready` if Meta emitted the state line. Check
+`app_id_source` and both IDs in deployment with the filtered command below. `install_available` means registration
+did not take; stop and report the IDs, canonical name and manifest shape. `timeout` requires inspecting the log
+format **locally on the device**, keeping any account data private.
+
+A folder install uses the same flow:
+
+```sh
+uv run frameport fex install --folder '/path/to/a/game copy' --title 'My Rift Game' \
+  --app-id 1234567890123456 --force-unverified --runtime-check
+```
+
+Replace the example ID with the game's actual ID; the option is a fallback and does not override a config ID.
+Do not try registering over First Contact already imported by the login tar: the collision refusal is deliberate.
+
+Inspect deployment fields and launch using the paired connection (edit the package below once):
+
+```sh
+uv run python - <<'PY'
+import json
+from frameport.cli import _fex_target
+frame = _fex_target(None).frame
+pkg = 'rift.robo_recall'
+try:
+    games = frame.agent('list_installed', package=pkg, details=True)['games']
+    for game in games:
+        print(json.dumps({k: game.get(k) for k in
+              ('package', 'kind', 'source', 'app_id', 'app_id_source', 'store_app_id', 'skipped', 'dest')}, indent=1))
+    print(frame.agent('launch', package=pkg))
+finally:
+    frame.close()
+PY
+```
+
+Expect `kind: frame_fex`, `source: local_copy`, IDs/provenance, and a Steam launch. In the headset check both eyes,
+controllers, audio and reaching a scene. Look locally for runtime `state: ready`, launcher `FramePort: starting
+Meta's runtime` / `FramePort: starting <title>`, and the game log. **Missing entitlement** is a valid ownership
+failure to report, never a reason to modify the copy or checks. Robo Recall may lack the generic IME patch site;
+report a hang without assuming the registration failed.
+
+Resume: interrupt the upload with Ctrl-C, then repeat the identical install command. Expect completed files to be
+skipped and big `.part` files to continue. Compare a few **non-patched** files' SHA-256 locally on source/Frame;
+manifests should list actual sizes/hashes. No archive, installer, `.AG` file or `VD.bat` should have been uploaded.
+
+External drive: first uninstall the test copy using the rollback below, then:
+
+```sh
+uv run frameport frame drives
+uv run frameport fex install --from-library rift.robo_recall --force-unverified \
+  --dest /run/media/steamos/REPLACE_WITH_MOUNT --runtime-check
+```
+
+Use an actual `usable: true` mount. Expect physical files in `FramePort/fexrift-games/<canonical>`, sibling
+`fexrift-library/Manifests`, a `Software` symlink, a separate registry library, and `runtime_state: ready`. With the
+card removed, reinstall/uninstall must fail explicitly rather than writing/deleting internal storage. Reinsert at
+the same mount path before rollback. Repeat with two games to confirm uninstalling one leaves the second library
+registered; removing the last should remove its registry key.
+
+## Undo
+
+For an installed local copy, end the game in Steam first, then run (substitute its package):
+
+```sh
+uv run python - <<'PY'
+from frameport.cli import _fex_target
+frame = _fex_target(None).frame
+try:
+    print(frame.agent('uninstall', package='rift.robo_recall', remove_shortcut=True, keep_data=True))
+finally:
+    frame.close()
+PY
+```
+
+Expect `removed: true`; game folder, both manifests, deployment and shortcut disappear. Shared prefix, login, saves
+and unrelated games remain. For a cancelled upload that never produced a deployment, remove only its reservation
+and uploaded copy through the helper on the Frame (replace canonical/package; stop shared-prefix games first):
+
+```sh
+python3 -I ~/.local/share/frameport/fexrift/artifacts/fexrift.py unregister_local \
+  '{"app":"robo-recall","package":"rift.robo_recall"}'
+```
+
+Reusable drive links and the empty external library scaffolding can remain for later installs; they contain no
+game/login data. Do not delete the shared prefix to undo one local installation.

docs/rift-fex/login.md

@@ -0,0 +1,178 @@
+# Stream A: Meta sign-in on the Frame
+
+Implemented on `rift/login`. No Frame or network access was used. The PE helper has **not** been compiled here
+(llvm-mingw is unavailable); the browser portal and pipe framing remain device acceptance checks.
+
+## What was built
+
+`frameport fex login [--start-now] [--timeout 900] [--via-pc]` signs in through Meta's own Client.exe, running in the
+existing shared FEX prefix. The default creates a temporary, flat Steam entry named **Meta sign-in (FramePort)**
+using the existing shortcut installer. `--start-now` instead starts a detached user unit without restarting Steam.
+`fex login --stop` repairs interrupted cleanup. All commands require `FRAMEPORT_EXPERIMENTAL_FEX=1`.
+
+`agent/fexrift_login.py` registers `login_start`, `login_status`, `login_stop` and private broker/callback commands.
+`agent/frameport_agent.py` has one separate `fex_login*` block; it passes login messages to the extension over stdin,
+never JSON argv. No agent version bump or changes to other streams' hook points were needed.
+
+The launch script imports Steam's display variables, disables gamescope WSI and preloads, starts the existing Meta
+runtime, waits for OVRLibrarian's completion and kills its stuck process, then starts Client.exe with Proton. Its
+stdout/stderr and Proton logging are disabled because Electron can print authentication URLs. A lock prevents a
+second Client.exe launcher. A private broker must be alive before the launcher can run. Cancellation signals the
+launcher (PID plus kernel start tick, to reject a reused PID), stops Wine, then restores the handler settings. This
+also prevents an interrupted runtime warm-up from starting Client.exe after cleanup.
+
+The prefix's WineBrowser `Browsers` setting temporarily points to `login/fp-open-url`. That helper sends the URL to
+an owner-only Unix socket broker. The broker records only `page_opened_at`, `callback_received_at` and the fixed
+query-free page URL in `login/state.json`. It opens the real URL with host xdg-open, with output discarded. The
+temporary host `frameport-oculus.desktop` invokes `fp-oculus-callback`, which sends the callback to the same broker.
+The broker passes it to `proton run fp_pipesend.exe` **through stdin**. Neither agent forwarding nor Wine invocation
+puts the callback into argv. The desktop protocol invocation itself necessarily supplies `%u` to its short-lived
+handler; do not collect process-command-line diagnostics during sign-in.
+
+`native/fexwine/pipesend.c` sends a NUL-terminated UTF-8 callback to `\\.\pipe\oculus`. It retries a missing or busy pipe
+for about 20 seconds and prints nothing. Exit codes: 0 written, 2 invalid input, 3 pipe unavailable, 4 write failed.
+Only Meta's running client receives the link; a second Client.exe is never started to deliver it.
+
+The extension snapshots the previous WineBrowser value/type, previous host scheme owner, desktop file and mimeapps
+files before registration. `login/restore.json` contains **registration settings only**. A failed restoration leaves
+this record for `--stop` to retry. Normal success, timeout, errors and Ctrl-C all clean up; a broker deadline also
+restores the Frame settings if the PC disconnects (requested timeout plus 180 seconds for Steam shortcut setup).
+An OS kill/reboot can interrupt this cleanup; rerun `--stop` after reconnecting. The temporary shortcut is removed
+by the PC's cancel request, asynchronously through the existing shortcut worker. A disconnected PC cannot remove
+that shortcut until it reconnects, but the launcher refuses to run without its broker.
+
+## PC browser fallback
+
+`--via-pc` keeps the full auth URL **only in broker memory**, draining it once through the agent's SSH status reply
+when the PC explicitly requests `take_url`. Ordinary `fex_login_status` replies never contain the URL. The PC opens
+the page in its default browser and temporarily borrows the `oculus` scheme. The handler POSTs directly to a loopback
+server with a random endpoint; it never uses the normal install-link `links/*.link` inbox. HTTP logging is disabled.
+WSL registers a Windows handler which invokes the WSL Python callback, and opens the sign-in page in Windows.
+
+Windows/WSL restoration exports and restores the **entire** HKCU `Software\Classes\oculus` tree, including arbitrary
+subkeys and value types, or removes it if absent before login. The non-secret export is deleted after restoration;
+if importing it fails, a recovery copy is retained as `<FRAMEPORT_HOME>/oculus-handler-restore.reg` and the error
+names it. Linux restores the exact previous desktop/mimeapps bytes, including an absent default. macOS fallback
+is explicitly unsupported. These temporary registrations are separate from the permanent FramePort install-link
+settings. The PC context restores registration even when sign-in, SSH forwarding or Frame cleanup raises.
+
+Saved login state in `sessions/` and CoreData stays in the prefix. Status only checks whether a non-empty session
+file exists; it does not read its contents, prove the session is unexpired, or imply entitlement to any game. This
+change does not replace Platform SDK DLLs, alter entitlement checks, or access repack archives. A game reporting
+**Missing entitlement** must remain an entitlement failure.
+
+## Offline verification
+
+Run from this worktree, keeping app data isolated in its existing `FRAMEPORT_HOME`:
+
+```sh
+UV_CACHE_DIR=/tmp/frameport-uv-cache uv run --offline pytest -q tests/test_fex_login.py tests/test_fexrift.py tests/test_fexrift_ext.py
+UV_CACHE_DIR=/tmp/frameport-uv-cache uv run --offline ruff check agent/fexrift_login.py src/frameport/fexlogin.py src/frameport/urlhandler.py src/frameport/cli.py tests/test_fex_login.py
+UV_CACHE_DIR=/tmp/frameport-uv-cache uv run --offline pytest -q
+```
+
+The focused suite passed (56 passed, 1 skipped); lint passed. The full suite rerun completed: **1,651 passed, 43 skipped,
+11 failed, 16 errors**. Every failure/error was `PermissionError: [Errno 1] Operation not permitted` from existing
+local HTTP/pairing/live-stream socket tests: this sandbox prohibits socket creation/binding. No other stream's files
+or tests were changed to hide those failures. Run the whole suite on a host permitting loopback sockets before
+integration. No triage/patch definitions were changed, so patch-doc regeneration is not required.
+
+## Exact maintainer device acceptance steps
+
+Use the maintainer's paired Frame configuration; do not copy credentials or configuration into this branch.
+Close any Rift game first: sign-in uses the same Wine prefix and stopping it ends that prefix's processes.
+
+1. Build the PE with llvm-mingw on an x86_64 host (or run the existing full `build_pe_dlls.sh` build):
+
+   ```sh
+   x86_64-w64-mingw32-clang -O2 -s -Wl,--no-insert-timestamp -o artifacts/fexrift/fp_pipesend.exe native/fexwine/pipesend.c
+   uv run python - <<'PY'
+   import hashlib
+   from pathlib import Path
+   root = Path("artifacts/fexrift")
+   sums = root / "SHA256SUMS"
+   lines = [s for s in sums.read_text().splitlines() if s.strip() and s.split()[-1].lstrip("*") != "fp_pipesend.exe"]
+   lines.append(hashlib.sha256((root / "fp_pipesend.exe").read_bytes()).hexdigest() + "  fp_pipesend.exe")
+   sums.write_text("\n".join(lines) + "\n")
+   PY
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex setup
+   ```
+
+   Setup uploads the extension automatically alongside the existing FEX artifacts. Without the exe, login must fail
+   with `fp_pipesend.exe missing: build native/fexwine/pipesend.c and upload it with fex setup`.
+
+2. Record the Frame's current scheme owner (substitute its paired SSH destination for `FRAME`):
+
+   ```sh
+   ssh steamos@FRAME 'xdg-mime query default x-scheme-handler/oculus'
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex login --timeout 900
+   ```
+
+   Expect `Put on the headset: open 'Meta sign-in (FramePort)' in your Steam library.` Open that entry. Allow about
+   two minutes for the runtime warm-up. Confirm Meta's app is a flat window, not another VR game.
+
+3. Choose Meta's sign-in action. Confirm Chromium opens **on the Frame**. The PC should print `Sign-in page opened
+   on the Frame.` Complete the real Meta sign-in. When Chromium asks to open an external app, accept it. This is the
+   unproven Flatpak boundary: OpenURI through xdg-desktop-portal must resolve the host's temporary `oculus` handler.
+   Expect `Sign-in response reached Meta's app on the Frame.` followed by `Signed in.` The CLI closes the app/runtime,
+   restores handlers and requests removal of the Steam entry. Check the Steam entry disappears after the shortcut
+   worker finishes; Steam may restart. The saved login must remain visible as `"login": true` in:
+
+   ```sh
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex status
+   ssh steamos@FRAME 'xdg-mime query default x-scheme-handler/oculus'
+   ```
+
+   The second command must return the original owner (including no owner, if originally unset). Do not dump Meta
+   logs, sessions, CoreData, process argv or the full browser URL for debugging.
+
+4. On an unsigned-in test prefix, or before completing the first sign-in, test the alternate launch route:
+
+   ```sh
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex login --start-now --timeout 900
+   ```
+
+   Expect `Meta's app is starting on the Frame.` There should be no Steam restart and no new shortcut. After a
+   successful login already exists, this command can immediately report `Signed in.` and clean up; that does not
+   exercise a fresh browser exchange. Do not delete the owner's session files just to force this test.
+
+5. If the portal never delivers the callback, cancel with Ctrl-C and use:
+
+   ```sh
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex login --start-now --via-pc --timeout 900
+   ```
+
+   Click sign-in in the Frame's Meta window; the page must open in the PC browser. Expect `Sign-in page opened in
+   the PC browser.`, then the response/success messages above. On Windows/WSL, verify Meta's previous
+   `HKCU\Software\Classes\oculus` registration is restored; on Linux verify the original xdg default. This also
+   needs a real Windows default-protocol check: OS UserChoice policy can override a Classes registration.
+
+6. To inspect progress without exposing URLs, use the ordinary agent status command from a second terminal:
+
+   ```sh
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run python - <<'PY'
+   import json
+   from frameport.cli import _fex_target
+   frame = _fex_target(None).frame
+   print(json.dumps(frame.agent("fex_login_status"), indent=2))
+   PY
+   ```
+
+   Expected keys: `runtime_running`, `client_running`, `page_opened_at`, `callback_received_at`, `signed_in`. Runtime
+   should become true before client; timestamps should appear in that order; signed_in should become true only
+   after a non-empty session file exists. If callback_received_at appears but signed_in never becomes true on a
+   fresh sign-in, the **pipe framing remains unverified**: this implementation uses UTF-8 plus a terminating NUL.
+   Compare against the maintainer's successful spike sender's bytes without printing the URL. Do not retry by
+   starting a second Client.exe, altering entitlement checks, or exposing tokens in diagnostics.
+
+7. Test cancellation during runtime warm-up, timeout with `--timeout 10`, and repeatable repair/undo:
+
+   ```sh
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex login --stop
+   FRAMEPORT_EXPERIMENTAL_FEX=1 uv run frameport fex login --stop
+   ```
+
+   Expect `Meta sign-in stopped. Your saved login stays on the Frame.` both times. No delayed Client.exe should
+   appear after waiting two minutes. Status should show client/runtime false, the previous protocol owner should
+   be restored, and the session files should remain. If SSH was lost, the broker cleans up the Frame by its deadline;
+   reconnect and run `--stop` to remove a leftover shortcut or retry an interrupted restoration.

docs/rift-fex/perf.md

@@ -0,0 +1,276 @@
+# Rift on Frame: performance stream
+
+Implemented offline on `rift/perf`, from `98786ab`. No Frame measurements were made. Existing research measurements
+are in `native/fexwine/README.md`; the commands below are for the maintainer to run on the paired Frame.
+
+## What changed
+
+`agent/fexrift_perf.py` registers `settings_get`, `settings_set`, `perf_prepare` and `bench`. Setup's existing `revive`
+step also builds three Revive folders. The PC's existing artifact discovery uploads the extension automatically.
+The only launcher template changes select the core list, Revive folder and motion-smoothing JSON from variables.
+The agent and CLI have separate settings/bench blocks; the agent version is unchanged.
+
+Settings live in `<ROOT>/settings/<Meta-app>.json`, separately from the game catalog. Defaults come from the game's
+`perf` object, with the existing `env.FP_MEM` / `env.FP_BIGCACHE_MB` as backward-compatible defaults. Overrides take
+precedence. `null` removes an override. Preparation runs on every launch, writes `<app>.dxvk.conf`, and exports
+validated values before Wine starts. Updating a setting requires no reinstall after the new launcher is installed.
+
+| Setting | Default | Accepted values / effect |
+| --- | --- | --- |
+| `dxvk_disable_msaa` | `false` | Boolean; `d3d11.disableMsaa` |
+| `dxgi_sync_interval` | `-1` | Integer -1..4; `dxgi.syncInterval` |
+| `dxgi_max_frame_latency` | `0` | Integer 0..16; `dxgi.maxFrameLatency` |
+| `eye_scale` | `1.5` | Divisor 1.0 / 1.25 / 1.5 (100 / 80 / 67 percent nominal eye size) |
+| `motion_smoothing` | `2` | 0 = default, 1 = force on, 2 = force off; SteamVR `motionSmoothingOverride` |
+| `cores` | `4-7` | taskset CPU list within 0..7; e.g. `4-7` or `0-3,7` |
+| `ntsync` | `true` | Off sets `PROTON_NO_NTSYNC=1`; on unsets it |
+| `fp_mem` | per-game opt-in | Boolean; guest preload enabled only when true |
+| `bigcache_mb` | `256` | Cache minimum block size, 1..6144 MiB (not the total cache budget) |
+| `fp_mem_zero` | `false` | Boolean; `FP_MEM_ZERO=1` opts into lazy zero pages |
+| `wine_large_address_aware` | `true` | Boolean; `WINE_LARGE_ADDRESS_AWARE=1/0` |
+| `fex` | `{}` | JSON map of whitelisted keys with 0/1 values |
+
+FEX keys: `FEX_TSOENABLED`, `FEX_VECTORTSOENABLED`, `FEX_MEMCPYSETTSOENABLED`, `FEX_MULTIBLOCK`,
+`FEX_X87REDUCEDPRECISION`. The first three retain the launcher's default 0, MULTIBLOCK defaults to 1, X87 to 0.
+Unknown keys, arbitrary environment variables, shell fragments and invalid paths are refused. The commands do not
+inspect login files, print process command lines, or change Platform SDK/entitlement checks.
+
+### Revive variants
+
+The checked-in PC `REVIVE_PATCHES` contains the six visibility patches but **does not contain the research eye-size
+redirect described in the brief**. Verified locally against the installed DLL's pinned upstream hash:
+
+- Stock `LibRevive64.dll`: SHA-256 `ef9ffd5342bb4afad9b1c0f4fee1ca3bf32f9d3159d49dd841cc9e22f02663e4`.
+- After the six PC patches: `eda2a449d230832c95734a03e8c83eeb531668ce676693f636e19c315765af4e`.
+- RVA `0x12eab` (file `0x122ab`) is `movss xmm4,[rip+0x4bb15]`, loading a shared 1.0 constant.
+- The research redirect loads the existing 1.5 at **RVA** `0x4eaa4` (file `0x4d4a4`). It is not file offset `0x4eaa4`.
+
+The extension accepts the pinned six-patch upload, optionally with exactly that research redirect. It redirects
+this one load into verified alignment padding at RVA `0x12e9c`, after the preceding function's `ret`. Each copy
+gets its own divisor there. It leaves shared constants untouched. `revive-scales/{1,1.25,1.5}/` hard-links all other
+files to `revive/`; the DLL is unlinked before writing, so variants and the base never modify one another. The
+injector is launched from the selected folder, which is where it finds `LibRevive64.dll`.
+Unexpected hashes, instructions or occupied padding fail explicitly. No Oculus binaries are patched here.
+
+### fp_mem v3
+
+`FP_MEM_ZERO=1` calls `madvise(MADV_DONTNEED)` on exactly the reused part before returning it: the requested prefix
+for short/equal reuse, the cached prefix for a longer allocation. The fresh tail needs no advice. Failed advice
+evicts the cache entry and falls through to real mmap, rather than returning stale contents. Without ZERO, v2's
+unzeroed behavior remains. Debug output counts advice calls, discarded bytes and failures.
+
+The fake-syscall host harness in `tests/test_fex_perf.py` checks equal, short and long reuse, advice failure,
+unzeroed compatibility, and `FP_MEM_ZERO=0`. It skips only the C test when no host C compiler is installed.
+The guest artifact has **not** been rebuilt in this stream. On an x86_64 glibc 2.34-compatible build host, from the
+repository root, the maintainer must run:
+
+```sh
+gcc -O2 -shared -fPIC -o artifacts/fexrift/fp_mem.so native/fexwine/fp_mem.c -ldl -lpthread
+python3 - <<'PY'
+import hashlib
+from pathlib import Path
+root = Path('artifacts/fexrift')
+manifest = root / 'SHA256SUMS'
+lines = manifest.read_text().splitlines()
+hash_ = hashlib.sha256((root / 'fp_mem.so').read_bytes()).hexdigest()
+lines = [f'{hash_}  ./fp_mem.so' if line.endswith('  ./fp_mem.so') else line for line in lines]
+manifest.write_text('\n'.join(lines) + '\n')
+PY
+```
+
+This is an **x86_64 guest** shared library, even though wineserver is native aarch64. Commit the rebuilt artifact
+and checksum at integration. ZERO experiments with the old artifact would silently measure v2 instead.
+
+## Benchmark behavior and limits
+
+`frameport fex bench APP --seconds N` and `scripts/rift_fex_bench.py` each request exactly one run. N is an integer
+1..120; it includes launcher/runtime startup, not just game sampling. The Frame enforces the deadline independently
+of the PC connection. A bench lock excludes another bench. The agent first rejects active Lepton/FramePort games;
+the helper rejects Wine/Proton/FEX processes, other Steam reapers, and Lepton container supervisors. It excludes
+SteamVR's own AppId 250820 reaper. An open Meta login session also blocks the benchmark.
+
+The helper requires `IVRSystem_022::GetTrackedDeviceActivityLevel(HMD)` to report **Standby (3)**. All other values,
+including unknown, idle, recently interacting and interacting, are refused. A write to Steam's `logs/controller.txt`
+within the last 60 seconds also blocks it (conservative: reconnection is enough). The same owner-activity checks run
+while sampling; interaction stops the run. This does not claim to detect every desktop keyboard event; do not use
+this headless tool while someone is using the Frame. A native non-Steam app outside Steam's reaper may also evade
+the process guard. Do not run simultaneous Play/login/install operations against the shared prefix.
+
+Before launch, read a positive finite `power/turnOffScreensTimeout`, set `power/pauseCompositorOnStandby=false`
+through the existing `vrsetting` helper, and temporarily set the screen timeout to N+10. Start `launch.sh` in its
+own process group. Finally, stop the shared-prefix wineserver (5-second limit), terminate/kill the launcher group,
+set `pauseCompositorOnStandby=true`, and restore the original screen timeout. Each restoration is attempted even
+when a preceding cleanup fails. SIGTERM and ordinary errors run this cleanup; SIGKILL, power loss or a dead SteamVR
+service cannot execute Python's finally. The temporary screen timeout is finite even in those cases.
+
+Every 0.5 seconds, read up to 128 compositor records via pinned `IVRCompositor_022::GetFrameTimings`. Deduplicate by
+frame index, retain updated present counts, exclude the initial ring, and count only while scene focus belongs to
+the game's PID. A hitch is one unique frame presented at least three times. GPU activity uses the actual game
+process's DRM fdinfo engine-nanosecond deltas, deduplicating shared DRM client IDs; no debugfs permissions needed.
+Thread wait states are histogrammed from the game's `/proc/<pid>/task/*/wchan` files. No shell commands or logs
+containing account data enter the summary.
+
+Successful stdout is one JSON line: effective settings, elapsed time, unique frames, `valid`, frame span, fps,
+hitches (also per 20 seconds), average render GPU time and client frame interval, game GPU busy percent, and sampled
+thread wait states. GPU busy is the sum of available engines and may exceed 100 percent on devices with independent
+engines. `null` means unavailable, not zero. Client frame interval is **not CPU ApplicationTime**. `valid=false`,
+zero frames or a short sample span means the launch produced insufficient data; do not treat it as a fast run.
+Use equivalent spans and a stable scene when comparing results. A launcher exiting early is an error.
+
+## Exact device checks
+
+The maintainer runs these commands; this stream did not access the network or the Frame. Use the account owner's
+normal sign-in workflow from the login stream. A missing entitlement is a failed run to report, never bypass.
+
+1. Build/checksum the guest artifact above. From this worktree on the PC:
+
+   ```sh
+   export FRAMEPORT_HOME="$PWD/.home"
+   export FRAMEPORT_EXPERIMENTAL_FEX=1
+   uv run frameport fex setup
+   uv run frameport fex install oculus-first-contact
+   uv run frameport fex settings oculus-first-contact
+   ```
+
+   Setup should complete the `revive` step and create all three scale folders. Install once to get the new launcher.
+   Settings should show fp_mem on, threshold 256, eye divisor 1.5, motion smoothing 2, cores 4-7 and ntsync on.
+   Run the Frame helper with `python3 -I` as usual; no additional pip packages are needed there.
+
+2. Wear the headset once after boot, then remove it and let it reach standby. End every game and the Meta client;
+   wait at least 60 seconds after controller input. A worn headset or a running game must make bench refuse **before
+   changing display settings**. Do not work around a refusal by disabling the checks.
+
+3. Establish a baseline, then run exactly one bounded experiment per command pair below. Each line is independent;
+   restore the previous changed key with `null` before moving to the next experiment.
+
+   ```sh
+   uv run frameport fex settings oculus-first-contact dxvk_disable_msaa=false dxgi_sync_interval=-1 dxgi_max_frame_latency=0 eye_scale=1.5 motion_smoothing=2 cores=4-7 ntsync=true fp_mem=true bigcache_mb=256 fp_mem_zero=false 'fex={}' wine_large_address_aware=true
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   ```
+
+   Expected: one summary JSON, `valid=true`, nonzero frames, finite fps/GPU timings; DRM busy may be null if fdinfo
+   is unavailable. After it returns, the game/runtime should be gone and the headset should sleep normally.
+   `launch.log` in the game's anchor should contain `FramePort: starting Meta's runtime` and
+   `FramePort: starting Oculus First Contact`. No rendering with `r.MobileMSAA=2` was proven; do not use that knob.
+
+4. Run these candidate experiments separately, returning to the baseline between them:
+
+   ```sh
+   uv run frameport fex settings oculus-first-contact dxvk_disable_msaa=true
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact dxvk_disable_msaa=null
+
+   uv run frameport fex settings oculus-first-contact dxgi_max_frame_latency=1
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact dxgi_max_frame_latency=null
+
+   uv run frameport fex settings oculus-first-contact eye_scale=1.25
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact eye_scale=null
+
+   uv run frameport fex settings oculus-first-contact 'fex={"FEX_X87REDUCEDPRECISION":1}'
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact fex=null
+
+   uv run frameport fex settings oculus-first-contact wine_large_address_aware=false
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact wine_large_address_aware=null
+
+   uv run frameport fex settings oculus-first-contact ntsync=false
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact ntsync=null
+
+   uv run frameport fex settings oculus-first-contact fp_mem_zero=true
+   uv run frameport fex bench oculus-first-contact --seconds 120
+   uv run frameport fex settings oculus-first-contact fp_mem_zero=null
+   ```
+
+   The baseline covers eye divisor 1.5, ntsync on, and ZERO off. MSAA off previously improved GPU load but reduced
+   edge quality. Compare hitches, frame span, GPU time and thread wait distributions; this stream makes no claim
+   that X87 or large-address-awareness helps. GE may ignore the latter for a 64-bit game. Test image quality later
+   in an ordinary worn-headset Play session; the headless bench intentionally refuses that session.
+
+   Script alternative for a single run (do not run this in addition unless another run is intended):
+
+   ```sh
+   uv run python scripts/rift_fex_bench.py oculus-first-contact --seconds 120
+   ```
+
+5. Interrupt a run by sending SIGTERM to the `python3 -I .../fexrift.py bench` helper **on the Frame**, after checking
+   its PID with `pgrep -af '[f]exrift.py bench'`. Use `kill -TERM <that-pid>` (never a broad pkill). Expected: interrupted
+   result, game stopped, compositor standby enabled and original screen timeout restored. Also check refusal while
+   the headset is worn and a deliberately invalid setting, e.g. `eye_scale=1.4`, without launching anything.
+   On the Frame, this reads the two settings without printing any account data:
+
+   ```sh
+   python3 -I - <<'PY'
+   import ctypes as C, importlib.util, os
+   path = os.path.expanduser('~/.local/share/frameport/fexrift/artifacts/fexrift.py')
+   spec = importlib.util.spec_from_file_location('fx', path)
+   fx = importlib.util.module_from_spec(spec); spec.loader.exec_module(fx)
+   core, method, settings = fx.vr_settings()
+   try:
+       for key, idx, typ in [('pauseCompositorOnStandby', 5, C.c_bool), ('turnOffScreensTimeout', 7, C.c_float)]:
+           err = C.c_int()
+           value = method(settings, idx, typ, C.c_char_p, C.c_char_p, C.POINTER(C.c_int))(
+               b'power', key.encode(), C.byref(err))
+           print(key, value, 'error', err.value)
+   finally:
+       method(core, 1, None)()
+   PY
+   ```
+
+   Record these values before the test. Afterwards expect `pauseCompositorOnStandby True error 0` and the original
+   positive timeout with error 0. Confirm the physical display sleeps. With guest `FP_MEM_DEBUG=1`, ZERO reuse logs
+   should show `fp_mem: zero calls ..., bytes ..., failures 0`. This debug variable can be set manually in a test
+   launcher for one run; remove that line afterwards (it is deliberately outside the user environment whitelist).
+
+## Undo and remaining device questions
+
+Reset every override (no login or game files removed):
+
+```sh
+uv run frameport fex settings oculus-first-contact dxvk_disable_msaa=null dxgi_sync_interval=null dxgi_max_frame_latency=null eye_scale=null motion_smoothing=null cores=null ntsync=null fp_mem=null bigcache_mb=null fp_mem_zero=null fex=null wine_large_address_aware=null
+```
+
+To remove this experiment entirely, restore the integration's previous launcher/module and guest artifact, then
+remove only `settings/<app>.json`, `settings/<app>.dxvk.conf` and `revive-scales/` after stopping all FEX games.
+Do not remove `compat/pfx`; it holds the owner's login and installed games. For emergency display restoration on the
+Frame (replace 300 with the previously recorded timeout):
+
+```sh
+R="$HOME/.local/share/frameport/fexrift"
+python3 -I "$R/artifacts/fexrift.py" vrsetting '{"section":"power","key":"pauseCompositorOnStandby","kind":"b","value":true}'
+python3 -I "$R/artifacts/fexrift.py" vrsetting '{"section":"power","key":"turnOffScreensTimeout","kind":"f","value":300}'
+```
+
+Unverified: SteamVR's availability of the pinned historical compositor/system interfaces; whether scene focus PID
+matches the FEX game's host PID; whether the HMD reports Standby while compositor rendering is forced; how many
+usable game frames remain after runtime startup within 120 seconds; fdinfo visibility on this OS; the cost of ZERO
+on the device; all visual/entitlement behavior for other games. Failures must stay visible, not be replaced by fake
+performance numbers. If startup consumes the window, report `valid=false` and adjust startup in the owning stream
+before drawing conclusions; do not silently extend the bounded run.
+
+## Offline validation and integration
+
+Run `uv run pytest -q` in a normal environment and `uv run python scripts/patch_docs.py --check`. In this sandbox,
+use a writable UV cache and the already installed environment:
+
+```sh
+UV_CACHE_DIR=/tmp/frameport-perf-uv uv run --offline --no-sync pytest -q
+UV_CACHE_DIR=/tmp/frameport-perf-uv uv run --offline --no-sync pytest -q tests/test_fex_perf.py tests/test_fexrift.py tests/test_fexrift_ext.py
+```
+
+The original worktree's Git common directory is mounted read-only. Commits are therefore in the local, writable
+repository `/tmp/frameport-rift-perf.git` (same base and `rift/perf` ref) and exported as
+`/tmp/frameport-rift-perf.bundle`. The worktree contains the complete edits. A maintainer with writable original
+Git metadata can fetch that bundle and fast-forward/cherry-pick the commits; do not discard the worktree edits
+until integration is confirmed. Local-only instruction files and `.home` are excluded from every commit.
+
+Validation result in this environment: 80 focused tests passed, 1 skipped; Ruff passed for the three new Python
+files; `scripts/patch_docs.py --check` passed; `git diff --check` passed. The full suite ran: **1676 passed,
+43 skipped, 11 failed, 16 errors**. Every remaining failure/error raised `PermissionError: [Errno 1] Operation not
+permitted` when existing pairing/download/live-stream tests attempted to create sockets. This sandbox forbids
+sockets, including loopback; these tests were not disabled or modified. A clean full-suite pass remains an
+integration check in a normal environment. The complete short traceback log is
+`/tmp/frameport-rift-perf-pytest.log`.

native/a32translator/src/jit.c

@@ -32,12 +32,6 @@ extern void jit_exit(void);
 #define HASH_BITS 18
 #define LTAB_BITS 18
 #define MAX_INSNS 96
-/* stubs one more instruction (up to 3: a helper or side exit, a conditional skip, its fall-through exit) and the
- * block's final exit may still need; a block ends before fewer than this are left of MAX_STUBS. Without it, runs of
- * helper-translated instructions (each needs a stub) overflowed the table: OpenSSL's sha1_block_data_order_armv8
- * (~60 SHA1 crypto instructions in a row, Pinball FX2 VR, GitHub #342) killed the game (fatal "overflowed the code
- * buffer"). */
-#define STUB_RESERVE 8
 
 static uint32_t *cache, *cache_cur, *cache_end;
 static jit_block *htab[1u << HASH_BITS];
@@ -1387,8 +1381,7 @@ static jit_block *translate(uint32_t pc, int thumb, uint32_t it, int *fault, int
         x->it = it_after;
         if (x->ended || b->overflow) break;
         /* a fused VCMP needs its VMRS in the same block (x->next is set, so it is within MAX_INSNS) */
-        if ((!x->skip_vmrs && (n + 1 >= MAX_INSNS || (size_t)(b->p - b->start) > (CACHE_MARGIN / 4) / 2 ||
-                               x->nstubs > MAX_STUBS - STUB_RESERVE)) ||
+        if ((!x->skip_vmrs && (n + 1 >= MAX_INSNS || (size_t)(b->p - b->start) > (CACHE_MARGIN / 4) / 2)) ||
             !(len = nlen ? nlen : decode_guest(cur, thumb, x->it, &in))) {
             jx_exit_direct(x, cur, thumb, x->it);
             break;

native/a32translator/tests/programs/sha1ce.c

@@ -1,108 +0,0 @@
-/* The ARMv8 crypto instructions (SHA1C/P/M/H/SU0/SU1), which the JIT translates through the interpreter (one exit
- * stub each): dense() = 72 of them in a row, as dense as OpenSSL's sha1_block_data_order_armv8, whose block
- * overflowed the JIT's stub table (fatal "overflowed the code buffer"; GitHub #342, Pinball FX2 VR); then a fully
- * unrolled SHA-1 checked against known digests. Built with -march=armv8-a -mfpu=crypto-neon-fp-armv8. */
-#include <arm_neon.h>
-#include <stdio.h>
-#include <string.h>
-
-#define K0 0x5A827999u
-#define K1 0x6ED9EBA1u
-#define K2 0x8F1BBCDCu
-#define K3 0xCA62C1D6u
-
-/* 4 rounds: e1 = sha1h(a), abcd = sha1{c,p,m}(abcd, e0, w + k); then the message schedule */
-#define R(op, k, e_in, e_out, w) do { \
-        e_out = vsha1h_u32(vgetq_lane_u32(abcd, 0)); \
-        abcd = op(abcd, e_in, vaddq_u32(w, vdupq_n_u32(k))); \
-    } while (0)
-#define SCHED(w0, w1, w2, w3) (w0 = vsha1su1q_u32(vsha1su0q_u32(w0, w1, w2), w3))
-
-static void block(uint32_t st[5], const uint8_t *p)
-{
-    uint32x4_t abcd = vld1q_u32(st), abcd0 = abcd;
-    uint32_t e0 = st[4], e1, e00 = e0;
-    uint32x4_t w0 = vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(p)));
-    uint32x4_t w1 = vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(p + 16)));
-    uint32x4_t w2 = vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(p + 32)));
-    uint32x4_t w3 = vreinterpretq_u32_u8(vrev32q_u8(vld1q_u8(p + 48)));
-    R(vsha1cq_u32, K0, e0, e1, w0); SCHED(w0, w1, w2, w3);
-    R(vsha1cq_u32, K0, e1, e0, w1); SCHED(w1, w2, w3, w0);
-    R(vsha1cq_u32, K0, e0, e1, w2); SCHED(w2, w3, w0, w1);
-    R(vsha1cq_u32, K0, e1, e0, w3); SCHED(w3, w0, w1, w2);
-    R(vsha1cq_u32, K0, e0, e1, w0); SCHED(w0, w1, w2, w3);
-    R(vsha1pq_u32, K1, e1, e0, w1); SCHED(w1, w2, w3, w0);
-    R(vsha1pq_u32, K1, e0, e1, w2); SCHED(w2, w3, w0, w1);
-    R(vsha1pq_u32, K1, e1, e0, w3); SCHED(w3, w0, w1, w2);
-    R(vsha1pq_u32, K1, e0, e1, w0); SCHED(w0, w1, w2, w3);
-    R(vsha1pq_u32, K1, e1, e0, w1); SCHED(w1, w2, w3, w0);
-    R(vsha1mq_u32, K2, e0, e1, w2); SCHED(w2, w3, w0, w1);
-    R(vsha1mq_u32, K2, e1, e0, w3); SCHED(w3, w0, w1, w2);
-    R(vsha1mq_u32, K2, e0, e1, w0); SCHED(w0, w1, w2, w3);
-    R(vsha1mq_u32, K2, e1, e0, w1); SCHED(w1, w2, w3, w0);
-    R(vsha1mq_u32, K2, e0, e1, w2); SCHED(w2, w3, w0, w1);
-    R(vsha1pq_u32, K3, e1, e0, w3); SCHED(w3, w0, w1, w2);
-    R(vsha1pq_u32, K3, e0, e1, w0);
-    R(vsha1pq_u32, K3, e1, e0, w1);
-    R(vsha1pq_u32, K3, e0, e1, w2);
-    R(vsha1pq_u32, K3, e1, e0, w3);
-    vst1q_u32(st, vaddq_u32(abcd, abcd0));
-    st[4] = e0 + e00;
-}
-
-static void sha1(const char *msg, uint8_t out[20])
-{
-    uint32_t st[5] = {0x67452301u, 0xEFCDAB89u, 0x98BADCFEu, 0x10325476u, 0xC3D2E1F0u};
-    uint8_t buf[128] = {0};
-    size_t n = strlen(msg), blocks = (n + 9 + 63) / 64;
-    memcpy(buf, msg, n);
-    buf[n] = 0x80;
-    unsigned long long bits = (unsigned long long)n * 8;
-    for (int k = 0; k < 8; k++) buf[blocks * 64 - 1 - k] = (uint8_t)(bits >> (8 * k));
-    for (size_t b = 0; b < blocks; b++) block(st, buf + 64 * b);
-    for (int k = 0; k < 20; k++) out[k] = (uint8_t)(st[k / 4] >> (24 - 8 * (k % 4)));
-}
-
-/* 72 crypto instructions with nothing between them: denser than the compiler's code above, as dense as OpenSSL's
- * hand-written rounds */
-__attribute__((noinline)) static void dense(uint32_t v[12])
-{
-    __asm__ volatile("vld1.32 {d0-d3}, [%0]!\n\t"
-                     "vld1.32 {d4-d5}, [%0]\n\t"
-                     ".rept 24\n\t"
-                     "sha1c.32 q0, q1, q2\n\t"
-                     "sha1h.32 q1, q0\n\t"
-                     "sha1su0.32 q2, q0, q1\n\t"
-                     ".endr\n\t"
-                     "vst1.32 {d4-d5}, [%0]\n\t"
-                     "sub %0, %0, #32\n\t"
-                     "vst1.32 {d0-d3}, [%0]"
-                     : "+r"(v)
-                     :
-                     : "memory", "d0", "d1", "d2", "d3", "d4", "d5");
-}
-
-int main(void)
-{
-    uint32_t v[12];
-    for (int k = 0; k < 12; k++) v[k] = 0x9e3779b9u * (k + 1);
-    for (int r = 0; r < 3; r++) dense(v);
-    printf("dense:");
-    for (int k = 0; k < 12; k++) printf(" %08x", v[k]);
-    printf("\n");
-
-    static const char *const msgs[] = {"", "abc", "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"};
-    static const char *const want[] = {"da39a3ee5e6b4b0d3255bfef95601890afd80709",
-                                       "a9993e364706816aba3e25717850c26c9cd0d89d",
-                                       "84983e441c3bd26ebaae4aa1f95129e5e54670f1"};
-    int bad = 0;
-    for (int m = 0; m < 3; m++) {
-        uint8_t d[20];
-        char hex[41];
-        sha1(msgs[m], d);
-        for (int k = 0; k < 20; k++) sprintf(hex + 2 * k, "%02x", d[k]);
-        printf("sha1(\"%s\") = %s %s\n", msgs[m], hex, strcmp(hex, want[m]) ? "WRONG" : "ok");
-        bad |= strcmp(hex, want[m]) != 0;
-    }
-    return bad;
-}

native/a32translator/tests/run_programs.py

@@ -31,9 +31,7 @@ PROGRAMS = {  # name -> (source, variants, args)
     "jitguest": ("jitguest.c", ["arm", "thumb"], []),
     "exec": ("exec.c", ["arm", "thumb"], []),
     "bench": ("bench.c", ["arm", "thumb"], []),
-    "sha1ce": ("sha1ce.c", ["arm", "thumb"], []),
 }
-EXTRA_FLAGS = {"sha1ce.c": ["-march=armv8-a", "-mfpu=crypto-neon-fp-armv8"]}  # ARMv8 crypto instructions
 JIT_ONLY = {"bench"}  # far too slow for the interpreter under emulation
 
 
@@ -44,7 +42,7 @@ def build(name, src, variant):
         return out
     BUILD.mkdir(parents=True, exist_ok=True)
     cc = NDK_BIN / ("armv7a-linux-androideabi29-clang++" if src.endswith(".cpp") else "armv7a-linux-androideabi29-clang")
-    cmd = [str(cc), *VARIANTS[variant], "-mfpu=neon-vfpv4", *EXTRA_FLAGS.get(src, []), "-static", "-g", str(srcp), "-lm", "-o", str(out)]
+    cmd = [str(cc), *VARIANTS[variant], "-mfpu=neon-vfpv4", "-static", "-g", str(srcp), "-lm", "-o", str(out)]
     if src.endswith(".cpp"):
         cmd += ["-static-libstdc++", "-std=c++17"]
     subprocess.run(cmd, check=True)

native/adapter/action_names.h

@@ -1,35 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-// action_dedup (session_fixes.c, GitHub #323): a free name for a controller action whose name or localized name is
-// already used in its action set. No OpenXR types, so the host tests can compile it.
-#pragma once
-#include <stdio.h>
-#include <string.h>
-
-static size_t action_name_len(const char *s, size_t max) {  // strnlen (not in plain C11)
-    size_t n = 0;
-    while (n < max && s[n]) ++n;
-    return n;
-}
-
-// taken(ctx, name, localized): 1 when `name` or `localized` is already used in the set.
-typedef int (*action_name_taken_fn)(void *ctx, const char *name, const char *localized);
-
-// Writes "<name>_N" / "<localized> N" (N = 2..99, the first pair not taken; cut to fit name_size/localized_size
-// including the terminator) and returns 1; 0 when the original names are free or no free pair exists.
-static int action_unique_names(const char *name, const char *localized, action_name_taken_fn taken, void *ctx,
-                               char *out_name, size_t name_size, char *out_localized, size_t localized_size) {
-    if (!taken(ctx, name, localized) || name_size < 8 || localized_size < 8) return 0;
-    for (int n = 2; n < 100; ++n) {
-        char suffix[8], lsuffix[8];
-        snprintf(suffix, sizeof(suffix), "_%d", n);
-        snprintf(lsuffix, sizeof(lsuffix), " %d", n);
-        size_t keep = action_name_len(name, name_size - 1);
-        if (keep + strlen(suffix) > name_size - 1) keep = name_size - 1 - strlen(suffix);
-        snprintf(out_name, name_size, "%.*s%s", (int)keep, name, suffix);
-        size_t lkeep = action_name_len(localized, localized_size - 1);
-        if (lkeep + strlen(lsuffix) > localized_size - 1) lkeep = localized_size - 1 - strlen(lsuffix);
-        snprintf(out_localized, localized_size, "%.*s%s", (int)lkeep, localized, lsuffix);
-        if (!taken(ctx, out_name, out_localized)) return 1;
-    }
-    return 0;
-}

native/adapter/alpha_blend.frag

@@ -1,5 +0,0 @@
-#version 450
-// alpha_blend_vk.c: with blending (one minus destination alpha, zero) and only alpha written, the image's alpha
-// becomes 1 - alpha.
-layout(location=0) out vec4 outputColor;
-void main(){outputColor=vec4(0,0,0,1);}

native/adapter/alpha_blend.vert

@@ -1,3 +0,0 @@
-#version 450
-// A triangle that covers the whole viewport (alpha_blend_vk.c).
-void main(){vec2 p=vec2((gl_VertexIndex<<1)&2,gl_VertexIndex&2);gl_Position=vec4(p*2-1,0,1);}

native/adapter/alpha_blend_spv.h

@@ -1,42 +0,0 @@
-// Generated from alpha_blend.vert and alpha_blend.frag.
-static const uint32_t alpha_blend_vert_spv[] = {
-    0x07230203,0x00010000,0x000d000a,0x0000002c,0x00000000,0x00020011,0x00000001,0x0006000b,
-    0x00000001,0x4c534c47,0x6474732e,0x3035342e,0x00000000,0x0003000e,0x00000000,0x00000001,
-    0x0007000f,0x00000000,0x00000004,0x6e69616d,0x00000000,0x0000000c,0x0000001d,0x00040047,
-    0x0000000c,0x0000000b,0x0000002a,0x00050048,0x0000001b,0x00000000,0x0000000b,0x00000000,
-    0x00050048,0x0000001b,0x00000001,0x0000000b,0x00000001,0x00050048,0x0000001b,0x00000002,
-    0x0000000b,0x00000003,0x00050048,0x0000001b,0x00000003,0x0000000b,0x00000004,0x00030047,
-    0x0000001b,0x00000002,0x00020013,0x00000002,0x00030021,0x00000003,0x00000002,0x00030016,
-    0x00000006,0x00000020,0x00040017,0x00000007,0x00000006,0x00000002,0x00040015,0x0000000a,
-    0x00000020,0x00000001,0x00040020,0x0000000b,0x00000001,0x0000000a,0x0004003b,0x0000000b,
-    0x0000000c,0x00000001,0x0004002b,0x0000000a,0x0000000e,0x00000001,0x0004002b,0x0000000a,
-    0x00000010,0x00000002,0x00040017,0x00000017,0x00000006,0x00000004,0x00040015,0x00000018,
-    0x00000020,0x00000000,0x0004002b,0x00000018,0x00000019,0x00000001,0x0004001c,0x0000001a,
-    0x00000006,0x00000019,0x0006001e,0x0000001b,0x00000017,0x00000006,0x0000001a,0x0000001a,
-    0x00040020,0x0000001c,0x00000003,0x0000001b,0x0004003b,0x0000001c,0x0000001d,0x00000003,
-    0x0004002b,0x0000000a,0x0000001e,0x00000000,0x0004002b,0x00000006,0x00000020,0x40000000,
-    0x0004002b,0x00000006,0x00000022,0x3f800000,0x0004002b,0x00000006,0x00000025,0x00000000,
-    0x00040020,0x00000029,0x00000003,0x00000017,0x0005002c,0x00000007,0x0000002b,0x00000022,
-    0x00000022,0x00050036,0x00000002,0x00000004,0x00000000,0x00000003,0x000200f8,0x00000005,
-    0x0004003d,0x0000000a,0x0000000d,0x0000000c,0x000500c4,0x0000000a,0x0000000f,0x0000000d,
-    0x0000000e,0x000500c7,0x0000000a,0x00000011,0x0000000f,0x00000010,0x0004006f,0x00000006,
-    0x00000012,0x00000011,0x000500c7,0x0000000a,0x00000014,0x0000000d,0x00000010,0x0004006f,
-    0x00000006,0x00000015,0x00000014,0x00050050,0x00000007,0x00000016,0x00000012,0x00000015,
-    0x0005008e,0x00000007,0x00000021,0x00000016,0x00000020,0x00050083,0x00000007,0x00000024,
-    0x00000021,0x0000002b,0x00050051,0x00000006,0x00000026,0x00000024,0x00000000,0x00050051,
-    0x00000006,0x00000027,0x00000024,0x00000001,0x00070050,0x00000017,0x00000028,0x00000026,
-    0x00000027,0x00000025,0x00000022,0x00050041,0x00000029,0x0000002a,0x0000001d,0x0000001e,
-    0x0003003e,0x0000002a,0x00000028,0x000100fd,0x00010038,
-};
-static const uint32_t alpha_blend_frag_spv[] = {
-    0x07230203,0x00010000,0x000d000a,0x0000000d,0x00000000,0x00020011,0x00000001,0x0006000b,
-    0x00000001,0x4c534c47,0x6474732e,0x3035342e,0x00000000,0x0003000e,0x00000000,0x00000001,
-    0x0006000f,0x00000004,0x00000004,0x6e69616d,0x00000000,0x00000009,0x00030010,0x00000004,
-    0x00000007,0x00040047,0x00000009,0x0000001e,0x00000000,0x00020013,0x00000002,0x00030021,
-    0x00000003,0x00000002,0x00030016,0x00000006,0x00000020,0x00040017,0x00000007,0x00000006,
-    0x00000004,0x00040020,0x00000008,0x00000003,0x00000007,0x0004003b,0x00000008,0x00000009,
-    0x00000003,0x0004002b,0x00000006,0x0000000a,0x00000000,0x0004002b,0x00000006,0x0000000b,
-    0x3f800000,0x0007002c,0x00000007,0x0000000c,0x0000000a,0x0000000a,0x0000000a,0x0000000b,
-    0x00050036,0x00000002,0x00000004,0x00000000,0x00000003,0x000200f8,0x00000005,0x0003003e,
-    0x00000009,0x0000000c,0x000100fd,0x00010038,
-};