Merge pull request #33 from saphid/remote-wake

Remote-wake test results and a Frame doctor runbook

.claude/skills/steam-frame/SKILL.md

@@ -28,6 +28,7 @@ desktop or panels.
 | Launch an app inside the desktop panel | the script's header comment | `scripts/run-on-frame.sh` |
 | Mac GUI over all of this | `README.md` → Frame Control | `scripts/frame-ui.sh` |
 | iPhone/iPad app (server runs on the Frame, `FRAME_LOCAL=1`) | `docs/iphone.md` | `ios/`, `ui/local-bin/ssh` |
+| Frame unreachable, Wi-Fi dead, Steam won't start (doctor runbook) | `docs/frame-doctor.md` | — |
 | Recovery images, factory reset, boot loops | `docs/recovery-and-images.md`, `docs/how-the-frame-works.md` | `~/Downloads/steam-frame-recovery/` |
 | Test without the headset (the Frame OS image's own sshd) | `tests/frame-container/README.md` | `tests/frame-container/frame-image.sh` |
 | What's still unverified | `docs/open-questions.md` | — |

.gitignore

@@ -1,7 +1,7 @@
 .DS_Store
 __pycache__/
 apk-catalog/data/cache/
-apk-catalog/data/index-v2*.json*
+apk-catalog/data/index-v2.json*
 compat-db/.env.lakebed.server
 compat-db/.lakebed/
 tests/smoke/results/

docs/apks.md

@@ -46,33 +46,6 @@ Lepton Development must be installed once. Over SSH,
 `ssh frame 'steam steam://install/3056000'` queues it, but the install still
 needs to be confirmed or started in the headset.
 
-## When an app needs a newer Android
-
-Lepton is Android 11 (API 30), with arm64-v8a only. If Frame Control refuses
-an APK, it shows compatible versions from F-Droid's main and archive repos and
-IzzyOnDroid. It shows at most eight version names, newest first, preferring an
-arm64-only build, and says how many compatible builds it found in total.
-Each index is reduced to its compatible builds once a day and cached (about
-16 MB). The first lookup takes about 30 s and 100 MB of memory; later ones are
-instant.
-Choose **Install** to download a listed version, verify its SHA-256 against
-the index, and install it as its own app.
-
-You can also inspect a file or look up a package from the command line:
-
-```sh
-python3 ui/frame_android.py info some-app.apk
-python3 ui/frame_android.py versions some-app.apk
-python3 ui/frame_android.py versions org.example.app
-```
-
-The search links open APKMirror, APKPure, Uptodown, F-Droid and GitHub. Pick a
-version whose minimum is Android 11 or lower and that has an arm64-v8a build
-(or no native code). Frame Control does not fetch APKs from those search sites.
-Older versions may lack fixes, and being installable does not guarantee an
-app will run: see the missing services below. Android may refuse a downgrade
-or an update signed by a different publisher; removing the app deletes its data.
-
 ## Installed apps disappear when Lepton Development closes (verified 2026-09-25)
 
 Lepton Development runs in a throwaway "dev" context. When it exits for any

docs/frame-doctor.md

@@ -0,0 +1,490 @@
+# Frame doctor runbook
+
+Checks and fixes for a Frame that's unreachable, crashing, or whose Steam,
+SteamVR, Lepton or panels misbehave. A future `scripts/frame-doctor.sh` should
+run the checks in section order, print OK, WARN or BROKEN for each, and apply
+only the fixes marked **safe**. Anything marked **ask** needs the user's OK,
+and anything marked **user** needs a hand on the headset.
+
+Sources are the Frame's own journal and `coredumpctl` history (boots from
+2026-09-25 to 2026-09-28) and this repo's docs. Each entry cites where it came
+from. Dates are when a fact was seen. BUILD_IDs were 20260922.6101926 until
+2026-09-26 and 20260925.6191901 after.
+
+## Never do these
+
+- `modprobe -r ath12k` on a wedged Wi-Fi chip. It oopsed the kernel on
+  2026-09-28 and caused the displays-broken, Steam-damaged boot in section 3.
+- Leave WoWLAN armed. The next sleep breaks Wi-Fi until reboot (section 2).
+- Suspend the Frame from a script. Nothing can wake it remotely (section 6).
+- Let the SteamOS health checks count up to their repair. The SteamVR one
+  re-extracts Steam at 3 failures and tries to switch OS slots at 4 (section 4).
+- Kill `gamescope` to stop a gamescope crash loop. Kill the orphaned SteamVR
+  processes instead (section 3).
+- Write the sudo password to disk or logs.
+- Leave `power.pauseCompositorOnStandby` or `power.turnOffScreensTimeout`
+  changed after testing (section 3).
+- Force a power-off (holding Power) or reset while Steam is extracting or
+  repairing. That's how files got truncated on 2026-09-28. Use an orderly
+  `systemctl reboot`/`poweroff` or the power menu. Holding Power is for an
+  unresponsive Frame, with the user's involvement.
+- Run long diagnostics while a Steam or SteamVR restart loop is live without
+  freezing the health-check trackers first (section 4). The repair threshold is
+  3 SteamVR failures, and a loop reaches it in under a minute.
+
+## 0. Reaching the Frame
+
+| Path | How | Works when |
+|---|---|---|
+| Tailscale | `ssh frame` (`frame.<tailnet>.ts.net`) | Wi-Fi up, and Tailscale on the Mac and the Frame |
+| LAN | `ssh -o HostName=192.168.1.237 -o HostKeyAlias=frame.<tailnet>.ts.net frame`, or `frame.local` | Wi-Fi up. The alias avoids "Host key verification failed" |
+| USB-C | Same, with `HostName=10.86.200.233` | Cable to the Mac, even with Wi-Fi dead. The Mac gets `en9` "Steam Frame" 10.86.200.234/29 (`networksetup -listallhardwareports`) |
+| ADB over USB-C | `adb -s frame shell` | SSH refused, for example after Developer Mode was lost ([how-the-frame-works.md](how-the-frame-works.md), boot-loop row) |
+
+- **Asleep means off the network (verified 2026-09-27, unreachable for about
+  2.5 h).** Every path times out and nothing remote wakes it
+  (section 6). **user**: press power. `tailscale status | grep frame` on the
+  Mac shows "offline, last seen N ago".
+- **`frame` alias doesn't resolve.** The Mac's Tailscale is off. Use
+  `frame.local` ([tailscale.md](tailscale.md)). Bare `frame` doesn't resolve on
+  macOS. Check with `dns-sd -G v4 frame.local` ([ssh.md](ssh.md)).
+- **Pairing answers `403 "please put the Steam client in pairing mode"`.**
+  **user**: Steam, then Settings → Developer → Pair new host. `connect.sh`
+  retries for 2 min ([ssh.md](ssh.md)).
+- **iPhone app can't use devkit pairing.** It only installs an RSA key, and
+  Citadel signs RSA with SHA-1, which OpenSSH 9.7 rejects. Use ed25519 and
+  password pairing instead ([ssh.md](ssh.md), 2026-09-27).
+- **Locked out after `connect.sh --harden`.** Undo with `sudo rm
+  /etc/ssh/sshd_config.d/01-frame-keys-only.conf && sudo systemctl reload sshd`
+  (**ask**, over USB-C or ADB) ([ssh.md](ssh.md)).
+- **No SSH at all (Developer Mode off).** Run `scripts/serve-bootstrap.sh`, and
+  the **user** types `curl -fsS mac.local:8765|bash` in Konsole. Stop the
+  server afterwards, because it's plain HTTP ([ssh.md](ssh.md)).
+- **Tailscale exposes every loopback port** (8080 Steam DevTools, 5555
+  unauthenticated ADB, 27062, 3389) to the tailnet. Check read-only with
+  `~/.local/bin/tailscale debug prefs | grep ShieldsUp` (the CLI isn't on `PATH`; verified 2026-09-28) and the tailnet ACLs. Report it
+  as a WARN. `~/.local/bin/tailscale set --shields-up` is a mitigation, not a check, and it
+  also blocks inbound SSH over Tailscale, so it's **ask**, and only with
+  another way in available ([tailscale.md](tailscale.md)).
+- **sudo:** `printf '%s\n' "$PW" | ssh frame 'sudo -S -p "" …'`. It's the
+  password the user set on the Frame.
+
+## 1. Boot and crash history
+
+```sh
+ssh frame 'uptime; journalctl --list-boots --no-pager | tail -n 6'
+ssh frame 'journalctl -b -1 -k --no-pager -q | grep -aE "Unable to handle kernel|Internal error|Kernel panic" | tail -n 3'
+ssh frame 'coredumpctl list --no-pager --since -1d'
+```
+
+- **Kernel oops in the previous boot.** Report "oops observed". An oops alone
+  doesn't prove a reset, because Linux can keep running after one. Classify the
+  reset as unclean only if the oops is among the last lines of that boot and no
+  shutdown lines follow
+  (`journalctl -b -1 -q -n 30 | grep -aE "systemd-shutdown|Reached target.*(Reboot|Power)"`
+  is empty). On 2026-09-28 the oops was the last thing logged at 20:57:53. After
+  an unclean reset, check sections 3 and 4 closely.
+- **A boot ending with no shutdown lines and no errors.** On 2026-09-26 there
+  were five boots of 0–12 min like this (−12, −9, −8, −7, −5), with nothing
+  failing beforehand. They were probably hard power-offs during setup. Treat
+  them as unexplained, not as crashes.
+- **Crash signatures seen so far** (all `coredumpctl`, UID 1000):
+
+| When | What crashed | Cause | Section |
+|---|---|---|---|
+| 09-25 21:02–21:03 | vrcompositor SEGV, steamwebhelper SEGV, then Android composer, surfaceflinger and gamescope ABRT | Lepton crash cascade. Two `pasta` processes were both failing to listen on port 16385 just before | 7 |
+| 09-25 22:30–22:42 | `app_process64` ×3 | Android apps during APK testing | 7 |
+| 09-25 23:20 | `ffmpeg` | hardware H.264 encoder | 10 |
+| 09-26 13:56–22:45, 09-27 09:51 | `chromium-xr/chrome` ×16 | Chromium XR (panels, Mac view) | 8 |
+| 09-26 21:11–21:49 | XRService ABRT ×9, vrcompositor SEGV ×5, gamescope ABRT ×4 | leftover SteamVR processes from a failed start (29 Steam restarts, 31 SteamVR failures that boot) | 3 |
+| 09-28 16:27–17:49 | `app_process64` ×4 | Android runtime amid `binder_user_error` floods | 7 |
+| 09-28 17:01 | `kdeconnectd` | SMS plugin during device teardown | 9 |
+| 09-28 20:58–21:39 | vrcompositor SEGV ×10, XRService ×15, steamwebhelper ×2 | broken displays after a kernel oops | 3 |
+
+Per-boot counters a doctor should print:
+
+```sh
+ssh frame 'for b in 0 -1; do
+  k=$(journalctl -b $b -k -q) || { echo "boot $b: journal unreadable"; continue; }
+  u=$(journalctl -b $b --user -u steam.service -q) || { echo "boot $b: user journal unreadable"; continue; }
+  s=$(journalctl -b $b -q) || { echo "boot $b: journal unreadable"; continue; }
+  echo "boot $b dsi=$(grep -ac "wait for video done" <<<"$k") steam_restarts=$(grep -ac "Scheduled restart" <<<"$u") steamvr_fail=$(grep -ac "steamvr.service: Failed" <<<"$s")"
+done'
+```
+
+Report an unreadable journal as unknown, not as zero. What matters is
+whether the counts are **still rising**, so run it twice a minute apart. One
+or two SteamVR start failures around boot are normal
+([how-the-frame-works.md](how-the-frame-works.md), boot-loop row). Healthy
+boots on 2026-09-28 were 0 / 0 / 0. The 2026-09-26 21:22 boot reached
+0 / 29 / 31 (leftover processes), and the 2026-09-28 20:58 boot reached
+424 / 61 / 62 (broken displays), both rising every ~15 s.
+
+## 2. Wi-Fi
+
+| Check | Healthy | Broken |
+|---|---|---|
+| `nmcli -t d \| grep ^wlan0` | `wlan0:wifi:connected:…` | `wlan0:wifi:unavailable:` |
+| `journalctl -b -k \| grep -a ath12k` | none, or a few at boot | `failed to wakeup from wow: -110`, `Resuming from non M3 state (RESET)`, `WMI_PDEV_SET_PARAM_CMDID timeout`, `fail to start mac operations` |
+| `iw phy phy0 wowlan show` | `WoWLAN is disabled.` | `wake up on magic packet` |
+
+- **WoWLAN armed (safe).** Disarm it by UUID, because the user may have made
+  same-name duplicates. `default` means "use NetworkManager's global
+  `wifi.wake-on-wlan`". The Frame sets none (checked 2026-09-28), so it falls
+  back to `ignore`, which leaves the chip untouched and doesn't clear an armed
+  chip. `0` disarms it:
+  ```sh
+  set -e
+  U=$(nmcli -t -f UUID,DEVICE c show --active | awk -F: '$2=="wlan0"{print $1}')
+  [ -n "$U" ] || { echo "no active connection on wlan0"; exit 1; }
+  nmcli -g 802-11-wireless.wake-on-wlan c show "$U"   # record the old value
+  systemd-run --user --wait --pipe -q nmcli c modify "$U" 802-11-wireless.wake-on-wlan 0
+  systemd-run --user --wait --pipe -q nmcli device modify wlan0 802-11-wireless.wake-on-wlan 0
+  iw phy phy0 wowlan show | grep -q "WoWLAN is disabled" || { echo "still armed"; exit 1; }
+  ```
+  Use the **active** connection on wlan0, because there can be same-name
+  duplicates. `c modify` saves the setting. `device modify` changes only
+  WoWLAN on the live device, unlike `device reapply`, which would also apply
+  any other saved changes such as IP or DNS. Tested 2026-09-28: Wi-Fi stayed
+  connected. NetworkManager only allows the
+  modify under `systemd-run --user`. From SSH it's `auth`. Leave the profile
+  at `0`, since that stays safe even if a global `wifi.wake-on-wlan` is added
+  later. Setting the recorded old value back is **ask**. On 2026-09-28 the
+  profile was set back to `default` by hand. If the Wi-Fi is `unavailable`,
+  there's no active connection, so this has to wait for the reboot, and then
+  arming comes from the profile.
+- **`unavailable` after resume (user/ask).** Do a **clean** reboot: power
+  menu, or `sudo systemctl reboot` over USB-C. Never reload the module.
+- **Duplicate "ThisIsTheWifi" profiles.** Ones with `TIMESTAMP-REAL` `never`
+  are unused. Deleting them is **ask**.
+
+## 3. Displays, SteamVR, gamescope
+
+| Check | Healthy | Broken |
+|---|---|---|
+| `journalctl -b -k \| grep -ac "wait for video done"` | `0` | hundreds (`msm_dsi ae94000.dsi / ae96000.dsi`) |
+| `coredumpctl list vrcompositor --since -10min` | none | SEGV every ~15 s |
+| `grep -a "failed to wait for present" ~/.local/share/Steam/logs/vrcompositor.txt` | none recent | `WaitForPendingPresent: failed to wait for present` |
+| `journalctl -b --user -u steamvr.service \| grep -a "left-over process"` | none | `Found left-over process … (vrserver) … (vrcompositor) in control group` |
+| journal `gamescope` | quiet | `rendervulkan.cpp:2181 … Assertion '!modifiers.empty()'` about once a second |
+
+- **Broken displays (DSI timeouts).** The chain is: the GPU can't present,
+  vrcompositor SEGVs on its first frame, `steamvr.service` fails and stops the
+  gamescope VR session, and gamescope and Steam get SIGKILLed. The user sees
+  "There was an issue launching Steam". Fix (**ask/user**): a **clean**
+  reboot. An unclean reset after a kernel oops caused it, and the clean reboot
+  had 0 DSI errors (2026-09-28). Don't touch Steam while this is happening.
+- **Leftover SteamVR processes (2026-09-26 21:22 boot).** A first
+  `steamvr.service` start failed on `dependency`, its vrserver, XRService and
+  vrcompositor kept running, and each restart crashed against them. The same
+  fix as the next item applies, with the same guard.
+- **gamescope crash loop on `!modifiers.empty()`** (verified 2026-09-25,
+  [apks.md](apks.md)). gamescope keeps attaching to SteamVR processes orphaned
+  from a dead session. The broad fix is
+  `for p in vrdashboard vrcompositor vrserver; do pkill -TERM -x $p; done`,
+  and it recovers within about a minute. That kills **every** matching
+  process, including a working session, so it's always **ask**. A doctor may
+  signal automatically only **individually verified stale PIDs**, and only
+  when **all** of these hold:
+  - The loop is live: new vrcompositor/gamescope crashes in the last 2
+    minutes, and `NRestarts` rising between two reads.
+  - The process started before the current `steamvr.service` main process:
+    compare `ps -o pid,lstart,args -C vrserver,vrcompositor,vrdashboard`
+    with `systemctl --user show steamvr.service -p ExecMainStartTimestamp`.
+  - The journal ties it to the failed run:
+    `Found left-over process <pid> (…) in control group`.
+
+  Re-read `/proc/<pid>/stat` start time and `comm` just before signalling, and
+  signal by number, never by name. A process that's merely outside
+  `steamvr.service`'s cgroup could be a legitimate launch, so that's **ask**.
+- **Standby test settings left on.** Check that `vrcmd --get-settings`
+  (or `~/.config/openvr/config/steamvr.vrsettings`) shows
+  `power.pauseCompositorOnStandby` = 1 and `power.turnOffScreensTimeout` = 5.
+  If they differ, report a WARN and leave them alone (**ask**), since the user
+  may want them. If a doctor run changes them for a test, it must snapshot both
+  values first, including whether they were set in `steamvr.vrsettings` at all.
+  Afterwards it restores exactly those values, removing the keys if they were
+  absent, rather than the defaults 1 and 5.
+  The bool setter needs `1`/`0`, not `true`
+  ([how-the-frame-works.md](how-the-frame-works.md)).
+- **Dashboard open over an app** (`visible-blurred` just means it's open).
+  Run `SteamClient.OpenVR.VROverlay.HideDashboard()` over CDP on port 8080
+  only when the doctor itself is driving an app test. Otherwise it's **ask**,
+  because the user may have opened it.
+- **Steam launch stuck in standby** at `ShowInterstitials`/`CreatingProcess`
+  (`console_log.txt`). Run `SteamClient.Apps.ContinueGameAction(<action id>,
+  "<appid>", "<task>")` over CDP.
+
+## 4. Steam client and the SteamOS health checks
+
+| Check | Healthy | Broken |
+|---|---|---|
+| `systemctl --user show steam.service -p NRestarts` | `0` or stable | climbing every ~15 s |
+| `tail -n 40 ~/.local/share/Steam/logs/connection_log.txt \| grep -a "Logged On"` | `[Logged On, …] [U:1:<id>]` | only `[Logged Off, 0, 0] [U:1:0]` |
+| `grep -a BVerifyInstalledFiles ~/.local/share/Steam/logs/steam_output.log` | none | `<file> is N bytes, expected M`, `bad symlink …` |
+| last line of `steam_output.log` | client running | `Installing update...` or `Extracting package...` for minutes |
+| `pgrep -af child-update-ui` + `/proc/<pid>/wchan` | none | `drm_syncobj_array_wait_timeout` |
+| `cat /run/user/1000/steam{,vr}-short-session-tracker; ls -l` those files | empty | `frog…` / `frog:glasses:…` building up |
+
+Check section 3 first. If the displays are broken, Steam can't get past its
+first frame, whatever the files look like.
+
+**The two health checks** (read from `/usr/share/deckard/`, 2026-09-28):
+
+- `steam-health-check` (run by `steam.service`) appends `frog` to
+  `steam-short-session-tracker` for each run that fails in under 120 s or lasts
+  under 5 s. At 5 it runs `do_repair`. On BUILD_ID 20260925.6191901 the
+  script deletes `~/.steam` (keeping `registry.vdf`) and then either extracts
+  `/usr/lib/steam/steam.tar.zst` (705 MB) over `~/.local/share/Steam` (the
+  "unpacked" install this Frame has) or, on an overlay install, deletes the
+  upper-dir files that shadow `/usr/local/steam`. Then it touches
+  `.install-complete`. It also repairs at **every Steam start** if
+  `.install-complete` is missing, whatever the counter says.
+- `steamvr-health-check` (run by `steamvr.service`) appends `frog:glasses:`
+  for each failed or under-10-s SteamVR run. At 3 it runs `steam-health-check
+  --repair-now`. At 4 it also runs `steamos-bootconf set-mode reboot-other`,
+  which fails as non-root.
+- **What a repair erases isn't consistent across notes.** On 2026-09-26
+  (BUILD_ID 20260922.6101926) the boot-loop row in
+  [how-the-frame-works.md](how-the-frame-works.md) records that all of
+  `~/.local/share/Steam` was deleted, including games, login and Developer
+  Mode. On 2026-09-28 the scripts above only extract over it, a repair ran at
+  21:13 (`.install-complete` mtime), and the login survived. Treat any repair
+  as possibly destructive. Before a restart that could trigger one, check that
+  `.install-complete` exists.
+- **Stop them counting while you fix the cause (safe, resets at boot).** Do
+  this **first**, right after connecting, if `NRestarts` or either tracker is
+  rising, before any long checks:
+  ```sh
+  rc=0
+  for f in /run/user/1000/steam-short-session-tracker /run/user/1000/steamvr-short-session-tracker; do
+    { [ -e "$f" ] || : > "$f"; } && chmod u+w "$f" && : > "$f" && chmod 444 "$f" || rc=1
+    # verify: empty and not writable
+    [ -e "$f" ] && [ ! -s "$f" ] && [ ! -w "$f" ] && echo "frozen $f" || { echo "NOT frozen $f"; rc=1; }
+  done
+  exit $rc
+  ```
+  A doctor must stop and not restart Steam or SteamVR unless this exits 0.
+  It's idempotent, so run it on files that are already 444. Both were
+  already 444 on 2026-09-28, applied by an earlier session. This only stops
+  the **counting**. The start-time repair when `.install-complete` is missing
+  still runs. Re-apply after every reboot while the loop's cause is unfixed.
+
+Fixes:
+
+- **Verify files yourself (safe, read-only).** The record is
+  `~/.local/share/Steam/package/steam_client_<branch>_linuxarm64.installed`,
+  with lines of `path,size;mtime;crc32` (size `-1` is a directory). Compare
+  sizes and `zlib.crc32` (13,518 files on 2026-09-28). `steam_output.log` is
+  rewritten on every launch, so copy it before the next restart. `bad symlink`
+  reports taken mid-extraction are transient.
+- **Truncated files (ask).** Restart Steam (`systemctl --user restart
+  steam.service`), and it re-verifies and re-extracts from `package/`.
+  Preconditions:
+  - The displays are healthy.
+  - The trackers are frozen.
+  - `.install-complete` exists.
+  - The updater is idle: the `steam_output.log` tail hasn't changed for 60 s
+    and the steam process isn't writing (`/proc/<pid>/io` `write_bytes` is
+    steady).
+  - No game or app is running.
+
+  Re-verify afterwards.
+- **Updater deadlocked on the update UI.** Kill only the `-child-update-ui`
+  process, and the install continues (worked 2026-09-26). On 2026-09-28 it
+  was followed by a truncated `steamui.so`, so re-verify afterwards. If the
+  deadlock came from broken displays, fix those first.
+- **Stale pending install (ask, with backup).** `package/steam_client_<branch>_linuxarm64`
+  with no extension means an install is pending. Only act when all of these hold:
+  - `cmp` shows it's identical to `.manifest`.
+  - The verify is clean.
+  - The updater is idle (as above).
+
+  Then stop Steam, move it to `~/.cache/frame-control/…pending-backup`, and
+  start Steam. The log should
+  show `Nothing to do`, then `Verification complete`, then webhelpers.
+- **Heavy repair (ask).** `steam-health-check --repair-now`, or the boot
+  menu's `Repair Steam Installation` (section 12).
+- **Dead ends (don't repeat).**
+  - `STEAM_EXTRA_ARGS=-no-child-update-ui` still draws GLX in-process and
+    blocks.
+  - With `DISPLAY` unset, Steam exits ("XOpenDisplay failed"), with no text
+    fallback.
+  - Xvfb has no GLX visual here.
+- Steam's launch path is `steam.service` → `/usr/share/deckard/select_steam.sh
+  RUNSTEAM.sh`. Runtime drop-ins in `/run/user/1000/systemd/user/steam.service.d/`
+  are cleared at reboot. Remove any you add.
+- **`create-shortcut` refuses ids with hyphens** (`missing/invalid arguments`).
+  Ids must match `^[A-Za-z_][A-Za-z0-9_.]+$`. It reports "Steam client is not
+  running" when Steam is down, and re-running finishes the install without a
+  re-upload ([sideloading.md](sideloading.md)).
+
+## 5. Idle sleep and keep-awake
+
+- **Frame slept mid-task.** SSH doesn't count as activity, and Steam's idle
+  timer (`system_idle_suspend_ac_sec` 3600, `…_battery_sec` 900) suspends it.
+  The journal shows `Switching to power state: [ k_ESystemPowerState_Sleep ]`.
+  Fix (**safe**): `scripts/keep-awake.sh on` before long work and `off` after.
+  It uses one shared unit and one saved-settings file. So a doctor records
+  whether `fc-keep-awake` was already active, and runs `off` only if it was
+  the one that turned it on. Otherwise it releases another task's lock and
+  restores that task's saved timers.
+  It sets both timers to 0 and holds the `fc-keep-awake` user-unit inhibitor.
+  A plain SSH-session inhibitor is refused.
+- **Check:** `systemctl --user is-active fc-keep-awake`,
+  `systemd-inhibit --list | grep "Frame Control"`. WARN if it's held with no
+  agent working, since that drains the battery on battery power.
+- **Charging shows "Discharging" at ~0 W while full on a charger.** This is a
+  reporting quirk. Treat under 0.5 W on a charger as "not charging"
+  ([how-the-frame-works.md](how-the-frame-works.md)).
+
+## 6. Remote wake
+
+It doesn't work on this build. WoWLAN arms, but the WCN7850 is reset in both
+`deep` and `s2idle`, packets don't wake it, and Wi-Fi is dead after resume.
+Tested 2026-09-28. Details are in [how-the-frame-works.md](how-the-frame-works.md)
+and [open-questions.md](open-questions.md). Doctor checks: `cat
+/sys/power/mem_sleep` should read `s2idle [deep]` (resets at boot), and WoWLAN
+should be disabled.
+
+## 7. Lepton (Android)
+
+| Check | Broken sign |
+|---|---|
+| `podman ps --format '{{.Names}} {{.Ports}}'` | two containers with the same name or instance, or both bound to the same host port. Several instances with different ports are normal ([apks.md](apks.md)) |
+| journal `pasta` | `Listen failed for HOST TCP port 0.0.0.0/16385: Address already in use` repeating |
+| journal | `android.hardware.graphics.composer@2.1-service` or `surfaceflinger` aborts right after an app crash |
+| `dmesg` / journal | floods of `binder_user_error: N callbacks suppressed` near `app_process64` crashes |
+| journal | `Clearing baked app data due to non steamlaunch container` |
+
+- **Duplicate Lepton containers or port clash (2026-09-25 21:01).** Two
+  `pasta` instances fought over 16385, and a minute later the compositor,
+  webhelper, Android composer, surfaceflinger and gamescope crashed together.
+  Fix (**ask**): find the two instances that share the port (`podman ps`,
+  `ss -ltnp | grep 16385`) and stop only the duplicate. Leave other instances
+  running.
+- **Lepton's graphics HAL aborts after an app crash, taking the container down**
+  (3 times on 2026-09-25). It's intermittent, so retry ([apks.md](apks.md)).
+  Then check section 3 for a gamescope loop.
+- **All ADB-installed apps gone.** Lepton Development wipes its data whenever
+  it exits outside a Steam launch. Use `install-apk.sh` (a per-app Steam
+  launch, whose data survives), or the launch option `LEPTON_NO_CLEANUP=1
+  %command%` (inferred) ([apks.md](apks.md)).
+- **App dies on first file write with `ENOENT`.** Its `STEAM_COMPAT_DATA_PATH`
+  is outside `~/.local/share/Steam`. Use `steamapps/compatdata/<id>`.
+- **Lepton won't start outside Steam.** Set `IS_PARENT=true` and use `setsid
+  --wait`. "unbound variable" means `STEAM_COMPAT_SHADER_PATH` is unset
+  ([apks.md](apks.md)).
+- **App compatibility, not a fault** ([apks.md](apks.md)):
+  - Compose older than 1.11, SDL2/Kivy and Godot 4.3 crash on the missing
+    clipboard service.
+  - `INSTALL_FAILED_OLDER_SDK` means minSdk is over 30.
+  - `INSTALL_FAILED_NO_MATCHING_ABIS` means there's no arm64 build.
+  - `monkey` returning `-5` means you should launch the activity directly.
+    `--brief` prints a metadata line first, so take the last line:
+    `adb -s $S shell am start -W -n "$(adb -s $S shell cmd package resolve-activity --brief -c android.intent.category.LAUNCHER <pkg> | tail -n 1)"`.
+
+## 8. Chromium XR (panels, Mac view, WebXR)
+
+- **16 crashes on 2026-09-26/27.** The logs showed `Failed to create a
+  temporary file for memory-mapping: No such process (3)`, then `Received
+  signal 11 SEGV_MAPERR`. The cause isn't known yet. Check with
+  `coredumpctl list chrome --since -1d`.
+- **Zygote crash about 30 s after a Steam-launched start.** Steam's
+  `gameoverlayrenderer.so` is in `LD_PRELOAD`, and the launcher strips it
+  (verified 2026-09-27, [webxr-chromium.md](webxr-chromium.md)). Check that
+  the running chrome's `/proc/<pid>/environ` has no `gameoverlayrenderer`.
+- **XR process seccomp crash (syscall 209) or `VRInitError_Init_Internal`.**
+  The launcher runs with `--disable-seccomp-filter-sandbox`. Use that profile
+  only for VR sites ([webxr-chromium.md](webxr-chromium.md)).
+- **Mac view kept working when Steam was down** (2026-09-28). It's a separate
+  Chromium talking to the Mac over the LAN. It's a useful way in when Steam is
+  broken, but it's killed by any reboot and needs relaunching.
+
+## 9. KDE Connect
+
+- **`kdeconnectd` crashed on 2026-09-28 17:01** in `kdeconnect_sms.so` under
+  `Device::~Device` (device teardown). Check whether it's still running with
+  `pgrep -f frame-control/kdeconnect/root/usr/lib/kdeconnectd`. Fix
+  (**safe**): restart it the way this repo launches it. A doctor should
+  report a missing daemon rather than guess.
+
+## 10. Streaming and capture
+
+- **`ffmpeg` crash with `h264_v4l2m2m`** (hardware encoder, 2026-09-25/26).
+  Use `libx264 -preset ultrafast -tune zerolatency`
+  ([how-the-frame-works.md](how-the-frame-works.md)).
+- **`vrcmd --screenshot` writes nothing.** Use `ui/frame_vrshot.py`
+  (`IVRScreenshots`).
+- **No Mac cursor in the VNC mirror.** Load `scripts/mac-cursor-ring.lua` in
+  Hammerspoon on the Mac (`dofile(".../scripts/mac-cursor-ring.lua")` in
+  `~/.hammerspoon/init.lua`). It isn't a standalone script. Toggle it with
+  ctrl+alt+cmd+M.
+- **Remmina asks for the Mac login password.** macOS offers RFB type 30
+  first. Seed the password with `--update-profile … --set-option password`
+  ([streaming.md](streaming.md)).
+
+## 11. Panels
+
+- **Window stays on the default panel.** Run one `panel-on-frame.sh` at a
+  time. Tag windows by hand with `DISPLAY=:0 xprop -id <win> -f STEAM_GAME 32c
+  -set STEAM_GAME <id>` ([panels.md](panels.md)).
+- **Single-instance apps** (Remmina, KDE). Close them in Plasma first.
+- **Wayland-only apps** can't be floated this way.
+- **Dragging selects instead of scrolling.** That's by design for tagged
+  windows (laser mode).
+- **`Failed to get app info`** for a made-up id is benign.
+
+## 12. Boot loop, recovery, re-image
+
+Work down this list, least destructive first ([recovery-and-images.md](recovery-and-images.md)).
+The boot menu is inferred from Valve's docs and hasn't been tried on this Frame.
+
+1. **If the Frame is reachable, freeze the health-check trackers first and
+   verify them** (section 4), then diagnose. A reboot clears the freeze and
+   restarts the failing services, and 3 SteamVR failures trigger a repair.
+2. **Clean reboot** only when the diagnosed fault needs one (broken displays,
+   dead Wi-Fi). Straight after reconnecting, freeze and verify the trackers
+   again before anything else.
+3. **Boot menu (user):** shut down cleanly if the Frame responds. Hold Power
+   ~10 s until the LED is off only if it doesn't, and never while Steam is
+   extracting or repairing. Then power on holding **AUX** (top button). Choose `Previous` (the other A/B slot, keeps data),
+   then try `Repair Steam Installation`.
+4. **`Erase User Data`** wipes `~`: SSH keys, Tailscale, Flatpaks and setup
+   (**ask**).
+5. **Re-image** with `steamframe-oobe-repair-<build>` over USB or cable/EDL
+   (`qdl`). Copies are in `~/Downloads/steam-frame-recovery/` (**ask**).
+
+## What a doctor script should do
+
+1. Find a path (Tailscale, then LAN, then USB), and report which one worked.
+2. Print uptime, the last boots, and whether the previous boot ended in an
+   oops.
+3. Run the read-only checks in sections 2–11 and print one line each: OK,
+   WARN or BROKEN.
+4. **Order matters.** If a restart loop is live (`NRestarts` or a tracker
+   rising between two reads a few seconds apart), freeze the trackers
+   **before** any other check. Then fix displays before Steam. After any
+   reboot, check the trackers again, because they reset.
+5. Apply only **safe** fixes, printing each command. For reboots, deleting
+   profiles, heavy repairs and anything touching a user profile: print the
+   fix and ask.
+6. Never do anything under "Never do these".
+7. Re-run the checks after any fix and report the before and after.
+8. The fake-Frame harness (`fakeframe-ctl sleep|disk-full|sshd|devkit-service|keys`,
+   [testing.md](testing.md)) can exercise the unreachable, disk-full and
+   no-SSH branches without a headset.
+
+## Incident 2026-09-28
+
+| Time | What happened |
+|---|---|
+| 19:36 | WoWLAN armed, `deep` suspend, magic packets sent. No wake. Power-button resume: chip in MHI RESET, Wi-Fi dead. User restarted. |
+| 20:10 | WoWLAN disarmed. Clean boot, no DSI errors. |
+| 20:29 | `s2idle` via sudo, WoWLAN re-armed, suspend. No wake, same chip reset, Wi-Fi `unavailable`. |
+| 20:57:53 | Over USB-C: `modprobe -r ath12k`, and the **kernel oopsed** and the Frame reset itself. |
+| 20:58 | Boot with `steamclient.so` truncated (18.6 of 50.3 MB) and DSI timeouts from +28 s. Steam "couldn't connect", then "There was an issue launching Steam". Mac view still worked. |
+| 21:00–21:13 | Steam re-extracts and hangs on "Installing update..." (update UI stuck on the GPU). Killing the UI child let it continue, and `steamui.so` was later found truncated. The health-check repair ran at 21:13. |
+| 21:28 | Own CRC check: all 13,518 files OK. |
+| 21:30 | Moved aside the identical pending manifest. Steam reached login, then died every ~15 s: vrcompositor SEGV on DSI timeouts. |
+| 21:39 | User did a clean reboot. 0 DSI errors, Steam logged on 21:40:30, NRestarts 0. |

docs/how-the-frame-works.md

@@ -55,6 +55,8 @@ Lepton (Android 11, podman container "lepton-dev") ← its own panel, app 305600
 | **Tools on the image:** Python 3.12.3, `ffmpeg`, `openssl`, `curl`, `rsync`, `zip`/`unzip`, `flatpak`, `wpctl`, `podman`. **No `adb`.** `steamos` is uid 1000, in `wheel`, and sudoers has `%wheel ALL=(ALL) ALL`, so `sudo -S` takes the Developer Mode password on stdin. **Verified 2026-09-27.** | Running Frame Control's server on the Frame (`FRAME_LOCAL=1`, [iphone.md](iphone.md)) |
 | **Each Lepton instance is a podman container** named `lepton-steamlaunch-<instance id>`, labelled with its ADB port (`podman ps --format '{{.Names}} {{.Labels.adb_port}}'`). `podman exec <container> /system/bin/sh -c '…'` runs Android's shell inside it with no adb at all (used for `pidof` and `logcat` by the app tester). Running `wm size`/`wm density` that way is untested. **Verified 2026-09-27.** | `ui/frame_android.py`, the iPhone app's display settings |
 | **Asleep means off the network.** In standby the Frame stops answering on its LAN address, `frame.local` and Tailscale alike (`Host is down`, `No route to host`, timeouts), and ping fails. It was unreachable for about 2.5 hours until woken. Nothing over SSH can wake it. **Verified 2026-09-27.** | Frame Control's offline banner and retries |
+| **What puts it to sleep is Steam's idle timer**, not logind. The journal shows `steamui_system: Switching to power state: [ k_ESystemPowerState_Sleep ] reason: 'ComputeNextPowerState: active: 3600 < 3600 (k_EACState_Connected)'`, then Steam suspends. SSH work doesn't count as activity. The timers are the client settings `system_idle_suspend_ac_sec` (3600) and `system_idle_suspend_battery_sec` (900); 0 means Never (Settings → Power → Sleep after inactivity). They can be written over DevTools the way the settings page does. logind refuses a `systemd-inhibit --mode=block` sleep lock from an SSH session (`Interactive authentication required`) but accepts one started with `systemd-run --user`. `scripts/keep-awake.sh on|off|status` does both and restores the old timers on `off`. **Verified 2026-09-28**, BUILD_ID 20260925.6191901. Whether Steam's suspend honours the inhibitor on its own is **inferred** (polkit gives `steamos` no `suspend-ignore-inhibit`), not tested. | Keeping the Frame awake for agent work |
+| **Wake-on-WLAN doesn't work from `deep` or `s2idle`, and leaving it on breaks Wi-Fi after resume. Leave it off.** Sleep is `PM: suspend entry (deep)` (`/sys/power/mem_sleep` = `s2idle [deep]`). The Wi-Fi is a WCN7850 on `ath12k_pci` (PCIe, SM8650). Magic-packet WoWLAN can be armed without sudo: under `systemd-run --user --wait --pipe`, `nmcli c modify <connection> 802-11-wireless.wake-on-wlan magic` then `nmcli device reapply wlan0` makes `iw phy phy0 wowlan show` report `wake up on magic packet` (from SSH, `settings.modify.system` is only `auth`). **Tested 2026-09-28**, BUILD_ID 20260925.6191901, on the charger: after `PM: suspend entry (deep)` at 19:36:55, a unicast magic packet (UDP 9 and 7, to 192.168.1.237, with the Mac's ARP entry still present) and broadcast packets (192.168.1.255 and 255.255.255.255) got no wake in 30 s each. On a manual power-button wake 12 min later, the journal showed the chip had been reset during sleep: `mhi mhi0: Resuming from non M3 state (RESET)`, then `ath12k_pci: failed to wakeup from wow: -110`, WMI timeouts, `wiphy_resume returns -11`. Wi-Fi then disconnected and didn't come back, and the Frame needed a restart. So WoW did arm (no power-down fallback), but the WCN7850 loses power in `deep`. To turn it off, `wake-on-wlan default` alone doesn't clear the chip. `default` means NM's global `wifi.wake-on-wlan`, and the Frame sets none, so it falls back to `ignore`, which leaves the chip untouched. Set `0` and reapply (`WoWLAN is disabled.`), then set `default` again, or leave `0`. The Steam Deck with iwd fails differently: the NM setting never reached the driver there ([Switchboard](https://github.com/lfkdsk/Switchboard/blob/main/docs/steam-deck.md#wake-on-wlan)). `s2idle` failed the same way (tested 2026-09-28, set with `echo s2idle | sudo tee /sys/power/mem_sleep`, which lasts until reboot): `PM: suspend entry (s2idle)` at 20:29:57, no wake from unicast or broadcast packets, and on the power-button wake the same `Resuming from non M3 state (RESET)` and `failed to wakeup from wow`. Wi-Fi stayed `unavailable` until a restart. So the WCN7850 is reset during sleep either way. That points at ath12k WoW on this kernel/firmware rather than at the sleep depth. `systemctl suspend -i` under `systemd-run --user` asks for authentication, and plain `systemctl suspend` is refused while keep-awake's block inhibitor is held. | Waking the Frame remotely, [open-questions.md](open-questions.md) |
 | **Battery at full on a charger** can read `Discharging` at about 0 W (for example 99 %, 0.0 W, USB-C PD 18 W). Treat under 0.5 W on a charger as "not charging", not "draining". **Verified 2026-09-27.** | Frame Control's battery card |
 | **The OS image is downloadable.** Valve's recovery images for the Frame are at `https://steamdeck-images.steamos.cloud/recovery/`. The root filesystem inside is btrfs, and it runs as an SSH test target on ARM64 Linux without the headset (`tests/frame-container/frame-image.sh`). **Verified 2026-09-27.** | [recovery-and-images.md](recovery-and-images.md) |
 | **Boot / recovery menu.** Hold Power ~10 s until the LED goes off, then power on while holding the **AUX button on top of the Power button** (not the volume keys) until a text menu appears. Entries: `Current` (SteamOS-A/B + build), `Previous` (the other A/B slot), `Boot from USB`, `Repair Steam Installation`, `Erase User Data` (factory reset), `ADB mode`, `Battery Ship Mode`. It auto-boots `Current` after a ~15 s countdown. **Volume Up/Down (left side) move, AUX (right side) selects.** For a boot loop, Valve says pick `Previous` (keeps user data); then `Repair Steam Installation`; `Erase User Data` wipes `~` (SSH keys, Tailscale, Flatpaks, T3 setup). Last resort is a full re-image, two ways: (1) USB: write `steamframe-oobe-repair-<build>.img.bz2` to an 8 GB+ USB-C stick (Balena Etcher on the Mac), pick `Boot from USB`, then use "Wipe Device & Install SteamOS" / "Repair SteamOS" (keeps games and personal content) from the recovery desktop; (2) cable/EDL: `steamframe-oobe-repair-qdl-<build>.tar.gz`, run `flash.sh` (Linux) or `flash.cmd` (Windows), then with the Frame off for 10 s hold Power + Vol Up + Vol Down for 10 s and plug it in; it reflashes and reboots. Both images: `https://steamdeck-images.steamos.cloud/recovery/` (build 20260922.5153644, 0.3.0, 3.8 GiB each, no published checksums); local copies in `~/Downloads/steam-frame-recovery/`. File names, checksums and what's inside: [recovery-and-images.md](recovery-and-images.md). Source: Valve's [SteamOS Recovery FAQ](https://help.steampowered.com/en/faqs/view/1B71-EDF2-EB6D-2BB3) and [Installation and Repair FAQ](https://help.steampowered.com/en/faqs/view/65B4-2AA3-5F37-4227), plus a menu photo in [EloiStree/HelloSteamFrame#9](https://github.com/EloiStree/HelloSteamFrame/issues/9). **Inferred** (Valve docs, 2026-09-26); not yet tried on our Frame. | Recovering from a boot loop |

docs/open-questions.md

@@ -137,3 +137,31 @@ Still open: 4, 6, 7, 12–15, 16 (off-LAN and after a reboot), 17–21.
   reports, not tested with the Frame.
 - `connect.sh --harden`, `serve-bootstrap.sh` and
   `bootstrap-on-frame.sh` haven't run against real hardware.
+
+## Remote wake (2026-09-28)
+
+Goal: the Frame sleeps on the charger but Frame Control can wake it to reach
+it over SSH. Findings so far are in the Wake-on-WLAN row of
+[how-the-frame-works.md](how-the-frame-works.md). Independent review: GPT-6
+Astra (xhigh), 2026-09-28.
+
+- **Magic packet from `deep`: no (tested 2026-09-28).** Unicast and broadcast packets didn't wake it, the chip came back in MHI RESET, and Wi-Fi stayed broken until a restart. Details are in how-the-frame-works.md. Don't leave WoWLAN on with `deep`.
+- **`s2idle`: no (tested 2026-09-28).** Same chip reset and broken Wi-Fi as `deep`. SteamOS doesn't pick `deep` itself (no `sleep.conf.d`, no `mem_sleep_default`, and no sleep hook touching ath12k), so this was a clean one-setting test. Wake over Wi-Fi is out until a SteamOS/ath12k update. Re-test after updates.
+- **Recovering from the broken Wi-Fi: reboot cleanly, never `modprobe -r ath12k`.** On 2026-09-28, unloading the wedged driver oopsed the kernel (`Unable to handle kernel paging request`) and the Frame reset itself. The next boot had truncated Steam files (`steamclient.so`, then `steamui.so`), and the displays were broken for the whole boot (`msm_dsi … wait for video done timed out` from 28 s in, 240 times). `vrcompositor` segfaulted on its first present, `steamvr.service` took the gamescope session and Steam down every ~15 s, and the screen said "There was an issue launching Steam". Steam's updater also hung on the same GPU wait. The fixes: Steam re-verified its files, a leftover pending-install manifest identical to the `.manifest` was moved aside, and a clean reboot brought the displays back (0 DSI errors). The USB-C cable gives SSH at 10.86.200.233 when Wi-Fi is down. Checks and fixes are in [frame-doctor.md](frame-doctor.md).
+- **Charger / smart-plug wake (hypothesis):** during confirmed sleep, test
+  physically attaching the charger, detaching it, and switching off its AC
+  supply, each separately. If one works, a Home Assistant smart plug on the
+  charger can wake it while it keeps deep sleep.
+- **RTC dark wake:** a root `WakeSystem=yes` timer that checks for queued
+  work and suspends again. Needs a root unit.
+- **Controller wake:** does a paired controller's button wake it? `hci0` is a
+  UART radio with no paired devices listed, so the controllers may use a
+  separate link.
+- **AC-only Never:** `system_idle_suspend_ac_sec = 0`, with battery left at
+  15 min. This is Steam's own setting and needs no sudo, but the Frame stays
+  awake with its displays off rather than suspended. Measure wall power and
+  confirm the displays blank.
+- **Off the LAN:** a sleeping Frame's Tailscale can't receive anything, so
+  something awake on the LAN has to send the packet (for example the
+  EdgeRouter's `etherwake`, already used for lxso2, or the Mac).
+

scripts/keep-awake.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env zsh
+# Mac-side: stop the Steam Frame from going to sleep while an agent works on it.
+#
+# The Frame sleeps when Steam's own idle timer runs out ("Sleep after
+# inactivity": 60 min on AC, 15 min on battery by default). SSH activity
+# doesn't count as input, and asleep the Frame is off the network. `on` sets
+# both timers to Never through Steam's UI (DevTools on 127.0.0.1:8080, via
+# ui/frame_steam.py) and holds a logind sleep inhibitor as a user unit.
+# `off` drops the inhibitor and restores the timers `on` saved.
+#
+# Usage:
+#   scripts/keep-awake.sh on
+#   scripts/keep-awake.sh off
+#   scripts/keep-awake.sh status
+set -euo pipefail
+
+FRAME_ALIAS=${FRAME_ALIAS:-frame}
+HERE=${0:A:h}
+cmd=${1:-status}
+case $cmd in on|off|status) ;; *) echo "usage: keep-awake.sh on|off|status" >&2; exit 2 ;; esac
+
+ssh -o ConnectTimeout=8 "$FRAME_ALIAS" \
+  'mkdir -p ~/.cache/frame-control && cat > ~/.cache/frame-control/frame_steam.py' < "$HERE/../ui/frame_steam.py"
+
+# Runs on the Frame. Verified 2026-09-28 (BUILD_ID 20260925.6191901): the
+# timers are client settings system_idle_suspend_{ac,battery}_sec (0 = Never),
+# written the way Steam's settings page does (steamui module exporting the
+# SetSetting wrapper). logind refuses an inhibitor from an SSH session
+# ("Interactive authentication required") but allows one from a user unit.
+ssh "$FRAME_ALIAS" python3 - "$cmd" <<'EOF'
+import json, os, subprocess, sys
+sys.path.insert(0, os.path.expanduser("~/.cache/frame-control"))
+from frame_steam import Page
+
+cmd = sys.argv[1]
+saved_path = os.path.expanduser("~/.cache/frame-control/keep-awake.json")
+unit = "fc-keep-awake"
+keys = ("system_idle_suspend_ac_sec", "system_idle_suspend_battery_sec")
+
+if cmd == "off":  # release the lock first, even if Steam's UI is down
+    subprocess.run(["systemctl", "--user", "stop", unit], stderr=subprocess.DEVNULL)
+page = Page()
+def read():
+    return {k: page.eval(f"settingsStore.clientSettings.{k}") for k in keys}
+def write(values):
+    page.eval("""(async () => { let req;
+      webpackChunksteamui.push([[Symbol()], {}, r => { req = r }]);
+      const mod = Object.keys(req.m).map(id => req.m[id].toString().includes("Settings.SetSetting") ? req(id) : null).find(Boolean);
+      const set = Object.values(mod).find(f => typeof f == "function" && f.toString().includes("SetSetting("));
+      for (const [k, v] of Object.entries(%s)) await set(k, v);
+      await new Promise(r => setTimeout(r, 1000)); })()""" % json.dumps(values))
+def inhibitor():
+    return subprocess.run(["systemctl", "--user", "is-active", "-q", unit]).returncode == 0
+
+if cmd == "on":
+    current = read()
+    if not os.path.exists(saved_path):
+        with open(saved_path, "w") as f:
+            json.dump(current, f)
+    write({k: 0 for k in keys})
+    if not inhibitor():
+        subprocess.run(["systemd-run", "--user", "-q", f"--unit={unit}",
+                        "--description=Frame Control: keep the Frame awake",
+                        "systemd-inhibit", "--what=sleep:idle:handle-suspend-key:handle-power-key",
+                        "--who=Frame Control", "--why=Keep the Frame awake while an agent works on it",
+                        "--mode=block", "sleep", "infinity"], check=True)
+elif cmd == "off":
+    if os.path.exists(saved_path):  # no backup: leave the timers as they are
+        with open(saved_path) as f:
+            write(json.load(f))
+        os.remove(saved_path)
+
+print(json.dumps({"timers": read(), "inhibitor": inhibitor()}))
+EOF

tests/test_frame_apk.py

@@ -35,7 +35,7 @@ def manifest(package, label_ref, version_ref, min_sdk, package_raw=True, foreign
     foreign_label adds a non-android `label` attribute after android:label.
     """
     strings = ['label', 'icon', 'versionName', 'minSdkVersion', 'package', 'manifest', 'uses-sdk',
-               'application', package, 'junk', 'label', 'versionCode']  # the second 'label' has no android id
+               'application', package, 'junk', 'label']  # the second 'label' has no android id
     resmap = struct.pack('<4I', 0x01010001, 0x01010002, 0x0101021c, 0x0101020c)
     resmap = struct.pack('<HHI', 0x0180, 8, 8 + len(resmap)) + resmap
 
@@ -48,8 +48,7 @@ def manifest(package, label_ref, version_ref, min_sdk, package_raw=True, foreign
     none = 0xffffffff
     chunks = (pool(strings) + resmap
               + element(5, [(4, 8 if package_raw else none, frame_apk.T_STRING, 8),
-                            (2, none, frame_apk.T_REF, version_ref),
+                            (2, none, frame_apk.T_REF, version_ref)])
-                            (11, none, frame_apk.T_INT_DEC, 210)])
               + element(6, [(3, none, frame_apk.T_INT_DEC, min_sdk)])
               + element(7, [(0, none, frame_apk.T_REF, label_ref), (1, none, frame_apk.T_REF, 0x7f020000)]
                         + ([(10, 9, frame_apk.T_STRING, 9)] if foreign_label else [])))
@@ -109,7 +108,6 @@ class ApkInfo(unittest.TestCase):
         self.assertEqual(info['package'], 'com.example.demo')
         self.assertEqual(info['label'], 'App label')  # the default, not French
         self.assertEqual(info['version'], '2.1')
-        self.assertEqual(info['version_code'], 210)
         self.assertEqual(info['min_sdk'], 26)
         self.assertEqual(info['abis'], ['arm64-v8a', 'x86_64'])
         self.assertEqual(info['icon_png'], b'hi')  # largest-density PNG, skipping the XML icon

tests/test_frame_apk_versions.py

@@ -1,260 +0,0 @@
-"""Offline version lookup with small index-v2 fixtures."""
-import io
-import json
-import os
-import sys
-import tempfile
-import time
-import unittest
-from concurrent.futures import ThreadPoolExecutor
-from unittest.mock import patch
-
-sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'ui'))
-import frame_apk_versions as versions
-import frame_catalog
-import frame_android
-
-
-def build(code, sdk=30, abis=None):
-    return {'manifest': {'versionName': str(code), 'versionCode': code,
-                         'usesSdk': {'minSdkVersion': sdk}, 'nativecode': abis or []},
-            'file': {'name': f'/example_{code}.apk', 'sha256': str(code).zfill(64)}}
-
-
-class VersionsTest(unittest.TestCase):
-    def setUp(self):
-        self.tmp = tempfile.TemporaryDirectory()
-        self.addCleanup(self.tmp.cleanup)
-        data = os.path.join(self.tmp.name, 'data')
-        os.mkdir(data)
-        for name, builds in [('index-v2.json', [build(5, 33), build(4, abis=['x86_64']),
-                                               build(3, abis=['arm64-v8a', 'x86_64']), build(2)]),
-                             ('index-v2.archive.json', [build(1, 21), build(2)]),
-                             ('index-v2.izzy.json', [])]:
-            with open(os.path.join(data, name), 'w') as f:
-                json.dump({'packages': {'org.example.app': {'versions': {str(i): b for i, b in enumerate(builds)}}}}, f)
-        self.enter_patch(patch.object(frame_catalog, 'CATALOG', self.tmp.name))
-        self.enter_patch(patch.dict(os.environ, {'FRAME_CONTROL_APP': ''}))
-        self.network = self.enter_patch(patch.object(frame_catalog.urllib.request, 'urlopen', side_effect=AssertionError('network used')))
-
-    def enter_patch(self, p):
-        result = p.start()
-        self.addCleanup(p.stop)
-        return result
-
-    def test_filter_order_archive_and_dedup(self):
-        result = versions.alternatives('org.example.app')
-        self.assertEqual([v['version_code'] for v in result['versions']], [3, 2, 1])
-        self.assertEqual(result['versions'][-1]['source'], 'F-Droid archive')
-        self.assertEqual(result['versions'][-1]['url'], 'https://f-droid.org/archive/example_1.apk')
-        self.assertEqual(result['errors'], [])
-        self.network.assert_not_called()
-
-    def test_current_version(self):
-        result = versions.alternatives('org.example.app', 3)
-        self.assertEqual([v['version_code'] for v in result['versions']], [2, 1])
-
-    def test_fallback(self):
-        result = versions.alternatives('com.missing.app')
-        self.assertEqual(result['versions'], [])
-        self.assertEqual([v['source'] for v in result['links']], ['APKMirror', 'APKPure', 'Uptodown', 'F-Droid', 'GitHub'])
-        self.assertTrue(all('com.missing.app' in v['url'] for v in result['links']))
-        self.assertIn('Android 11', result['note'])
-        self.assertIn('arm64-v8a', result['note'])
-
-    def test_failed_indexes_keep_search_links(self):
-        with patch.object(frame_catalog, 'load_index', side_effect=OSError('offline')):
-            result = versions.alternatives('org.example.app')
-        self.assertEqual(len(result['errors']), 3)
-        self.assertEqual(len(result['links']), 5)
-
-    def test_no_compatible_versions(self):
-        with patch.object(frame_catalog, 'load_index', return_value={}):
-            result = versions.alternatives('org.example.app')
-        self.assertEqual(result['versions'], [])
-        self.assertEqual(len(result['links']), 5)
-
-    def test_reduction_memory_cache_and_refresh(self):
-        repo = versions.REPOS[0][1]
-        index = frame_catalog.load_index(repo)
-        self.assertEqual([v['version_code'] for v in index['org.example.app']], [3, 2])
-        self.assertEqual(set(index['org.example.app'][0]),
-                         {'version', 'version_code', 'min_sdk', 'abis', 'name', 'sha256'})
-        raw = os.path.join(self.tmp.name, 'data', 'index-v2.json')
-        self.assertTrue(os.path.exists(raw))  # the catalogue build reads it
-        os.utime(raw, ns=(1, 1))
-        with patch.object(frame_catalog.json, 'load', side_effect=AssertionError('reparsed')):
-            self.assertIs(frame_catalog.load_index(repo), index)
-        path = raw + '.installable-v1'
-        with open(path, 'w') as f:
-            json.dump({}, f)
-        os.utime(path, ns=(1, 1))
-        self.assertEqual(frame_catalog.load_index(repo, cached_only=True), {})
-        payload = json.dumps({'packages': {'org.example.app': {'versions': {'x': build(9)}}}}).encode()
-        with patch.object(frame_catalog.urllib.request, 'urlopen', return_value=io.BytesIO(payload)) as fetch:
-            self.assertEqual(frame_catalog.load_index(repo)['org.example.app'][0]['version_code'], 9)
-            fetch.assert_called_once()
-        self.assertTrue(os.path.exists(raw))
-
-    def test_malformed_entries_are_skipped(self):
-        raw = os.path.join(self.tmp.name, 'odd.json')
-        with open(raw, 'w') as f:
-            json.dump({'packages': {'a.b': {'versions': {'x': {'manifest': {}}, 'y': None, 'z': build(4)}},
-                                    'c.d': {'versions': None}, 'e.f': []}}, f)
-        self.assertEqual([v['version_code'] for v in frame_catalog._reduce_index(raw)['a.b']], [4])
-
-    def test_one_failing_repo_keeps_the_others(self):
-        real = frame_catalog.load_index
-        def load(repo, cached_only=False):
-            if 'izzy' in repo:
-                raise KeyError('file')
-            return real(repo, cached_only=cached_only)
-        with patch.object(frame_catalog, 'load_index', side_effect=load):
-            result = versions.alternatives('org.example.app')
-        self.assertEqual([v['version_code'] for v in result['versions']], [3, 2, 1])
-        self.assertEqual(len(result['errors']), 1)
-
-    def test_newer_raw_index_outdates_reduced_copy(self):
-        repo = versions.REPOS[0][1]
-        frame_catalog.load_index(repo)
-        raw = os.path.join(self.tmp.name, 'data', 'index-v2.json')
-        with open(raw, 'w') as f:
-            json.dump({'packages': {'org.example.app': {'versions': {'x': build(8)}}}}, f)
-        os.utime(raw, ns=(time.time_ns() + 10**9,) * 2)
-        self.assertEqual(frame_catalog.load_index(repo)['org.example.app'][0]['version_code'], 8)
-
-    def test_concurrent_requests_share_download(self):
-        raw = os.path.join(self.tmp.name, 'data', 'index-v2.json')
-        os.remove(raw)
-        payload = json.dumps({'packages': {'org.example.app': {'versions': {'x': build(7)}}}}).encode()
-        with patch.object(frame_catalog.urllib.request, 'urlopen', side_effect=lambda *a, **k: io.BytesIO(payload)) as fetch:
-            with ThreadPoolExecutor(max_workers=4) as pool:
-                indexes = list(pool.map(frame_catalog.load_index, [versions.REPOS[0][1]] * 4))
-            fetch.assert_called_once()
-        self.assertTrue(all(index is indexes[0] for index in indexes))
-
-    def test_failed_refresh_preserves_cache(self):
-        repo = versions.REPOS[0][1]
-        index = frame_catalog.load_index(repo)
-        path = os.path.join(self.tmp.name, 'data', 'index-v2.json.installable-v1')
-        os.utime(path, ns=(1, 1))
-        os.utime(os.path.join(self.tmp.name, 'data', 'index-v2.json'), ns=(1, 1))
-        with patch.object(frame_catalog.urllib.request, 'urlopen', return_value=io.BytesIO(b'{')):
-            with self.assertRaises(ValueError):
-                frame_catalog.load_index(repo)
-        self.assertEqual(frame_catalog.load_index(repo, cached_only=True), index)
-        self.assertFalse(any(name.endswith('.part') for name in os.listdir(os.path.dirname(path))))
-
-    def test_stream_boundaries_and_invalid_index(self):
-        raw = os.path.join(self.tmp.name, 'stream.json')
-        with open(raw, 'w') as f:
-            json.dump({'repo': {'description': 'é' * 70000}, 'packages': {
-                'org.example.app': {'metadata': {'text': 'escaped " packages { }' * 6000},
-                                    'versions': {'x': build(7)}}}, 'tail': {}}, f)
-        self.assertEqual(frame_catalog._reduce_index(raw)['org.example.app'][0]['version_code'], 7)
-        for invalid in ('{}', '{"packages": []}', '{"packages": {', '{"packages": {}} trailing'):
-            with open(raw, 'w') as f:
-                f.write(invalid)
-            with self.assertRaises(ValueError):
-                frame_catalog._reduce_index(raw)
-
-    def test_cap_and_preferred_build(self):
-        records = [dict(version=str(i), version_code=i, min_sdk=21, abis=[],
-                        name='/app_%s.apk' % i, sha256=str(i)) for i in range(20)]
-        records += [dict(records[-1], version_code=21, abis=['arm64-v8a'], name='/arm.apk'),
-                    dict(records[-1], version_code=22, abis=['arm64-v8a', 'x86_64'], name='/all.apk')]
-        with patch.object(frame_catalog, 'load_index', return_value={'org.example.app': records}):
-            result = versions.alternatives('org.example.app')
-        self.assertEqual(result['total'], 22)
-        self.assertEqual(len(result['versions']), 8)
-        self.assertEqual(len({v['version'] for v in result['versions']}), 8)
-        self.assertEqual([v['version_code'] for v in result['versions']], [21, 18, 17, 16, 15, 14, 13, 12])
-
-    def test_android_names_and_verdict(self):
-        for sdk, name in [(23, 'Android 6.0'), (30, 'Android 11'), (32, 'Android 12L'), (33, 'Android 13'), (99, 'Android API 99')]:
-            self.assertEqual(versions.android_name(sdk), name)
-        info = {'package': 'org.example.app', 'label': 'Example', 'version': '5.0',
-                'version_code': 50, 'min_sdk': 33, 'abis': ['arm64-v8a']}
-        description = versions.describe(info)
-        for text in ['org.example.app', '5.0', 'code 50', 'Android 13', 'arm64-v8a', 'cannot install']:
-            self.assertIn(text, description)
-        info.update(min_sdk=30, abis=[])
-        self.assertIn('can install', versions.describe(info))
-        info['abis'] = ['armeabi-v7a']
-        self.assertIn('no arm64-v8a build', versions.describe(info))
-
-    def test_install_resolves_index_hash(self):
-        versions.alternatives('org.example.app')
-        with patch.object(versions, 'alternatives', side_effect=AssertionError('recomputed')), \
-                patch.object(frame_catalog, 'fetch_apk', return_value='/tmp/example.apk') as fetch, \
-                patch.object(frame_android, 'apk_info', return_value={'package': 'org.example.app', 'version_code': 1}), \
-                patch.object(frame_android, 'install', return_value={'label': 'Example'}) as install:
-            versions.install('org.example.app', 'https://f-droid.org/archive/example_1.apk')
-            self.assertEqual(fetch.call_args[0][0]['h'], str(1).zfill(64))
-            install.assert_called_once_with('/tmp/example.apk', source='F-Droid archive')
-        with self.assertRaises(frame_android.FrameError):
-            versions.install('org.example.app', 'https://evil.example/app.apk')
-
-    def test_install_checks_identity_without_network_refresh(self):
-        versions.alternatives('org.example.app')
-        for name in ('index-v2.json', 'index-v2.archive.json'):
-            os.utime(os.path.join(self.tmp.name, 'data', name + '.installable-v1'), ns=(1, 1))
-        for info in ({'package': 'wrong.package', 'version_code': 1},
-                     {'package': 'org.example.app', 'version_code': 99}):
-            with patch.object(frame_catalog, 'fetch_apk', return_value='/tmp/example.apk'), \
-                    patch.object(frame_android, 'apk_info', return_value=info), \
-                    patch.object(frame_android, 'install') as install:
-                with self.assertRaises(frame_android.FrameError):
-                    versions.install('org.example.app', 'https://f-droid.org/archive/example_1.apk')
-                install.assert_not_called()
-        self.network.assert_not_called()
-
-
-class UploadVersionsTest(unittest.TestCase):
-    def test_endpoint_validation(self):
-        import server
-        for query in ('', 'package=', 'package=foo', 'package=a..b', 'package=a.1b',
-                      'package=a.b/path', 'package=a.b&package=c.d', 'package=a.b&code=-1',
-                      'package=a.b&code=x', 'package=a.b&code=', 'package=a.b&code=1&code=2'):
-            handler = object.__new__(server.Handler)
-            handler.path = '/api/apk-versions?' + query
-            with patch.object(handler, 'local_request', return_value=True), \
-                    patch.object(handler, 'send_json') as reply, \
-                    patch.object(versions, 'alternatives') as lookup:
-                handler.do_GET()
-                self.assertEqual(reply.call_args[0][1], 400, query)
-                lookup.assert_not_called()
-        handler.path = '/api/apk-versions?package=org.example_app.demo&code=123'
-        with patch.object(handler, 'local_request', return_value=True), \
-                patch.object(handler, 'send_json') as reply, \
-                patch.object(versions, 'alternatives', return_value={'total': 0}) as lookup:
-            handler.do_GET()
-            lookup.assert_called_once_with('org.example_app.demo', 123)
-            reply.assert_called_once_with({'total': 0})
-
-    def test_blocked_uploads_do_not_lookup_before_reply(self):
-        import server
-        info = {'package': 'org.example.app', 'label': 'Example', 'version': '5',
-                'version_code': 5, 'min_sdk': 33, 'abis': [], 'icon_png': None}
-        for mode in ('apkinfo', 'apk'):
-            handler = object.__new__(server.Handler)
-            handler.headers = {'X-Filename': 'app.apk', 'X-Mode': mode, 'Content-Length': '1'}
-            handler.rfile = io.BytesIO(b'x')
-            with patch.object(frame_android, 'apk_info', return_value=dict(info)), \
-                    patch.object(versions, 'alternatives', side_effect=AssertionError('lookup during upload')) as lookup, \
-                    patch.object(server, 'ensure_master') as ssh:
-                if mode == 'apkinfo':
-                    reply = handler.upload()
-                    self.assertNotIn('alternatives', reply['apk'])
-                    self.assertIn('API 33', reply['apk']['blocker'])
-                else:
-                    with self.assertRaises(server.Failure) as error:
-                        handler.upload()
-                    self.assertEqual(error.exception.status, 400)
-                    self.assertEqual(error.exception.apk['package'], info['package'])
-                lookup.assert_not_called()
-                ssh.assert_not_called()
-
-
-if __name__ == '__main__':
-    unittest.main()

tests/test_server.py

@@ -212,23 +212,6 @@ class ServerGuards(unittest.TestCase):
         self.assertNotEqual(status, 200, body)
         self.assertNotIn("job", body)
 
-    def test_android_install_of_another_version_runs_as_a_job(self):
-        pkg = "org.example.frame_control.not_in_any_repo"
-        sys.path.insert(0, str(ROOT / "ui"))
-        import frame_apk_versions
-        # The job must fail on the cached lookup, before any download: nothing is cached for this package.
-        self.assertEqual(frame_apk_versions._versions(pkg, cached_only=True)[0], [])
-        status, started = self.post("/api/android", {"action": "install", "package": pkg,
-                                                     "url": f"https://f-droid.org/repo/{pkg}_1.apk"})
-        self.assertEqual(status, 200, started)
-        for _ in range(200):
-            job = json.loads(self.request("GET", f"/api/job?id={started['job']}", headers={"X-Frame-UI": "1"})[2])
-            if job["done"]:
-                break
-            time.sleep(0.05)
-        self.assertTrue(job["done"])
-        self.assertIn("no longer available", job["error"])
-
     def test_unknown_routes(self):
         self.assertEqual(self.request("GET", "/nope")[0], 404)
         self.assertEqual(self.post("/api/nope", {})[0], 404)

ui/frame_android.py

@@ -6,7 +6,7 @@ apps, the lepton-show-flatscreen marker; plus a non-Steam shortcut, so it shows
 in the Steam library and gets its own SteamVR panel. Nothing goes through
 Lepton Development, which wipes its apps on exit. See docs/apks.md.
 
-Python stdlib only. CLI: python3 ui/frame_android.py {info APK|versions APK-or-PKG|install APK|list|launch PKG|stop PKG|remove PKG|probe PKG}
+Python stdlib only. CLI: python3 ui/frame_android.py {install APK|list|launch PKG|stop PKG|remove PKG|probe PKG}
 """
 import json, os, re, shlex, shutil, subprocess, sys, threading, time, zlib
 
@@ -276,15 +276,7 @@ def probe(pkg, wait=20):
 def main():
     cmd, *args = sys.argv[1:] or ['help']
     try:
-        if cmd in ('info', 'versions'):
+        if cmd == 'install':
-            import frame_apk_versions
-            if cmd == 'info':
-                print(frame_apk_versions.describe(apk_info(args[0])))
-                return
-            info = apk_info(args[0]) if os.path.isfile(args[0]) or args[0].lower().endswith('.apk') else None
-            r = frame_apk_versions.alternatives(
-                info['package'] if info else args[0], info.get('version_code') if info else None)
-        elif cmd == 'install':
             r = install(args[0], flatscreen='--vr' not in args)
         elif cmd == 'list':
             r = list_apps()

ui/frame_apk.py

@@ -229,7 +229,6 @@ def apk_info(path):
         min_sdk = sdk.get('minSdkVersion')
         info = {
             'package': package,
-            'version_code': manifest.get('versionCode', (None, None))[1],
             'version': _text(manifest.get('versionName'), res) or '',
             'label': _text(app.get('label'), res) or package,
             'abis': sorted({n.split('/')[1] for n in names if n.startswith('lib/') and n.count('/') >= 2}),

ui/frame_apk_versions.py

@@ -1,90 +0,0 @@
-"""Explain APK requirements and find installable versions in F-Droid's indexes."""
-from urllib.parse import quote, urlencode
-
-import frame_android
-import frame_catalog
-
-ANDROID = dict(enumerate([
-    '1.0', '1.1', '1.5', '1.6', '2.0', '2.0.1', '2.1', '2.2', '2.3', '2.3.3',
-    '3.0', '3.1', '3.2', '4.0', '4.0.3', '4.1', '4.2', '4.3', '4.4', '4.4W',
-    '5.0', '5.1', '6.0', '7.0', '7.1', '8.0', '8.1', '9', '10', '11', '12',
-    '12L', '13', '14', '15', '16',
-], 1))
-REPOS = (('F-Droid', 'https://f-droid.org/repo/'),
-         ('F-Droid archive', 'https://f-droid.org/archive/'),
-         ('IzzyOnDroid', 'https://apt.izzysoft.de/fdroid/repo/'))
-NOTE = ('Pick a version whose minimum is Android 11 or lower and that has an '
-        'arm64-v8a build (or no native code). Installable does not mean every feature works.')
-
-
-def android_name(sdk):
-    return 'Android ' + ANDROID[sdk] if sdk in ANDROID else f'Android API {sdk}'
-
-
-def describe(info):
-    sdk = info.get('min_sdk')
-    minimum = f'{android_name(sdk)} (API {sdk})' if sdk else 'not specified'
-    try:
-        frame_android.check_installable(info)
-        verdict = 'Lepton can install this APK. Features may still need services Lepton lacks.'
-    except frame_android.FrameError as e:
-        verdict = f'Lepton cannot install this APK: {e}'
-    return (f"{info['package']} · {info.get('version') or '?'} "
-            f"(code {info.get('version_code') if info.get('version_code') is not None else '?'})\n"
-            f"Minimum: {minimum}\nABIs: {', '.join(info['abis']) or 'no native code'}\n{verdict}")
-
-
-def search_links(package):
-    q = quote(package, safe='')
-    return [{'source': name, 'url': url} for name, url in (
-        ('APKMirror', 'https://www.apkmirror.com/?' + urlencode({'post_type': 'app_release', 's': package})),
-        ('APKPure', 'https://apkpure.com/search?q=' + q),
-        ('Uptodown', 'https://en.uptodown.com/android/search/' + q),
-        ('F-Droid', 'https://search.f-droid.org/?q=' + q),
-        ('GitHub', 'https://github.com/search?type=repositories&q=' + q),
-    )]
-
-
-def _versions(package, cached_only=False):
-    versions, errors, seen = [], [], set()
-    for source, repo in REPOS:
-        try:
-            index = frame_catalog.load_index(repo, cached_only=cached_only)
-        except Exception as e:  # one bad repo (dropped download, odd index) mustn't hide the others
-            errors.append(f'Could not check {source}: {e}')
-            continue
-        for v in index.get(package, []):
-            url = repo + v['name'].lstrip('/')
-            key = (v['version_code'], v.get('sha256') or url)
-            if key in seen:
-                continue
-            seen.add(key)
-            versions.append(dict(v, url=url, source=source))
-    return versions, errors
-
-
-def alternatives(package, current_version_code=None):
-    """At most eight releases, preferring arm64-only builds over universal builds."""
-    versions, errors = _versions(package)
-    versions = [v for v in versions if v['version_code'] != current_version_code]
-    total = len(versions)
-    versions.sort(key=lambda v: (v['abis'] == ['arm64-v8a'], v['version_code']), reverse=True)
-    releases = {}
-    for v in versions:
-        releases.setdefault(v['version'], v)
-    versions = sorted(releases.values(), key=lambda v: v['version_code'], reverse=True)[:8]
-    return {'package': package, 'versions': versions, 'total': total,
-            'links': search_links(package), 'note': NOTE, 'errors': errors}
-
-
-def install(package, url):
-    # Resolve the selection again: the client cannot supply a trusted hash or arbitrary URL.
-    records, _ = _versions(package, cached_only=True)
-    version = next((v for v in records if v['url'] == url), None)
-    if not version:
-        raise frame_android.FrameError('That version is no longer available; check the APK again')
-    apk = frame_catalog.fetch_apk({'a': version['url'], 'h': version['sha256'], 'n': package})
-    info = frame_android.apk_info(apk)
-    if info['package'] != package or info.get('version_code') != version['version_code']:
-        raise frame_android.FrameError('The downloaded APK does not match the selected version')
-    return frame_android.install(apk, source=version['source'])

ui/frame_catalog.py

@@ -2,7 +2,7 @@
 list, verified downloads, installs into per-app Lepton instances, and
 compatibility reports. Python stdlib only.
 """
-import hashlib, json, os, shutil, sys, tempfile, threading, time, urllib.error, urllib.request
+import hashlib, os, shutil, sys, tempfile, threading, time, urllib.error, urllib.request
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 CATALOG = os.path.join(ROOT, 'apk-catalog')
@@ -17,149 +17,12 @@ import frame_compat_db as compat_db  # noqa: E402
 # the per-user cache (FRAME_CONTROL_APP is set by app/main.js).
 CACHE = (str(frame_host.cache_dir('apk')) if os.environ.get('FRAME_CONTROL_APP') or '.app/Contents/Resources' in CATALOG
          else os.path.join(CATALOG, 'data', 'cache'))
-# Repo base URL -> local name of its index; every APK download must come from one of these.
+APK_HOSTS = ('https://f-droid.org/repo/', 'https://f-droid.org/archive/')
-INDEX_FILES = {'https://f-droid.org/repo/': 'index-v2.json',
-               'https://f-droid.org/archive/': 'index-v2.archive.json',
-               'https://apt.izzysoft.de/fdroid/repo/': 'index-v2.izzy.json'}
-APK_HOSTS = tuple(INDEX_FILES)
 _lock = threading.Lock()
 _cache = {'mtime': None, 'sig': None, 'apps': None, 'by_pkg': None}
 _env = {}
 
 
-_index_lock = threading.Lock()
-_indexes = {}
-
-
-class _IndexReader:
-    """Decode one object member at a time; never retain the whole raw index."""
-    def __init__(self, stream):
-        self.stream, self.buffer = stream, ''
-        self.decoder = json.JSONDecoder()
-
-    def fill(self):
-        chunk = self.stream.read(1 << 16)
-        if not chunk:
-            raise ValueError('incomplete F-Droid index')
-        self.buffer += chunk
-
-    def peek(self):
-        self.buffer = self.buffer.lstrip()
-        while not self.buffer:
-            self.fill()
-            self.buffer = self.buffer.lstrip()
-        return self.buffer[0]
-
-    def expect(self, char):
-        if self.peek() != char:
-            raise ValueError('invalid F-Droid index')
-        self.buffer = self.buffer[1:]
-
-    def value(self):
-        self.peek()
-        while True:
-            try:
-                value, end = self.decoder.raw_decode(self.buffer)
-                self.buffer = self.buffer[end:]
-                return value
-            except json.JSONDecodeError:
-                self.fill()
-
-    def members(self):
-        self.expect('{')
-        if self.peek() != '}':
-            while True:
-                key = self.value()
-                if not isinstance(key, str):
-                    raise ValueError('invalid F-Droid index key')
-                self.expect(':')
-                yield key
-                if self.peek() == '}':
-                    break
-                self.expect(',')
-        self.expect('}')
-
-
-def _reduce_index(path):
-    from pick import installable
-    packages = {}
-    found = False
-    with open(path, encoding='utf-8') as f:
-        reader = _IndexReader(f)
-        for key in reader.members():
-            if key != 'packages':
-                reader.value()
-                continue
-            found = True
-            for package in reader.members():
-                records, entry = [], reader.value()
-                versions = entry.get('versions') if isinstance(entry, dict) else None
-                for v in (versions.values() if isinstance(versions, dict) else ()):
-                    # Skip malformed entries rather than losing the whole repo.
-                    if not (isinstance(v, dict) and isinstance(v.get('manifest'), dict)
-                            and isinstance(v.get('file'), dict) and v['file'].get('name')):
-                        continue
-                    if not installable(v):
-                        continue
-                    m, file = v['manifest'], v['file']
-                    records.append({'version': m.get('versionName', ''),
-                                    'version_code': m.get('versionCode', 0),
-                                    'min_sdk': m.get('usesSdk', {}).get('minSdkVersion', 1),
-                                    'abis': m.get('nativecode') or [],
-                                    'name': file['name'], 'sha256': file.get('sha256')})
-                if records:
-                    packages[package] = records
-        if reader.buffer.strip() or f.read().strip():
-            raise ValueError('trailing data in F-Droid index')
-    if not found:
-        raise ValueError('invalid F-Droid index')
-    return packages
-
-
-def load_index(repo, cached_only=False):
-    """Compact installable records by package, cached on disk and by mtime in memory."""
-    if repo not in APK_HOSTS:
-        raise ValueError('unexpected index URL')
-    directory = CACHE if os.environ.get('FRAME_CONTROL_APP') or '.app/Contents/Resources' in CATALOG else os.path.join(CATALOG, 'data')
-    filename = INDEX_FILES[repo]
-    raw = os.path.join(directory, filename)
-    path = raw + '.installable-v1'
-    with _index_lock:
-        mtime = os.stat(path).st_mtime_ns if os.path.exists(path) else None
-        # A newer raw index (the catalogue script refreshed it) outdates the reduced copy.
-        newer_raw = mtime is not None and os.path.exists(raw) and os.stat(raw).st_mtime_ns > mtime
-        if mtime is not None and (cached_only or (time.time() - mtime / 1e9 < 86400 and not newer_raw)):
-            cached = _indexes.get(path)
-            if cached is None or cached[0] != mtime:
-                with open(path) as f:
-                    cached = (mtime, json.load(f))
-                _indexes[path] = cached
-            return cached[1]
-        if cached_only:
-            return {}
-        os.makedirs(directory, exist_ok=True)
-        fd, tmp = tempfile.mkstemp(prefix=filename, suffix='.part', dir=directory)
-        os.close(fd)
-        try:
-            if os.path.exists(raw) and time.time() - os.path.getmtime(raw) < 86400:
-                index = _reduce_index(raw)
-                refreshed = os.stat(raw).st_mtime_ns
-            else:
-                with open(tmp, 'wb') as f, urllib.request.urlopen(repo + 'index-v2.json', timeout=30) as r:
-                    shutil.copyfileobj(r, f, 1 << 20)
-                index = _reduce_index(tmp)
-                refreshed = time.time_ns()
-            with open(tmp, 'w') as f:
-                json.dump(index, f, separators=(',', ':'))
-            os.utime(tmp, ns=(refreshed, refreshed))
-            os.replace(tmp, path)
-            _indexes[path] = (os.stat(path).st_mtime_ns, index)
-            return index
-        finally:
-            if os.path.exists(tmp):
-                os.remove(tmp)
-
-
 def catalog():
     """Rated apps with the database's reports applied."""
     path = os.path.join(CATALOG, 'site', 'apps.js')

ui/index.html

@@ -254,10 +254,10 @@
   .and-grid { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 2fr); gap: 22px; align-items: start; }
   .and-col { display: grid; gap: 22px; align-content: start; }
   .rep-item .s { white-space: normal; }
-  #repDlg, #titleDlg, #wiDlg, #pwDlg, #apkAltDlg { background: #1e2329; color: var(--text); border: 1px solid rgba(255,255,255,.1); border-radius: 4px;
+  #repDlg, #titleDlg, #wiDlg, #pwDlg { background: #1e2329; color: var(--text); border: 1px solid rgba(255,255,255,.1); border-radius: 4px;
             padding: 22px; width: min(560px, 92vw); box-shadow: 0 20px 60px rgba(0,0,0,.6); }
-  #repDlg::backdrop, #titleDlg::backdrop, #wiDlg::backdrop, #pwDlg::backdrop, #apkAltDlg::backdrop { background: rgba(0,0,0,.55); }
+  #repDlg::backdrop, #titleDlg::backdrop, #wiDlg::backdrop, #pwDlg::backdrop { background: rgba(0,0,0,.55); }
-  #repDlg h2, #titleDlg h2, #wiDlg h2, #pwDlg h2, #apkAltDlg h2 { margin: 0 0 14px; font-size: 15px; letter-spacing: 1.5px; text-transform: uppercase; color: var(--bright); }
+  #repDlg h2, #titleDlg h2, #wiDlg h2, #pwDlg h2 { margin: 0 0 14px; font-size: 15px; letter-spacing: 1.5px; text-transform: uppercase; color: var(--bright); }
   #repForm label, #titleForm label { display: block; font-size: 12.5px; color: var(--muted); margin-top: 10px; }
   #repForm label input[type=text], #repForm textarea, #titleForm label input, #titleForm label select { margin-top: 5px; }
   #titleForm select { width: 100%; background: rgba(0,0,0,.28); color: var(--text); border: 1px solid transparent;
@@ -656,16 +656,6 @@
   <span class="last" id="lastLog">Ready</span>
   <span class="sub" id="drawerHint">Show ▴</span>
 </div>
-<dialog id="apkAltDlg" aria-labelledby="apkAltTitle">
-  <h2 id="apkAltTitle">Try another APK version</h2>
-  <p id="apkAltReason"></p>
-  <div class="list" id="apkAltVersions"></div>
-  <p class="sub" id="apkAltNote"></p>
-  <div id="apkAltLinks"></div>
-  <p class="sub" id="apkAltErrors"></p>
-  <div class="actions"><button id="apkAltClose">Close</button></div>
-</dialog>
-
 <dialog id="repDlg" aria-labelledby="repTitle">
   <form method="dialog" id="repForm">
     <h2 id="repTitle">Report an APK</h2>
@@ -1420,56 +1410,12 @@ function upload(file, mode) {
     xhr.onload = () => {
       $("prog").style.display = "none";
       let data; try { data = JSON.parse(xhr.responseText); } catch { data = { error: `HTTP ${xhr.status}` }; }
-      if (data.apk?.blocker && xhr.status >= 300) checkApkAlternatives(data.apk);
       xhr.status < 300 ? resolve(data) : reject(new Error(data.error));
     };
     xhr.onerror = () => { $("prog").style.display = "none"; reject(new Error("network error")); };
     xhr.send(file);
   });
 }
-let apkLookup = 0;
-async function checkApkAlternatives(apk) {
-  const lookup = ++apkLookup;
-  $("apkAltReason").textContent = apk.blocker;
-  $("apkAltVersions").textContent = "Checking F-Droid for older versions…";
-  $("apkAltVersions").onclick = null;
-  for (const id of ["apkAltNote", "apkAltErrors", "apkAltLinks"]) $(id).textContent = "";
-  if (!$("apkAltDlg").open) $("apkAltDlg").showModal();
-  const query = new URLSearchParams({package: apk.package});
-  if (apk.version_code != null) query.set("code", apk.version_code);
-  try {
-    const result = await api(`/api/apk-versions?${query}`);
-    if (lookup === apkLookup && $("apkAltDlg").open) showApkAlternatives(apk.blocker, result);
-  } catch (e) {
-    if (lookup === apkLookup) $("apkAltVersions").textContent = e.message;
-  }
-}
-function showApkAlternatives(reason, result) {
-  $("apkAltReason").textContent = reason;
-  $("apkAltNote").textContent = `${result.versions.length} of ${result.total} compatible versions. ${result.note}`;
-  $("apkAltErrors").textContent = result.errors.join(" · ");
-  $("apkAltLinks").innerHTML = result.links.map(l => `<a href="${esc(l.url)}" target="_blank" rel="noopener noreferrer">${esc(l.source)}</a>`).join(" · ");
-  $("apkAltVersions").innerHTML = result.versions.length ? result.versions.map((v, i) =>
-    `<div class="item"><div class="grow"><div class="t">${esc(v.version || "?")} <span class="sub">code ${esc(v.version_code)}</span></div>
-    <div class="s">${esc(v.source)} · minimum API ${esc(v.min_sdk)} · ${esc(v.abis.join(", ") || "no native code")}</div></div>
-    <button class="small" data-version="${i}" ${v.sha256 ? "" : "disabled"}>Install</button></div>`).join("") :
-    `<p>No compatible version found in F-Droid. Try the searches below.</p>`;
-  $("apkAltVersions").onclick = async e => {
-    const b = e.target.closest("[data-version]"); if (!b) return;
-    const v = result.versions[+b.dataset.version];
-    if (installing.has(result.package)) return;
-    b.disabled = true; b.textContent = "Installing…";
-    const res = await runJob(`Install ${result.package} ${v.version}`, result.package, () => api("/api/android", {
-      action: "install", package: result.package, url: v.url
-    }));
-    if (res) $("apkAltDlg").close(); else { b.disabled = false; b.textContent = "Install"; }
-    await loadAndroid();
-    if (cat.apps) { const y = window.scrollY; filterCatalog(); window.scrollTo(0, y); }
-  };
-  if (!$("apkAltDlg").open) $("apkAltDlg").showModal();
-}
-$("apkAltClose").onclick = () => $("apkAltDlg").close();
-
 const TITLE_EXT = /\.(zip|exe)$/i;
 async function sendFiles(files, dirs = new Set()) {
   for (const [i, f] of files.entries()) {
@@ -2050,7 +1996,6 @@ $("repFile").onchange = async () => {
     const { apk } = await upload(file, "apkinfo");
     $("repPkg").value = apk.package; $("repVer").value = apk.version; $("repLabel").value = apk.label;
     if (!$("repSrc").value) $("repSrc").value = file.name;
-    if (apk.blocker) checkApkAlternatives(apk);
     $("repFileNote").textContent = apk.blocker ? `Note: ${apk.blocker}` : `${apk.package} ${apk.version}`;
   } catch (e) { $("repFileNote").textContent = e.message; }
   $("repFile").value = "";

ui/server.py

@@ -37,7 +37,6 @@ from urllib.parse import parse_qs, unquote, urlparse
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 import frame_android  # noqa: E402
-import frame_apk_versions  # noqa: E402
 import frame_catalog  # noqa: E402
 import frame_host  # noqa: E402
 import frame_store  # noqa: E402
@@ -92,10 +91,9 @@ exit 1
 
 
 class Failure(Exception):
-    def __init__(self, message, status=502, apk=None):
+    def __init__(self, message, status=502):
         super().__init__(message)
         self.status = status
-        self.apk = apk
 
 
 # What ssh prints when it never reached the Frame, and what to tell the user
@@ -563,28 +561,16 @@ def open_thing(body):
     raise Failure("unknown target", 400)
 
 
-def apk_versions(query):
-    args = parse_qs(query, keep_blank_values=True)
-    packages, codes = args.get('package', []), args.get('code', [])
-    if len(packages) != 1 or not frame_android.PKG_RE.match(packages[0]):
-        raise Failure('invalid Android package id', 400)
-    if codes and (len(codes) != 1 or not re.fullmatch(r'[0-9]{1,19}', codes[0])):
-        raise Failure('invalid version code', 400)
-    return frame_apk_versions.alternatives(packages[0], int(codes[0]) if codes else None)
-
-
 def android(body):
     """Android apps, each in its own persistent Lepton instance (frame_android.py)."""
     action, pkg = body.get("action"), str(body.get("package", ""))
     ensure_master()
     try:
         if action == "install":
-            url = body.get("url")
+            frame_catalog.app(pkg)  # an unknown package fails now, not in the background
-            if not url:
-                frame_catalog.app(pkg)  # an unknown package fails now, not in the background
 
             def work():
-                m = frame_apk_versions.install(pkg, url) if url else frame_catalog.install(pkg)
+                m = frame_catalog.install(pkg)
                 return {"message": f"Installed {m['label']}. It's in the Steam library; launching it opens its own panel.",
                         "app": m}
             return start_job(f"Install {pkg}", work)
@@ -1317,10 +1303,8 @@ class Handler(BaseHTTPRequestHandler):
     def send_json(self, obj, status=200):
         self.send_bytes(json.dumps(obj).encode(), "application/json", status)
 
-    def send_error_json(self, message, status, apk=None):
+    def send_error_json(self, message, status):
         body, offline_status = error_body(message)
-        if apk is not None:
-            body["apk"] = apk
         self.send_json(body, offline_status or status)
 
     def do_GET(self):
@@ -1335,8 +1319,6 @@ class Handler(BaseHTTPRequestHandler):
                 self.send_json({"os": "SteamOS", "fileManager": None, "computer": DEVICE, "mobile": True} if LOCAL else
                                {"os": frame_host.NAME, "fileManager": frame_host.FILE_MANAGER,
                                 "computer": "Mac" if frame_host.MAC else "PC"})
-            elif path == "/api/apk-versions":
-                self.send_json(apk_versions(url.query))
             elif path == "/api/android":
                 ensure_master()
                 self.send_json({"apps": frame_android.list_apps()})
@@ -1376,7 +1358,7 @@ class Handler(BaseHTTPRequestHandler):
             else:
                 self.send_json({"error": "not found"}, 404)
         except Failure as e:
-            self.send_error_json(str(e), e.status, e.apk)
+            self.send_error_json(str(e), e.status)
         except frame_android.FrameError as e:
             self.send_error_json(str(e), 502)
         except Exception as e:
@@ -1402,7 +1384,7 @@ class Handler(BaseHTTPRequestHandler):
                 raise Failure("request body must be a JSON object", 400)
             self.send_json(handler(body))
         except Failure as e:
-            self.send_error_json(str(e), e.status, e.apk)
+            self.send_error_json(str(e), e.status)
         except (ValueError, TypeError) as e:
             self.send_json({"error": f"bad request: {e}"}, 400)
         except frame_android.FrameError as e:
@@ -1507,14 +1489,6 @@ class Handler(BaseHTTPRequestHandler):
                 keep = True  # stage_title owns tmp now, and removes it on failure
                 return stage_title(str(dest), temp_dir=str(tmp))
             if mode == "apk":
-                try:
-                    info = frame_android.apk_info(str(dest))
-                except frame_android.FrameError as e:
-                    raise Failure(str(e), 400)
-                try:
-                    frame_android.check_installable(info)
-                except frame_android.FrameError as e:
-                    raise Failure(str(e), 400, {"package": info["package"], "version_code": info.get("version_code"), "blocker": str(e)})
                 ensure_master()
                 try:
                     m = frame_android.install(str(dest), source=name)