Merge remote-tracking branch 'origin/main' into fix/apk-install-instant-failures

Review pr75-review-r2: _webinstall_run catches non-FrameError APK install
failures without a diagnostic, and apk_installed now leaves those to the
caller, so they went unreported. Report them there; test the full worker.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

.github/workflows/release.yml

@@ -14,7 +14,31 @@ permissions:
   contents: write
 
 jobs:
+  # One job makes the draft, before the builds: three matrix jobs each running
+  # "view || create" could race and make duplicate drafts. The draft is tied to
+  # the pushed tag (--verify-tag, then tag_name set explicitly), so
+  # scripts/publish-release.sh and `gh release upload` find it by tag.
+  draft:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create the draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          id=$(gh api --paginate "repos/$GH_REPO/releases?per_page=100" --jq ".[] | select(.tag_name == \"$tag\") | .id" | head -n 1)
+          if [ -z "$id" ]; then
+            gh release create "$tag" --draft --verify-tag --title "Frame Control ${tag#v}" --notes ""
+            id=$(gh api --paginate "repos/$GH_REPO/releases?per_page=100" --jq ".[] | select(.draft and .name == \"Frame Control ${tag#v}\") | .id" | head -n 1)
+          fi
+          gh api -X PATCH "repos/$GH_REPO/releases/$id" -f tag_name="$tag" --jq '"release " + (.id|tostring) + " tag_name " + .tag_name'
+
   build:
+    needs: draft
+    # Still runs for pull requests and manual runs, where the draft job is skipped.
+    if: ${{ !failure() && !cancelled() }}
     strategy:
       fail-fast: false
       matrix:
@@ -40,15 +64,27 @@ jobs:
         run: npm ci && npm run ${{ matrix.script }}
         env:
           CSC_IDENTITY_AUTO_DISCOVERY: "false"
+      # The installer, not just the unpacked build: its 7-Zip payload once dropped
+      # the OpenXR layer's arm64 library without any error. Install it silently
+      # and compare every installed file with the unpacked build.
+      - name: Check the Windows installer installs every file
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          $setup = Get-ChildItem app/dist/Frame-Control-Setup-*.exe | Select-Object -First 1
+          $p = Start-Process -FilePath $setup.FullName -ArgumentList '/S' -Wait -PassThru
+          if ($p.ExitCode -ne 0) { throw "installer exited $($p.ExitCode)" }
+          $installed = Join-Path $env:LOCALAPPDATA 'Programs\Frame Control'
+          for ($i = 0; $i -lt 60 -and -not (Test-Path (Join-Path $installed 'Uninstall Frame Control.exe')); $i++) { Start-Sleep 2 }
+          node app/build/check-resources.js (Join-Path $installed 'resources') app/dist/win-unpacked/resources
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
       - name: Upload to the release
         if: startsWith(github.ref, 'refs/tags/')
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          tag="${GITHUB_REF_NAME}"
-          gh release view "$tag" >/dev/null 2>&1 || gh release create "$tag" --draft --title "Frame Control ${tag#v}" --notes ""
-          gh release upload "$tag" ${{ matrix.files }} --clobber
+          gh release upload "${GITHUB_REF_NAME}" ${{ matrix.files }} --clobber
       - uses: actions/upload-artifact@v4
         with:
           name: frame-control-${{ matrix.os }}

apk-catalog/reports.py

@@ -6,11 +6,25 @@ A report: package, version, result (runs | crashes | install_failed |
 instance_failed, from an automated test), rating (works | issues | broken, from
 a person), notes, via (harness | probe | user), date, steamos, lepton, runtime.
 Newest wins, and a person's rating beats an automated result.
+
+An install_failed report saying the file had no arm64-v8a build (or needed a
+newer Android) is about that one APK file, often the wrong per-ABI download of
+an app that has an arm64 build, so it says nothing about the app and is left out.
 """
+import re
+
+FILE_FAULT = re.compile(r'no arm64-v8a build|needs Android API')
+
+
+def about_app(r):
+    """False for reports about one wrong APK file rather than the app itself."""
+    return not (r.get('result') == 'install_failed' and not r.get('rating')
+                and FILE_FAULT.search(r.get('notes') or ''))
 
 
 def verdict(reports):
     """(verdict, summary lines) for one package's reports, or None."""
+    reports = [r for r in reports or () if about_app(r)]
     if not reports:
         return None
     rs = sorted(reports, key=lambda r: r.get('date') or '')

app/build/check-resources.js

@@ -0,0 +1,79 @@
+// Checks that the app's resources hold what Frame Control can't work without.
+// The OpenXR compatibility layer is why this exists: VR APK installs need its
+// arm64-v8a library (ui/frame_android.py XR_COMPAT_FILES).
+//
+// As electron-builder's afterPack hook it checks the unpacked app. From the
+// command line it checks an installed copy, which is what caught the Windows
+// installer silently dropping the library (see .github/workflows/release.yml):
+//   node build/check-resources.js INSTALLED_RESOURCES [REFERENCE_RESOURCES]
+// With a reference (the unpacked build's resources), every file in it must also
+// be in the installed copy, at the same size.
+const fs = require("fs");
+const path = require("path");
+
+const REQUIRED = [
+  "ui/server.py",
+  "ui/frame_android.py",
+  "frame/android/lepton-app.sh",
+  "frame/openxr-compat/XrApiLayer_FRAME_compat.json",
+  "frame/openxr-compat/prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so.gz",
+];
+
+function resourcesDir(context) {
+  if (context.electronPlatformName === "darwin" || context.electronPlatformName === "mas") {
+    const app = `${context.packager.appInfo.productFilename}.app`;
+    return path.join(context.appOutDir, app, "Contents", "Resources");
+  }
+  return path.join(context.appOutDir, "resources");
+}
+
+function size(file) {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return -1;
+  }
+}
+
+// Required files that are missing or empty.
+function missing(dir) {
+  return REQUIRED.filter((rel) => size(path.join(dir, rel)) <= 0);
+}
+
+// Files under reference that aren't in dir at the same size.
+function differences(dir, reference) {
+  const out = [];
+  (function walk(rel) {
+    for (const e of fs.readdirSync(path.join(reference, rel), { withFileTypes: true })) {
+      const r = path.join(rel, e.name);
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile() && size(path.join(dir, r)) !== size(path.join(reference, r))) out.push(r.split(path.sep).join("/"));
+    }
+  })("");
+  return out;
+}
+
+exports.default = async function afterPack(context) {
+  const dir = resourcesDir(context);
+  const gone = missing(dir);
+  if (gone.length) {
+    throw new Error(`packaged app is missing required resources in ${dir}: ${gone.join(", ")}`);
+  }
+};
+exports.missing = missing;
+exports.differences = differences;
+exports.REQUIRED = REQUIRED;
+
+if (require.main === module) {
+  const [dir, reference] = process.argv.slice(2);
+  if (!dir) {
+    console.error("usage: node build/check-resources.js INSTALLED_RESOURCES [REFERENCE_RESOURCES]");
+    process.exit(2);
+  }
+  const problems = [...missing(dir), ...(reference ? differences(dir, reference) : [])];
+  if (problems.length) {
+    console.error(`${dir} is missing or has the wrong size for:\n  ${[...new Set(problems)].join("\n  ")}`);
+    process.exit(1);
+  }
+  console.log(`${dir}: all required resources present${reference ? ", and every file of " + reference : ""}`);
+}

app/package.json

@@ -29,6 +29,7 @@
         ]
       }
     ],
+    "afterPack": "build/check-resources.js",
     "directories": {
       "output": "dist",
       "buildResources": "build"
@@ -81,7 +82,7 @@
         "to": "frame/openxr-compat",
         "filter": [
           "XrApiLayer_FRAME_compat.json",
-          "prebuilt/**/*.so"
+          "prebuilt/**/*.so.gz"
         ]
       },
       {

app/test/updater.test.js

@@ -51,6 +51,27 @@ test("update.json assets always download from this repository's release", () =>
   assert.throws(() => require("../updater").fromManifest({ version: "nope", assets: [] }));
 });
 
+test("the release page is this repository's tag page, never a draft's untagged-... link", () => {
+  const { fromManifest, fromApi } = require("../updater");
+  const tagPage = "https://github.com/saphid/frame-control/releases/tag/v0.4.0";
+  const page = (p) => fromManifest({ version: "0.4.0", assets: [], page: p }).page;
+  assert.strictEqual(page(tagPage), tagPage);
+  // 0.4.0's real update.json: the draft's address, a 404 once published.
+  assert.strictEqual(page("https://github.com/saphid/frame-control/releases/tag/untagged-c6ddfed7f75d67db2e99"), tagPage);
+  assert.strictEqual(page(undefined), tagPage);
+  assert.strictEqual(page("https://evil.example/releases/tag/v0.4.0"), tagPage);
+  assert.strictEqual(page("https://github.com/saphid/frame-control/releases/tag/v0.4.0?x=1"), tagPage);
+  // Paths that normalize to another repository.
+  assert.strictEqual(page("https://github.com/saphid/frame-control/releases/tag/..\\..\\..\\..\\other-owner\\other-repo"),
+                     tagPage);
+  assert.strictEqual(page("https://github.com/saphid/frame-control/releases/tag/%2e%2e/%2e%2e/%2e%2e/%2e%2e/other-owner/other-repo"),
+                     tagPage);
+  assert.strictEqual(page("https://github.com/saphid/frame-control/releases/tag/v0.3.9"), tagPage);  // only its own tag
+  assert.strictEqual(fromApi({ tag_name: "../../x", assets: [] }).page, "https://github.com/saphid/frame-control/releases");
+  assert.strictEqual(fromApi({ tag_name: "v0.4.0", assets: [],
+                               html_url: "https://github.com/saphid/frame-control/releases/tag/untagged-x" }).page, tagPage);
+});
+
 test("prepare refuses a release that isn't newer (no downgrades)", async () => {
   const { prepare } = require("../updater");
   const release = { version: "0.3.1", assets: [] };

app/updater.js

@@ -106,12 +106,24 @@ async function getJson(url, headers) {
   return JSON.parse(body);
 }
 
+// The release page the banner links to. update.json for 0.4.0 carried the draft's
+// address (releases/tag/untagged-...), which is dead once the release is published,
+// and a page from the manifest could also be steered elsewhere (e.g. tag/..\..\other/repo
+// normalizes to another repository) before shell.openExternal. So the given page is
+// ignored: the link is always this repository's tag page, built from a valid version.
+function releasePage(version) {
+  const v = parseVersion(version);
+  if (!v) return RELEASES;
+  return `${RELEASES}/tag/v${v.nums.join(".")}${v.pre ? "-" + v.pre : ""}`;
+}
+
 // update.json and the API's release both become { version, notes, page, assets }.
 function fromManifest(m) {
   if (!parseVersion(m.version) || !Array.isArray(m.assets)) throw new Error("update.json is malformed");
-  const base = `https://github.com/${REPO}/releases/download/v${String(m.version).replace(/^v/i, "")}/`;
-  return { version: String(m.version).replace(/^v/i, ""), notes: String(m.notes || "").slice(0, 4000),
-           page: m.page || RELEASES,
+  const version = String(m.version).replace(/^v/i, "");
+  const base = `https://github.com/${REPO}/releases/download/v${version}/`;
+  return { version, notes: String(m.notes || "").slice(0, 4000),
+           page: releasePage(version),
            // Assets always come from this repository's release, whatever the manifest says.
            assets: m.assets.map((a) => ({ name: String(a.name), url: base + encodeURIComponent(String(a.name)),
                                           size: a.size, digest: a.digest || null })) };
@@ -119,8 +131,9 @@ function fromManifest(m) {
 
 function fromApi(r) {
   if (r.draft || r.prerelease) throw new Error("GitHub returned an unpublished release");
-  return { version: String(r.tag_name || "").replace(/^v/i, ""), notes: String(r.body || "").slice(0, 4000),
-           page: r.html_url || RELEASES,
+  const version = String(r.tag_name || "").replace(/^v/i, "");
+  return { version, notes: String(r.body || "").slice(0, 4000),
+           page: releasePage(version),
            assets: (r.assets || []).map((a) => ({ name: a.name, url: a.browser_download_url, size: a.size,
                                                  digest: a.digest || null })) };
 }

docs/privacy.md

@@ -43,13 +43,20 @@ computer, exactly as they were sent.
 | `app_opened` | At most once a day | |
 | `frame_connected` | The first time a SteamOS build is seen | `steamos_build`, `steamos_version` |
 | `tab_viewed` | The first click on each tab in a session | `tab` |
-| `install_finished` | Any install finishes, working or not | `kind` (apk, flatpak, steam, title, web), `ok`, `seconds`, `error_category`, `installer_code`, and see below |
+| `install_finished` | Any install finishes, working or not | `kind` (apk, flatpak, steam, title, web), `ok`, `seconds`, `error_category` (only when `ok` is false), `installer_code`, `xr_layer_missing`, and see below |
 | `update_offered`, `update_started`, `update_failed` | The update banner | `to_version`, `error_category` |
 
 `install_finished` never includes a file name, path or error message. An
-error becomes one category from a fixed list (for example `apk_wrong_abi` or
-`frame_unreachable`), plus Android's own `INSTALL_FAILED_…` code when there
-is one. It names what was installed only when that's already public:
+error becomes one category from this fixed list, plus Android's own
+`INSTALL_FAILED_…` code (`installer_code`) when there is one:
+`android_installer`, `apk_needs_newer_android`, `apk_wrong_abi`,
+`layer_missing`, `apk_repack_failed`, `tool_missing`, `apk_unreadable`,
+`cant_run_on_frame`, `steam_shortcut`, `frame_not_set_up`, `frame_auth`,
+`frame_unreachable`, `frame_disk_full`, `download_failed`, `flatpak`,
+`cancelled`, `lepton` or `other`. A VR APK that installed without Frame
+Control's OpenXR compatibility layer, because this copy of the app is missing
+it, carries `xr_layer_missing: true`; otherwise that field is left out. It
+names what was installed only when that's already public:
 
 - F-Droid catalogue apps: `package`. Never the version, since a local build can reuse a
   catalogue app's package name

docs/releasing.md

@@ -24,13 +24,20 @@ count. So a build reaches people only when you publish it, after testing it.
 4. Publish:
 
    ```sh
+   scripts/publish-release.sh --dry-run v0.4.0   # checks and shows update.json, changes nothing
    scripts/publish-release.sh v0.4.0
    ```
 
-   The script checks that all eight installers are attached, each with the
-   SHA-256 digest GitHub records. It attaches `update.json` (the version, the
-   notes and each installer's digest), then publishes the release and marks it
-   latest. From then on, running copies see the update. They check about 8
+   The script checks that the tag is on GitHub and that all eight installers
+   are attached, each with the SHA-256 digest GitHub records. It attaches
+   `update.json` (the version, the notes, the release page and each
+   installer's digest), then publishes the release and marks it latest. It
+   uses only the REST API: `gh release view` can't find a draft whose
+   `tag_name` still reads `untagged-…`, and GraphQL is often rate-limited.
+   Such a draft is found by its exact title (`Frame Control 0.4.0`, or that
+   followed by `: subtitle`) and tied to the tag when it's published. The release page in `update.json` is always
+   `releases/tag/<tag>`, because a draft's own address (`releases/tag/untagged-…`)
+   stops working once it's published. From then on, running copies see the update. They check about 8
    seconds after starting, then every 6 hours, and anyone can use **Check for
    Updates…** (the app menu on macOS, the Help menu elsewhere).
 

docs/vr-apks.md

@@ -249,6 +249,10 @@ the app wants 1.1 and enables the extensions that became 1.1 core; maps
 and keeps the current refresh rate when SteamVR refuses a requested one.
 `meta.json` records `"patched": ["openxr-compat"]`. Skip it with
 `install … --no-xr-compat`. Its decisions go to logcat under `FrameXrCompat`.
+If this copy of Frame Control is missing the layer's library (an incomplete
+install, or a file removed after installing), VR apps install without it and
+the install message says so; OpenXR 1.0 apps still run. Release builds fail
+to package without it (`app/build/check-resources.js`).
 
 Verified on the headset (2026-09-28):
 

frame/openxr-compat/README.md

@@ -190,8 +190,11 @@ ctest --test-dir frame/openxr-compat/build-host --output-on-failure
 
 The script produces arm64-v8a / android-24, C++17, `-O2`, static libc++, hidden
 internal symbols, stripped output, and `-Wl,-z,max-page-size=16384`.
-The committed prebuilt is `prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so`.
-Its SHA-256 is recorded below with the APK checks.
+The committed prebuilt is `prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so.gz`,
+gzipped (`gzip -9 -n`) so the Windows installer carries it intact: electron-builder's
+7-Zip compresses a bare arm64 ELF with its ARM64 filter, which the installer's
+extractor skips. Frame Control decompresses it when injecting the layer. The
+SHA-256 of the uncompressed library is recorded below with the APK checks.
 
 [Host test output](evidence/ctest.txt): two tests passed, covering pure logic
 and the actual layer with a fake next layer and host-only log/JNI shims.

frame/openxr-compat/build.sh

@@ -8,5 +8,8 @@ cmake -S "$here" -B "$here/build-android" -G Ninja \
   -DANDROID_STL=c++_static -DCMAKE_BUILD_TYPE=Release
 cmake --build "$here/build-android"
 mkdir -p "$here/prebuilt/arm64-v8a"
-cp "$here/build-android/libXrApiLayer_FRAME_compat.so" "$here/prebuilt/arm64-v8a/"
-shasum -a 256 "$here/prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so"
+# Committed and shipped gzipped: electron-builder's 7-Zip applies its ARM64
+# branch filter to a bare arm64 ELF, which the Windows installer's extractor
+# can't decode, so the installed app silently lacked the library.
+shasum -a 256 "$here/build-android/libXrApiLayer_FRAME_compat.so"
+gzip -9 -n -c "$here/build-android/libXrApiLayer_FRAME_compat.so" > "$here/prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so.gz"

scripts/publish-release.sh

@@ -3,23 +3,65 @@
 # (docs/releasing.md). Checks every installer is attached with a SHA-256
 # digest first, since the app's updater refuses assets without one, then
 # attaches update.json, the manifest the updater reads.
-# Usage: scripts/publish-release.sh v0.4.0
+# Usage: scripts/publish-release.sh [--dry-run] v0.4.0
+#
+# Everything goes through the REST API (gh api), not `gh release view/edit`:
+# those look a draft up by its tag, and a draft can show tag_name
+# "untagged-..." until it's published, so they report "release not found"
+# (and GraphQL is often rate-limited). A draft's html_url is an untagged-...
+# link that dies on publishing, so update.json's page is built from the tag.
 set -eu
-tag="${1:?usage: $0 vX.Y.Z}"
+dry=""
+[ "${1:-}" = "--dry-run" ] && { dry=1; shift; }
+tag="${1:?usage: $0 [--dry-run] vX.Y.Z}"
 repo=saphid/frame-control
 expected="Frame-Control-mac-arm64.dmg Frame-Control-mac-arm64.zip Frame-Control-Setup-x64.exe
 Frame-Control-win-x64.zip Frame-Control-linux-x86_64.AppImage Frame-Control-linux-arm64.AppImage
 Frame-Control-linux-amd64.deb Frame-Control-linux-arm64.deb"
+page="https://github.com/$repo/releases/tag/$tag"
 
-info=$(gh release view "$tag" -R "$repo" --json isDraft,isPrerelease,assets)
 version=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' "$(dirname "$0")/../app/package.json")
 [ "v$version" = "$tag" ] || echo "note: app/package.json here says $version (the release was built from the tag)"
 
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+# Publishing sets tag_name; if the tag didn't exist GitHub would create it on
+# the default branch, which isn't what was built and tested.
+gh api "repos/$repo/git/ref/tags/$tag" >/dev/null 2>&1 \
+  || { echo "tag $tag isn't on GitHub; push it first (git push origin $tag)" >&2; exit 1; }
+
+# Every release, drafts included, one JSON object per line.
+gh api --paginate "repos/$repo/releases?per_page=100" --jq '.[]' > "$tmp/releases"
+# The release whose tag_name is the tag; failing that, the one untagged-... draft
+# titled "Frame Control X.Y.Z" (release.yml's title), optionally ": subtitle".
+python3 - "$tag" "$tmp/releases" > "$tmp/release.json" <<'EOF'
+import json, re, sys
+tag, path = sys.argv[1], sys.argv[2]
+rels = [json.loads(line) for line in open(path) if line.strip()]
+hits = [r for r in rels if r.get("tag_name") == tag]
+if not hits:
+    # Exactly this version: "Frame Control 0.4.0", or that followed by ": <subtitle>".
+    # Never "Frame Control 0.4.0-rc.1" or "0.4.00", and only drafts with no real tag.
+    title = re.compile(r"Frame Control " + re.escape(tag.lstrip("v")) + r"(: .*)?", re.S)
+    hits = [r for r in rels if r.get("draft") and str(r.get("tag_name") or "").startswith("untagged-")
+            and title.fullmatch(r.get("name") or "")]
+if len(hits) != 1:
+    why = "no release" if not hits else "%d releases (ids %s)" % (len(hits), ", ".join(str(r["id"]) for r in hits))
+    sys.exit("found %s for %s; expected one draft" % (why, tag))
+r = hits[0]
+if not r.get("draft"):
+    print("note: %s is already published; refreshing update.json and marking it latest" % tag, file=sys.stderr)
+json.dump(r, sys.stdout)
+EOF
+id=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["id"])' "$tmp/release.json")
+echo "release  $id ($(python3 -c 'import json,sys; r=json.load(open(sys.argv[1])); print(("draft" if r["draft"] else "published") + ", tag_name " + str(r["tag_name"]))' "$tmp/release.json"))"
+
 missing=""
 for name in $expected; do
-  digest=$(printf '%s' "$info" | python3 -c 'import json,sys
-d=json.load(sys.stdin); n=sys.argv[1]
-print(next((a.get("digest") or "" for a in d["assets"] if a["name"]==n), "absent"))' "$name")
+  digest=$(python3 -c 'import json,sys
+d=json.load(open(sys.argv[1])); n=sys.argv[2]
+print(next((a.get("digest") or "" for a in d["assets"] if a["name"]==n), "absent"))' "$tmp/release.json" "$name")
   case "$digest" in
     sha256:*) echo "ok       $name" ;;
     absent) echo "MISSING  $name"; missing=1 ;;
@@ -30,16 +72,32 @@ done
 
 # update.json: what running copies read (app/updater.js), from github.com's
 # latest/download link rather than the rate-limited REST API.
-tmp=$(mktemp -d)
-trap 'rm -rf "$tmp"' EXIT
-gh release view "$tag" -R "$repo" --json tagName,url,body,assets | python3 -c 'import json,sys
-d=json.load(sys.stdin)
-names=set(sys.argv[1].split())
-print(json.dumps({"version": d["tagName"].lstrip("v"), "page": d["url"], "notes": d["body"][:4000],
+python3 - "$tmp/release.json" "$tag" "$page" "$expected" > "$tmp/update.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+tag, page, names = sys.argv[2], sys.argv[3], set(sys.argv[4].split())
+print(json.dumps({"version": tag.lstrip("v"), "page": page, "notes": (d.get("body") or "")[:4000],
                   "assets": [{"name": a["name"], "size": a["size"], "digest": a["digest"]}
-                             for a in d["assets"] if a["name"] in names]}, indent=1))' "$expected" > "$tmp/update.json"
-gh release upload "$tag" -R "$repo" "$tmp/update.json" --clobber
+                             for a in d["assets"] if a["name"] in names]}, indent=1))
+EOF
+old=$(python3 -c 'import json,sys
+d=json.load(open(sys.argv[1]))
+print(" ".join(str(a["id"]) for a in d["assets"] if a["name"]=="update.json"))' "$tmp/release.json")
+
+if [ -n "$dry" ]; then
+  echo "dry run: would replace update.json (old asset ids: ${old:-none}) with:"
+  cat "$tmp/update.json"
+  echo "dry run: would PATCH release $id: tag_name=$tag draft=false prerelease=false make_latest=true"
+  exit 0
+fi
+
+for asset in $old; do
+  gh api -X DELETE "repos/$repo/releases/assets/$asset" >/dev/null
+done
+gh api -X POST "https://uploads.github.com/repos/$repo/releases/$id/assets?name=update.json" \
+  -H "Content-Type: application/json" --input "$tmp/update.json" >/dev/null
 echo "ok       update.json"
 
-gh release edit "$tag" -R "$repo" --draft=false --prerelease=false --latest
-echo "published $tag; running copies will offer it at their next check"
+gh api -X PATCH "repos/$repo/releases/$id" -f tag_name="$tag" -F draft=false -F prerelease=false \
+  -f make_latest=true --jq '"published " + .tag_name + " at " + .html_url'
+echo "running copies will offer $tag at their next check"

tests/fakegh/gh

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""A stand-in for the GitHub CLI's `gh api`, for tests/test_publish_release.py. Serves
+the releases in $FAKEGH_RELEASES (a JSON list, drafts included) and the tags in
+$FAKEGH_TAGS (space-separated); an upload's body is written to $FAKEGH_UPLOAD.
+Every call is appended to $FAKEGH_LOG as a JSON line. Anything else fails, so the
+script under test can't fall back to `gh release ...` (GraphQL) unnoticed."""
+import json
+import os
+import sys
+
+args = sys.argv[1:]
+with open(os.environ["FAKEGH_LOG"], "a") as f:
+    f.write(json.dumps(args) + "\n")
+if not args or args[0] != "api":
+    sys.exit("fakegh: only `gh api` is supported: %r" % args)
+
+method, endpoint, fields, inp, i = "GET", None, {}, None, 1
+while i < len(args):
+    a = args[i]
+    if a == "-X":
+        method = args[i + 1]; i += 2
+    elif a in ("-f", "-F"):
+        k, _, v = args[i + 1].partition("="); fields[k] = v; i += 2
+    elif a == "--input":
+        inp = args[i + 1]; i += 2
+    elif a in ("-H", "--jq"):
+        i += 2
+    elif a.startswith("-"):
+        i += 1
+    elif endpoint is None:
+        endpoint = a; i += 1
+    else:
+        sys.exit("fakegh: unexpected argument %r" % a)
+
+releases = json.load(open(os.environ["FAKEGH_RELEASES"]))
+repo = "repos/saphid/frame-control/"
+if method == "GET" and endpoint.startswith(repo + "git/ref/tags/"):
+    tag = endpoint.rsplit("/", 1)[1]
+    if tag not in os.environ.get("FAKEGH_TAGS", "").split():
+        sys.exit("gh: Not Found (HTTP 404)")
+    print(json.dumps({"ref": "refs/tags/" + tag}))
+elif method == "GET" and endpoint.startswith(repo + "releases?"):
+    for r in releases:  # what --jq '.[]' prints
+        print(json.dumps(r))
+elif method == "DELETE" and endpoint.startswith(repo + "releases/assets/"):
+    pass
+elif method == "POST" and endpoint.startswith("https://uploads.github.com/" + repo + "releases/"):
+    with open(inp) as src, open(os.environ["FAKEGH_UPLOAD"], "w") as dst:
+        dst.write(src.read())
+    print("{}")
+elif method == "PATCH" and endpoint.startswith(repo + "releases/"):
+    print("published %s at https://github.com/saphid/frame-control/releases/tag/%s"
+          % (fields.get("tag_name"), fields.get("tag_name")))
+else:
+    sys.exit("fakegh: unhandled %s %s" % (method, endpoint))

tests/test_fdroid_sources.py

@@ -256,6 +256,36 @@ class Repositories(unittest.TestCase):
         self.assertEqual(result['icon'], URL + 'icons/legacy.1.png')
         self.assertEqual(result['images']['screenshots'], [URL + 'org.example.app/fr/sevenInchScreenshots/tablet.png'])
 
+    def test_per_abi_builds_offer_and_download_the_arm64_one(self):
+        import hashlib
+
+        def build(code, name, abis):
+            self.files[name] = name.encode()
+            return {'manifest': {'versionName': '391', 'versionCode': code, 'usesSdk': {'minSdkVersion': 28},
+                                 'nativecode': abis},
+                    'file': {'name': '/' + name, 'sha256': hashlib.sha256(name.encode()).hexdigest(), 'size': code},
+                    'added': 0}
+        # One APK per ABI under different codes (the x86_64 one highest, as F-Droid often does),
+        # plus a universal and an arm64-only build sharing a code.
+        builds = [build(3911, 'app-armeabi-v7a.apk', ['armeabi-v7a']), build(3914, 'app-x86_64.apk', ['x86_64']),
+                  build(3913, 'app-x86.apk', ['x86']),
+                  build(3912, 'app-universal.apk', ['arm64-v8a', 'armeabi-v7a', 'x86_64']),
+                  build(3912, 'app-arm64-v8a.apk', ['arm64-v8a'])]
+        raw = self.root / 'splits.json'
+        raw.write_text(json.dumps({'packages': {'com.futo.platformplayer': {
+            'metadata': {'name': {'en-US': 'Grayjay'}},
+            'versions': {str(i): b for i, b in enumerate(builds)}}}}))
+        source = {'id': 'test', 'url': URL}
+        app = fdroid._reduce(raw, source)['com.futo.platformplayer']
+        self.assertEqual([v['name'] for v in app['versions']], ['/app-arm64-v8a.apk', '/app-universal.apk'])
+        self.assertEqual((app['version_code'], app['abis']), (3912, ['arm64-v8a']))
+        with patch.object(fdroid, 'details', return_value=app):
+            for code in (None, 3912):
+                fdroid.download(source, 'com.futo.platformplayer', version_code=code)
+                self.assertTrue(self.fetch_mock.call_args[0][0].endswith('/app-arm64-v8a.apk'))
+            with self.assertRaises(SourceError):  # the x86_64 build is never offered
+                fdroid.download(source, 'com.futo.platformplayer', version_code=3914)
+
     def test_v2_legacy_screenshot_keys_and_limit(self):
         meta = {'phoneScreenshots': {'fr': [{'name': '/phone/' + str(i) + '.png'} for i in range(8)]},
                 'sevenInchScreenshots': {'en-US': [{'name': '/tablet.png'}]}}

tests/test_frame_apk_versions.py

@@ -184,6 +184,35 @@ class VersionsTest(unittest.TestCase):
         info['abis'] = ['armeabi-v7a']
         self.assertIn('no arm64-v8a build', versions.describe(info))
 
+    def test_wrong_abi_error_says_which_file_to_get(self):
+        import frame_telemetry
+        for abis in (['armeabi-v7a'], ['x86_64']):  # the two per-ABI Grayjay files users tried
+            info = {'label': 'Grayjay', 'min_sdk': 28, 'abis': abis}
+            with self.assertRaises(frame_android.FrameError) as error:
+                frame_android.check_installable(info)
+            message = str(error.exception)
+            self.assertIn('no arm64-v8a build (%s)' % abis[0], message)
+            self.assertIn('download the APK marked arm64-v8a', message)
+            self.assertEqual(frame_telemetry.categorize(message)[0], 'apk_wrong_abi')
+        frame_android.check_installable({'label': 'Universal', 'min_sdk': 28,
+                                         'abis': ['arm64-v8a', 'armeabi-v7a', 'x86', 'x86_64']})
+
+    def test_wrong_file_reports_do_not_rate_the_app(self):
+        reports = frame_catalog.reports
+        wrong_file = {'package': 'org.example.app', 'version': '391', 'result': 'install_failed',
+                      'notes': 'Example has no arm64-v8a build (x86_64); Lepton is 64-bit ARM only',
+                      'date': '2026-10-01T10:00:00'}
+        self.assertIsNone(reports.verdict([wrong_file]))
+        app = frame_catalog.catalog_build.finalize({'pr': 'likely', 'pw': ['No known blockers']}, [wrong_file])
+        self.assertEqual((app['r'], app['t']), ('likely', False))  # the prediction stands
+        # A real installer failure, a crash or a person's rating still counts.
+        installer = dict(wrong_file, notes='INSTALL_FAILED_INVALID_APK')
+        self.assertEqual(reports.verdict([installer])[0], 'no')
+        crash = dict(wrong_file, result='crashes', notes=None, date='2026-10-02')
+        self.assertEqual(reports.verdict([wrong_file, crash])[0], 'no')
+        rated = dict(wrong_file, rating='works', date='2026-10-03')
+        self.assertEqual(reports.verdict([wrong_file, rated])[0], 'works')
+
     def test_install_resolves_index_hash(self):
         versions.alternatives('org.example.app')
         with patch.object(versions, 'alternatives', side_effect=AssertionError('recomputed')), \

tests/test_frame_apk_vr.py

@@ -255,6 +255,10 @@ class VRTests(unittest.TestCase):
             self.assertEqual(set(add), set(frame_android.XR_COMPAT_FILES))
             self.assertIn(b'XR_APILAYER_FRAME_compat', add['assets/openxr/1/api_layers/implicit.d/XrApiLayer_FRAME_compat.json'])
             self.assertTrue(add['lib/arm64-v8a/libXrApiLayer_FRAME_compat.so'].startswith(b'\x7fELF'))
+            # The library verified on the headset (its SHA-256 is in the layer's README).
+            import hashlib
+            digest = hashlib.sha256(add['lib/arm64-v8a/libXrApiLayer_FRAME_compat.so']).hexdigest()
+            self.assertIn(digest, (Path(frame_android.XR_COMPAT) / 'README.md').read_text())
             with zipfile.ZipFile(apk, 'a') as z:  # already injected: nothing more to add
                 z.writestr('lib/arm64-v8a/libXrApiLayer_FRAME_compat.so', b'')
             self.assertEqual(frame_android.xr_compat_files(str(apk)), {})
@@ -269,8 +273,82 @@ class VRTests(unittest.TestCase):
             with zipfile.ZipFile(apk, 'w') as z:
                 z.writestr('lib/arm64-v8a/libopenxr_loader.so', b'')
             with patch.object(frame_android, 'XR_COMPAT', d):
-                with self.assertRaisesRegex(frame_android.FrameError, 'build.sh'):
+                with self.assertRaisesRegex(frame_android.LayerMissing, 'build.sh'):
                     frame_android.xr_compat_files(str(apk))
+            # Present but corrupt, or empty, counts as missing too.
+            for rel in frame_android.XR_COMPAT_FILES.values():
+                os.makedirs(os.path.dirname(os.path.join(d, rel)) or d, exist_ok=True)
+                with open(os.path.join(d, rel), 'wb') as f:
+                    f.write(b'\x1f\x8b not really gzip')
+            with patch.object(frame_android, 'XR_COMPAT', d):
+                with self.assertRaises(frame_android.LayerMissing):
+                    frame_android.xr_compat_files(str(apk))
+            for rel in frame_android.XR_COMPAT_FILES.values():
+                os.makedirs(os.path.dirname(os.path.join(d, rel)) or d, exist_ok=True)
+                open(os.path.join(d, rel), 'wb').close()
+            with patch.object(frame_android, 'XR_COMPAT', d):
+                with self.assertRaises(frame_android.LayerMissing):
+                    frame_android.xr_compat_files(str(apk))
+
+    def test_layer_ships_in_packaged_builds(self):
+        """The arm64 library is in the repo, copied by electron-builder, and checked after packing."""
+        import fnmatch, json
+        root = Path(__file__).resolve().parents[1]
+        for rel in frame_android.XR_COMPAT_FILES.values():
+            self.assertGreater((root / 'frame/openxr-compat' / rel).stat().st_size, 0, rel)
+        # No bare arm64 ELF ships: electron-builder's 7-Zip gives those an ARM64 filter the
+        # Windows installer can't extract, so the installed app silently lacked the library.
+        for f in (root / 'frame/openxr-compat/prebuilt').rglob('*'):
+            if f.is_file():
+                self.assertNotEqual(f.read_bytes()[:4], b'\x7fELF', f)
+        build = json.loads((root / 'app/package.json').read_text())['build']
+        self.assertEqual(build.get('afterPack'), 'build/check-resources.js')
+        entry = next(e for e in build['extraResources'] if e['from'] == '../frame/openxr-compat')
+        self.assertEqual(entry['to'], 'frame/openxr-compat')
+        check = (root / 'app/build/check-resources.js').read_text()
+        for rel in frame_android.XR_COMPAT_FILES.values():
+            self.assertTrue(any(fnmatch.fnmatch(rel, f.replace('**/', '*/')) for f in entry['filter']), rel)
+            self.assertFalse(any(f.endswith('.so') for f in entry['filter']))
+            self.assertIn('frame/openxr-compat/' + rel, check)
+
+    def test_install_goes_ahead_without_a_missing_layer(self):
+        """A copy of Frame Control without the layer installs VR apps anyway and says so."""
+        base = {'package': 'org.test.vr', 'label': 'VR', 'abis': [], 'min_sdk': None, 'vr_issues': [],
+                'vr': True, 'vr_activity': True, 'launchable': True, 'repairable': False}
+        seen = []
+        missing = frame_android.LayerMissing(frame_android.LAYER_MISSING)
+        with patch.object(frame_android, 'apk_info', side_effect=lambda p: dict(base)), \
+                patch.object(frame_android, 'xr_compat_files', side_effect=missing), \
+                patch.object(frame_android, 'patch') as repair, \
+                patch.object(frame_android, '_install', return_value={'package': 'org.test.vr'}) as install, \
+                patch.object(frame_android, 'install_hooks', [lambda *a: seen.append(a)]):
+            frame_android.install('game.apk')
+            repair.assert_not_called()  # nothing to add and nothing to repair: the APK goes as is
+            info = install.call_args.args[1]
+            self.assertTrue(info['xr_layer_missing'])
+            self.assertEqual(info['vr_issues'], [frame_android.LAYER_MISSING_NOTE])
+            self.assertIsNone(seen[-1][2])  # reported as a working install
+            # Asked for explicitly, a missing layer is still an error.
+            with self.assertRaises(frame_android.LayerMissing):
+                frame_android.install('game.apk', xr_compat=True)
+            self.assertIsInstance(seen[-1][2], frame_android.LayerMissing)
+
+    def test_patch_failures_are_named_and_every_failure_is_reported(self):
+        base = {'package': 'org.test.vr', 'label': 'VR', 'abis': [], 'min_sdk': None,
+                'vr': True, 'vr_activity': True, 'launchable': True, 'repairable': False}
+        seen = []
+        with patch.object(frame_android, 'apk_info', side_effect=lambda p: dict(base)), \
+                patch.object(frame_android, 'xr_compat_files', return_value={'x': b'1'}), \
+                patch.object(frame_android, 'patch', side_effect=frame_android.FrameError('ZIP64 APKs are unsupported')), \
+                patch.object(frame_android, 'install_hooks', [lambda *a: seen.append(a)]):
+            with self.assertRaisesRegex(frame_android.FrameError, 'could not prepare the APK for the Frame: ZIP64'):
+                frame_android.install('game.apk')
+        with patch.object(frame_android, 'apk_info', side_effect=lambda p: dict(base, vr=False)), \
+                patch.object(frame_android, '_install', side_effect=FileNotFoundError(2, 'No such file or directory', 'ssh')), \
+                patch.object(frame_android, 'install_hooks', [lambda *a: seen.append(a)]):
+            with self.assertRaises(FileNotFoundError):
+                frame_android.install('game.apk')
+        self.assertIsInstance(seen[-1][2], FileNotFoundError)  # not only FrameErrors reach telemetry
 
     def test_patch_rejects_corrupt_manifest_cleanly(self):
         with patch.object(frame_android, 'apk_info', side_effect=struct.error('bad')):

tests/test_publish_release.py

@@ -0,0 +1,110 @@
+"""scripts/publish-release.sh against a stand-in gh (tests/fakegh/gh): finds the draft
+through the REST API even when its tag_name still says untagged-..., refuses
+missing installers or digests, writes update.json's page from the tag, and
+publishes with one PATCH. Nothing here talks to GitHub.
+
+Run: python3 -m unittest discover -s tests
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import json
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = ROOT / "scripts" / "publish-release.sh"
+FAKEGH = ROOT / "tests" / "fakegh"
+INSTALLERS = ["Frame-Control-mac-arm64.dmg", "Frame-Control-mac-arm64.zip", "Frame-Control-Setup-x64.exe",
+              "Frame-Control-win-x64.zip", "Frame-Control-linux-x86_64.AppImage",
+              "Frame-Control-linux-arm64.AppImage", "Frame-Control-linux-amd64.deb",
+              "Frame-Control-linux-arm64.deb"]
+
+
+def draft(tag_name="untagged-c6ddfed7f75d67db2e99", name="Frame Control 9.8.7", rid=42, assets=None):
+    if assets is None:
+        assets = [{"id": 100 + i, "name": n, "size": 1000 + i, "digest": "sha256:" + "%064x" % i}
+                  for i, n in enumerate(INSTALLERS)]
+    return {"id": rid, "tag_name": tag_name, "name": name, "draft": True, "prerelease": False,
+            "body": "notes", "html_url": "https://github.com/saphid/frame-control/releases/tag/" + tag_name,
+            "assets": assets}
+
+
+class PublishRelease(unittest.TestCase):
+    def run_script(self, releases, *args, tags="v9.8.7"):
+        d = Path(tempfile.mkdtemp())
+        (d / "releases.json").write_text(json.dumps(releases))
+        env = dict(os.environ, PATH="%s:%s" % (FAKEGH, os.environ["PATH"]),
+                   FAKEGH_RELEASES=str(d / "releases.json"), FAKEGH_TAGS=tags,
+                   FAKEGH_LOG=str(d / "log"), FAKEGH_UPLOAD=str(d / "upload.json"))
+        p = subprocess.run(["sh", str(SCRIPT), *args], env=env, capture_output=True, text=True, timeout=30)
+        log = [json.loads(line) for line in (d / "log").read_text().splitlines()] if (d / "log").exists() else []
+        upload = json.loads((d / "upload.json").read_text()) if (d / "upload.json").exists() else None
+        return p, log, upload
+
+    def test_publishes_an_untagged_draft_by_title_with_the_tag_page(self):
+        old = {"id": 7, "name": "update.json", "size": 1, "digest": None}
+        rel = draft(assets=draft()["assets"] + [old])
+        p, log, upload = self.run_script([rel], "v9.8.7")
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(upload["page"], "https://github.com/saphid/frame-control/releases/tag/v9.8.7")
+        self.assertEqual(upload["version"], "9.8.7")
+        self.assertEqual(sorted(a["name"] for a in upload["assets"]), sorted(INSTALLERS))
+        self.assertIn(["api", "-X", "DELETE", "repos/saphid/frame-control/releases/assets/7"], log)
+        patch = next(c for c in log if "PATCH" in c)
+        self.assertEqual(patch[3], "repos/saphid/frame-control/releases/42")
+        for f in ("tag_name=v9.8.7", "draft=false", "prerelease=false", "make_latest=true"):
+            self.assertIn(f, patch)
+        self.assertTrue(all(c[0] == "api" for c in log))  # never `gh release ...` (GraphQL)
+
+    def test_an_untagged_draft_may_carry_a_subtitle(self):
+        p, log, upload = self.run_script([draft(name="Frame Control 9.8.7: faster")], "v9.8.7")
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(upload["version"], "9.8.7")
+
+    def test_prefers_the_release_whose_tag_name_matches(self):
+        p, log, upload = self.run_script([draft(name="Frame Control 9.8.7 old", rid=1),
+                                          draft(tag_name="v9.8.7", name="Renamed", rid=2)], "v9.8.7")
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(next(c for c in log if "PATCH" in c)[3], "repos/saphid/frame-control/releases/2")
+
+    def test_refuses_missing_or_unhashed_installers(self):
+        assets = draft()["assets"][1:]
+        assets[0] = dict(assets[0], digest=None)
+        p, log, upload = self.run_script([draft(assets=assets)], "v9.8.7")
+        self.assertNotEqual(p.returncode, 0)
+        self.assertIn("MISSING  Frame-Control-mac-arm64.dmg", p.stdout)
+        self.assertIn("NO HASH  Frame-Control-mac-arm64.zip", p.stdout)
+        self.assertIsNone(upload)
+        self.assertFalse(any(c[1:3] == ["-X", "PATCH"] for c in log))
+
+    def test_refuses_ambiguous_or_absent_drafts_and_missing_tags(self):
+        p, _, _ = self.run_script([draft(rid=1), draft(rid=2)], "v9.8.7")
+        self.assertNotEqual(p.returncode, 0)
+        self.assertIn("2 releases", p.stderr)
+        p, _, _ = self.run_script([draft(name="Frame Control 9.8.70")], "v9.8.7")
+        self.assertNotEqual(p.returncode, 0)
+        self.assertIn("no release", p.stderr)
+        # A pre-release's draft, or one bound to an unrelated tag, is never taken for v9.8.7.
+        for rel in (draft(name="Frame Control 9.8.7-rc.1"), draft(name="Frame Control 9.8.7.1"),
+                    draft(tag_name="kdeconnect-frame-1"), draft(tag_name="")):
+            p, log, upload = self.run_script([rel], "v9.8.7")
+            self.assertNotEqual(p.returncode, 0, rel)
+            self.assertIn("no release", p.stderr)
+            self.assertIsNone(upload)
+            self.assertFalse(any("PATCH" in c for c in log))
+        p, log, _ = self.run_script([draft()], "v9.8.7", tags="")
+        self.assertNotEqual(p.returncode, 0)
+        self.assertIn("push it first", p.stderr)
+
+    def test_dry_run_changes_nothing(self):
+        p, log, upload = self.run_script([draft()], "--dry-run", "v9.8.7")
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertIn('"page": "https://github.com/saphid/frame-control/releases/tag/v9.8.7"', p.stdout)
+        self.assertIsNone(upload)
+        self.assertTrue(all("-X" not in c for c in log))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_telemetry.py

@@ -180,6 +180,17 @@ class Scrub(unittest.TestCase):
                          "frame_unreachable")
         self.assertEqual(tm.categorize("something new")[0], "other")
 
+    def test_install_failure_categories(self):
+        import frame_android
+        self.assertEqual(tm.categorize(frame_android.LayerMissing(frame_android.LAYER_MISSING))[0], "layer_missing")
+        # The message 0.4.0 sent, so old and new builds land in the same bucket.
+        self.assertEqual(tm.categorize("the OpenXR compatibility layer isn't built; run "
+                                       "frame/openxr-compat/build.sh")[0], "layer_missing")
+        self.assertEqual(tm.categorize("could not prepare the APK for the Frame: ZIP64 APKs are unsupported")[0],
+                         "apk_repack_failed")
+        self.assertEqual(tm.categorize(FileNotFoundError(2, "No such file or directory", "ssh"))[0], "tool_missing")
+        self.assertEqual(tm.categorize("[WinError 2] The system cannot find the file specified")[0], "tool_missing")
+
 
 class Compat(Base):
     def test_reports_are_shared_only_after_opting_in_without_file_names(self):
@@ -205,6 +216,114 @@ class Compat(Base):
         self.assertEqual([e["properties"]["id"] for e in self.queued() if e["event"] == "compat_report"], ["old1"])
 
 
+class InstallFinished(unittest.TestCase):
+    def test_failure_category_only_no_text(self):
+        """install_finished carries a fixed category for a failure, never the message or a file name."""
+        import frame_android
+        with mock.patch.object(tm, "capture") as capture, mock.patch.object(tm, "diagnostic"):
+            tm.install_finished("apk", False, 0.0, frame_android.LayerMissing(
+                "C:\\Users\\Bob\\My Game.apk: " + frame_android.LAYER_MISSING), catalog=False)
+            props = capture.call_args[0][1]
+            self.assertEqual(props["error_category"], "layer_missing")
+            self.assertNotIn("Bob", repr(props))
+            self.assertEqual(set(props), {"kind", "ok", "seconds", "error_category", "catalog"})
+            tm.install_finished("apk", False)
+            self.assertEqual(capture.call_args[0][1]["error_category"], "other")
+
+
+class ApkInstallJobs(unittest.TestCase):
+    """The whole job path: what the page is told, and what telemetry sends, once."""
+
+    def setUp(self):
+        import frame_android
+        import frame_webinstall
+        import server
+        self.server, self.android, self.web = server, frame_android, frame_webinstall
+        for target, name, kw in ((server, "ensure_master", {}), (server.frame_catalog, "app", {}),
+                                 (server.frame_catalog, "add_report", {})):
+            p = mock.patch.object(target, name, **kw)
+            p.start()
+            self.addCleanup(p.stop)
+
+    def run_job(self, body):
+        job = self.server.android(body)["job"]
+        for _ in range(500):
+            with self.server._jobs_lock:
+                state = dict(self.server._jobs[job])
+            if state["done"]:
+                return state
+            time.sleep(0.01)
+        self.fail("job did not finish")
+
+    def test_missing_layer_warning_reaches_every_completion_message(self):
+        meta = {"label": "VR", "package": "org.test.vr", "vr_issues": [self.android.LAYER_MISSING_NOTE]}
+        with mock.patch.object(self.server.frame_catalog, "install", return_value=meta):
+            state = self.run_job({"action": "install", "package": "org.test.vr"})
+        self.assertIsNone(state["error"])
+        self.assertIn(self.android.LAYER_MISSING_NOTE, state["message"])
+        with mock.patch.object(self.server.frame_apk_versions, "install", return_value=meta):
+            state = self.run_job({"action": "install", "package": "org.test.vr", "url": "https://example.com/v.apk"})
+        self.assertIn(self.android.LAYER_MISSING_NOTE, state["message"])
+        with mock.patch.object(self.android, "install", return_value=meta):
+            self.assertIn(self.android.LAYER_MISSING_NOTE, self.web.dispatch("/tmp/v.apk")["message"])
+        # A normal install says nothing about the layer.
+        with mock.patch.object(self.server.frame_catalog, "install", return_value=dict(meta, vr_issues=[])):
+            state = self.run_job({"action": "install", "package": "org.test.vr"})
+        self.assertNotIn("OpenXR", state["message"])
+
+    def test_unexpected_failure_is_one_event_and_one_diagnostic(self):
+        info = {"package": "org.test.flat", "label": "Flat", "abis": [], "min_sdk": None, "vr": False,
+                "vr_activity": False, "launchable": True, "repairable": False}
+        sent = []
+        tm._seen_errors.clear()
+        with mock.patch.object(tm, "enabled", return_value=True), \
+                mock.patch.object(tm, "capture", side_effect=lambda e, p=None, level="usage": sent.append((e, p))), \
+                mock.patch.object(self.android, "apk_info", side_effect=lambda path: dict(info)), \
+                mock.patch.object(self.android, "_install",
+                                  side_effect=FileNotFoundError(2, "No such file or directory", "scp")), \
+                mock.patch.object(self.server.frame_catalog, "install",
+                                  side_effect=lambda pkg: self.android.install("/tmp/x.apk")):
+            state = self.run_job({"action": "install", "package": "org.test.flat"})
+        self.assertIn("FileNotFoundError", state["error"])
+        events = [e for e, _ in sent]
+        self.assertEqual(events.count("install_finished"), 1)
+        self.assertEqual(events.count("$exception"), 1, events)
+        finished = next(p for e, p in sent if e == "install_finished")
+        self.assertEqual((finished["ok"], finished["error_category"]), (False, "tool_missing"))
+        # The same failure through a web link: one event and one diagnostic there too.
+        sent.clear()
+        tm._seen_errors.clear()
+        job = {"phase": "download", "done": 0, "total": None, "detail": "", "message": None, "error": None,
+               "cancel": False}
+        plan = {"name": None, "exe": None, "url": "https://example.com/x.apk", "kind": "apk"}
+        with mock.patch.object(tm, "enabled", return_value=True), \
+                mock.patch.object(tm, "capture", side_effect=lambda e, p=None, level="usage": sent.append((e, p))), \
+                mock.patch.object(self.android, "apk_info", side_effect=lambda path: dict(info)), \
+                mock.patch.object(self.android, "_install",
+                                  side_effect=FileNotFoundError(2, "No such file or directory", "scp")), \
+                mock.patch.object(self.server.frame_webinstall, "download",
+                                  side_effect=lambda plan, tmp, **kw: os.path.join(tmp, "x.apk")):
+            self.server._webinstall_run(plan, job)
+        self.assertEqual(job["phase"], "error")
+        self.assertIn("FileNotFoundError", job["error"])
+        events = [e for e, _ in sent]
+        self.assertEqual(events.count("install_finished"), 1, events)
+        self.assertEqual(events.count("$exception"), 1, events)
+        finished = next(p for e, p in sent if e == "install_finished")
+        self.assertEqual((finished["kind"], finished["error_category"]), ("apk", "tool_missing"))
+        # A FrameError still gets its install diagnostic (the job reports it as well, as before).
+        sent.clear()
+        tm._seen_errors.clear()
+        with mock.patch.object(tm, "enabled", return_value=True), \
+                mock.patch.object(tm, "capture", side_effect=lambda e, p=None, level="usage": sent.append((e, p))), \
+                mock.patch.object(self.android, "apk_info", side_effect=lambda path: dict(info)), \
+                mock.patch.object(self.android, "_install", side_effect=self.android.FrameError("timed out talking to frame")), \
+                mock.patch.object(self.server.frame_catalog, "install",
+                                  side_effect=lambda pkg: self.android.install("/tmp/x.apk")):
+            self.run_job({"action": "install", "package": "org.test.flat"})
+        self.assertEqual([e for e, _ in sent].count("install_finished"), 1)
+
+
 class ApkInstallReports(unittest.TestCase):
     """server.apk_installed: an APK that won't install is reported; connection trouble isn't."""
 
@@ -224,6 +343,12 @@ class ApkInstallReports(unittest.TestCase):
         self.assertEqual((args[0], args[1], kw["result"], kw["via"]), ("org.x", "2.0", "install_failed", "install"))
         self.assertIs(self.install_finished.call_args[0][1], False)
 
+    def test_install_without_layer_is_flagged(self):
+        self.server.apk_installed({"package": "com.private.vr", "xr_layer_missing": True}, {}, None, 4.0)
+        self.assertIs(self.install_finished.call_args[1]["xr_layer_missing"], True)
+        self.server.apk_installed({"package": "com.private.vr"}, {}, None, 4.0)
+        self.assertIsNone(self.install_finished.call_args[1]["xr_layer_missing"])
+
     def test_connection_trouble_is_not_reported(self):
         self.server.apk_installed({"package": "org.x", "version": "2.0"}, None,
                                   self.server.frame_android.FrameError("timed out talking to frame"), 3.0)

ui/frame_android.py

@@ -11,7 +11,7 @@ Python stdlib only. CLI: python3 ui/frame_android.py
   install-obb PKG OBB [OBB ...] | backup-data PKG ARCHIVE | restore-data PKG ARCHIVE
   refresh-art PKG|--all | patch SRC DST [--add NAME=PATH ...] | list | launch PKG | stop PKG | remove PKG | probe PKG
 """
-import base64, json, os, re, shlex, shutil, struct, subprocess, sys, threading, time, zlib
+import base64, gzip, json, os, re, shlex, shutil, struct, subprocess, sys, threading, time, zlib
 
 import frame_apk
 import frame_artwork
@@ -33,7 +33,8 @@ SHORTCUTS = os.path.join(ROOT, 'frame', 'android', 'steam_shortcuts.py')
 XR_COMPAT = os.path.join(ROOT, 'frame', 'openxr-compat')
 XR_COMPAT_FILES = {
     'assets/openxr/1/api_layers/implicit.d/XrApiLayer_FRAME_compat.json': 'XrApiLayer_FRAME_compat.json',
-    'lib/arm64-v8a/libXrApiLayer_FRAME_compat.so': 'prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so',
+    # Gzipped in the repo and the app; see frame/openxr-compat/build.sh for why.
+    'lib/arm64-v8a/libXrApiLayer_FRAME_compat.so': 'prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so.gz',
 }
 PKG_RE = re.compile(r'^[A-Za-z][\w]*(\.[A-Za-z_][\w]*)+$')
 SSH_OPTS = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=8']
@@ -43,6 +44,18 @@ class FrameError(RuntimeError):
     pass
 
 
+class LayerMissing(FrameError):
+    """The OpenXR compatibility layer's files aren't in this copy of Frame Control."""
+
+
+LAYER_MISSING = ("Frame Control's OpenXR compatibility layer is missing from this copy "
+                 "(frame/openxr-compat/prebuilt); reinstall Frame Control, or in a source "
+                 "checkout run frame/openxr-compat/build.sh")
+LAYER_MISSING_NOTE = ("Installed without the OpenXR compatibility layer, which is missing from this "
+                      "copy of Frame Control; apps that need OpenXR 1.1 may not start. Reinstalling "
+                      "Frame Control restores it.")
+
+
 def ssh(cmd, input=None, timeout=120):
     try:
         # No inherited stdin (see server.ssh): Windows' ssh.exe would wait on it.
@@ -94,17 +107,29 @@ def xr_compat_files(apk_path):
     for entry, rel in XR_COMPAT_FILES.items():
         try:
             with open(os.path.join(XR_COMPAT, rel), 'rb') as f:
-                add[entry] = f.read()
-        except OSError:
-            raise FrameError("the OpenXR compatibility layer isn't built; run frame/openxr-compat/build.sh")
+                data = f.read()
+            add[entry] = gzip.decompress(data) if rel.endswith('.gz') else data
+        except (OSError, EOFError, zlib.error):  # gzip.BadGzipFile is an OSError
+            add[entry] = b''
+        if not add[entry]:  # missing, unreadable (antivirus, permissions) or truncated
+            raise LayerMissing(LAYER_MISSING)
     return add
 
 
+def layer_note(meta):
+    """The missing-layer warning for an install's completion message, or ''."""
+    return LAYER_MISSING_NOTE if LAYER_MISSING_NOTE in ((meta or {}).get('vr_issues') or []) else ''
+
+
 def check_installable(info):
     if info['min_sdk'] and info['min_sdk'] > 30:
         raise FrameError(f"{info['label']} needs Android API {info['min_sdk']}; Lepton is Android 11 (API 30)")
     if info['abis'] and 'arm64-v8a' not in info['abis']:
-        raise FrameError(f"{info['label']} has no arm64-v8a build ({', '.join(info['abis'])}); Lepton is 64-bit ARM only")
+        # Sites that offer one APK per ABI (Grayjay: arm64-v8a, armeabi-v7a, x86, x86_64,
+        # universal) leave the choice to the user; say which file to fetch instead.
+        raise FrameError(f"{info['label']} has no arm64-v8a build ({', '.join(info['abis'])}); Lepton is 64-bit ARM only. "
+                         "This file is for other devices: download the APK marked arm64-v8a "
+                         "(or arm64, or universal) and install that instead")
 
 
 _install_lock = threading.Lock()  # installs are rare; one at a time avoids every race
@@ -159,18 +184,31 @@ def install(apk_path, flatscreen=None, name=None, source=None, icon_png=None, xr
         if flatscreen is None:
             flatscreen = not info['vr']
         # VR apps get the OpenXR compatibility layer unless told otherwise; it only
-        # changes calls SteamVR would otherwise reject.
-        add = xr_compat_files(apk_path) if (info['vr'] if xr_compat is None else xr_compat) else {}
+        # changes calls SteamVR would otherwise reject. Without it OpenXR 1.0 apps
+        # still run, so a copy of Frame Control that lacks it installs anyway and
+        # says so, unless the layer was asked for explicitly.
+        add = {}
+        if info['vr'] if xr_compat is None else xr_compat:
+            try:
+                add = xr_compat_files(apk_path)
+            except LayerMissing:
+                if xr_compat:
+                    raise
+                info['vr_issues'] = list(info.get('vr_issues') or []) + [LAYER_MISSING_NOTE]
+                info['xr_layer_missing'] = True
         with _install_lock:
             if add or info['repairable']:
                 with tempfile.TemporaryDirectory(prefix='frame-vr-') as tmp:
                     patched = os.path.join(tmp, 'app.apk')
-                    info['patched'] = patch(apk_path, patched, add)['patched']
+                    try:
+                        info['patched'] = patch(apk_path, patched, add)['patched']
+                    except FrameError as e:
+                        raise FrameError(f'could not prepare the APK for the Frame: {e}') from e
                     info['launchable'] = True
                     meta = _install(patched, info, pkg, flatscreen, name, source or os.path.basename(apk_path), artwork)
             else:
                 meta = _install(apk_path, info, pkg, flatscreen, name, source, artwork)
-    except FrameError as e:
+    except Exception as e:  # not only FrameError: every failed install is reported
         _after_install(info, None, e, start)
         raise
     _after_install(info, meta, None, start)

ui/frame_telemetry.py

@@ -243,6 +243,9 @@ CATEGORIES = [
     ('android_installer', re.compile(r'INSTALL_(?:FAILED|PARSE_FAILED)_[A-Z_]+')),
     ('apk_needs_newer_android', re.compile(r'needs Android API')),
     ('apk_wrong_abi', re.compile(r'no arm64-v8a build')),
+    ('layer_missing', re.compile(r'OpenXR compatibility layer')),
+    ('apk_repack_failed', re.compile(r'could not prepare the APK for the Frame')),
+    ('tool_missing', re.compile(r"\[WinError 2\]|No such file or directory: '(?:ssh|scp|rsync|adb)")),
     ('apk_unreadable', re.compile(r'(?i)not a zip|bad apk|AndroidManifest|ApkError|unexpected package name')),
     ('cant_run_on_frame', re.compile(r"can't run on the Frame")),
     ('steam_shortcut', re.compile(r'(?i)steam did not return a shortcut|shortcut list|no Steam shortcut')),
@@ -349,8 +352,9 @@ def frame_seen(build, version):
     capture('frame_connected', {'steamos_build': str(build)[:40], 'steamos_version': str(version or '')[:40]})
 
 
-def install_finished(kind, ok, seconds=None, error=None, **props):
-    """kind: apk, flatpak, steam, title or web. props must already be public (no file names)."""
+def install_finished(kind, ok, seconds=None, error=None, diagnose=True, **props):
+    """kind: apk, flatpak, steam, title or web. props must already be public (no file names).
+    diagnose=False when the error is reported as a diagnostic elsewhere."""
     p = {'kind': kind, 'ok': bool(ok), **{k: v for k, v in props.items() if v is not None}}
     if seconds is not None:
         p['seconds'] = round(seconds, 1)
@@ -358,8 +362,10 @@ def install_finished(kind, ok, seconds=None, error=None, **props):
         p['error_category'], code = categorize(error)
         if code:
             p['installer_code'] = code
+    elif not ok:
+        p['error_category'] = 'other'
     capture('install_finished', p)
-    if error is not None and not ok:
+    if error is not None and not ok and diagnose:
         diagnostic(f'{kind} install failed', error)
 
 

ui/frame_webinstall.py

@@ -456,7 +456,9 @@ def dispatch(path, name=None, exe=None, progress=None, source=None):
             m = frame_android.install(path, source=source or os.path.basename(path))
         except frame_android.FrameError as e:
             raise WebInstallError(str(e))
-        return {"message": f"Installed {m['label']} as its own app in the Steam library", "kind": kind, "result": m}
+        message = f"Installed {m['label']} as its own app in the Steam library"
+        note = frame_android.layer_note(m)
+        return {"message": f"{message}. {note}" if note else message, "kind": kind, "result": m}
     try:
         import frame_titles
     except ImportError as e:

ui/server.py

@@ -1255,8 +1255,8 @@ def android(body):
 
             def work():
                 m = frame_apk_versions.install(pkg, url) if url else frame_catalog.install(pkg)
-                return {"message": f"Installed {m['label']}. It's in the Steam library; launching it opens its own panel.",
-                        "app": m}
+                message = f"Installed {m['label']}. It's in the Steam library; launching it opens its own panel."
+                return {"message": f"{message} {frame_android.layer_note(m)}".strip(), "app": m}
             return start_job(f"Install {pkg}", work)
         if action == "refresh-art":
             if not pkg and not body.get("all"):
@@ -1304,8 +1304,12 @@ def apk_installed(info, meta, error, seconds):
     in_catalog = bool(pkg) and pkg in by_pkg
     # Package names only for catalogue apps, which are public; a private APK's name stays here.
     # No version: a local rebuild can share a catalogue app's package name but carry anything in its version.
+    # frame_android.install re-raises anything that isn't a FrameError, and whoever
+    # catches it (a job, a request) reports it with its traceback: once is enough.
     frame_telemetry.install_finished("apk", error is None, seconds, error, catalog=in_catalog,
-                                     package=pkg if in_catalog else None)
+                                     diagnose=error is None or isinstance(error, frame_android.FrameError),
+                                     package=pkg if in_catalog else None,
+                                     xr_layer_missing=True if (info or {}).get("xr_layer_missing") else None)
     if error is not None and pkg and frame_telemetry.categorize(error)[0] in APK_FAULTS:
         frame_catalog.add_report(pkg, info.get("version"), result="install_failed", notes=str(error)[:300],
                                  via="install", label=info.get("label"))
@@ -1844,8 +1848,12 @@ def _webinstall_run(plan, job):
         job["error"] = str(e) if isinstance(e, known) else f"{type(e).__name__}: {e}"
         job["phase"] = "error"
         # An APK that failed to install was counted by apk_installed.
-        if not isinstance(e, frame_webinstall.Cancelled) and not (stage == "install" and plan.get("kind") == "apk"):
+        apk_install = stage == "install" and plan.get("kind") == "apk"
+        if not isinstance(e, frame_webinstall.Cancelled) and not apk_install:
             frame_telemetry.install_finished("web", False, error=e, stage=stage, kind_detail=plan.get("kind"))
+        elif apk_install and not isinstance(e, known):
+            # Not a FrameError, so apk_installed left its diagnostic to whoever caught it: here.
+            frame_telemetry.diagnostic("web install", e)
     finally:
         with _web_lock:
             job.pop("_conn", None)