FrameBridge: answer xrGetDisplayRefreshRateFB with the real rate (PreyVR black menu, #306)

The Frame's runtime has no XR_FB_display_refresh_rate (-7); OVRPort's dispatcher still
offers it and answered 0 Hz. Team Beef's idTech 4 ports run USERCMD_MSEC = 1000 / refresh,
so PreyVR had 0 ms tics: the async thread spun (~1.9M tics/s), com_frameTime stayed 0 and
the main menu's timeline never got past its first step (black backdrop + cursor only).
FrameBridge now always answers with 1 / predictedDisplayPeriod (else the refresh_rate
setting, else 72 Hz). Headless: menu drawn (snapshot mean 68 vs 0.1 before), clocks advance.

- glmv: gl_mv_debug=2 traces draws (state, GL errors per framebuffer), failed texture
  uploads/copies/compiles and idTech 4 clocks; how this was found
- triage: a single xrEndFrame -16 is info, not the black-menu error it was blamed for
- PLAYBOOK row, CLAUDE.md fact, host test for the fallback rate

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.
@@ -59,21 +58,7 @@ Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debug
     agent ends at EOF); sources and costs in docs/FRAME_RUNTIME.md "Monitoring sources"; game card (fps from
     FrameBridge pacing; End game = Steam's Exit game, then cmd_stop), tiles with `C.Sparkline` (Flet canvas, no charts
     extension), details, a pooled process table (Game / Steam & SteamVR / All; right-click: end / force kill / end
-    game; MON_CRITICAL needs force, MON_NEVER is refused)); room (`views/room.py`, persistent, "experimental" pill:
-    scan with progress + Cancel = agent v106 `room_capture_stop`, play area, delete; cache `ui/room_state.py` shared
-    with the Frame page's short card, mesh cached in `<data>/rooms-cache/<frame>/`; in-window 3D `ui/room3d.py`
-    RoomCanvas over `mr/view3d.py` (pure-Python projection, mesh reduced to ≤4k/≤1.5k edges at rest/moving, ≤18 fps
-    worker; each redraw sends NEW shape controls: changing a Points list made Flet diff it item by item, 0.3-1 s);
-    "Open full 3D view" = `mr/room_viewer.py` token server on 127.0.0.1 + hand-written WebGL `mr/viewer_page.py`,
-    stopped on disconnect/close; Test Quest MR tip = `mr.TESTER_*`; editing cards `views/room_edit.py` (agent v107):
-    Clean-up = fp_roomscan's refinement settings, `install/rooms.REFINE_DEFAULTS` = the owner's defaults + slider
-    metadata (agent `ROOM_REFINE_DEFAULTS` must match, a test checks), saved non-defaults in the Frame's
-    `rooms/refine.json`, used by every build; Apply = job → agent `room_refine` (`--refine-only` on a copy of the room
-    folder from `room-raw.txt`/`room-mesh-raw.bin`, scan.json → status `report`/`labels`/`suggestions`); Labels =
-    the label rules' decisions + Add as door / Add as closet; Furniture & screens = box editor (click a box in the
-    canvas: `view3d.pick`) + doors/windows on a wall (`mr.room.plane_on_wall`), Save = `rooms.put_room` → `room_put
-    edited` (keeps raw files, `edits.txt` survives a new clean-up; "Back to the scan's boxes" = keep_edits false); no
-    eraser in the GUI (`rooms.refine(erase=)` only)); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    game; MON_CRITICAL needs force, MON_NEVER is refused)); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
     (one `ft.ContextMenu` per view, filled on right-click; on one of several selected items they act on the whole
     selection, `C.menu_targets`) and click-and-drag multi-select (`C.DragSelect`: pan start/end on the area + item
     hover events, which Flutter also sends with the button held; Flet can't report item positions, so no rubber band).
@@ -138,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
@@ -154,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;
@@ -240,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
@@ -258,18 +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`. Agent v101: PC folder `saves.folder`
-    (Settings → Data; old folders stay listed in `saves.previous_folders`), automatic snapshots `saves.auto` (default
-    off; flag `~/.local/share/frameport/save-snapshots/enabled`, Quest launchers run `_snapshot_close` in the EXIT
-    trap under the launch lock, newest 3 per game on the Frame; `install/saves.sync_snapshots` imports them as
-    "automatic" once, ledger `<data>/save-snapshots-synced.json`). Device-checked 2026-10-17 with BlazeRush.
   - `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(...)`.
@@ -303,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
@@ -378,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).
 
@@ -469,9 +462,7 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 - 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). OVRPlugin treats that rect as a configured
-  boundary but can't outline it ("ovrpBoundary_Outer is not supported"): Demeter's guardian check indexed an empty
-  array → with `scene_emul` the app's STAGE `xrGetReferenceSpaceBoundsRect` returns XR_SPACE_BOUNDS_UNAVAILABLE.
+- 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
   give GL_INVALID_OPERATION. Some GLES games hit `zink: DEVICE LOST` (Unity MSAA RTT; Sniper Elite VR even without).
@@ -540,14 +531,28 @@ 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).
+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).
@@ -561,7 +566,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
@@ -573,66 +594,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).
 
-**Quest controller mode:** adapter `quest_buttons` (0/1/2, per game + library `input.quest_buttons`) suggests Frame Controller bindings translated from the game's Touch set (`suggest_frame`, mapping docs/input/quest_buttons.json = single source for C table, tests, diagram `scripts/controller_diagram.py`); runtime accepts them headless. → docs/DEVICE_NOTES.md#quest-controller-mode-quest_buttons-2026-10-17
-**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
-**Mixed reality: scanned rooms (branch mr-scene):** agent `room_capture` records Valve's RoomView 3D depth mesh -> `fp_roomscan` -> `room.txt` + `room-mesh.bin` (docs/mr/ROOM_FORMAT.md; refined by default: the owner's cleanup passes + label rules in `native/roomscan/refine.c`/`rules.c`, unrefined output kept as `room-raw.txt` + `room-mesh-raw.bin`, head path/settings/report/labels/door suggestions in `scan.json`, `--refine-only <dir>` re-runs it, `--refine 0` = old output; docs/mr/scan.md "Refinement") in `~/.local/share/frameport/rooms/<universe>/`, copied next to settings.conf (`_room_sync`); FrameBridge (`scene_room.c/scene_meta.c/scene_anchors.c`, all through xrshim) serves walls, volumes, planes, the room mesh, META discovery/persistence, saved anchors and `XR_META_boundary_visibility`; `scene_emul` + `frame.meta_permissions` for every USE_SCENE/USE_ANCHOR_API game (migrations `scene_emul_all`, `scene_permissions`); per-game `scene_hide_bounds` (Demeter). → docs/DEVICE_NOTES.md#mixed-reality-scanned-rooms
-**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`.
@@ -689,13 +1058,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.
@@ -783,15 +1145,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).

README.md

@@ -36,9 +36,6 @@ Frame, patches each game so it runs there, uploads it and adds it to your Steam
   in FramePort.
 - **Your Frame from your PC:** Type on Frame (your keyboard on the Frame), Files, Screenshots, Live view (what the
   headset shows, in your browser) and Monitor (frame rate, temperatures, battery, processes).
-- **Your room for mixed reality (experimental):** scan the room in the headset, see it in 3D, clean up the scan and
-  fix furniture, screen and door labels, so mixed-reality games get your room. Try it with
-  [Test Quest MR](https://github.com/spoopyghosty0/TestQuestMR).
 - **Updates itself**, and reports problems without personal data.
 
 Details for each: [Install and first steps](docs/INSTALL.md).
@@ -47,8 +44,6 @@ Details for each: [Install and first steps](docs/INSTALL.md).
 
 ![Screenshots](docs/images/screenshots.png)
 
-![Room (experimental): the scanned room in 3D, clean-up and labels](docs/images/room.png)
-
 ## Quick start
 
 1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) the build for Windows, macOS (Apple
@@ -129,7 +124,6 @@ What FramePort adds: [Architecture](docs/ARCHITECTURE.md).
 | [Compatibility](docs/COMPATIBILITY.md) | What runs and how well |
 | [Tested games](docs/GAMES.md) | Tested games and how well they run |
 | [FAQ](docs/FAQ.md) | Game folders and common questions |
-| [Controller buttons](docs/CONTROLLERS.md) | Quest Touch buttons on the Frame: SteamVR default, Mirror and Quest pair |
 | [Porting playbook](docs/PLAYBOOK.md) | Symptoms and fixes per game |
 | [Steam Frame runtime reference](docs/FRAME_RUNTIME.md) | Facts about the Frame's runtime |
 | [Architecture](docs/ARCHITECTURE.md) | How the code is organized |

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
-e32f9b3222bfe2e58c193db809ac2cf54086df36fd2ec6651aa2e58308f6b39d  ./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
+8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-001e699b64062e2cc260915c75aa3508aff10e590125a38c1a3007f61c13c681  ./arm64-v8a/libopenxr_loader_generic.so
+86261c4d7c4b78af5e182b81ae172f6d5fd5b12d8dc6194a876eee08b589d3ce  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi_foveation.so
-b022dc0d48c9ee46e5afa6e169386cdce36d896102fb8677f930abf15408e963  ./armeabi-v7a/libopenxr_loader_generic.so
+1a3b250835798f46049f527a6b32f9d0b33a2a976006d08f5997bfccc215ee89  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
@@ -27,38 +27,6 @@ b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING
 6cda3076a8c09b31bb1f90da614ea89e7ee194589626eeac613e522849604e47  ./licenses/LuaJIT.txt
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
-2cc16b90abcd3d359f1658c581172bd650017bf2725e24268915f50904c000ec  ./linux-arm64-bin/fp_roomscan
 b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc
-00c2dead0fd7497929833467f0e55699d57d26be1b85dce35402993852f7b111  ./roomscan/ceiling.png
-c1962de31ed2810d31c760cf9ee63316ac2b8c9528ccbcd9299ebf5ba39b2995  ./roomscan/done.png
-0dfaea4c68979b0a45a9fef06fdf1a92468ffc8f46f80a3a014fce1d805972d5  ./roomscan/failed.png
-f2bae84f1d1512f87b25e688acdddb29b3f360f3f0d0cd4fdeeb741a79e7b19a  ./roomscan/finish_00.png
-9be7720c45f162e99813cb9a7a03e026fed53b41f06637b30ded309eeac91759  ./roomscan/finish_01.png
-220d699f879b3a8669cfaf4dc714496e8c1db7e7878e7cd12b1a41aec9b62faa  ./roomscan/finish_02.png
-42871b440b77449d4fe41be1c809a930148a874caa8bc92b13b5d25bb6effa83  ./roomscan/finish_03.png
-a470f62624c94ed6791cc7ee03066e1ffb0a676d520658a0a8b02a6af1605b3b  ./roomscan/finish_04.png
-195ff1c649fd9b42bfa6eea29c43a8b67116fd6ffe9b0fe53dcbdb1074bd34fa  ./roomscan/finish_05.png
-a45accab86b02d7b78327a17b84a6fea543ecc549282055dd3182c686fc2b1b8  ./roomscan/finish_06.png
-b88d6c590ea839a9d11b3a4de8c3effb39752f7114318966fddae09995e0fd37  ./roomscan/finish_07.png
-4a3615db26cf765b855a997be3e067aed58464894dab4a6700fdec5c2b854501  ./roomscan/finish_08.png
-f532a83044e707c66dbc74787ce7b844890bc05829d3e9c8f7e33dae9db246a5  ./roomscan/finish_09.png
-ffce61a9f13bbb250fad3582396a5bec82a1bad1d585b7ef9b8f65d343806b26  ./roomscan/finish_10.png
-4a63772adacb31004749ab04b592076bd36cda61eef52f59037d5abdc9e527db  ./roomscan/finish_11.png
-f373e7021cfce0d1078227f473425a10035ee426102b78f13e0fea4833b736d5  ./roomscan/finish_12.png
-1147391822be3f1aa5351374b8fd9ec85f8b5ce40e3cb9f3146d778e6fbc652a  ./roomscan/floor.png
-eb3c8b55a9dbafa030797ca9f06a22c3ee3bbef96cb7adea26d433ebad43d43f  ./roomscan/look_00.png
-6ba965ff6d22a469c558f2a68229bd2ff48fc28badb95889ca245310d1dd3e96  ./roomscan/look_01.png
-0a11cec25ebc76fe11d505d1f2ec162c9b4a6754393065800e73b1f81e2d94c8  ./roomscan/look_02.png
-fa5a4c94d20af56797b9fcc111148767847a6633ade9217cab373de232efad90  ./roomscan/look_03.png
-e80fa493e380fba39084be2ee62859adcff4e39aa66566abee10a4d6339c52e9  ./roomscan/look_04.png
-133617f0d8d1e69c37408aac80033f71856b592b62e3b780cc12b446bd974680  ./roomscan/look_05.png
-d5dd296ff23641c6973c57ac139147e99c7b783316ab60537adb2155dd196880  ./roomscan/look_06.png
-c08570aa78f966ae937b2e21d0bad887c5352fbca56aa579a2a7ef8541fb96ad  ./roomscan/look_07.png
-3767e7db5fb6babc872fa62c42604f749c65936717d332101745b201cd450cd5  ./roomscan/look_08.png
-2924dc65e5c497545340209edc16060e12e1834d11af6871d1c1baa50b7b2562  ./roomscan/look_09.png
-cd0150dfc10b2aea39403c74eff72fd05fb0111178ef39b4c98657a6d16d105e  ./roomscan/look_10.png
-011355e412f73ade3896e9037490e607c4365d0cf8ceb807d236bf68b414d3ed  ./roomscan/look_11.png
-1b8b47ffb47568d540921f065b5958eeb44a6489498d58e0f33f5d1f535154e2  ./roomscan/look_12.png
-926c7bc6a103adee5b9bf938f5d4e39095ab77fd6270b5301be3b0428edd9ae6  ./roomscan/start.png
 c2c70f4af1a5c3e6089dff1130161dd417f8044f99ec639eeecf1083930aab16  ./win-x64/fp_oculushmd.exe
 60ebc5fea05b8945082e2ca8b9f2eb74616012a26eb50133af273dff0fcddc42  ./win-x64/fp_vrsettings.exe

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,22 +0,0 @@
-package: ScaredBySquares.Game
-title: Scared By Squares
-status: works
-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 (confirmed in the headset by the reporter). 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
-verified:
-  date: '2026-10-17'
-  issue: 323
-updated: '2026-10-17'
-min_app: 1.2.1
-source_hint: Scared By Squares

catalog/games/com.And7Limited.Hitstream.yaml

@@ -1,16 +0,0 @@
-package: com.And7Limited.Hitstream
-title: Hitstream
-status: works
-tested_version: 2.06bQuest
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-adapter:
-  controller_models: 1
-  haptic_fix: 1
-notes: Fitness rhythm game; uses controller models and haptics fix.
-verified:
-  date: '2026-10-12'
-  known_good_sha256: ecc9e2eee79073ae97ad5d3f70c21e8f049f899f21b51dfd541430bb7dd04cac
-source_hint: Hitstream

catalog/games/com.Appnori.SummerSports.yaml

@@ -1,23 +0,0 @@
-package: com.Appnori.SummerSports
-title: Summer Sports
-status: works
-tested_version: 0.5.1
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-- frame.unity_runtime_msaa_off
-- frame.unity_gl_shim
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 582adf5a538eb9565921cc0384e61bf113ab9215c1ad462fade82d06ad3302fa
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 395
-source_hint: All in One summer Sports VR

catalog/games/com.BolverkGamesFlat2VR.SurvivingMarsPioneer.yaml

@@ -1,23 +0,0 @@
-package: com.BolverkGamesFlat2VR.SurvivingMarsPioneer
-title: 'Surviving Mars: Pioneer'
-status: works
-tested_version: 1.0.14
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-- frame.hw_video_decode
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scale: 2.0
-verified:
-  date: '2026-10-18'
-  known_good_sha256: 3a9ff281417c219736ee10969e6ce4f7d8395472cb60718db8839d65edac4777
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 399
-source_hint: Surviving Mars Pioneer

catalog/games/com.CarbonStudio.TheWizards.yaml

@@ -1,24 +0,0 @@
-package: com.CarbonStudio.TheWizards
-title: The Wizards
-status: works
-tested_version: '1.11'
-engine: Unreal
-xr: VrApi
-alt_overport:
-- patch_remove_unreal_force_quit
-use_alt: true
-frame:
-- frame.unreal_thumb_touch
-adapter:
-  haptic_fix: 1
-  pose_time_fix: 1
-  scale: 2.0
-verified:
-  date: '2026-10-18'
-  known_good_sha256: c1d979d746c2be941e150e948aec755d85034de829abfe30e5bf0761a49135ef
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 397
-source_hint: the wizards

catalog/games/com.CortopiaStudios.Spectre.yaml

@@ -1,25 +0,0 @@
-package: com.CortopiaStudios.Spectre
-title: Spectre
-status: works
-notes: Works since 1.2.1 (the loading screen waited for a Meta analytics request).
-tested_version: 1.0.1.1354
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-- frame.hw_video_decode
-- frame.cortopia_org_id
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scale: 2.0
-verified:
-  date: '2026-10-17'
-  known_good_sha256: a37a5400ef58906b575f6da1649b62ac7ce024eab831fae105457c1d5d12c2de
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 390
-source_hint: Wonder

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,30 +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. LAN multiplayer works; online rooms need Meta's account check (user proof), so online
-  multiplayer can't work (#408)."
-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.GexagonVR.HardBullet.yaml

@@ -1,25 +0,0 @@
-package: com.GexagonVR.HardBullet
-title: HardBullet
-status: issues
-notes: Loading screens (a cube overlay) are missing or corrupted up to FramePort 1.2.1; cube_quads (next release)
-  shows them as six panels, not confirmed in the headset yet. Level loads stall frame submission for up to ~1 s, so
-  the view freezes during loads.
-tested_version: 1.0.9.704Q
-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: ecbb758d98083a590f100d5ac6efe9490ef74ad39b59217e0b4a11db920ecd51
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 96
-  issue: 385
-source_hint: HARD BULLET

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.Meta4.TFBeyondReality.yaml

@@ -1,20 +0,0 @@
-package: com.Meta4.TFBeyondReality
-title: 'Transformers Beyond Reality: Redux'
-status: unknown
-notes: Starts and runs at 72 fps in headless launch tests (2026-10-17); not yet checked in the headset. Steam's shader
-  cache layer is left out and a few shaders the Frame's driver refuses are skipped, so some objects may be missing.
-details: Unreal Engine game (Binned3 allocator, GitHub issue 349). Crash 1 - the allocator's 76 GiB up-front
-  reservation is refused by the Frame's kernel (frame.unreal_noreserve, suggested by analysis). Crash 2 - Unreal's
-  "Shader compilation failures are Fatal." With Lepton's Fossilize layer loaded every graphics pipeline failed with
-  VK_ERROR_OUT_OF_HOST_MEMORY, even a constant-colour one (not the pipeline cache, not the CPU allocator, not Valve's
-  FDM/RPO layers); vk_no_fossilize takes the layer out of the game's instance. A few pipelines with the game's
-  multiview vertex shaders then still fail in Turnip; vk_pipeline_fallback creates them with blank shaders.
-tested_version: 1.495.34291
-engine: Unreal
-xr: OpenXR
-adapter:
-  vk_no_fossilize: 1
-  vk_pipeline_fallback: 1
-verified:
-  date: '2026-10-17'
-  issue: 349

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

@@ -12,7 +12,6 @@ overport_extra:
 - patch_force_passthrough
 adapter:
   scene_emul: 1
-  scene_hide_bounds: 1
 device:
 - device.text_input_window
 verified:
@@ -23,4 +22,4 @@ verified:
 frame:
 - frame.meta_permissions
 - frame.unity_text_input
-updated: '2026-10-17'
+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.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.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.WenklyStudio.SurvivalNation.yaml

@@ -1,21 +0,0 @@
-package: com.WenklyStudio.SurvivalNation
-title: Survival Nation
-status: works
-tested_version: 1.14.1
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
-adapter:
-  scale: 1.8
-verified:
-  date: '2026-10-18'
-  known_good_sha256: 7903dfee1c9c36d19e1c6c78a1f0ede1f0b25ce6a6065811997297e701009250
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 401
-source_hint: survival nation

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.cosmorama.tabletroopers.yaml

@@ -1,24 +0,0 @@
-package: com.cosmorama.tabletroopers
-title: Table Troopers
-status: works
-tested_version: 2026.40.4
-engine: Unity
-xr: OpenXR
-frame:
-- frame.gms_platform_version
-- frame.photon_voice_audio_route
-- frame.unity_text_input
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scale: 2.0
-verified:
-  date: '2026-10-17'
-  known_good_sha256: b0a4b0e29855277712b580bd5507721fff137bde77b1911b34cca89c627feef1
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 391
-source_hint: Troopers

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.el.blackholepooldemo.yaml

@@ -1,22 +0,0 @@
-package: com.el.blackholepooldemo
-title: Black Hole Pool
-status: works
-tested_version: 5.3.2
-engine: Unity
-xr: OpenXR
-frame:
-- frame.vivox_audio_route
-- frame.unity_text_input
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: 17c23df3813324250ec1792d8dc0488dadf0df0a7ccbe33157d88f427889a92e
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 396
-source_hint: Black Hole Pool

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.gritGames.Nope.yaml

@@ -5,10 +5,8 @@ source_hint: NOPE CHALLENGE
 engine: Unreal
 xr: OpenXR
 status: works
-notes: "Meta XR Audio telemetry patch + nodebug. MR mode: needs a scanned room."
-details: The MR 'Reality Breach' mode needs passthrough and a room; standard VR mode was verified.
-adapter:
-  scene_emul: 1
+notes: Meta XR Audio telemetry patch + nodebug. MR "Reality Breach" mode unavailable.
+details: The MR 'Reality Breach' mode needs passthrough; standard VR mode used.
 alt_overport:
 - patch_remove_unreal_force_quit
 frame:

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.mrf.tvb.cubism.yaml

@@ -1,23 +0,0 @@
-package: com.mrf.tvb.cubism
-title: cubism
-status: works
-notes: works and passthrough play works also
-tested_version: 1.8.0
-engine: Unity
-xr: OpenXR
-frame:
-- frame.unity_text_input
-device:
-- device.text_input_window
-adapter:
-  haptic_fix: 1
-  scene_emul: 1
-verified:
-  date: '2026-10-17'
-  known_good_sha256: fd1ba8eae19efe0f2a17fc146847de677263125f9ec5437cea5c632f0cd88dcf
-  app: 1.2.0
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 91
-  issue: 403
-source_hint: Cubism

catalog/games/com.mrf.tvb.laser_dance.yaml

@@ -1,19 +0,0 @@
-package: com.mrf.tvb.laser_dance
-title: Laser Dance
-engine: Unity
-xr: OpenXR
-status: works
-notes: Mixed reality laser obstacle course; requires spatial data and room layout emulation (scene_emul=1). frame.meta_depth_occlusion keeps close lasers visible (its asset fixes only for the build they were made for); tested version not recorded (PR #246).
-details: Mixed reality game that projects lasers across your room; needs Meta scene emulation and spatial data permission.
-adapter:
-  controller_fix: 1
-  haptic_fix: 1
-  scene_emul: 1
-  passthrough_emul: 1
-frame:
-- frame.meta_permissions
-- frame.meta_depth_occlusion
-- frame.unity_scene_active_rooms
-- frame.unity_text_input
-min_app: 1.2.2
-updated: '2026-10-18'

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.rrrgames.ThiefSimVRQuest.yaml

@@ -1,12 +0,0 @@
-package: com.rrrgames.ThiefSimVRQuest
-title: Thief Simulator
-status: unsupported
-notes: Quits at start with the game's own "installed from unknown source" message. Lepton installs the game itself at
-  every start (there is no Meta store app on the Frame), so the game never sees the Meta store as its source.
-tested_version: 1.1.7.3
-engine: Unity
-xr: OpenXR
-verified:
-  date: '2026-10-17'
-  issue: 368
-updated: '2026-10-17'

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.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.team17.killerfrequency.yaml

@@ -1,26 +0,0 @@
-package: com.team17.killerfrequency
-title: KillerFrequency
-status: works
-tested_version: 1.0.767.38513
-engine: Unity
-xr: VrApi
-frame:
-- frame.unity_no_msaa
-- 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
-  scale: 1.4000000000000001
-verified:
-  date: '2026-10-18'
-  known_good_sha256: a11b008fcc0f5bc7aa5a3bb04d4267144d5ec60b26529a9b20e6499e12dcf079
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261007.6125817'
-  agent: 96
-  issue: 402
-source_hint: killer freq

catalog/games/com.zenstudios.PFXVRQuest.yaml

@@ -1,14 +1,13 @@
 package: com.zenstudios.PFXVRQuest
 title: Pinball FX VR
 status: issues
-notes: "Plays; space warp off (fewer stutters). MR mode: needs a scanned room."
+notes: Plays; mixed reality mode not working yet. Space warp off (fewer stutters).
 tested_version: '1.9'
 engine: Unreal
 xr: OpenXR
 alt_overport:
 - patch_remove_unreal_force_quit
 adapter:
-  scene_emul: 1
   equirect_emul: 1
   hide_space_warp: 1
 verified:

catalog/games/io.github.spoopyghosty0.testquestcontrollers.yaml

@@ -1,16 +0,0 @@
-package: io.github.spoopyghosty0.testquestcontrollers
-title: Test Quest Controllers
-status: works
-notes: A controller tester for the Controller buttons settings. Picking a controller type on the Frame closes the
-  app; start it again to use that type (SteamVR's runtime can't switch within one app start).
-tested_version: 0.2.2
-engine: Other
-xr: OpenXR
-verified:
-  date: '2026-10-18'
-  known_good_sha256: 7db99515fb1a9c9796ee4613f716c0b76caa72c68003db8fc6c14bf20a8eecce
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 102
-source_hint: Test Quest Controllers

catalog/games/io.github.spoopyghosty0.testquestmr.yaml

@@ -1,20 +0,0 @@
-package: io.github.spoopyghosty0.testquestmr
-title: Test Quest MR
-status: works
-notes: An MR debug viewer that shows what the Meta MR APIs return (room, planes, mesh, anchors, play area). With
-  FramePort's emulated room it shows a room made from the play area.
-tested_version: 0.2.1
-engine: Other
-xr: OpenXR
-frame:
-- frame.meta_permissions
-adapter:
-  scene_emul: 1
-verified:
-  date: '2026-10-18'
-  known_good_sha256: 98936ca80d548a753a6645ab89610af19f6e8c3190b5f5f67854cf854691fba5
-  app: 1.2.1
-  overport_cli: 1.2.5
-  frame_build: '20261015.6141207'
-  agent: 102
-source_hint: Test Quest MR

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/jp.strippers.punchfit.yaml

@@ -1,21 +0,0 @@
-package: jp.strippers.punchfit
-title: Punch Fit
-status: works
-tested_version: 1.7.2
-engine: Unity
-xr: OpenXR
-frame:
-- frame.meta_permissions
-- frame.unity_text_input
-adapter:
-  haptic_fix: 1
-  pose_time_fix: 1
-  scene_emul: 1
-  passthrough_emul: 1
-notes: Mixed reality workout arena; composition layer trimming prevents 21+ layer overflow.
-verified:
-  date: '2026-10-12'
-  known_good_sha256: 1a0050272526360542d62e7e6d1fc2daecb765c34378a6fe4ad51568ec550c0d
-source_hint: Punch Fit
-min_app: 1.2.2
-updated: '2026-10-18'

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.primedgun.v2.yaml

@@ -1,15 +0,0 @@
-package: org.primedgun.v2
-title: PrimedGun v2
-status: unknown
-notes: 'Without the Vulkan library rename: the game builds the library name from two pieces, so the renamed name didn''t
-  exist ("libfp_vkn.so"), its renderer fell back to OpenGL and VR couldn''t start (GitHub #254). Not yet confirmed in
-  the headset.'
-tested_version: 2.0.0-alpha.4
-engine: Other
-xr: OpenXR
-frame:
-- frame.sdl_clipboard
-frame_remove:
-- frame.vk_sanitize
-updated: '2026-10-18'
-source_hint: PrimedGun v2 Quest APK (github.com/iChris4/MetroidPrimePortVR)

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/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/triage.yaml

@@ -6,59 +6,11 @@
 # with diagnostics. Launch tests and real play sessions (agent session_log, `frameport session`) are both matched.
 # Sources: every failure we hit porting 34 games to the Steam Frame (see docs/PLAYBOOK.md).
 signatures:
-  - id: mr-no-room
-    pattern: 'FrameBridge[^\r\n]*scene: (?:capture requested -> (?:guardian box|using guardian room)|room from guardian|room [^\r\n]*(?:from guardian|configured/default size|box))'
-    severity: info
-    diagnosis: 'The game is using a simple fallback room. Scan your room for mixed reality, or use Frame > Room > Use my play area for walls without furniture. A recorded scan can be imported until headset capture is available.'
-    suggest: []
-  - id: mr-discovery-unsupported
-    pattern: '(?:Unknown proc addr:\s*xrDiscoverSpacesMETA|(?:MRUK[^\r\n]*)?NoRoomsFound)'
-    # discovery reached FrameBridge and found the room (OVRPort's "Unknown proc addr" comes before the shim takes over)
-    unless: 'FrameBridge[^\r\n]*scene: discovery request=\d+ results=[1-9]'
-    severity: warning
-    diagnosis: 'The game cannot discover a Meta room. Enable room layout (adapter.scene_emul), rebuild and reinstall for the updated extension shim, then save a room under Frame > Room.'
-    suggest: [adapter.scene_emul]
-  - id: quest2-headset-identity
-    pattern: 'venderId[^\r\n]*systemName Oculus Quest2'
-    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]
   - 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
@@ -99,13 +51,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
@@ -116,13 +61,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
@@ -159,7 +97,7 @@ 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'
@@ -230,8 +168,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
@@ -239,13 +176,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
@@ -308,33 +238,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: vulkan-pipeline-refused
-    # GitHub #349: with Lepton's Fossilize layer loaded every Transformers pipeline failed with -1; without it a few
-    # multiview vertex shaders still fail in Turnip. Unreal ends at the first one.
-    pattern: '(Shader compilation failures are Fatal|vk shim: vkCreateGraphicsPipelines failed: -\d+)'
-    severity: fatal
-    diagnosis: The Frame's graphics driver refused to build some of the game's shaders, and Unreal ends the game at the
-      first one (for example Transformers Beyond Reality). Try leaving out Steam's shader cache layer, and skipping the
-      shaders the driver still refuses (they then draw nothing).
-    suggest: [adapter.vk_no_fossilize, adapter.vk_pipeline_fallback]
-    supersedes: [native-crash, force-quit]
   - id: graphics-requirements-missing
     pattern: '(XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING|Failed to create XR session: -50\b|xrCreateSession[^\n]*-50\b)'
     severity: fatal
@@ -395,12 +298,8 @@ signatures:
     diagnosis: Frame controller models are on, but the converted models are missing from the game's files. The agent found no Frame controller render models in SteamVR at install time; see the install log, or run the agent's controller_models command.
     suggest: []
   - id: scene-missing
-    # not extension listings, which every Meta XR game prints: OVRPlugin's "Unavailable OpenXR extension:" and
-    # "Name=XR_FB_scene SpecVersion=1", OVRPort's "overportOXR: - XR_FB_scene 1", Unity's 'Meta XR Feature: ...
-    # Extensions="..."' (GitHub #404); XR_FB_scene_capture alone doesn't count either
-    pattern: '(?m)^(?!.*(?:Unavailable OpenXR extension: |Name=|overportOXR: - |Extensions=")).*XR_FB_scene\b|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
-    # FrameBridge serves the room (OVRPort still lists XR_FB_scene and the shim names xrQuerySpacesFB): no finding
-    unless: 'FrameBridge[^\r\n]*scene: emulation active'
+    # not OVRPlugin's routine "Unavailable OpenXR extension: XR_FB_scene" (printed by every OVRPlugin game)
+    pattern: '(?<!Unavailable OpenXR extension: )XR_FB_scene|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
     severity: warning
     diagnosis: The game wants Meta's room data (scene API), which the Frame lacks. The adapter can emulate a room from the guardian bounds.
     suggest: [adapter.scene_emul]
@@ -415,13 +314,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'
@@ -450,13 +342,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
@@ -470,22 +355,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/"
@@ -493,24 +366,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
@@ -549,12 +404,6 @@ signatures:
     diagnosis: The game crashed while leaving VR, inside Valve's foveation layer when it destroys a swapchain (for example Lambda1VR). This can happen after manually quitting; it is not a startup crash and does not explain distorted geometry seen before quitting.
     suggest: []
     supersedes: [native-crash]
-  - id: batman-audio-geometry-allocation
-    pattern: '(?s)\A(?=.*com\.camouflaj\.manta)(?=.*Trying to allocate: [1-9][0-9]{10,}B)(?=.*MetaXRAudioUnityMemoryAllocator\.cpp)'
-    severity: fatal
-    diagnosis: "Batman's Meta XR Audio geometry loader requested tens of gigabytes while loading a scene. Its background task can outlive the UnityWebRequest that owns the input buffer. Update Batman on Frame with the current FramePort: the adapter retains a private copy until parsing finishes, for the verified Batman build. This is a game allocation crash, not evidence of a headset thermal shutdown."
-    suggest: [frame.adapter]
-    supersedes: [native-crash]
   - id: native-crash
     pattern: 'Fatal signal (\d+) \(SIG[A-Z]+\)'
     severity: fatal
@@ -575,12 +424,6 @@ signatures:
     severity: fatal
     diagnosis: 'Games can''t start until the Frame restarts: it ran out of kernel keys. Rootless podman leaks one session keyring per container start; the FramePort agent sets keyring=false in ~/.config/containers/containers.conf, and a reboot frees the leaked keys.'
     suggest: []
-  - id: app-separate-process
-    pattern: 'Start proc \d+:[\w.]+:\w+/\S+ for (pre-)?top-activity'
-    severity: error
-    diagnosis: The game's activity runs in an Android process of its own, while Lepton watches only the app's main process, which never starts. About a minute in, Lepton decides the app "did not start" and closes it, wherever the game is. Newer FramePort versions run the activity in the main process (patch "Start the game in the app's main process"); update FramePort and use Update on Frame.
-    suggest: []
-    supersedes: [app-not-started, force-quit]
   - id: app-not-started
     pattern: 'Target app \(.*\) did not start'
     severity: error

docs/AUDIO_GEOMETRY.md

@@ -1,105 +0,0 @@
-# Batman audio geometry input lifetime
-
-Batman: Arkham Shadow 1.4.1 could abort while loading a save or streaming the area
-around a real-time cutscene. Unity reported requests for 26,388,238,103 or
-147,520,448,640 bytes through `MetaXRAudioUnityMemoryAllocator.cpp`, followed by
-`SIGTRAP` on an IL2CPP worker. The first captured stack reached
-`GeometricAudioMeshPreprocessor::readMeshInfo` through
-`ovrAudio_AudioGeometryReadMeshMemory`.
-
-The serialized asset on disk was intact. In one failed run its vertex count was
-read as 1 instead of 17,251. The managed-code trace showed a lifetime risk:
-`LoadGeometryAsync` obtains a `NativeArray<byte>.ReadOnly` from a
-`UnityWebRequest` download handler, calls async-void `LoadGeometryFromMemory`,
-then returns. The background task retains the pointer/length pair, but not the
-request owning those bytes. Its `GC.KeepAlive` boxes the read-only view rather
-than retaining the request. The trace and device test support premature source
-reuse as the cause; no hardware watch established the exact freeing instruction.
-
-## Repair and isolation
-
-`audio_geometry_owned.h` copies the input synchronously at
-`LoadGeometryFromMemory`, before `Task.Run` can outlive the request. A mutex
-protects the list of copies. The original worker still parses and processes the
-audio geometry; its completion wrapper removes and frees the corresponding copy.
-This also handles a worker finishing before the queuing call returns. NativeArray
-length/padding bits and IL2CPP's hidden method-info arguments are preserved.
-Null/invalid lengths and allocation failure retain the original call. A task
-that never runs retains its copy until process exit; there is no timed expiry
-that could free data beneath a late worker.
-
-`batman_audio_geometry.h` enables the repair only in `com.camouflaj.manta`, on
-AArch64, after the existing audio metadata initializer verifies Meta XR Audio
-Wwise build `e1619e7fb839badf0ea5ecc22d9f028d0b17c34d`. It additionally requires
-IL2CPP build `1d48a41d7e9011bef5fae0c23c404c62a4e7a73c` and exact 16-byte entry
-sequences at both managed hooks. Unknown builds are left untouched. The live
-IL2CPP addresses are `0x2e61bb4` (queue) and `0x2e63a28` (worker); text file
-offsets in this build are 0x1000 lower. These offsets must not be reused for
-another game or build.
-
-Both geometry hooks and the metadata hooks use `audio_detour.h`. After the
-16-byte entry guard, only the first, naturally aligned instruction is replaced:
-a release atomic store publishes an AArch64 `B` to a nearby stub. The stub's
-absolute jump and the trampoline (one verified non-PC-relative instruction,
-then a direct branch to entry+4) are complete, instruction-cache flushed and RX
-before publication. The original-call pointer is published first. Remaining
-entry instructions are unchanged, so workers already past the entry can finish
-normally. `/proc/self/maps` supplies free gaps, clipped to the ranges of both
-branches. Page-aligned candidates are tried outward from the target (lower
-address first on equal distances) with `MAP_FIXED_NOREPLACE`; EEXIST/EINVAL
-advance to the next candidate. Existing mappings are never replaced, and a
-kernel that ignores the flag and relocates a mapping has that result unmapped.
-If no candidate works, that hook is skipped without changing its entry. No ELF
-page-slack fallback is used: zero bytes alone cannot establish that padding is
-outside all section content, and the loaded program headers do not prove this.
-
-Every mprotect result is checked. Failures before entry publication free the
-mapping. If restoring RX after publication fails, the entry word is restored,
-its instruction cache is flushed, and restoring RX is attempted again. The
-mapping and original-call pointer must then remain valid until process exit:
-a worker may already have followed the published branch. Freeing them without
-quiescing those threads would introduce a use-after-unmap. A persistent kernel
-mprotect failure can leave the entry page RWX. Each hook failure logs its target
-and failing operation once; metadata installation is attempted once per verified
-library. Allocation failure reports the closest eligible free page, last
-attempted address, actual mmap result, errno and attempt count. Null closest and
-zero attempts mean no eligible free gap. Protection failures identify stub RX,
-entry RWX, or entry RX, including the rollback RX errno (zero means it succeeded).
-This exceptional rollback cannot provide immediate reclamation or guarantee RX
-when the kernel refuses it. The previous hint-based publication build failed installation on the Steam
-Frame; this gap-search replacement has host validation only.
-
-This is separate from the existing [audio metadata retirement repair](AUDIO_METADATA.md).
-It does not change the decoder, acoustic processing, tracking, foveation,
-resolution, refresh rate, or other games' recipes. Temporary input dumps, native
-parser bypasses and redundant late copies used during investigation are not
-included. Production logs are limited to installation and the first four
-copy/completion pairs. No game assets are included in the repository.
-
-The `frame.adapter` package revision increases only for Batman. Existing Batman
-installs therefore offer **Update on Frame**; other games are not marked outdated
-by this repair. Updating/rebuilding Batman installs the new adapter through the
-normal path; no launcher script or additional option is needed.
-
-## Validation
-
-- Native regressions cover deferred and inline completion, source destruction
-  before worker execution, concurrent loads, cleanup, allocation failure,
-  argument preservation, and rejection of unknown build IDs/function entries.
-  Host C tests also cover branch-range endpoints, stub/trampoline encoding,
-  publication order, synthetic maps with in-range/out-of-range/absent gaps and
-  adjacent mappings, outward placement order, EEXIST/EINVAL fallback, rejected
-  relocated mmap results and mprotect failure cleanup/rollback.
-- On the headset, the affected save loaded successfully with the repair. Logs
-  showed private copies of 2,599,300, 159,020 and 628,088 bytes made before dispatch;
-  each original parser completed and each copy was released. Another 180,120-byte
-  geometry input also completed normally.
-- The game continued for over seven minutes after that load with zero allocation
-  failures, rejected meshes or fatal signals. Acoustic geometry was loaded, not
-  disabled. That device test used the ownership repair with diagnostic guards;
-  none of the guards rejected a mesh. The production repair omits those guards.
-- The rebuilt latest adapter passes the repository checks recorded in the PR;
-  the device result above is for the experimental build tested before integration.
-
-This does not establish long-term stability or resolve the separately observed
-whole-headset power-offs. Those require their own power/reset investigation.

docs/CONTROLLERS.md

@@ -1,93 +0,0 @@
-# Controller buttons
-
-> **Experimental.** The Frame's runtime accepts these bindings, but the modes haven't been tried in the headset on
-> many games yet. If buttons stop working in a game, set it back to **SteamVR default** (Game settings →
-> Controllers) and report it.
-
-Quest games usually bind Quest Touch controllers. Steam Frame has a d-pad and View button on the left controller,
-and an A/B/X/Y diamond and Menu button on the right. Without a game's own Frame bindings, SteamVR maps Touch X/A
-to the bottom button and Touch Y/B to all three top buttons. View sends Touch Menu. The right X and Y therefore
-send Touch B, rather than the left-hand X and Y of a Quest controller.
-
-**Controller buttons** chooses an alternative for Quest games running through FrameBridge:
-
-- **SteamVR default (0)** leaves SteamVR's Touch remapping in place. This is the initial default.
-- **Mirror (1)** uses every face button. On each controller, bottom and outer send X/A; top and inner send Y/B, as on Quest controllers, whose second button sits up and toward the other hand.
-- **Quest pair (2)** uses two face buttons per controller, placed like Touch's: left X = d-pad down, Y = d-pad
-  right; right A = A, B = X. The other face buttons send no Touch input.
-
-![Quest Touch reference and the three Steam Frame button mappings](images/controllers/quest-buttons.svg)
-
-The small label identifies the physical button; the larger label is the Touch input the game receives. Blue is
-X/A, orange is Y/B or Menu, and a dash means no Touch input. Left and right refer to the hand holding the controller.
-
-<!-- quest-buttons-table:start -->
-| Frame input | SteamVR default (0) | Mirror (1) | Quest pair (2) |
-|---|---|---|---|
-| Left d-pad ↑ | Y | Y | — |
-| Left d-pad ↓ | X | X | X |
-| Left d-pad ← | Y | X | — |
-| Left d-pad → | Y | Y | Y |
-| Left View | Menu | Menu | Menu |
-| Right A (bottom) | A | A | A |
-| Right B (right) | B | A | — |
-| Right X (left) | B | B | B |
-| Right Y (top) | B | B | — |
-| Right Menu | — | — | — |
-| Left bumper | — | — | — |
-| Right bumper | — | — | — |
-<!-- quest-buttons-table:end -->
-
-The table describes button clicks and face-button touches. View sends Menu click only. Triggers, grip pressure,
-thumbsticks, tracked poses and vibration keep their corresponding Touch bindings.
-
-## Choose a mode
-
-For one game, open its **Game settings → Controllers → Controller buttons**. Choose **Use global default** to
-follow Settings, or select a specific mode to keep an override for that game. An explicit **SteamVR default**
-keeps mode 0 even when the global choice is Mirror or Quest pair.
-
-For the library default, open **Settings → Controllers**. The diagram follows the selected mode. New installs
-and configuration updates use this default for games without an override. With a Frame connected, choose
-**Apply to installed games now** to send it to installed Quest games that follow the global default. Overrides
-are kept. Changing the default does not mark every game as needing an update.
-
-Changes take effect at the **next launch**. Close and relaunch a running game.
-Games installed before this feature need **Update on Frame** once for the mode to work.
-
-The CLI can change an installed game's runtime setting:
-
-```sh
-frameport settings <pkg> quest_buttons=2
-```
-
-Use `0` for SteamVR default or `1` for Mirror. This command writes the installed settings directly; it does not
-save a per-game recipe override. To keep the value through later installs and global applies, also save it in
-the recipe, or use Game settings:
-
-```sh
-frameport recipe <pkg> --set quest_buttons=2
-```
-
-## Limits
-
-- SteamVR's binding UI can still override these suggested bindings. Check custom bindings if the result differs
-  from the diagram.
-- The d-pad has a single touch sensor: a thumb resting on it touches X and Y together. The right controller's
-  face buttons sense touch one by one.
-- Bumpers have no Touch counterpart and are unbound. Thumbrest touch is dropped; the Frame profile has no
-  corresponding input. System buttons keep their runtime role.
-- Mirror and Quest pair require the Frame runtime's `XR_VALVE_frame_controller_interaction` extension. If it is
-  absent, FrameBridge logs that fact and leaves SteamVR's remap in place.
-- Games suggesting their own Frame Controller bindings keep those bindings and continue seeing the Frame
-  Controller profile, even if they also suggest Touch bindings. These modes do not replace the game's own mapping.
-- Touch suggestions using bare pose, trigger, squeeze or button paths are translated too; explicit components
-  such as `/pose`, `/value`, `/click` and `/touch` are also supported where the mapping provides them.
-- Finger proximity emulation (`proximity_emul`) continues to work with Mirror and Quest pair. Dropping the
-  unsupported thumbrest path does not disable proximity emulation from the other touch inputs.
-- The setting applies to Quest VR games, including 32-bit games through the bridge. It does not change PC VR or
-  flat Android Steam Input layouts.
-
-The mapping follows [Valve's Frame Controller input reference](https://partner.steamgames.com/doc/steamhardware/steamframe/input)
-and the [shared mapping data](input/quest_buttons.json). To regenerate the diagram, app illustrations and table,
-run `uv run python scripts/controller_diagram.py`; add `--check` to verify them without writing files.

docs/DEVICE_NOTES.md

@@ -1,844 +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). The shared detour now publishes one aligned AArch64 branch to a range-checked nearby stub, with a one-instruction trampoline; protection failures roll back (published mappings must remain alive for in-flight threads). See [AUDIO_GEOMETRY.md](AUDIO_GEOMETRY.md) for failure limits and host validation; this publication change has not been device-tested. Original repair 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/#385, 2026-10-17):** the Frame's runtime refuses `faceCount=6`
-swapchains (-2, XR_ERROR_RUNTIME_FAILURE). `cube_standin` (default on, `native/adapter/cube_standin.c`)
-serves refused cubes with a GLES cube texture in the app's context or a Vulkan cube-compatible image.
-This prevents OVRPlugin's empty-image-list crash (Budget Cuts Ultimate; Vulkan UNDERDOGS).
-
-`cube_quads` (int, default 1) now copies mip 0 into six runtime quad swapchains, replacing each cube at
-its original layer-list position. Face order is +X, -X, +Y, -Y, +Z, -Z; inward-facing quad right/up axes
-match GL cube s/t. Vulkan copies reverse rows for its top-left quad image origin. The cube orientation
-rotates the box; its centre follows the stereo view midpoint in the layer's space at displayTime
-(falls back to the space origin without valid tracking). Faces are 100 m square at 50 m distance.
-Eye visibility and layer flags are retained. Quads submitted by the game retain their order.
-
-The Frame draws quads above **every** projection, regardless of order. This implementation conservatively
-drops cubes whenever any projection is submitted, including alpha projections: it supports cube-only
-loading screens with optional quad overlays, not skyboxes behind gameplay. Multiple cubes of the same
-size/format share six swapchains, using separate array slices so their images cannot overwrite one another.
-Each pool is copied once per frame. Other sizes need another six swapchains; runtime allocation refusal
-(particularly near its ~15-swapchain cap) frees partial allocations and disables that pool until reset.
-Pools are freed on stand-in creation/destruction, xrEndSession and session destruction; stand-ins are also freed at
-session destruction. Set `cube_quads=0` for the previous drop-only behaviour.
-
-Look for `cube_quads: created six ... face swapchains (GLES|Vulkan)` and
-`cube_quads: submitting cube as six quads (half-size=50m, mip=0)`. Refusals log
-`cube_quads: face swapchain creation failed (result=...); dropping cube layers`; mixed frames log
-`cube_quads: skipping cube with projection; preserving scene visibility` once.
-Host math/settings/artifact checks and Android builds are available; no device test yet. Headset checks
-still needed: face seams/orientation, sRGB/alpha, GLES context availability, Vulkan synchronization and
-loading-to-gameplay transitions (HardBullet's 1024²/32² Vulkan cubes; Budget Cuts GLES).
-
-## 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.
-
-## Mixed reality: scanned rooms
-
-Live floor coverage (agent v104) is enabled by default for manual and game-requested scans; the capture
-payload accepts `preview: false`, and `frameport frame room scan --no-preview` disables it. A world-locked,
-upward-facing 6 m square at floor height follows the current raw-to-STAGE calibration and stays centred on the
-scan's first recorded camera position. Every 16th depth vertex contributes to raw-space 10 cm voxels; at most once
-per second, newly occupied cells redraw a 256×256 RGBA map in one colour (FramePort's secondary blue), each cell a
-filled 10 cm square, only the opacity telling floor (<0.3 m, faint), raised surfaces (0.3–1.5 m) and tall surfaces
-(>1.5 m, strongest, the room's outline) apart; unseen transparent. Overlays have no depth (they draw over hands and
-passthrough), so the map stays faint; three colours in 3x3 blotches clashed in the owner's first run. It shows
-coverage, not a validated room boundary. IVROverlay_028 slots 1/3/20/22/33/43/62 (OpenVR 2.15.6 header)
-create/destroy/sort order (1, below the scan prompts' 10)/set width/set absolute STAGE transform/show/upload raw
-pixels. Each upload is 256 KiB (at most 256 KiB/s); timing for the first
-20 uploads and every tenth thereafter, plus failures, goes to `rooms/scans/scan-*.fprs.log` and the built room’s `scan.log`. Overlay errors or an
-upload taking over 50 ms disable the preview while capture continues; headset appearance and upload cost still
-need device validation.
-
-When an MR game asks for a room scan, FramePort scans in the headset and FrameBridge loads the new room before
-answering the game. If no scanner answers within five seconds, the game gets the stored room. Set
-`scene_scan_request=0` to always use the stored room. A scan that starts but fails keeps the old room and reports
-a capture failure to the game.
-
-**Mixed reality: scanned rooms (agent v92, 2026-10-16, branch mr-scene; docs/mr/):** Quest MR games read the room
-through Meta's scene APIs; the Frame offers none, and Valve's chaperone is no room (2D outline raised to 2.43 m, often
-the default 1 m circle -> the Android runtime's STAGE rect falls back to 1x1 m; XRService's plane detection is
-horizontal-only, its persistent map sparse ORB, its XRIPC single-client; cameras are XRService's alone,
-IVRTrackedCamera gives no frames). **The passthrough's RoomView 3D depth mesh is readable** (docs/mr/PHASE0.md:
-IVRBlockQueue_005 `/xrservice/roomview3d/meshData|meshLayout`, metadata through the C++ `IVRPaths_002` on the block
-handle, `meshIsUpToDate` on the queue handle; 132x128 fan, ~30/s; raw->standing moves during a session -> convert
-with the final one), so FramePort scans rooms itself: agent `room_capture` (Background/Overlay OpenVR app, prompts =
-artifacts/roomscan/*.png via IVROverlay_028 slots 1/3/20/22/35/43/44/63, `scripts/mr/render_prompts.py`) -> `.fprs`
-dump -> `fp_roomscan` (native/roomscan, freestanding, offline) -> `room.txt` + `room-mesh.bin`
-(docs/mr/ROOM_FORMAT.md; outline = positive shoelace in x-z, wall inward normal (-dz, dx)) in
-`~/.local/share/frameport/rooms/<universe>/`; launch.sh copies it next to settings.conf (`_room_sync`, games with
-`scene_emul`); FrameBridge (`scene_room.c/scene_meta.c/scene_anchors.c`) serves N walls, volumes (BOUNDED_3D),
-planes, GLOBAL_MESH (XR_META_spatial_entity_mesh), XR_META discovery/persistence (newer Meta SDKs and MRUK), anchors
-saved in `files/framebridge-anchors.txt`; all through xrshim (OVRPort's dispatcher drops unknown META calls).
-`scene_emul` is now suggested for every USE_SCENE/USE_ANCHOR_API game (migration `scene_emul_all`; NOPE and Pinball
-FX had none). PC: Frame page "Room" card, `frameport frame room scan|status|from-boundary|import|export|build|show`.
-Real data (owner's room, 2026-10-16): floor at 0, table surfaces, orthogonal walls found; the ceiling needs "look up".
-
-Scan on request (agent v103): scene-emulation launchers run `_scan_watch` alongside the game. FrameBridge's
-`framebridge-scan-request` in the game's external files directory gets an ack, then the existing prompted headset
-capture/build flow saves and copies the new room before an `ok` result; errors, cancellation and timeout return
-`failed`. Captures share a global lock, stale protocol files are cleared on launch, and the watcher stops with the
-launcher. Logs: `<base>/scan-watch.log`. Device validation is still required.
-
-PR #246 (@alicecatpaw, merged into mr-scene 2026-10-18): FrameBridge trims frames to maxLayerCount (Punch Fit sent
-21+ layers; projection layers and FrameBridge's fade quad always stay), drops quads with zero size or an empty image
-rect, and logs up to 10 quads with pose and swapchain. Two Unity patches, both only from a catalog recipe or the
-user's choice: `frame.meta_depth_occlusion` (Depth API occlusion off; Laser Dance's lasers vanished up close) and
-`frame.unity_scene_active_rooms` (OVRSceneManager's player-in-room check). The PR's own META discovery and boundary
-visibility code was replaced by this branch's (`scene_meta.c`). The PR's recipes were checked on the author's Frame
-only; open question: does OVRPort's dispatcher advertise XR_META_environment_depth (then a FrameBridge setting that
-hides it would fix depth occlusion for every engine).
-
-## Vulkan pipelines refused: Fossilize and Turnip (Transformers, #349)
-
-Transformers Beyond Reality: Redux (Unreal, Vulkan) ended its first frames with Unreal's "Shader compilation failures
-are Fatal." (2026-10-17, headless on the dev Frame). `vk_pipeline_log=1` showed every graphics pipeline failing in
-pairs: the precache attempt with `VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT` (flags 0x100) answers
-`1000297000` (= VK_PIPELINE_COMPILE_REQUIRED, normal), the real compile answers `-1` (VK_ERROR_OUT_OF_HOST_MEMORY)
-in the same millisecond, and the shim never logged a single success. The dumped SPIR-V was valid (spirv-val), one
-module a constant-colour fragment shader. Ruled out in one run each: the app's VkPipelineCache, its
-VkAllocationCallbacks (retry without either/both), Valve's VALVE_rpo/VALVE_fdm_injection (`device.foveation: off`).
-Khronos' validation layer added a crash of its own (null deref in its vkCreateRenderPass2 on the game's create info,
-the shim changed nothing there): don't use it for this game. Removing `VK_LAYER_fossilize` from GraphicsEnv's debug
-layer list (`android::GraphicsEnv::setDebugLayers`, as `native/zinkfix` adds its layer) made the pipelines compile:
-360 modules instead of 10, frames submitted. Two Fossilize instances are still created by other threads before the
-engine loads the shim; they aren't the renderer's. About six pipelines with the game's multiview vertex shader
-(module 12944, ViewIndex) still fail in Turnip; a blank fragment shader alone doesn't help, blank vertex + fragment
-does. Settings `vk_no_fossilize` + `vk_pipeline_fallback` (catalog entry): headless RUNNING after 72 s at 72 fps.
-Headset check pending (some objects may be missing).
-
-## Quest controller mode (`quest_buttons`, 2026-10-17)
-
-Adapter setting `quest_buttons` (0 SteamVR default, 1 Mirror, 2 Quest pair; contract docs/input/QUEST_BUTTONS.md,
-user page docs/CONTROLLERS.md). FrameBridge enables `XR_VALVE_frame_controller_interaction` and, after a game's Touch
-suggestion succeeds, suggests `/interaction_profiles/valve/frame_controller_valve` bindings translated from the
-accepted Touch set (SteamVR uses a Frame binding before its own Touch remap: Touch B/Y on all three top buttons).
-
-Headless check on the device (I Am Cat, Unity + OVRPlugin, mode 2, `input_diag=1`): the runtime offers and enables the
-extension in a Lepton app, and accepts the generated Frame suggestion (`quest_buttons: frame_controller bindings
-(mode 2, 27 bindings, 7 dropped): 0`); the game's Touch (34 paths) and hand-interaction suggestions were accepted as
-before; 72 fps, no new errors. Translations as in the JSON at the time: left `x/*` -> `dpad_down/*`, `y/*` -> `dpad_left/*`,
-`menu/click` -> `view/click`. Not provable headless (tracking needs the headset worn): that SteamVR then reads the
-buttons from the Frame binding; one launch in the headset settles it.
-
-Pitfall seen during the test: OVRPort runs from two sessions on the same data folder share
-`overport-workspace/dec/working.apk` and fail at once (`OVRPort failed (exit 1)`, `FileAlreadyExistsException` in
-OVRPort's own output, which the CLI doesn't print without a verbose reporter). Build one game at a time per data folder.
-
-Headset round 2026-10-18 (owner, TestQuestControllers): the button mapping works. Owner's corrections, now in the JSON:
-Quest's second button sits up and toward the other hand, so Quest pair = left Y on d-pad right, right B on X (Mirror
-follows: X/A = bottom + outer, Y/B = top + inner). The d-pad has one capacitive sensor: a thumb on it touches every
-direction, so X and Y touch light together (left as is, hardware limit); the right face buttons sense touch singly.
-SteamVR's own Touch remap (`/opt/steamvr/drivers/frame_controller/resources/input/frame_controller_remapping.json`,
-layout `oculus_touch`) is the diagram's "SteamVR default": X -> d-pad down, Y -> d-pad left/right/up, A -> A,
-B -> B/X/Y, Menu -> View, plus trigger click -> bumper. Games with their own Valve binding file in that folder
-(Beat Saber, Batman, Accounting+, In Death, ...) use that file instead.

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,30 +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: **Back up saves** next to Play on
-the installed game's page, 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).
-
-In **Settings → Data**, **Choose backup folder…** selects a different folder, including a local Drive or Nextcloud
-sync folder. FramePort checks that it can write there. **Use the default** resets the location. Existing backups stay
-where they are and remain listed for restoring; retention only removes old backups in the currently selected folder.
-FramePort writes local files; your cloud client handles uploading them.
-
-**Back up saves when a game closes** (Settings → Data, off by default) keeps the newest three changed snapshots per
-game on the Frame, even while FramePort is closed. Connect once after changing this setting to apply it to the Frame.
-New snapshots are copied to your backup folder when FramePort connects or polls the connection, marked **automatic**,
-and count toward the same backup limit. Unchanged saves are skipped. A snapshot captures what the game wrote to disk;
-it cannot recover progress a forcibly closed game never saved.
-
-**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,96 +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.
 
-## Room data
-
-Live floor coverage (agent v104) is enabled by default for manual and game-requested scans; the capture
-payload accepts `preview: false`, and `frameport frame room scan --no-preview` disables it. A world-locked,
-upward-facing 6 m square at floor height follows the current raw-to-STAGE calibration and stays centred on the
-scan's first recorded camera position. Every 16th depth vertex contributes to raw-space 10 cm voxels; at most once
-per second, newly occupied cells redraw a 256×256 RGBA map in one colour (FramePort's secondary blue), each cell a
-filled 10 cm square, only the opacity telling floor (<0.3 m, faint), raised surfaces (0.3–1.5 m) and tall surfaces
-(>1.5 m, strongest, the room's outline) apart; unseen transparent. Overlays have no depth (they draw over hands and
-passthrough), so the map stays faint; three colours in 3x3 blotches clashed in the owner's first run. It shows
-coverage, not a validated room boundary. IVROverlay_028 slots 1/3/20/22/33/43/62 (OpenVR 2.15.6 header)
-create/destroy/sort order (1, below the scan prompts' 10)/set width/set absolute STAGE transform/show/upload raw
-pixels. Each upload is 256 KiB (at most 256 KiB/s); timing for the first
-20 uploads and every tenth thereafter, plus failures, goes to `rooms/scans/scan-*.fprs.log` and the built room’s `scan.log`. Overlay errors or an
-upload taking over 50 ms disable the preview while capture continues; headset appearance and upload cost still
-need device validation.
-
-- SteamVR on the Frame has no Meta scene/anchor extensions. Its chaperone supplies only a 2D outline raised to
-  2.43 m, without furniture, ceiling or a room mesh. Valve's default boundary is a 20-point circle of roughly 1 m
-  radius; FramePort refuses to treat it as a room.
-- FrameBridge's `scene_emul=1` serves saved room data, with a guardian box when no room is available. OVRPort's
-  loader only dispatches functions in its own table: newer Meta entry points go through FramePort's extension shim.
-  MRUK uses discovery (`xrDiscoverSpacesMETA`, older versions `xrQuerySpacesFB`) and requests Space Setup when
-  discovery returns no rooms. Volumes hang below their top-face anchor in Meta's coordinate convention.
-- Room files use STAGE coordinates (metres, +Y up, floor y=0, -Z forward). The format contract is
-  [mr/ROOM_FORMAT.md](mr/ROOM_FORMAT.md). On the Frame: `~/.local/share/frameport/rooms/<universe>/room.txt`,
-  optional `room-mesh.bin` and `scan.log`; `rooms/current` points to the most recently saved room.
-- A room belongs to its chaperone universe. The agent reads the last universe switch from `vrserver.txt`, falling
-  back to the newest universe in `~/.config/openvr/config/chaperone_info.vrchap`; dummy 424242 means none.
-  A matching room is selected first, else `current`; the app reports `aligned: false` after a universe change.
-- Quest launchers copy that room beside `settings.conf` before Lepton starts; FrameBridge reads
-  `dirname($FRAMEBRIDGE_CONFIG)/room.txt`. Stale copies are removed if no room exists or emulation is disabled.
-  Each game's persistent anchors stay in `/sdcard/Android/data/<pkg>/files/framebridge-anchors.txt`.
-- With `scene_emul`, launch.sh starts `_scan_watch <pkg>` after Lepton, closing fd 9; its exit trap stops the
-  watcher, which also exits if the launcher disappears. It polls once a second and logs to `<base>/scan-watch.log`.
-  In `<base>/lepton-data/external/Android/data/<pkg>/files/`, FrameBridge writes `framebridge-scan-request`
-  (`request <id> <unix_seconds>`); the watcher clears stale request/ack/result files at startup, writes
-  `framebridge-scan-ack` (`ack <id>`), reuses the headset capture/build worker, stores the current room and copies
-  it beside settings.conf before atomically writing `framebridge-scan-result` (`ok <id>` or `failed <id> <reason>`).
-  A global `rooms/.scan.lock` excludes concurrent captures, including manual scans; `rooms/.lock` still protects
-  room publication. Launcher exit cancels the scan; a 350-second deadline leaves time for the six-minute protocol timeout.
-- Frame → Room and `frameport frame room` manage rooms. `from-boundary` creates walls without furniture;
-  `import` / `export` transfer room files; `show` writes an SVG preview; `build <dump.fprs>` syncs the bundled
-  `fp_roomscan` by SHA-256 and runs it on the Frame with `--offline`. `scan` = agent `room_capture`: records the
-  RoomView meshes (`/xrservice/roomview3d/meshData` + `/meshLayout`, `IVRBlockQueue_005`) while in-headset prompts
-  guide the player, then builds the room from that recording.
-
-## Save backups (Quest games, agent v101, 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.
-- PC destination: `saves.folder` (empty = `<data>/save-backups`); Settings → Data has an awaited folder picker,
-  a default reset and a write probe. Old destinations (`saves.previous_folders`) stay listed; switching never moves
-  or deletes files. `saves.keep` defaults to 10 and prunes only the selected destination.
-- `saves.auto` defaults off. Connection and 30 s poll hooks sync its value using `save_snapshot_settings` (flag
-  `~/.local/share/frameport/save-snapshots/enabled`). Updated and newly written Quest launchers call `_snapshot_close`
-  after stopping the container, inside the EXIT trap, with the launch lock still held on fd 9. The worker verifies
-  that fd against `<base>/.launch.lock` and passes it through `podman unshare`; another launch cannot run meanwhile.
-  `timeout -k 5 90` bounds the whole worker. PC VR/Linux launchers have no snapshot step.
-- Snapshots use the same archive builder, exclusions and 64 MiB/file, 4 GiB/total limits as manual backups.
-  File paths/sizes/content hashes form a fingerprint; unchanged saves skip compression. Complete snapshots are
-  atomically published under `~/.local/share/frameport/save-snapshots/<pkg>/<ns>-<sha256>.tar.gz`, with fingerprint
-  sidecars. The newest three per game are retained; interrupted `.part` files are overwritten on the next attempt.
-- `save_snapshots` lists immutable snapshots oldest first per game; `_fetch_save_snapshot '<json>'` streams one
-  (archive stdout, result JSON stderr). PC `install/saves.sync_snapshots` runs in the background, verifies the archive
-  hash and package, imports it as a normal backup marked `automatic`, and applies `saves.keep`. A local
-  `<data>/save-snapshots-synced.json` digest ledger prevents reimporting snapshots after pruning or deleting backups.
-  Failures leave snapshots on the Frame for the next poll. This path does no disk/SSH work in rendering.
-
 ## 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
@@ -171,39 +75,15 @@ need device validation.
   `ComposeLayerQuad` and `ComposeLayerProjection`; cube/cylinder/equirect/equirect2 exist only as enum names, so
   there is nothing to switch on. It has a layer limit ("Exceeded the layer limit"; the value is logged by
   `layer_debug` from `maxLayerCount`). The adapter emulates cylinders (strips) and, per game, equirect layers
-  (`equirect_emul`, an adapter projection layer). Refused cube swapchains use GLES/Vulkan stand-ins;
-  `cube_quads` (default on) copies their faces into six quads for frames without a projection
-  (see DEVICE_NOTES "Cube swapchains"). Quad layers are drawn above every projection layer regardless of
+  (`equirect_emul`, an adapter projection layer). Quad layers are drawn above every projection layer regardless of
   submission order (seen 2026-10-01: quads placed before 4XVR's projection layer covered it).
 - 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.
 
-### Frame Controller input
-
-The runtime offers `XR_VALVE_frame_controller_interaction`, with interaction profile
-`/interaction_profiles/valve/frame_controller_valve`. [Valve's input reference](https://partner.steamgames.com/doc/steamhardware/steamframe/input)
-describes two gamepad halves. Under `/user/hand/<hand>/input/`:
-
-- Left: `dpad_up`, `dpad_down`, `dpad_left`, `dpad_right`, `view` (click and touch).
-- Right: `a`, `b`, `x`, `y`, `menu` (click and touch). The face diamond is A bottom, B right, X left, Y top.
-- Both: `system`, `bumper`; `squeeze` and `trigger` (click, touch, value); `thumbstick` (vector, x, y, click,
-  touch); `grip/pose`, `aim/pose`. Haptics use `/user/hand/<hand>/output/haptic`.
-
-SteamVR prefers a game's Frame Controller binding. Without one, its Touch remap sends left d-pad down as Touch X
-and left/up/right as Touch Y; right A as Touch A and X/Y/B as Touch B. Left View sends Touch Menu.
-FrameBridge's `quest_buttons` preference (`0` default, `1` Mirror, `2` Quest pair) enables the extension when offered
-and suggests a Frame binding translated from the game's Touch suggestions. Common pressure/trigger/thumbstick,
-pose and haptic paths keep their Touch counterparts; thumbrest touch and system click are dropped, bumpers stay
-unbound. The player's SteamVR custom bindings can override suggestions. This works on both bridge ABIs, without
-the arm64-only extension shim. See [Controller buttons](CONTROLLERS.md) and the [mapping contract](input/QUEST_BUTTONS.md).
-Device verification of the new modes is pending integration with the native stream.
-
 ## Lua native pointer compatibility
 
 Frame's Android processes can map libraries above the lowest 2^47 bytes of address space. The verified xLua API 105
@@ -482,59 +362,15 @@ 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.
-The area selector now uses Valve's supported `FOVE_LEVEL` presets (GitHub #394; binary analysis
-2026-10-17). Default leaves the runtime choice alone; on the shared injection path this is `lo`.
-The old `FOVE_INNER`/`FOVE_OUTER` radius exports had no effect: Lepton does not pass them through,
-and the layer does not read them. The previously documented 0.30/0.60, 0.25/0.50, 0.20/0.40
-radius pairs do **not** describe the generated shared-injection density map.
-
-The inspected arm64 `libVkLayer_VALVE_fdm_injection.so` has these semantics (virtual addresses):
-- `init_fdm_fove_level` at `0x1cdf4` calls the cached option reader, then
-  `debug_parse_flags_option` (`0x21d74`) with table `0x27e70`: named tokens `lo` → 1,
-  `med` → 2, `hi` → 3. It does not call atoi/strtol. Unset, empty, unknown and numeric
-  strings parse to zero and retain the current profile (initialized to 1 at `0x1ce74`).
-  Tokens are case-sensitive and separated by non-alphanumeric/non-underscore characters;
-  matching values are ORed, so combinations can alias another profile. `all` also yields 3;
-  `help` prints the table and returns zero. Use a single preset token.
-- Profile selection at `0x1918c–0x19364` uses normalized **rectangles**, not circular radii.
-  `lo` has a full-density center rectangle `(x=.364, y=.367, width=.295, height=.286)`
-  (constant at `0xe440`), then density byte `0x76` outside. `med` uses rectangles from
-  `0xe988`: sizes `.250×.245`, `.295×.286`, `.386×.367`, with density bytes
-  `0xff`, `0xa8`, `0x76` and `0x50` outside. `hi` uses `0xe9b8`: sizes
-  `.246×.211`, `.281×.246`, `.351×.316`, `.386×.351`, with bytes
-  `0xff`, `0xa8`, `0x76`, `0x50`, then `0x38` outside. Each byte is written to both
-  R8G8 density channels. All three retain a full-density center (`0xff`); medium/high make it smaller
-  and reduce peripheral density more. Coordinates are sampled on the density-map grid (`0x19378` onward).
-- `FDM_DEBUG` flags `lo`/`med`/`hi` also select presets (high takes precedence), but an
-  explicit recognized `FOVE_LEVEL` overrides them (`0x1ce14`). `enable` gates injection;
-  `disable_offsets` fixes the gaze position (`0x1b6c8`), and `yflip` flips the vertical
-  offset (`0x1b9b8`). These three flags do not resize the profile.
-- `FDM_SWAPCHAIN_SIZE` is parsed by `atoi` (`0x1c518`), clamped to nonnegative, and
-  seeds a known swapchain size (`0x1ccf8`). It is a size/matching hint, not a radius.
-  The synthetic map is square with side `ceil(size/32)` (`0x19048–0x19088`); image
-  association also matches this tile size (`0x16c78`). Changing render resolution changes
-  the pixel extent, tile quantization and potentially the matched render target/map. This can
-  change the visible diagnostic area without making the ignored radius exports effective;
-  a matched device capture is needed to establish which path a particular game used.
-
-Per-game library preferences now store `level`. Legacy radius choices are translated on read
-(and written as `level` on Save): nearest old nominal .30 → lo, .25 → med, .20 → hi,
-with larger values clamped by nearest choice; zero or unknown/invalid values → Default.
-This preserves approximate intent, not a claim that these presets implement those radii.
-Explicit `level` wins. Obsolete radius exports are removed from managed launchers.
-
-For device verification, hold game scene, render resolution and gaze constant; compare explicit
-`lo`, `med`, `hi` across fresh game starts (Default should match lo absent another runtime override).
-First use Fixed for a stable comparison, then Eye-tracked to check gaze following. Enable
-**Darken coarse fragments (test)** and adapter `snapshot=N` to capture submitted eye images headlessly
-every N seconds (GLES only, left eye at quarter size); compare the undarkened center and peripheral bands. Existing adapter
-builds need diagnostic support installed. Turn the test and snapshots off before benchmarking.
-Agent `FOVEATION_ENV_KEYS` must include `"FOVE_LEVEL"` for launcher updates via `set_settings`.
+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.
+The inspected runtime's built-in inner/outer pairs are 0.30/0.60, 0.25/0.50 and 0.20/0.40.
+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, profile 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.
@@ -550,18 +386,18 @@ 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.
-Preset export/migration has configuration coverage; these preset comparisons have not been device-tested here.
+The new configurable radii have configuration/build coverage; each radius has not been separately play-tested.
 
 ## Monitoring sources (probed 2026-10-07, SteamOS 0.4.3, kernel 6.18; used by the Monitor tab, agent `_monitor`)
 
@@ -570,7 +406,7 @@ All readable by the steamos user without root; the agent reads them directly (no
 | Metric | Source | Notes |
 |---|---|---|
 | CPU | `/proc/stat` deltas; `cpufreq/policy{0,2,5,7}` | 8 cores in 4 clusters: 0-1 / 2-4 / 5-6 / 7 (max 2.27 / 3.15 / 2.96 / 3.05 GHz) |
-| GPU busy | Sum of `drm-engine-gpu` (ns) deltas in `/proc/<pid>/fdinfo/<fd>` over every render-node fd (msm DRM) | Gives GPU % per process too. A process can hold several render fds: add them all. Lepton games see the node as `/dev/kgsl-3d0` (bind mount of `/dev/dri/renderD128`). `drm-total-memory` reads 0. msm can report garbage engine time (SteamVR's vrcompositor: near 2^64, rising ~1000x faster than real time; idle Frame at 100 %, 2026-10-18): a per-fd delta longer than the interval falls back to `drm-cycles-gpu` / GPU clock (agent v102 `gpu_busy_ns`) |
+| GPU busy | Sum of `drm-engine-gpu` (ns) deltas in `/proc/<pid>/fdinfo/<fd>` over every render-node fd (msm DRM) | Gives GPU % per process too. A process can hold several render fds: add them all. Lepton games see the node as `/dev/kgsl-3d0` (bind mount of `/dev/dri/renderD128`). `drm-total-memory` reads 0 |
 | GPU clock | `/sys/class/devfreq/3d00000.gpu/{cur,max}_freq` | 231–903 MHz in 12 steps |
 | Memory / pressure | `/proc/meminfo`; `/proc/pressure/{cpu,memory,io}` (`some avg10`) | 16 GB RAM, 8 GB swap |
 | Temperatures | `/sys/class/thermal/thermal_zone*/{type,temp}` | 48 zones: `cpu*`/`cpuss*`, `gpuss-*`, `ddr`, `nsph*` (NPU), `pm8550*`/`pm8010*` (power ICs), `modem*`, `camera*`, `video`, `max1720x_bat*` |
@@ -585,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, a runtime profile, 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.