Headset store: pending game data belongs to the installed package, in every view, and goes when the app does

From review round 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

@@ -22,6 +22,7 @@ desktop or panels.
 | See the Frame from the Mac, or the Mac inside the Frame | `docs/streaming.md` | `scripts/run-on-frame.sh mac-screen` |
 | Files and clipboard | `docs/file-transfer.md` | `scripts/push.sh`, `scripts/paste-to-frame.sh` |
 | Android apps (Lepton) | `docs/apks.md` | `scripts/install-apk.sh` |
+| Browse and install Android apps from inside the headset (APK Store panel) | `docs/apks.md` | `scripts/store-on-frame.sh` |
 | Reach the Frame off the home LAN (Tailscale) | `docs/tailscale.md` | `scripts/tailscale-on-frame.sh` |
 | Install or buy Steam games, Frame ratings | `docs/steam-games.md` | `ui/frame_steam.py` |
 | Flatpaks | `docs/streaming.md` | `scripts/install-apps.sh` |

.github/workflows/release.yml

@@ -14,7 +14,40 @@ 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 (the tag must already exist on GitHub, then tag_name is set
+  # explicitly), so scripts/publish-release.sh and `gh release upload` find it
+  # by tag. It is created with the REST API so the id comes straight back: the
+  # release list can lag a fresh draft (v0.4.2's first run found nothing and
+  # PATCHed releases/ with an empty id). tests/test_release_workflow.py runs
+  # this step against tests/fakegh.
+  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}"
+          # A rerun finds the draft an earlier attempt made.
+          id=$(gh api --paginate "repos/$GH_REPO/releases?per_page=100" --jq ".[] | select(.tag_name == \"$tag\") | .id" | head -n 1)
+          if [ -z "$id" ]; then
+            # Given a missing tag, GitHub would create it on the default branch.
+            gh api "repos/$GH_REPO/git/ref/tags/$tag" >/dev/null \
+              || { echo "tag $tag isn't on GitHub" >&2; exit 1; }
+            id=$(gh api -X POST "repos/$GH_REPO/releases" -f tag_name="$tag" -f name="Frame Control ${tag#v}" \
+              -F draft=true -f body="" --jq .id)
+          fi
+          [ -n "$id" ] || { echo "no release id for $tag; not PATCHing releases/" >&2; exit 1; }
+          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 +73,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 }}

README.md

@@ -73,7 +73,7 @@ Drag files onto the window to send them. Drop a game's .zip, folder or .exe to a
 Browse the shots you take in the headset and save them to your Pictures folder.
 
 **⌨️ Keyboard and trackpad**<br>
-Type and point in the headset from your computer or phone, through Valve's own input path, with nothing to install. Accents and emoji use KDE Connect, which Frame Control brings along and sets up the first time you type one.
+Type and point in the Frame's apps from your computer or phone, through KDE Connect, which Frame Control brings along and sets up on the Frame. Nothing else to install, anywhere.
 
 </td>
 </tr>

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/main.js

@@ -115,10 +115,11 @@ function ping(target) {
 }
 
 async function startServer() {
-  // The version and whether this is a built app go to ui/frame_telemetry.py, which
-  // sends nothing from a source checkout.
+  // The version, the time zone and whether this is a built app go to ui/frame_telemetry.py,
+  // which sends nothing from a source checkout.
   const env = { ...process.env, PATH: await loginPath(), FRAME_CONTROL_APP: "1",
                 FRAME_CONTROL_VERSION: app.getVersion(), FRAME_CONTROL_LOG: LOG,
+                FRAME_CONTROL_TIMEZONE: Intl.DateTimeFormat().resolvedOptions().timeZone || "",
                 ...(app.isPackaged ? { FRAME_CONTROL_PACKAGED: "1" } : {}),
                 ...(fs.existsSync(TOOLS) ? { FRAME_CONTROL_TOOLS: TOOLS } : {}) };
   python = await findPython(env);

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.0",
+  "version": "0.4.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.0",
+      "version": "0.4.6",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.0",
+  "version": "0.4.6",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",
@@ -29,6 +29,7 @@
         ]
       }
     ],
+    "afterPack": "build/check-resources.js",
     "directories": {
       "output": "dist",
       "buildResources": "build"
@@ -49,6 +50,7 @@
           "*.py",
           "*.html",
           "*.js",
+          "*.css",
           "telemetry.json"
         ]
       },
@@ -81,7 +83,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/apks.md

@@ -177,6 +177,63 @@ See
 [compat-db/README.md](../compat-db/README.md) and
 [apk-catalog/README.md](../apk-catalog/README.md).
 
+## Store and Library in Frame Control
+
+The Android tab has two views. **Store** finds apps across the sources (F-Droid,
+IzzyOnDroid, curated GitHub releases, itch.io). **Library** shows the apps on the
+Frame as cards, with Play and a menu for Test, Report and Remove; the display
+settings and recent reports are below it.
+
+The store groups apps by what a headset is good for, not by F-Droid's list:
+VR, Games, Emulators, Watch & listen, Read & learn, Create, Work, Web & chat
+and Tools (`ui/apk_sources/_categories.py`). A VR app is always in VR. Otherwise
+F-Droid's own categories decide, the finer one first (an app in *Multimedia* and
+*Social Network* is Web & chat).
+
+Apps built around a phone are hidden from browsing unless **Show phone-only
+apps** is on; a search always finds them, labelled *Phone app*. Hidden: apps in
+a category that only makes sense in a phone's own system (launchers, keyboards,
+wallpapers, Xposed modules), apps in a phone-side category (calls and SMS, VPNs,
+fitness, alarms, system tools) unless a useful category says otherwise
+(FluffyChat is in Phone & SMS, but it's a messenger), apps named for a phone
+part (a widget, a launcher, a battery tool), and apps that need hardware the
+Frame lacks (an IR blaster, a watch, NFC, root). They would install and run in
+Lepton, but do nothing useful on the Frame. In the October 2026 indexes that is
+about 1,600 of F-Droid's 4,500 apps and 550 of IzzyOnDroid's 1,300.
+
+Without a search, each source offers its best 300 for the chosen category:
+apps with a banner first, then with screenshots, then the newest.
+
+## The store in the headset: Frame Control's store as a panel (inferred, not yet run on the Frame)
+
+The **APK Store** panel is the Store above, drawn for the laser: the same
+sources, categories and artwork, with Install, Open, Stop and Remove, opened as
+its own floating panel:
+
+```sh
+scripts/store-on-frame.sh open     # copy the server over if it changed, start it, open the panel
+scripts/store-on-frame.sh close
+```
+
+`open` copies the same bundle the iPhone app uses
+(`ios/scripts/make_frame_bundle.py`) to
+`~/.local/share/frame-control/store-server/<version>` on the Frame. It then
+starts `ui/server.py` there with `FRAME_LOCAL=1` on `127.0.0.1:47812`, with a
+fresh `X-Frame-UI` key. Chromium XR (or the `org.chromium.Chromium` Flatpak)
+opens `/store` (`ui/store.html`) in a 1280×800 app window, tagged as panel
+`2001947812` ([panels.md](panels.md)). Downloads, SHA-256 checks and installs
+all run on the Frame, so the Mac can go away after `open`.
+
+The page has a category rail (Home, the store's categories, Installed), eight
+art cards a page, and a featured VR app on Home. It turns pages instead of
+scrolling, because a tagged panel gets mouse clicks and a drag would select
+text; the thumbstick (a mouse wheel) turns pages, and an on-screen keyboard is
+there for search. **Checked on the Mac only** (2026-10-14, 1280×800, against
+the real sources): Home, categories, Installed, the detail sheet. **Still to
+check in the headset:** that the panel opens and takes laser clicks, that an
+install completes when run on the Frame, and that **Open** brings up the app's
+panel.
+
 ## In-headset app store: F-Droid 1.17 (verified 2026-09-25)
 
 F-Droid 1.23 uses an old Compose and crashes on launch. **F-Droid 1.17.2**, the

docs/devices.md

@@ -104,7 +104,9 @@ connection is an SSH ControlMaster that every command shares; when it dies (the
 headset slept or left the network) the connector notices and starts again. On
 Windows, where OpenSSH can't share a connection, the same handshake runs once
 and each command then connects on its own; a command that can't reach the
-headset makes the connector start again.
+headset makes the connector start again. There ssh's stderr goes to a file that
+the connector reads as it grows, not a pipe: Windows' OpenSSH can block writing
+to a redirected pipe.
 
 Once connected, every `ssh`, `scp` and `rsync` the app runs gets
 `-o HostName=<address> -o HostKeyAlias=frame-control-<id>
@@ -121,9 +123,57 @@ lease that moved) would look like a new host there. The app keeps one known_host
 file per headset instead, so saving or forgetting one headset's key never touches
 another's: a different device answering at one of its
 addresses is refused, and the pill says so. A headset's first connection trusts
-the key it shows, as Set Up Connection does. After reinstalling SteamOS the
-headset has a new key; **Forget identity** on the Devices tab lets the next
-connection save the new one.
+the key it shows, as Set Up Connection does: while a headset has never had an
+identity here, every ssh command gets `StrictHostKeyChecking=accept-new` (the
+first contact saves it, whichever command makes it), and from then on
+`StrictHostKeyChecking=yes`. `accept-new` never replaces a saved key, so it
+can't hide a change. The saved key's fingerprint is also recorded in
+`devices.json` (`identity`), along with a flag that never clears
+(`identity_established`), as soon as ssh saves the key: even if the login is then
+refused. A headset counts as having had an identity if the flag is set, a
+fingerprint is recorded, its pin file exists at all, or a connection to it ever
+worked (older files get the flag from that when loaded, so editing or removing
+the address that worked doesn't undo it); then
+a pin file that's deleted, empty, unreadable or not parseable **fails closed**
+(*Checking the headset's identity* fails, "missing or can't be read") rather than
+trusting whatever answers, and only **Check its key…** saves a key again. It
+says when the key it reads matches the recorded fingerprint.
+
+**When the key changes** (SteamOS reinstalled or reset, a new headset at the
+same address, or a different device answering there), nothing is accepted by
+itself. The connection fails at *Checking the headset's identity*; the banner
+and the headset on the Devices tab say so, with **Check the new key…** (also
+**Check its key…** on the Devices tab at any time). That reads the key the
+headset shows now, and nothing more: ssh writes it to a throwaway known_hosts
+file during the key exchange, before any login, and is stopped as soon as it
+has. Every other kind of contact is ruled out on the command line, ahead of
+anything `~/.ssh/config` says: no authentication of any kind, no agent
+(`IdentityAgent=none`, `ForwardAgent=no`), no X11 or port forwarding, no local
+or remote command (`-N`), no terminal, and `-F none`. Through a ProxyJump host
+it builds that hop itself, as a ProxyCommand whose ssh forwards nothing and runs
+no local command (ProxyJump's own ssh would take `ForwardAgent` and
+`LocalCommand` from `~/.ssh/config`); it still logs in to the jump host as
+configured. Every word of that ProxyCommand is quoted for the shell that runs it
+(and `%` doubled for ssh's own tokens), the forward is `[%h]:%p` so an IPv6
+headset works, and an IPv6 jump host is passed bare with its port. Through a ProxyCommand from `~/.ssh/config`, or several jump hosts,
+it refuses, since those can't be made safe from here: add an address it can
+reach directly, or compare the key by hand. It shows the key's SHA256 fingerprint next to
+the saved one, with the command that prints it on the headset
+(`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`, in Konsole on its desktop).
+**This is my headset: trust its new key** then saves exactly that key, replacing
+the old one, and reconnects. The server keeps the key it showed for 10 minutes
+and saves it only if the page sends back the same fingerprint, and only while
+the headset's port, user and that address are unchanged; it never saves whatever
+answers next. The API's old `forget-identity`, which deleted the pin so that the
+next contact saved any key unseen, is refused. Set Up Connection can't fix a changed key: it checks your
+own `known_hosts`, not the headset's file.
+
+**When the headset refuses this computer's key** (`Permission denied
+(publickey,…)`), the connection stops at *Logging in*, and the banner and the
+Devices tab offer **Set Up Connection…**, which pairs this computer again.
+
+Neither is reported as a fault: the diagnostics report each kind at most once
+a session ([privacy.md](privacy.md)).
 
 ## One server at a time
 
@@ -144,7 +194,7 @@ All under the usual `/api/` guards (loopback `Host`, `X-Frame-UI` header).
 | `GET /api/devices` | Headsets, the current network, known networks, the next free alias |
 | `GET /api/devices/tailscale?id=` | Tailscale peers, likely headsets first |
 | `GET /api/devices/mdns?id=` | Headsets found on this network |
-| `POST /api/devices` | `{"action": ...}`: `use`, `update` (name, user, port), `remove`, `address-add`, `address-update`, `address-remove`, `address-move`, `test`, `forget-identity`, `name-network`, `setup` (alias, optional host), `retry` |
+| `POST /api/devices` | `{"action": ...}`: `use`, `update` (name, user, port), `remove`, `address-add`, `address-update`, `address-remove`, `address-move`, `test`, `identity-scan` (read the key the headset shows: `scan` with `type`, `fingerprint`, `host`, `saved`, `recorded`, `matches`, `recorded_match`), `identity-trust` (`fingerprint`: save the key `identity-scan` showed), `forget-identity` (refused: use the two before), `name-network`, `setup` (alias, optional host), `retry` |
 
 Every host, alias and user is checked against strict patterns before it's
 stored, because they end up in ssh arguments and `~/.ssh/config`; nothing goes
@@ -161,7 +211,7 @@ share the format later (it still connects to one host; see
 ```json
 {"version": 1, "active": "f67f8b7e",
  "devices": [{"id": "f67f8b7e", "name": "Steam Frame", "alias": "frame", "user": "steamos", "port": 22,
-              "identity_files": ["~/.ssh/id_ed25519_frame"],
+              "identity_files": ["~/.ssh/id_ed25519_frame"], "identity": ["SHA256:…"], "identity_established": true,
               "addresses": [{"host": "frame.local", "kind": "mdns", "label": "",
                              "networks": ["n-e0998baa61"], "last_ok": 1790593550.4, "last_rtt_ms": 0.9}]}],
  "networks": {"n-e0998baa61": {"name": "Home Wi-Fi", "ssid": null, "gateway": "192.168.1.1",

docs/frame-control.md

@@ -17,11 +17,12 @@ python3 ui/server.py         # anywhere: then open http://127.0.0.1:47810
 
 ## Features
 
-The window has five tabs: **Home** (headset view, status, screenshots),
+The window has six tabs: **Home** (headset view, status, screenshots),
 **Games** (installed games, sideloaded titles, getting games), **Android** (apps,
 the catalogue, display settings, reports), **Tools** (sending files and text,
-Flatpaks, remote and power) and **Devices** (your headsets and their addresses).
-Keys 1–5 switch between them. Files can be dropped anywhere in the window. A
+Flatpaks, remote and power), **Devices** (your headsets and their addresses),
+and **Control** (the searchable Control Center, metrics, supported settings and
+headset guidance). Keys 1–6 switch between them. Files can be dropped anywhere in the window. A
 connection pill in the header always shows which headset, which network this
 computer is on, the address in use or being tried, and each step of connecting
 as it happens; click it for the whole timeline. When the Frame can't be
@@ -88,8 +89,68 @@ counts them while they run.
   name your networks, and switch headsets. See [devices.md](devices.md).
 - **One-click tools**: SSH or SFTP in a terminal window, Steam Link, and remote
   desktop (Windows App on macOS, Remote Desktop on Windows, Remmina or FreeRDP on
-  Linux). Sleep, restart and shut down open a terminal window because SteamOS
-  asks for the sudo password over SSH.
+  Linux). Remote desktop first checks that the Frame's xrdp answers on port
+  3389 (Developer Mode turns it on). On Windows it opens a connection file for
+  user `steamos`, because `mstsc /v:` alone offers your Windows account, which
+  xrdp turns away. Accept the warning about the Frame's own certificate, then
+  sign in with the Developer Mode password. Sleep, restart and
+  shut down open a terminal window because SteamOS asks for the sudo password
+  over SSH.
+
+## Control Center
+
+Open **Control** or `#control` to search controls, status and help. Categories
+cover device/audio, VR/comfort, apps/files, connection/remote and Frame Control
+preferences. Search is local: it matches labels, descriptions and familiar terms
+such as “DPI”, “microphone”, “recenter” and “keep awake”. Queries are not sent to
+Steam, app catalogues, analytics or models. Choosing a workflow link opens its
+existing screen; it does not install, cast, open a helper or change a setting.
+Home, Games, Android, Tools and Devices retain their existing features.
+
+The overview and detail cards use the shared `/api/status` sample: charge and
+power, user/system storage, memory, Wi-Fi, IP, OS/build, uptime, detected services
+and VR timings. Values refresh with the normal 30-second poll. A failed status
+request, lost connection, headset switch or sample received more than 90 seconds
+ago clears current readings and disables audio writes. The client receipt time
+and failed-read state are retained through page startup and UI redraws. Only a
+new successful status read clears a failure; reusing the retained sample does not.
+The headset timestamp is shown without assuming
+its clock matches this computer. Missing sensors show **Unavailable**;
+they are not converted to zero. Compositor FPS is separate from application FPS;
+GPU time is render time, not GPU utilisation. The temperature is the hottest
+readable sensor. Thermal trip warnings use per-zone kernel hot/critical limits,
+not a guessed universal temperature threshold.
+
+**Audio** controls the default output sink through the existing `/api/volume`
+endpoint. Moving its slider prepares a value; **Apply volume** sends it. **Mute**
+and **Unmute** send explicit mute states. The UI captures the selected headset,
+blocks duplicate/pending actions, and requests status after command acknowledgment
+for readback, draining an earlier poll first. Mute preserves an unapplied volume
+draft; switching headsets discards it. It reports
+unconfirmed or differing output separately from confirmed state. API validation
+rejects invalid types, out-of-range levels and invalid mute states before SSH.
+
+Other settings link to the existing forms and their validation, progress,
+confirmations and reset behavior: per-instance Android resolution/density/text,
+comfort sessions and alerts, media layouts, Mac streaming quality, privacy,
+sources and artwork. Android display links reveal the **Library** before
+scrolling to the form. Mac streaming remains searchable on all platforms, with
+its action shown only when the server is on macOS.
+
+Hardware guidance is deliberately separate from controls. Microphone/routing,
+brightness, refresh selection, optics, controllers, Bluetooth, passthrough,
+tracking-origin changes, saved spatial layouts, firmware updates and recovery
+have no verified remote setting here. Use the headset's own controls or the
+documented manual procedures. Movement comfort remains per-game; automatic
+sleep is in Steam Settings → Power → Sleep after inactivity. Keep-awake and
+Android data backup/restore remain script/MCP capabilities, not new UI switches.
+
+**Verification:** the Control Center's JavaScript runs under Node with mocked
+API and DOM boundaries; the server tests mock SSH and reject invalid values
+before any device command. Packaging tests cover the shared CSS/JS in desktop
+and iPhone bundles. These checks establish wiring, search, navigation, offline,
+error and device-switch behavior; they do not establish wearer experience,
+physical settings persistence or a new hardware capability.
 
 ## How it works
 

docs/privacy.md

@@ -33,23 +33,46 @@ computer, exactly as they were sent.
   yours.
 - Every event includes the app version, OS name (macOS, Windows or Linux),
   CPU architecture and Python version.
+- `app_installed`, `app_updated` and `app_opened` carry `country`: a
+  two-letter code such as `DE`, worked out on your computer from its time zone
+  setting (`Europe/Berlin` becomes `DE`), so we can see roughly where Frame
+  Control is used without knowing your address. The time zone itself isn't
+  sent, and a setting that isn't a country's zone (such as UTC) sends nothing.
+  Copies that showed the first-run notice before it mentioned this (before
+  0.4.6) show it again, and don't send a country until it has been seen.
+- `frame_connected` carries `headset_id`: the first 16 hex digits of a
+  SHA-256 hash of the headset's `/etc/machine-id`, worked out on the headset,
+  so the machine-id itself never leaves it. It is the same for one headset on
+  every computer, which lets us count headsets rather than installs; it can't
+  be turned back into the machine-id or a serial number. `headsets_saved` is how
+  many headsets this copy of Frame Control has set up.
 
 ## Usage events
 
 | Event | When | Properties besides the common ones |
 |---|---|---|
-| `app_installed` | First run | |
-| `app_updated` | First run of a new version | `from_version` |
-| `app_opened` | At most once a day | |
-| `frame_connected` | The first time a SteamOS build is seen | `steamos_build`, `steamos_version` |
+| `app_installed` | First run | `country` |
+| `app_updated` | First run of a new version | `from_version`, `country` |
+| `app_opened` | At most once a day | `country` |
+| `frame_connected` | The first time a SteamOS build is seen on each headset | `steamos_build`, `steamos_version`, `headset_id`, `headsets_saved` |
 | `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`, `steam_not_running`,
+`steam_not_responding`, `steam_js_error`, `artwork_failed`, `copy_timeout`,
+`frame_not_set_up`, `frame_auth`, `frame_unreachable`, `frame_disk_full`,
+`copy_failed`, `download_failed`, `flatpak`, `cancelled`, `lepton`,
+`internal_error` (a mistake in Frame Control's own code) 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
@@ -93,7 +116,11 @@ scrubbed:
   names, passwords, ports, paths and queries are dropped
 - `token=`, `key=`, `password=` and similar values are replaced
 
-The same error is sent at most once every 10 minutes.
+The same error is sent at most once every 10 minutes. When ssh reports that
+it couldn't reach the Frame (asleep, away, or not set up yet), or that ssh and
+the Frame refused each other's keys (a changed host key, or this computer's
+key not accepted), that is sent at most once per kind each time Frame Control
+runs.
 
 ## Report a problem
 
@@ -107,7 +134,14 @@ wrote, a short reference shown after sending, and the diagnostics below. Your
 email address goes with it only if you tick **The maintainer may contact me
 with follow-up questions** (the report then carries `contact_followup: true`);
 it's filled in from **Contact email** below when you've agreed there. It has its own random id, so it isn't linked to
-your analytics events.
+your analytics events. With that box ticked, the address also becomes your
+**Contact email** below with follow-up questions ticked, so you remove it there
+like any other. If it's a different address from the one saved there, it
+replaces it, and update notices stop until you turn them on again (they were
+agreed for the old address); the form says so before you send. The report then also
+carries this copy's contact id and change number (`contact_id`, `contact_rev`,
+see below), so removing or changing the address later takes back the
+follow-up permission given with the report too.
 
 With **Include diagnostics** ticked (the default), the report adds:
 
@@ -115,10 +149,56 @@ With **Include diagnostics** ticked (the default), the report adds:
 - the OS, its release and CPU, and the Python version
 - the Frame's SteamOS build, if it has connected since the app started
 - which analytics levels are on
+- a short connection summary, so "the app can't find the headset" can be
+  diagnosed. It is made of fixed words and counts only; no text from an
+  error message or from ssh, and no name you chose, goes in it:
+  - the connector's state (idle, connecting, connected or failed), the stage
+    it failed at (network, find, ssh, identity or login), the attempt number
+    and why it started (such as "Starting up" or "Trying again")
+  - how many headsets are saved; whether the active one's ssh alias is the
+    default `frame` or a custom one (a custom alias itself is never named);
+    whether it's saved or a bare ssh alias; and its number of addresses
+  - for the current error and the last failure: the stage and an error
+    category (the same fixed names as error details, such as
+    `frame_unreachable`, `frame_not_set_up`, `frame_auth` or `other`), and
+    how long ago the last failure was. The category is decided when the
+    failure happens
+  - for each address tried, only its kind (`.local`, `ipv4`, `ipv6`,
+    `ipv6 link-local`, `tailscale`, `hostname`, `alias` for one read from
+    `~/.ssh/config`, and what a name resolved to, such as
+    `.local->ipv6 link-local`) and how the try went (answered, unresolved,
+    timeout, refused, unreachable, sshfailed). Never the address itself
+  - when connected, the kind of address used and its round trip in ms
+  - whether this computer has a network gateway, and whether Tailscale is on,
+    off or not installed
+  - which kind of `ssh` the app runs (Windows OpenSSH in System32, OpenSSH in
+    Program Files, Git for Windows, MSYS2/Cygwin, Homebrew or /usr/local,
+    Nix, the system one, or "other"), never its path; its version, rebuilt
+    from the numbers in the banner `ssh -V` prints (such as
+    `OpenSSH for Windows 9.5p1, LibreSSL 3.8.2`; anything that isn't a
+    plain OpenSSH banner is reported as `unknown`); and the kinds of any
+    other `ssh` on the PATH.
+    This is looked up once in the background after the app starts, so a
+    report sent straight away may say "still being checked"
+  - whether `~/.ssh/config` exists, whether it has Set Up Connection's
+    managed block for the active alias, how many managed blocks it has, and
+    whether a hand-written `Host` line also names the alias (yes or no; the
+    alias isn't named)
 
 **Also include recent activity and the server log** is off by default,
 because those lines can name files and apps. When ticked, it adds the newest
-Activity lines and server log lines, without the request lines.
+Activity lines and server log lines, without the request lines. The server
+log has a line for each failed connection attempt: its stage, the message
+shown on the connection pill, ssh's last line about it, and the address kinds
+above. That free text is scrubbed when the line is written: the addresses, ssh alias
+and display name of the headset being tried (whole, whatever their case), and
+then any name ssh gives after "hostname", "host" or "to", become `<host>`; a Windows home folder's
+whole name (spaces and apostrophes included) becomes `<user>`, and ssh's
+whole `user@host:` field (spaces, `DOMAIN\user` and full domain names
+included) becomes `<user>@<host>:`; then the scrubbing below. A host name ssh mentions
+in some other wording can still get through, so check the log lines in **Show
+exactly what's included** before sending. A failure that repeats on every
+retry is written at most once every 5 minutes.
 
 Everything is scrubbed like error details and limited to what fits in the
 report. Environment details are kept first, then the newest lines. **Show
@@ -141,8 +221,8 @@ are two separate choices, both off until you tick them:
 | **The maintainer may contact me with follow-up questions** | Questions about problem reports you send, mostly |
 
 You're asked once, in a bar at the top of the page, after the Frame has
-connected for the first time, and never while or straight after the
-first-run privacy notice is showing. **No thanks** hides it for good, and it isn't
+connected for the first time, and never in the same visit as the first-run
+privacy notice. **No thanks** hides it for good, and it isn't
 shown again even if you ignore it. **Contact email** in **Privacy & updates**
 is where you add, change or remove the address and either choice at any time.
 
@@ -151,7 +231,10 @@ Frame Control's PostHog project, the same place as problem reports, as a
 `contact_consent` event with `email`, `updates`, `followup`, `action` (`set`
 or `withdraw`) and the common properties above. Only the maintainer can read
 that project, and nothing in it is published or shared. It's sent only when
-you save, whatever the analytics settings are, because you chose to. It
+you save, or when you send a problem report with follow-up questions ticked,
+whatever the analytics settings are, because you chose to. With a report, the
+address and choices are saved before the report is sent and stay saved if it
+fails; like any change, they're sent as soon as PostHog can be reached. It
 carries its own random contact id, not the analytics id, so it isn't linked
 to your usage events, and a `rev` number that goes up with each change, so
 the newest choice always wins. Like everything else sent, it's listed under
@@ -164,7 +247,11 @@ deletes it from this computer, including from the **Show what's been sent**
 log (in earlier contact events and problem reports), and sends a `withdraw`
 event with no address in it. The maintainer's list only uses the newest event from each copy, so from
 then on the address isn't listed for either choice. Unticking one choice
-works the same way for that choice. If you're offline, the change waits on
+works the same way for that choice. This also covers problem reports you sent
+from this copy with follow-up questions ticked: if your newest choice since the
+report (by change number, not the clock) no longer agrees to follow-up
+questions at that address, the maintainer's inbox shows the permission as
+withdrawn and leaves the address out. If you're offline, the change waits on
 this computer and is sent when PostHog can be reached. The earlier event
 stays in PostHog until its data retention removes it; to have it deleted
 sooner, ask the maintainer (for example in a problem report).

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/scripts.md

@@ -89,6 +89,7 @@ controls to place each panel. See [docs/panels.md](panels.md).
 | Script | Runs on | Purpose |
 |---|---|---|
 | `scripts/tailscale-on-frame.sh` | Mac → Frame | Install Tailscale in `~` as a userspace user service so `frame` works from anywhere; `--uninstall` (**verified** on the LAN) |
+| `scripts/store-on-frame.sh` | Mac → Frame | Open the APK Store (Frame Control's Android store) as a panel in the headset; installs run on the Frame (**inferred**; see [docs/apks.md](apks.md)) |
 | `scripts/connect.sh` | Mac | Discover, set up key and `~/.ssh/config`, copy key, optional `--harden` (**verified**; `--harden` untested) |
 | `scripts/install-apps.sh` | Mac → Frame | Install Flatpaks (Remmina, Moonlight, …) on the Frame over SSH as `--user` (**verified** with Remmina) |
 | `scripts/paste-to-frame.sh` | Mac → Frame | Send the Mac clipboard (or stdin) to the Frame clipboard (**verified**) |

docs/streaming.md

@@ -25,6 +25,20 @@ The confidence labels are the same as in [ssh.md](ssh.md).
 documents it. Use Windows App (RDP) when you want a proper Linux desktop on the
 Mac with keyboard, mouse, and clipboard.
 
+**Verified 2026-09-30** (Frame BUILD_ID 20260925.6191901, Windows 11 25H2,
+Remote Desktop Connection): signing in to xrdp as `steamos` with the Developer
+Mode password opens a Plasma (X11) desktop within about 6 seconds.
+
+- xrdp has no NLA, so the client shows a certificate warning (xrdp's own
+  `www.xrdp.org` certificate) and then xrdp's own login box. Frame Control
+  fills in `steamos` there on Windows, Remmina and FreeRDP.
+- The desktop is a separate login session (Xorg on display `:10`), not the
+  headset's view. It uses about 1.3 GB of the Frame's memory.
+- Closing the client leaves the session running, and the next login
+  reconnects to it. To end it over SSH, find it with `loginctl list-sessions`
+  and run `loginctl terminate-session <id>`. That doesn't touch the headset's
+  gamescope or SteamVR session.
+
 ## B. Show the Mac's desktop inside the Frame
 
 The Frame's VR streaming uses **SteamVR** on the host. Linux hosts had
@@ -123,13 +137,10 @@ two fingers to scroll, two-finger tap to right-click) plus a text field that
 types on the Frame. On a computer, clicking the pad passes your mouse and
 keyboard through to the Frame until you press Esc (⌘ is sent as Ctrl on a Mac).
 
-Since Control (below), the pad goes through **gamescope's own input socket**
-([`ui/frame_touch.py`](../ui/frame_touch.py)), so it reaches whichever panel has
-focus, Steam's own menus included, and needs nothing installed on the Frame.
-Only characters that aren't on a US keyboard (accents, emoji) go through
-**KDE Connect** as below; it starts the first time you type one. (Before
-Control, everything went through KDE Connect, which is why the notes below
-describe it in detail.)
+It goes through **KDE Connect**, the first-party route (KDE makes the Frame's
+desktop): Frame Control's server runs [`ui/frame_input_agent.py`](../ui/frame_input_agent.py)
+on the Frame, which talks KDE Connect's own LAN protocol to the Frame's
+`kdeconnectd` as if it were a phone. KDE Connect does the typing and clicking.
 
 **Verified 2026-09-28** (SteamOS 0.4.1, build 20260925.6191901):
 
@@ -250,6 +261,16 @@ How (**verified 2026-09-29**, SteamOS 0.4.1, build 20260925.6191901):
   -window_id <window> -i :<display>` works on gamescope's redirected windows,
   while grabbing the root gives black. It streams as H.264 like the headset view
   (about 30 fps at 720p).
+- **When no panel is found**, `frame_touch.py panels` says why (`"why"`), and the
+  Desktop view shows that instead of a bare "no app panel": X tools missing,
+  gamescope listing windows that aren't X11 windows on any display, the desktop
+  running but not listed, or nothing open. It reads gamescope's properties from
+  `:0` first (one `xprop` call) and probes the other displays, 2 s each, only if `:0`
+  has none. A whole run stops after 12 s, inside the server's 20 s, and says the headset
+  was too slow. Added for
+  [#73](https://github.com/saphid/frame-control/issues/73) (SteamOS 0.4.5, desktop
+  open but not found). The likely cause there was the page itself: a second
+  `loadPanels` (the panel switcher's) replaced the Desktop view's, fixed in #84.
 - Tested from the iPhone app (Simulator): a tap on the Desktop view focused a
   text box in the panel and the text field typed into it; a trackpad move went
   exactly (+40, +25).

docs/testing.md

@@ -15,6 +15,29 @@ A fourth, a SteamOS VM, may come later ([issue #6](https://github.com/saphid/ste
 python3 -m unittest discover -s tests
 ```
 
+The Control Center is covered by `tests/test_control_center.py` and its Node
+behavior suite `tests/control_center.cjs` (also run by unittest discovery).
+They exercise production search, metrics, navigation and action handlers with
+mocked API/DOM boundaries: volume Apply/mute/readback, offline and failed reads,
+stale samples, selected-headset capture, duplicate actions and validation before
+SSH. Integration regressions run the production shared refresh, Home renderer,
+host callback and Control Center bootstrap: a pre-command status request must be
+drained before audio readback starts, and delayed startup retains sample receipt
+age, failed-read state and early host capabilities. The actual Flatpak install
+redraw cannot revive a failed sample; a new successful poll restores metrics and
+audio after either redraw or delayed mount. Draft regressions cover a pending headset
+switch and mute followed by Apply. Static asset HTTP tests and desktop/iPhone bundle checks catch missing CSS
+or JavaScript. A focused run is:
+
+```sh
+python3 -m unittest discover -s tests -p test_control_center.py -v
+node --test tests/control_center.cjs
+node --check ui/control-center.js
+```
+
+Responsive layout, actual browser rendering and keyboard/touch behavior still
+need browser verification. No Control Center test connects to a real headset.
+
 About 120 tests, a few seconds, on Python 3.9 and newer. GitHub Actions runs
 them on macOS, Windows and Linux. They don't pick up `tests/e2e`.
 

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"

ios/scripts/make_frame_bundle.py

@@ -18,7 +18,7 @@ import tarfile
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[2]
-PATTERNS = ["ui/*.py", "ui/*.html", "ui/local-bin/*", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py",
+PATTERNS = ["ui/*.py", "ui/*.html", "ui/*.js", "ui/*.css", "ui/local-bin/*", "ui/apk_sources/*.py", "ui/apk_sources/*.json", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py",
             "frame/devkit-utils/**/*", "apk-catalog/*.py", "apk-catalog/pins.json", "apk-catalog/site/apps.js",
             "frame/kdeconnect/packages.json", "frame/kdeconnect/NOTICE.md", "frame/kdeconnect/LICENSES/*/*",
             "frame/kdeconnect/packages/*.pkg.tar.zst", "LICENSE", "THIRD_PARTY_NOTICES.md"]

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"

scripts/store-on-frame.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env zsh
+# Mac-side: the APK Store in the headset. Frame Control's Android catalogue
+# (the same rated F-Droid list, Install, Open and Remove) as its own floating
+# panel on the Steam Frame, so you can browse and install apps from inside.
+# See docs/apks.md → "The store in the headset".
+#
+# Frame Control's server runs on the Frame itself (FRAME_LOCAL=1, as the iPhone
+# app runs it) on the Frame's loopback, and Chromium opens ui/store.html as a
+# panel. Installs then download and verify the APK on the Frame; the Mac isn't
+# needed after `open`.
+#
+# Usage:
+#   scripts/store-on-frame.sh open     # copy the server over if it changed, start it, open the panel
+#   scripts/store-on-frame.sh close    # close the panel and stop the server
+#   scripts/store-on-frame.sh status
+set -euo pipefail
+
+FRAME_ALIAS=${FRAME_ALIAS:-frame}
+HERE=${0:A:h}
+ROOT=${HERE:h}
+PORT=47812           # the Frame's 127.0.0.1 only
+APPID=2001947812     # the panel's id (panel-on-frame.sh's range)
+# Not ~/.cache/frame-control: the iPhone app prunes other versions there.
+REMOTE=.local/share/frame-control/store-server
+
+cmd=${1:-}
+
+# Same bundle the iPhone app copies (ios/scripts/make_frame_bundle.py), so the
+# server on the Frame has exactly the files the desktop app ships.
+deploy() {
+  local tmp version
+  tmp=$(mktemp -d)
+  trap "rm -rf ${(q)tmp}" EXIT
+  version=$(python3 "$ROOT/ios/scripts/make_frame_bundle.py" "$tmp/bundle.tar.gz")
+  if ! ssh "$FRAME_ALIAS" "test -f $REMOTE/$version/ui/server.py"; then
+    print -u2 "==> Copying Frame Control ($version) to the Frame"
+    ssh "$FRAME_ALIAS" "set -e; mkdir -p $REMOTE; cd $REMOTE; rm -rf $version.tmp; mkdir $version.tmp
+      tar xzf - -C $version.tmp; rm -rf $version; mv $version.tmp $version" <"$tmp/bundle.tar.gz"
+  fi
+  # Older versions, unless a server is still running from one.
+  ssh "$FRAME_ALIAS" "cd $REMOTE && for d in */; do d=\${d%/}; [ \"\$d\" = $version ] && continue
+    pgrep -f \"\$PWD/\$d/\" >/dev/null && continue; rm -rf -- \"\$d\"; done"
+  print -r -- "$version"
+}
+
+# Runs on the Frame. Args: dir port appid key
+OPEN=$(cat <<'EOF'
+set -u
+dir=$HOME/$1 port=$2 appid=$3 key=$4
+export DISPLAY=:0 LC_ALL=C.UTF-8
+unset WAYLAND_DISPLAY
+xprop -root GAMESCOPE_FOCUSABLE_WINDOWS >/dev/null 2>&1 || { echo "The headset isn't showing anything (gamescope's :0 isn't up). Wake it and try again." >&2; exit 2; }
+if [ -x "$HOME/chromium-xr/chrome" ]; then
+  # Steam's overlay library crashes Chromium's zygote (docs/webxr-chromium.md).
+  browser=(env LD_PRELOAD= "$HOME/chromium-xr/chrome" --user-data-dir="$HOME/.local/share/frame-control/store")
+elif flatpak info org.chromium.Chromium >/dev/null 2>&1; then
+  browser=(flatpak run org.chromium.Chromium --user-data-dir="$HOME/.var/app/org.chromium.Chromium/frame-store")
+else
+  echo "The store needs a Chromium on the Frame: Chromium XR (docs/webxr-chromium.md) or the org.chromium.Chromium Flatpak (scripts/install-apps.sh)." >&2
+  exit 3
+fi
+# A fresh server each time, so it runs this version with this key.
+[ -f /tmp/frame-store-server.pid ] && kill "$(cat /tmp/frame-store-server.pid)" 2>/dev/null
+# Match the browser by its profile flag and the server by its script path: this
+# launcher's own command line holds the bundle path, so a looser pattern kills it.
+pkill -f '[-]-user-data-dir=[^ ]*/(frame-control/store|frame-store) ' || true
+pkill -f '[s]tore-server/[^/ ]*/ui/server[.]py' || true
+sleep 0.5
+cd "$dir" || exit 1
+FRAME_LOCAL=1 FRAME_UI_KEY=$key FRAME_DEVICE=headset setsid nohup python3 -I -u -B "$dir/ui/server.py" --port "$port" \
+  >/tmp/frame-store-server.log 2>&1 </dev/null &
+echo $! > /tmp/frame-store-server.pid
+up=
+for _ in $(seq 1 40); do
+  curl -s -o /dev/null "http://127.0.0.1:$port/store" && { up=1; break; }
+  sleep 0.25
+done
+[ -n "$up" ] || { echo "Frame Control's server didn't start on the Frame:" >&2; tail -n 15 /tmp/frame-store-server.log >&2; exit 1; }
+setsid nohup "${browser[@]}" --ozone-platform=x11 --force-device-scale-factor=1 --no-first-run --no-default-browser-check \
+  --password-store=basic --disable-session-crashed-bubble --noerrdialogs --disable-infobars \
+  --disable-features=Translate,MediaRouter --window-size=1280,800 \
+  "--app=http://127.0.0.1:$port/store?key=$key" >/tmp/frame-store.log 2>&1 </dev/null &
+# Tag the window so it's its own panel (docs/panels.md).
+for _ in $(seq 1 60); do
+  sleep 0.5
+  for win in $(xwininfo -root -children 2>/dev/null | awk '/^ +0x/ {print $1}'); do
+    xprop -id "$win" _NET_WM_NAME WM_NAME 2>/dev/null | grep -qF "APK Store" || continue
+    if xprop -id "$win" -f STEAM_GAME 32c -set STEAM_GAME "$appid" 2>/dev/null; then
+      echo "panel valve.steam.desktopgame.$appid window $win"
+      exit 0
+    fi
+  done
+done
+echo "Chromium started, but its window didn't appear within 30 s:" >&2
+tail -n 15 /tmp/frame-store.log >&2
+exit 1
+EOF
+)
+
+case "$cmd" in
+  open)
+    version=$(deploy | tail -n 1)
+    key=$(openssl rand -hex 16)
+    ssh "$FRAME_ALIAS" bash -s -- "$REMOTE/$version" "$PORT" "$APPID" "$key" <<<"$OPEN"
+    ;;
+  close)
+    ssh "$FRAME_ALIAS" 'pkill -f "[-]-user-data-dir=[^ ]*/(frame-control/store|frame-store) " || true
+      pkill -f "[s]tore-server/[^/ ]*/ui/server[.]py" || true
+      [ -f /tmp/frame-store-server.pid ] && kill "$(cat /tmp/frame-store-server.pid)" 2>/dev/null; rm -f /tmp/frame-store-server.pid; true'
+    ;;
+  status)
+    ssh "$FRAME_ALIAS" "ls $REMOTE 2>/dev/null; curl -s -o /dev/null http://127.0.0.1:$PORT/store && echo 'server up' || echo 'server down'
+      pgrep -af '[-]-user-data-dir=[^ ]*/(frame-control/store|frame-store) |[s]tore-server/[^/ ]*/ui/server[.]py' | head -n 1 | cut -c1-120"
+    ;;
+  *) sed -n '2,15p' "$0"; exit 2 ;;
+esac

scripts/timezones.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Regenerate ui/frame_timezones.py, the time zone -> country table usage statistics use.
+
+From the IANA tz database's zone.tab (each zone's country) and tzdata.zi (the old
+names that link to them), as installed on macOS and most Linux systems. It prints the
+old names left out because their zone is shared by several countries: check any new
+one, and add it to OLD_SPELLINGS if it's just an old spelling of a zone.tab zone.
+
+Run: python3 scripts/timezones.py [/usr/share/zoneinfo]
+"""
+import sys
+from pathlib import Path
+
+src = Path(sys.argv[1] if len(sys.argv) > 1 else '/usr/share/zoneinfo')
+country = {}
+for line in (src / 'zone.tab').read_text().splitlines():
+    if line and not line.startswith('#'):
+        cc, _, zone = line.split('\t')[:3]
+        country[zone] = cc
+links = {}
+for line in (src / 'tzdata.zi').read_text().splitlines():
+    if line.startswith('L '):
+        _, target, alias = line.split()
+        links[alias] = target
+def resolve(z):
+    for _ in range(5):
+        z = links.get(z, z)
+    return z
+
+
+# An old name links to a zone with the same clocks, which can be in another country
+# (Africa/Asmera, Eritrea, links to Africa/Nairobi), so it only gets a country when every
+# zone.tab zone sharing that target is in one country.
+countries_of = {}
+for zone, cc in country.items():
+    countries_of.setdefault(resolve(zone), set()).add(cc)
+# Clock rules rather than places (EET links to Athens, WET to Lisbon): no country.
+GENERIC = {'CET', 'EET', 'MET', 'WET', 'EST', 'MST', 'HST', 'CST6CDT', 'EST5EDT', 'MST7MDT', 'PST8PDT'}
+# Places that have left zone.tab, so their target's group looks like another country's.
+PLACES = {'Pacific/Johnston': 'UM'}
+dropped = []
+for alias in links:
+    if alias in country or alias in GENERIC or alias.startswith('Etc/'):
+        continue
+    if alias in PLACES:
+        country[alias] = PLACES[alias]
+        continue
+    ccs = countries_of.get(resolve(alias), set())
+    if len(ccs) == 1:
+        country[alias] = next(iter(ccs))
+    else:
+        dropped.append(alias)
+# Old names for a place in a zone.tab zone whose target is shared, checked by hand.
+OLD_SPELLINGS = {
+    'Africa/Asmera': 'Africa/Asmara', 'Africa/Timbuktu': 'Africa/Bamako', 'America/Coral_Harbour': 'America/Atikokan',
+    'America/Montreal': 'America/Toronto', 'America/Nipigon': 'America/Toronto', 'America/Thunder_Bay': 'America/Toronto',
+    'Canada/Eastern': 'America/Toronto', 'America/Virgin': 'America/St_Thomas', 'Antarctica/South_Pole': 'Antarctica/McMurdo',
+    'Asia/Rangoon': 'Asia/Yangon', 'Atlantic/Jan_Mayen': 'Arctic/Longyearbyen', 'Europe/Belfast': 'Europe/London',
+    'GB': 'Europe/London', 'GB-Eire': 'Europe/London', 'Iceland': 'Atlantic/Reykjavik', 'NZ': 'Pacific/Auckland',
+    'Pacific/Samoa': 'Pacific/Pago_Pago', 'US/Samoa': 'Pacific/Pago_Pago', 'Singapore': 'Asia/Singapore',
+    'US/Arizona': 'America/Phoenix', 'Pacific/Truk': 'Pacific/Chuuk', 'Pacific/Ponape': 'Pacific/Pohnpei',
+    'Pacific/Yap': 'Pacific/Chuuk'}
+for alias, zone in OLD_SPELLINGS.items():
+    if alias in links and zone in country:
+        country[alias] = country[zone]
+        dropped.remove(alias)
+version = (src / '+VERSION').read_text().strip() if (src / '+VERSION').exists() else 'unknown'
+rows = ''.join(f'    {z!r}: {c!r},\n' for z, c in sorted(country.items()))
+out = Path(__file__).resolve().parent.parent / 'ui' / 'frame_timezones.py'
+out.write_text(f'''"""Time zone name -> two-letter country, from the IANA tz database {version} (zone.tab, and
+the old names in tzdata.zi that link to its zones). Generated by scripts/timezones.py.
+Zones that aren't in one country, such as UTC, aren't here."""
+COUNTRY = {{
+{rows}}}
+''')
+print(f'{len(country)} zones, tz {version} -> {out}')
+print('no country (shared by several):', ' '.join(sorted(dropped)) or 'none')

tests/apk_fixtures.py

@@ -0,0 +1,87 @@
+"""Small APKs built in memory (binary manifest plus resource table), for test_frame_apk
+and the end-to-end tests. Deliberately doesn't import sandbox: tests/e2e runs in a
+throwaway container and keeps its real home, which sandbox would move."""
+import io
+import os
+import struct
+import sys
+import zipfile
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'ui'))
+import frame_apk  # noqa: E402
+
+
+def pool(strings, utf8=False):
+    """A ResStringPool chunk."""
+    data, offsets = b'', []
+    for s in strings:
+        offsets.append(len(data))
+        if utf8:
+            b = s.encode()
+            data += bytes([len(s), len(b)]) + b + b'\0'
+        else:
+            data += struct.pack('<H', len(s)) + s.encode('utf-16-le') + b'\0\0'
+    data += b'\0' * (-len(data) % 4)
+    start = 28 + 4 * len(strings)
+    body = struct.pack(f'<{len(strings)}I', *offsets) + data
+    return struct.pack('<HHIIIIII', 1, 28, 28 + len(body), len(strings), 0, 0x100 if utf8 else 0, start, 0) + body
+
+
+def manifest(package, label_ref, version_ref, min_sdk, package_raw=True, foreign_label=False):
+    """<manifest package versionName><uses-sdk minSdkVersion/><application label icon/></manifest>.
+
+    package_raw=False drops the package's raw string (as some repackers do);
+    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
+    resmap = struct.pack('<4I', 0x01010001, 0x01010002, 0x0101021c, 0x0101020c)
+    resmap = struct.pack('<HHI', 0x0180, 8, 8 + len(resmap)) + resmap
+
+    def element(name, attrs):
+        body = struct.pack('<IIHHHHHH', 0xffffffff, name, 20, 20, len(attrs), 0, 0, 0)
+        for aname, raw, dtype, value in attrs:
+            body += struct.pack('<IIIHBBI', 0xffffffff, aname, raw, 8, 0, dtype, value)
+        return struct.pack('<HHIII', 0x0102, 16, 16 + len(body), 1, 0xffffffff) + body
+
+    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),
+                            (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 [])))
+    return struct.pack('<HHI', 3, 8, 8 + len(chunks)) + chunks
+
+
+def resources(values):
+    """resources.arsc with package 0x7f; values: {(type id, entry, language, density): global string index}."""
+    strings = ['French label', 'App label', '2.1', 'res/icon_lo.png', 'res/icon_hi.png', 'res/icon.xml']
+    pkg_body = b''
+    for (tid, lang, density), entries in values.items():
+        cfg = struct.pack('<I4x2s4xH', 64, lang.encode().ljust(2, b'\0'), density).ljust(64, b'\0')
+        count = max(entries) + 1
+        offsets, data = [], b''
+        for i in range(count):
+            if i in entries:
+                offsets.append(len(data))
+                data += struct.pack('<HHI', 8, 0, 0) + struct.pack('<HBBI', 8, 0, frame_apk.T_STRING, entries[i])
+            else:
+                offsets.append(0xffffffff)
+        header = 20 + 64
+        estart = header + 4 * count
+        body = struct.pack(f'<{count}I', *offsets) + data
+        pkg_body += struct.pack('<HHIBBHII', 0x0201, header, header + len(body), tid, 0, 0, count, estart) + cfg + body
+    pkg_header = struct.pack('<HHII', 0x0200, 288, 288 + len(pkg_body), 0x7f).ljust(288, b'\0')
+    pkg = pkg_header + pkg_body
+    table = pool(strings, utf8=True) + pkg
+    return struct.pack('<HHII', 2, 12, 12 + len(table), 1) + table
+
+
+def apk(files):
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, 'w') as z:
+        for name, data in files.items():
+            z.writestr(name, data)
+    return buf.getvalue()

tests/control_center.cjs

@@ -0,0 +1,471 @@
+// Real Control Center logic with a minimal DOM; no network, browser or headset.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const vm = require('node:vm');
+const cc = require('../ui/control-center.js');
+
+const sample = () => ({time:Date.now()/1000, hostname:'Test Frame', battery:{percent:99,status:'Discharging',watts:0,tempC:33,health:'Good'},
+  power:{type:'C PD [PD_PPS]',watts:18}, disk:{home:{total:256*1073741824,free:128*1073741824}},
+  memory:{total:16*1073741824,available:6*1073741824}, wifi:{ssid:'Test LAN',signal:80},
+  performance:{compositorFps:90,appFps:45,frameMs:11.11,gpuMs:3,cpuPercent:12,gpuMHz:600},
+  volume:{level:.4,muted:false}, os:{version:'0.4.1',build:'test-build'},services:{steamvr:true}, thermalAlerts:[],games:[],flatpaks:[]});
+function fixture() {
+  const elements = new Map();
+  function element(id) {
+    if (!elements.has(id)) elements.set(id, {id,hidden:false,disabled:false,textContent:'',innerHTML:'',value:'',dataset:{},
+      classList:{toggle(){}},querySelectorAll(){return [];},setAttribute(key,value){this[key]=value;},addEventListener(key,callback){this[key]=callback;},focus(){this.focused=true;}});
+    return elements.get(id);
+  }
+  const cards = cc.catalog.map(item=>{const e=element(item.id);e.dataset.ccCard=item.id;return e;});
+  const buttons = cc.categories.map(([id])=>{const e=element('category-'+id);e.dataset.ccCategory=id;e.querySelector=()=>element('count-'+id);return e;});
+  const metrics = Object.keys(cc.metrics(null)).map(id=>{const e=element('metric-'+id);e.dataset.ccMetric=id;return e;});
+  const page = element('controlCenter');
+  page.querySelectorAll = selector => selector === '[data-cc-category]' ? buttons : selector === '[data-cc-metric]' ? metrics : selector === '[data-cc-mac-link]' ? [element('macLink')] : [];
+  page.querySelector = selector => selector === '[href="#connection"]' ? element('connectionLink') : cards.find(e=>selector === `[data-cc-card="${e.dataset.ccCard}"]`);
+  return {document:{getElementById:element},element,cards,buttons};
+}
+function mounted(options = {}) {
+  const f = fixture(), calls = [];
+  let context = {online:true,generation:1,device:'frame-a'}, refreshes = 0, opened = 0;
+  const ui = cc.mount({document:f.document,platform:'darwin',api:async(...args)=>{calls.push(args);return {message:'Volume updated'};},
+    refresh:async()=>{refreshes++;},getContext:()=>context,openConnection:()=>opened++,...options});
+  return {...f,ui,calls,get context(){return context;},set context(v){context=v;},get refreshes(){return refreshes;},get opened(){return opened;}};
+}
+const pageSource = fs.readFileSync(require.resolve('../ui/index.html'),'utf8');
+const deferred = () => { let resolve, reject; const promise=new Promise((ok,bad)=>{resolve=ok;reject=bad;});return {promise,resolve,reject}; };
+const flush = async () => { for(let i=0;i<12;i++)await Promise.resolve(); };
+// Execute the actual shared refresh/deduplication, host callback and mount
+// bootstrap, including the real Home-to-Control status handoff. Only unrelated
+// rendering helpers, timers and transport are stubbed.
+function sharedPage({productionApi=false} = {}) {
+  const f=fixture(), requests=[], writes=[], host=deferred(), job=deferred();
+  const context={document:f.document,FrameControlCenter:cc,window:{frameApp:{setUpConnection(){}}},
+    Date,setInterval,clearInterval,setTimeout:()=>1,clearTimeout(){},$:f.element,QUICK:[],installing:new Set(),
+    battery(){},setVolume(){},gb:String,dur:String,esc:String,meter(){},toast(){},
+    runJob(title,id){context.installing.add(id);return job.promise;},
+    api:(path,body,device)=>{
+      if(path==='/api/host')return host.promise;
+      if(path==='/api/status'){const request=deferred();requests.push(request);return request.promise;}
+      writes.push({path,body,device});return Promise.resolve({message:'Volume updated'});
+    },renderPerformance(){},setConn(){},setOnline(ok){vm.runInContext(`online = ${ok}`,context);},log(){},failed(){},
+    watchConnection(){context.watched=true;}};
+  vm.createContext(context);
+  const stateDeclaration=pageSource.match(/let state = null[^\n]*/)[0];
+  vm.runInContext(stateDeclaration+'\nlet online = true, devGen = 1; const HOST = {computer:"computer"}; window.connDevice="frame-a";',context);
+  const refreshStart=pageSource.indexOf('let refreshing = null'),refreshEnd=pageSource.indexOf('// ---- our VR HUD',refreshStart);
+  const renderStart=pageSource.indexOf('function render(s) {'),renderEnd=pageSource.indexOf('// ---- view ----',renderStart);
+  vm.runInContext(pageSource.slice(renderStart,renderEnd)+pageSource.slice(refreshStart,refreshEnd),context);
+  if(productionApi) {
+    // Keep api/onConnection/setOnline intact: defer fetch itself, not api(), so
+    // rejection classification and the real switch/reset notifications run.
+    context.fetch=(path,opts)=>{
+      if(path==='/api/host')return host.promise.then(data=>({ok:true,status:200,json:async()=>data}));
+      const request=deferred();request.path=path;request.opts=opts;requests.push(request);return request.promise;
+    };
+    Object.assign(context,{renderPill(){},renderConnDlg(){},renderBanner(){},viaText(){},netLabel(){},
+      resetShots(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
+    vm.runInContext(`const UI_KEY = 'test-only';
+      const link = {s:null,device:'frame-a',phase:'connected',rev:0,net:null};
+      const disp = {}, gm = {seq:0}, cat = {}, wi = {};
+      let viewGen = 0, lastImg = null, lastShot = null, androidApps = [], titlesSeq = 0, page = 'control';`,context);
+    const apiStart=pageSource.indexOf('const HEADSET_FREE ='),apiEnd=pageSource.indexOf('// What a panel shows',apiStart);
+    const onlineStart=pageSource.indexOf('function setOnline('),onlineEnd=pageSource.indexOf('function reloadAll()',onlineStart);
+    const connectionStart=pageSource.indexOf('function onConnection('),connectionEnd=pageSource.indexOf('// Read the event stream',connectionStart);
+    vm.runInContext(pageSource.slice(apiStart,apiEnd)+pageSource.slice(onlineStart,onlineEnd)+pageSource.slice(connectionStart,connectionEnd),context);
+  }
+  const installStart=pageSource.indexOf('function installFlatpak(id) {'),installEnd=pageSource.indexOf('$("fpInstall").onclick',installStart);
+  vm.runInContext(pageSource.slice(installStart,installEnd),context);
+  const hostStart=pageSource.lastIndexOf('api("/api/host").then(h =>'),hostEnd=pageSource.indexOf('</script>',hostStart);
+  vm.runInContext(pageSource.slice(hostStart,hostEnd),context);
+  const bootstrapStart=pageSource.indexOf('window.frameControlCenter = FrameControlCenter.mount('),bootstrapEnd=pageSource.indexOf('</script>',bootstrapStart);
+  return {...f,context,requests,writes,host,refresh:()=>vm.runInContext('refresh()',context),
+    switchHeadset:()=>vm.runInContext('onConnection({now:Date.now()/1000,phase:"connected",devices_rev:0,device:{id:"frame-b",name:"Second Frame"}})',context),
+    installFlatpak:()=>vm.runInContext('installFlatpak("test.app")',context),
+    mount(){vm.runInContext(pageSource.slice(bootstrapStart,bootstrapEnd),context);return context.window.frameControlCenter;}};
+}
+const response = data => ({ok:true,status:200,json:async()=>data});
+for(const rejection of ['transport','body'])for(const delayedMount of [false,true]) {
+  test(`production ${rejection} rejection from A preserves B ${delayedMount ? 'before delayed mount' : 'after mount'}`, async t => {
+    const f=sharedPage({productionApi:true});
+    if(!delayedMount){const ui=f.mount();t.after(()=>ui.destroy());}
+    const old=f.refresh(),body=deferred();
+    assert.equal(f.requests[0].path,'/api/status');
+    if(rejection==='body') {
+      f.requests[0].resolve({ok:true,status:200,json:()=>body.promise});await flush();
+    }
+    f.switchHeadset();
+    assert.equal(f.requests.length,2,'real connected B callback starts its own status fetch');
+    const next=sample();next.hostname='Second Frame';next.battery.percent=20;next.volume.level=.2;
+    f.requests[1].resolve(response(next));await flush();
+    const receipt=vm.runInContext('stateReceivedAt',f.context);
+    assert.equal(vm.runInContext('stateRead.valid && online && devGen === 2',f.context),true);
+    if(!delayedMount)assert.equal(f.element('metric-battery').textContent,'20%');
+    (rejection==='body' ? body : f.requests[0]).reject(Error('Old A request failed'));await old;
+    assert.equal(vm.runInContext('stateRead.valid',f.context),true,'A must not invalidate B');
+    assert.equal(vm.runInContext('stateRead.error',f.context),null);
+    assert.equal(vm.runInContext('stateReceivedAt',f.context),receipt);
+    if(delayedMount){const ui=f.mount();t.after(()=>ui.destroy());}
+    const assertB=()=>{
+      assert.equal(f.element('ccDeviceName').textContent,'Second Frame');
+      assert.equal(f.element('metric-battery').textContent,'20%');
+      assert.equal(f.element('ccVolume').value,20);
+      for(const id of ['ccVolume','ccApplyVolume','ccMute'])assert.equal(f.element(id).disabled,false);
+      assert.doesNotMatch(f.element('ccSampleState').textContent,/No live sample|local server|Old A/);
+    };
+    assertB();vm.runInContext('render(state)',f.context);assertB();
+    assert.equal(f.requests.length,2,'preservation and redraw need no recovery poll');
+    // An ordinary failure on B must still invalidate the current sample.
+    const failed=f.refresh();
+    if(rejection==='body')f.requests[2].resolve({ok:true,status:200,json:async()=>{throw Error('B body failed');}});
+    else f.requests[2].reject(Error('B transport failed'));
+    await failed;
+    assert.equal(vm.runInContext('stateRead.valid',f.context),false);
+    assert.equal(f.element('metric-battery').textContent,'Unavailable');
+    for(const id of ['ccVolume','ccApplyVolume','ccMute'])assert.equal(f.element(id).disabled,true);
+    assert.equal(f.element('ccStatusLabel').textContent,'No live sample');
+  });
+}
+test('production headset-free API keeps transport errors and responses across a switch', async t => {
+  for(const failure of [false,true]) {
+    const f=sharedPage({productionApi:true}),ui=f.mount();t.after(()=>ui.destroy());
+    const pending=vm.runInContext('api("/api/devices")',f.context);
+    const result=pending.then(value=>({value}),error=>({error}));
+    f.switchHeadset();f.requests[1].resolve(response(sample()));await flush();
+    if(failure)f.requests[0].reject(Error('Device list transport failed'));
+    else f.requests[0].resolve(response({devices:['frame-b']}));
+    const settled=await result;
+    if(failure){assert.equal(settled.error.stale,undefined);assert.match(settled.error.message,/local server isn't running/);}
+    else assert.deepEqual(settled.value,{devices:['frame-b']});
+    assert.equal(vm.runInContext('stateRead.valid',f.context),true);
+  }
+});
+test('search finds settings by aliases, all words, category and guidance', () => {
+  const find = (q,category='all')=>cc.catalog.filter(item=>cc.matches(item,q,category)).map(item=>item.id);
+  assert.ok(find('DPI').includes('display'));
+  assert.ok(find('sleep inactivity').includes('power'));
+  assert.ok(find('MOTION SICKNESS').includes('playspace'));
+  assert.ok(find('font','apps').includes('display'));
+  assert.deepEqual(find('font','vr'),[]);
+  assert.deepEqual(find('<script>alert(1)</script>'),[]);
+  assert.ok(find('   ').length > 20);
+});
+test('metrics use real fields, preserve zero, and distinguish unavailable values', () => {
+  const m = cc.metrics(sample());
+  assert.equal(m.battery,'99%');
+  assert.equal(m.power,'0 W');
+  assert.match(m.batteryDetail,/not charging/);
+  assert.equal(m.fps,'90'); assert.equal(m.appFps,'45');
+  assert.equal(m.storage,'128 GiB'); assert.equal(m.memory,'10 GiB');
+  assert.equal(m.thermal,'No hot / critical trip reported');
+  assert.equal(cc.metrics(null).fps,'Unavailable');
+  assert.equal(cc.metrics({performance:{appFps:null,gpuMHz:0,cpuPercent:0}}).appFps,'Unavailable');
+  assert.equal(cc.metrics({performance:{cpuPercent:0}}).cpu,'0%');
+  assert.equal(cc.metrics({battery:{percent:0,status:'Discharging'}}).battery,'0%');
+  assert.match(cc.metrics({thermalAlerts:[{zone:'battery',tempC:45,limitC:44}]}).thermal,/battery 45 °C ≥ 44 °C/);
+});
+test('audio controller validates before any API call and rejects offline or expired readings', async () => {
+  let context={online:true,fresh:true,sample:sample(),device:'frame-a',generation:1},calls=[];
+  const controller=cc.createController({api:async(...args)=>{calls.push(args);return {};},getContext:()=>context});
+  for (const change of [{level:-.1},{level:1.1},{level:NaN},{level:Infinity},{level:'0.5'},{level:null},{muted:'false'},{unknown:true},{}]) {
+    await assert.rejects(controller.audio(change),/valid mute state/);
+  }
+  context.online=false;await assert.rejects(controller.audio({level:.5}),/Connect and refresh/);
+  context.online=true;context.fresh=false;await assert.rejects(controller.audio({muted:true}),/Connect and refresh/);
+  assert.equal(calls.length,0);
+});
+test('audio uses the captured device, prevents duplicate writes, and ignores switched-headset success', async () => {
+  let context={online:true,fresh:true,sample:sample(),device:'frame-a',generation:1},complete,calls=[];
+  const controller=cc.createController({api:(...args)=>{calls.push(args);return new Promise(r=>complete=r);},getContext:()=>context});
+  const pending=controller.audio({level:.7});
+  await assert.rejects(controller.audio({muted:true}),/still in progress/);
+  assert.deepEqual(calls,[['/api/volume',{level:.7},'frame-a']]);
+  context={...context,device:'frame-b',generation:2};complete({message:'Done'});
+  assert.equal(await pending,null);assert.equal(controller.busy,false);
+});
+test('controller surfaces real API errors and allows a deliberate retry', async () => {
+  let calls=0;
+  const controller=cc.createController({api:async()=>{if(++calls===1)throw Error('SSH connection lost');return {message:'Done'};},
+    getContext:()=>({online:true,fresh:true,sample:sample(),device:'frame-a',generation:1})});
+  await assert.rejects(controller.audio({muted:true}),/SSH connection lost/);
+  assert.equal(controller.busy,false);
+  assert.deepEqual(await controller.audio({muted:true}),{message:'Done'});
+});
+test('mounted controls only write on Apply or Mute, show readback, and reset on switch', async t => {
+  const f=mounted();t.after(()=>f.ui.destroy());
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  f.ui.status(sample());
+  assert.equal(f.element('ccApplyVolume').disabled,false);
+  assert.equal(f.element('ccVolume').value,40);
+  f.element('ccVolume').value='65';f.element('ccVolume').oninput();
+  assert.equal(f.calls.length,0);
+  assert.equal(f.element('ccVolumeValue').textContent,'65%');
+  f.ui.status(sample()); // a poll must not overwrite an unapplied value
+  assert.equal(f.element('ccVolume').value,'65');
+  await f.element('ccApplyVolume').onclick();
+  assert.deepEqual(f.calls,[['/api/volume',{level:.65},'frame-a']]);
+  assert.equal(f.refreshes,1);
+  await f.element('ccMute').onclick();
+  assert.deepEqual(f.calls[1],['/api/volume',{muted:true},'frame-a']);
+  f.context={online:null,generation:2,device:'frame-b'};f.ui.reset();
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  assert.equal(f.element('metric-battery').textContent,'Unavailable');
+  assert.equal(f.element('ccAudioResult').textContent,'');
+});
+test('offline/errors clear live readings, disable audio and keep companion navigation usable', async t => {
+  const f=mounted();t.after(()=>f.ui.destroy());f.ui.status(sample());
+  f.context.online=false;f.ui.connection(false);
+  assert.equal(f.element('metric-fps').textContent,'Unavailable');
+  assert.equal(f.element('ccVolume').disabled,true);
+  await f.element('ccMute').onclick();
+  assert.equal(f.calls.length,0);
+  assert.match(f.element('ccAudioResult').textContent,/Connect and refresh/);
+  assert.equal(f.cards.find(c=>c.dataset.ccCard==='privacy').hidden,false);
+  f.ui.unavailable(Error('Local server is unavailable'));
+  assert.match(f.element('ccSampleState').textContent,/Local server is unavailable/);
+  f.context.online=true;f.ui.status(sample());
+  assert.equal(f.element('ccVolume').disabled,false);
+});
+test('mounted audio failure is visible and never reports success', async t => {
+  const f=mounted({api:async()=>{throw Error('Permission denied');}});t.after(()=>f.ui.destroy());f.ui.status(sample());
+  await f.element('ccApplyVolume').onclick();
+  assert.match(f.element('ccAudioResult').textContent,/Couldn’t apply audio: Permission denied/);
+  assert.equal(f.element('ccApplyVolume').disabled,false);
+  assert.equal(f.refreshes,0);
+});
+test('audio confirmation depends on fresh readback rather than command acknowledgment', async t => {
+  let expected=.65, mode='confirmed';
+  const f=mounted({refresh:async()=>{
+    if(mode==='offline')return f.ui.unavailable(Error('Headset unreachable'));
+    const reading=sample();reading.volume.level=mode==='different' ? .64 : expected;f.ui.status(reading);
+  }});t.after(()=>f.ui.destroy());f.ui.status(sample());
+  f.element('ccVolume').value='65';await f.element('ccApplyVolume').onclick();
+  assert.match(f.element('ccAudioResult').textContent,/Confirmed: 65%, unmuted/);
+  mode='different';f.element('ccVolume').value='65';await f.element('ccApplyVolume').onclick();
+  assert.match(f.element('ccAudioResult').textContent,/reported output differs: 64%/);
+  mode='offline';await f.element('ccApplyVolume').onclick();
+  assert.match(f.element('ccAudioResult').textContent,/command sent; current output could not be confirmed/);
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+});
+test('pending audio never overwrites the new headset with old success or error', async t => {
+  let complete;
+  const f=mounted({api:()=>new Promise(resolve=>{complete=resolve;})});t.after(()=>f.ui.destroy());f.ui.status(sample());
+  const pending=f.element('ccMute').onclick();
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  f.context={online:true,generation:2,device:'frame-b'};f.ui.reset();
+  const newSample=sample();newSample.hostname='Second Frame';newSample.volume.muted=true;f.ui.status(newSample);
+  complete({message:'Old headset muted'});await pending;
+  assert.equal(f.element('ccDeviceName').textContent,'Second Frame');
+  assert.equal(f.element('ccAudioResult').textContent,'');
+  assert.equal(f.refreshes,0);
+  assert.equal(f.element('ccMute').textContent,'Unmute');
+  f.ui.unavailable({stale:true,message:'Switched headsets'});
+  assert.equal(f.element('metric-battery').textContent,'99%');
+  assert.equal(f.element('ccMute').disabled,false);
+});
+test('pending old-headset volume cannot become a draft on the new headset', async t => {
+  for(const failure of [false,true]) {
+    const request=deferred(),f=mounted({api:()=>request.promise});t.after(()=>f.ui.destroy());
+    f.ui.status(sample());f.element('ccVolume').value='65';f.element('ccVolume').oninput();
+    const pending=f.element('ccApplyVolume').onclick();
+    f.context={online:true,generation:2,device:'frame-b'};f.ui.reset();
+    const next=sample();next.volume.level=.2;f.ui.status(next);
+    assert.equal(f.element('ccApplyVolume').disabled,true);
+    if(failure)request.reject(Error('Old headset failed'));else request.resolve({message:'Done'});
+    await pending;
+    assert.equal(f.element('ccVolume').value,20);
+    assert.equal(f.element('ccVolumeValue').textContent,'20%');
+    assert.equal(f.element('ccAudioReadback').textContent,'Reported 20% · unmuted');
+    assert.equal(f.element('ccApplyVolume').disabled,false);
+    assert.equal(f.element('ccAudioResult').textContent,'');
+  }
+});
+test('production host response works before and after mounting with the actual bridge shape', async t => {
+  for(const early of [true,false]) {
+    const f=sharedPage();let ui;
+    if(!early){ui=f.mount();t.after(()=>ui.destroy());assert.equal(f.element('macLink').hidden,true);}
+    f.host.resolve({os:'macOS',mobile:false});await flush();
+    if(early){ui=f.mount();t.after(()=>ui.destroy());}
+    assert.equal(f.context.watched,true);
+    assert.equal(f.element('macLink').hidden,false);
+    f.element('ccSearch').value='mac';f.element('ccSearch').input();
+    assert.equal(f.element('macLink').hidden,false);
+    ui.host({os:'SteamOS',mobile:true});assert.equal(f.element('macLink').hidden,true);
+  }
+});
+test('production shared refresh drains a pre-command request then samples after acknowledgment', async t => {
+  const f=sharedPage(),ui=f.mount();t.after(()=>ui.destroy());ui.status(sample());
+  const prior=f.refresh();assert.equal(f.requests.length,1);
+  assert.equal(f.refresh(),prior); // the ordinary poll/manual deduplication still holds
+  f.element('ccVolume').value='65';f.element('ccVolume').oninput();
+  const command=f.element('ccApplyVolume').onclick();await flush();
+  assert.equal(f.writes.length,1);assert.equal(f.requests.length,1);
+  f.requests[0].resolve(sample());await prior;await flush();
+  assert.equal(f.requests.length,2,'readback must issue a real post-command status request');
+  assert.doesNotMatch(f.element('ccAudioResult').textContent,/Confirmed|reported output differs/);
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  const after=sample();after.volume.level=.65;f.requests[1].resolve(after);await command;
+  assert.match(f.element('ccAudioResult').textContent,/Confirmed: 65%, unmuted/);
+  assert.equal(f.element('ccApplyVolume').disabled,false);
+});
+test('production audio readback survives an old poll failure and treats its own failed read as unconfirmed', async t => {
+  for(const failedReadback of [false,true]) {
+    const f=sharedPage(),ui=f.mount();t.after(()=>ui.destroy());ui.status(sample());
+    const prior=f.refresh();f.element('ccVolume').value='65';f.element('ccVolume').oninput();
+    const command=f.element('ccApplyVolume').onclick();await flush();
+    f.requests[0].reject(Error('Pre-command poll failed'));await prior;await flush();
+    assert.equal(f.requests.length,2);
+    assert.equal(f.element('ccApplyVolume').disabled,true);
+    if(failedReadback)f.requests[1].reject(Error('Readback unavailable'));
+    else {const after=sample();after.volume.level=.64;f.requests[1].resolve(after);}
+    await command;
+    assert.match(f.element('ccAudioResult').textContent,failedReadback ? /command sent; current output could not be confirmed/ : /reported output differs: 64%/);
+    assert.equal(f.element('ccApplyVolume').disabled,failedReadback);
+  }
+});
+test('production Flatpak redraw cannot revive a failed status; only a fresh successful poll recovers', async t => {
+  const f=sharedPage(),ui=f.mount();t.after(()=>ui.destroy());
+  const first=f.refresh(),reading=sample();f.requests[0].resolve(reading);await first;
+  const receipt=vm.runInContext('stateReceivedAt',f.context);
+  assert.equal(f.element('ccApplyVolume').disabled,false);
+  const failed=f.refresh();f.requests[1].reject(Error('Synthetic status parsing error'));await failed;
+  assert.equal(f.element('metric-battery').textContent,'Unavailable');
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  f.installFlatpak(); // actual production render(state), with job held pending
+  assert.equal(f.requests.length,2,'redraw must not start a replacement reading');
+  assert.equal(vm.runInContext('stateReceivedAt',f.context),receipt);
+  assert.equal(f.element('metric-battery').textContent,'Unavailable');
+  assert.equal(f.element('ccStatusLabel').textContent,'No live sample');
+  assert.match(f.element('ccSampleState').textContent,/Synthetic status parsing error/);
+  for(const id of ['ccVolume','ccApplyVolume','ccMute'])assert.equal(f.element(id).disabled,true);
+  const fresh=f.refresh();
+  assert.equal(f.element('ccApplyVolume').disabled,true,'starting a poll does not clear failure');
+  const next=sample();next.battery.percent=98;next.volume.level=.2;
+  f.requests[2].resolve(next);await fresh;
+  assert.equal(f.element('metric-battery').textContent,'98%');
+  assert.equal(f.element('ccVolume').value,20);
+  assert.equal(f.element('ccApplyVolume').disabled,false);
+  assert.doesNotMatch(f.element('ccSampleState').textContent,/Synthetic status parsing error/);
+});
+test('delayed production bootstrap retains failed-read state and fresh-poll recovery', async t => {
+  for(const priorSuccess of [true,false]) {
+    const f=sharedPage();
+    if(priorSuccess){const first=f.refresh();f.requests[0].resolve(sample());await first;}
+    const failed=f.refresh();f.requests.at(-1).reject(Error('Status failed before mount'));await failed;
+    const calls=f.requests.length,ui=f.mount();t.after(()=>ui.destroy());
+    assert.equal(f.requests.length,calls);
+    assert.equal(f.element('metric-battery').textContent,'Unavailable');
+    assert.equal(f.element('ccStatusLabel').textContent,'No live sample');
+    assert.match(f.element('ccSampleState').textContent,/Status failed before mount/);
+    for(const id of ['ccVolume','ccApplyVolume','ccMute'])assert.equal(f.element(id).disabled,true);
+    const fresh=f.refresh();assert.equal(f.element('ccApplyVolume').disabled,true);
+    f.requests.at(-1).resolve(sample());await fresh;
+    assert.equal(f.element('metric-battery').textContent,'99%');
+    assert.equal(f.element('ccApplyVolume').disabled,false);
+    assert.doesNotMatch(f.element('ccSampleState').textContent,/Status failed before mount/);
+  }
+});
+test('same-object replay preserves invalidation and receipt age after a failed reading', t => {
+  const f=mounted();t.after(()=>f.ui.destroy());const reading=sample();
+  f.ui.status(reading);f.ui.unavailable(Error('Status failure'));
+  f.ui.status(reading,Date.now()+1000);
+  assert.equal(f.element('metric-battery').textContent,'Unavailable');
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  assert.match(f.element('ccSampleState').textContent,/Status failure/);
+  f.ui.status(sample());assert.equal(f.element('ccApplyVolume').disabled,false);
+});
+test('delayed production bootstrap preserves client receipt age despite headset clock skew', async t => {
+  const original=Date.now;let now=1000000;Date.now=()=>now;t.after(()=>{Date.now=original;});
+  const f=sharedPage(),prior=f.refresh();const reading=sample();reading.time-=3600;
+  f.requests[0].resolve(reading);await prior;
+  now+=91000;const ui=f.mount();t.after(()=>ui.destroy());
+  assert.equal(f.element('metric-battery').textContent,'Unavailable');
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  assert.match(f.element('ccSampleState').textContent,/expired/);
+  const fresh=f.refresh();f.requests[1].resolve(sample());await fresh;
+  assert.equal(f.element('ccApplyVolume').disabled,false);
+  assert.equal(f.element('metric-battery').textContent,'99%');
+});
+test('sample replay cannot renew receipt age; fresh receipts tolerate missing or skewed headset time', t => {
+  const original=Date.now;let now=1000000;Date.now=()=>now;t.after(()=>{Date.now=original;});
+  const f=mounted();t.after(()=>f.ui.destroy());const reading=sample();f.ui.status(reading);
+  now+=91000;f.ui.status(reading);
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+  assert.equal(f.element('metric-battery').textContent,'Unavailable');
+  for(const time of [undefined,null,'invalid',NaN,Infinity,now/1000-3600,now/1000+3600]) {
+    f.ui.status({...sample(),time});
+    assert.equal(f.element('ccApplyVolume').disabled,false);
+    assert.doesNotMatch(f.element('ccSampleState').textContent,/Invalid Date/);
+  }
+  for(const receipt of [null,NaN,Infinity,now+1000,now-91000]) {
+    f.ui.status(sample(),receipt);assert.equal(f.element('ccApplyVolume').disabled,true);
+  }
+});
+test('mute-only readback preserves an unapplied volume until Apply sends it', async t => {
+  let reading=sample();const f=mounted({api:async(path,change,device)=>{
+    f.calls.push([path,change,device]);reading={...reading,volume:{...reading.volume,...change}};return {message:'Done'};
+  },refresh:async()=>f.ui.status({...reading})});t.after(()=>f.ui.destroy());f.ui.status(reading);
+  f.element('ccVolume').value='65';f.element('ccVolume').oninput();
+  await f.element('ccMute').onclick();
+  assert.deepEqual(f.calls[0],['/api/volume',{muted:true},'frame-a']);
+  assert.equal(f.element('ccVolume').value,'65');assert.equal(f.element('ccVolumeValue').textContent,'65%');
+  assert.match(f.element('ccAudioReadback').textContent,/Reported 40% · muted/);
+  assert.match(f.element('ccAudioResult').textContent,/Confirmed: 40%, muted/);
+  await f.element('ccApplyVolume').onclick();
+  assert.deepEqual(f.calls[1],['/api/volume',{level:.65},'frame-a']);
+  assert.equal(f.element('ccVolume').value,65);
+  assert.match(f.element('ccAudioResult').textContent,/Confirmed: 65%, muted/);
+});
+test('live samples expire even when the status poll is paused', t => {
+  const original=Date.now;let now=100000;Date.now=()=>now;t.after(()=>{Date.now=original;});
+  const f=mounted();t.after(()=>f.ui.destroy());f.ui.status(sample());
+  now+=91000;
+  // A connection update must also re-check freshness before enabling a control.
+  f.ui.connection(true);
+  assert.equal(f.element('ccApplyVolume').disabled,true);
+});
+test('mounted filters show empty state, counts, reset and host-dependent features', t => {
+  const f=mounted();t.after(()=>f.ui.destroy());
+  f.element('ccSearch').value='dpi';f.element('ccSearch').input();
+  assert.equal(f.cards.find(c=>c.dataset.ccCard==='display').hidden,false);
+  assert.equal(f.element('ccResultCount').textContent,'1 section');
+  f.element('ccSearch').value='nothing-matches-this';f.element('ccSearch').input();
+  assert.equal(f.element('ccEmpty').hidden,false);
+  f.element('ccResetFilter').onclick();assert.equal(f.element('ccEmpty').hidden,true);
+  f.ui.host({os:'Windows'});assert.equal(f.element('macLink').hidden,true);
+  assert.equal(f.cards.find(c=>c.dataset.ccCard==='mac').hidden,false);
+  f.ui.host({os:'macOS'});assert.equal(f.element('macLink').hidden,false);
+  f.ui.host({os:'SteamOS',mobile:true});assert.equal(f.element('macLink').hidden,true);
+  f.element('connectionLink').onclick({preventDefault(){}});assert.equal(f.opened,1);
+});
+test('every linked workflow selects its real page and section, preserving shortcuts', () => {
+  const html=fs.readFileSync(require.resolve('../ui/index.html'),'utf8');
+  const start=html.indexOf('const PAGES ='),end=html.indexOf('window.addEventListener("hashchange", showPage);',start);
+  const ids=new Set([...html.matchAll(/\bid="([^"]+)"/g)].map(m=>m[1]));
+  let activePage,scrolled;
+  const nodes=['home','games','android','tools','devices','control'].map(page=>({dataset:{page},classList:{toggle(key,on){if(on)activePage=page;}}}));
+  const sections=new Map();
+  const context={location:{hash:'#control'},document:{querySelectorAll:s=>s==='.page'?nodes:[],title:''},
+    window:{scrollTo(){}},$:id=>{
+      if(!ids.has(id))return null;
+      if(!sections.has(id))sections.set(id,{hidden:false,scrollIntoView(){scrolled=id;}});
+      return sections.get(id);
+    },live:false,toggleLive(){},loadMacView(){},loadPanelSwitcher(){}};
+  const androidStart=html.indexOf('function showAndroidTab(');
+  const androidEnd=html.indexOf("document.querySelectorAll('[data-store-tab]').forEach(button => button.onclick",androidStart);
+  vm.createContext(context);vm.runInContext(html.slice(androidStart,androidEnd)+html.slice(start,end)+'\nPAGES.push("devices", "control");',context);
+  vm.runInContext('showPage()',context);assert.equal(activePage,'control');
+  const expected={view:'home',shots:'home',vrTools:'home',comfort:'home',pad:'home',library:'games',getgames:'games',sideloaded:'games',android:'android',display:'android',androidLibrary:'android',appStore:'android',
+    power:'tools',transfer:'tools',media:'tools',apps:'tools',artworkSettings:'tools',privacy:'tools',panels:'tools',macview:'tools',devices:'devices'};
+  for(const item of cc.catalog) for(const [href] of item.links||[]) {
+    if(!href.startsWith('#')||href==='#connection')continue;
+    const id=href.slice(1);assert.ok(ids.has(id)||['android','devices'].includes(id),href);
+    context.location.hash=href;scrolled=null;vm.runInContext('showPage()',context);
+    assert.equal(activePage,expected[id],href);
+    if(!['android','devices'].includes(id))assert.equal(scrolled,id,href);
+    if(id==='display'||id==='androidLibrary') { assert.equal(sections.get('androidLibrary').hidden,false);assert.equal(sections.get('appStore').hidden,true); }
+    if(id==='appStore') { assert.equal(sections.get('appStore').hidden,false);assert.equal(sections.get('androidLibrary').hidden,true); }
+  }
+  assert.equal(vm.runInContext('PAGES[4]',context),'devices');
+  assert.equal(vm.runInContext('PAGES[5]',context),'control');
+});

tests/e2e/harness.py

@@ -10,6 +10,7 @@ import atexit
 import http.client
 import json
 import os
+import shutil
 import socket
 import subprocess
 import sys
@@ -22,7 +23,22 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[2]
 sys.path[:0] = [str(ROOT / 'ui'), str(ROOT / 'tests'), str(ROOT / 'tests' / 'smoke')]
 
-ENABLED = os.environ.get('FRAME_E2E') == '1'
+# Only inside the compose `host` container (FRAME_E2E_CONTAINER from compose.yaml, plus
+# the container runtime's marker file): these tests drive ui/server.py with the real
+# home, ~/.ssh and cache, which is only safe in a throwaway container.
+REQUESTED = os.environ.get('FRAME_E2E') == '1'
+IN_CONTAINER = os.environ.get('FRAME_E2E_CONTAINER') == '1' and (
+    os.path.exists('/.dockerenv') or os.path.exists('/run/.containerenv'))
+ENABLED = REQUESTED and IN_CONTAINER
+if ENABLED:
+    # What tests/sandbox.py does, minus moving HOME: the container's real ~/.ssh is what
+    # points `ssh frame` at the fake Frame, and OpenSSH reads ~/.ssh from the password
+    # database, not $HOME. (These tests used to get this through test_frame_apk.)
+    _data = tempfile.mkdtemp(prefix='frame-control-e2e-')
+    atexit.register(shutil.rmtree, _data, ignore_errors=True)
+    os.environ['FRAME_CONTROL_DATA_DIR'] = _data
+    os.environ['FRAME_CONTROL_TELEMETRY'] = '0'
+    os.environ['FRAME_COMPAT_DB_URL'] = 'http://127.0.0.1:9'
 CTL = os.environ.get('FAKEFRAME_CTL', 'http://fakeframe:9999').rstrip('/')
 FAKE_HOST = os.environ.get('FAKEFRAME_HOST', 'fakeframe')
 HOME = '/home/steamos'
@@ -30,9 +46,14 @@ SERVER_LOG = os.path.join(tempfile.gettempdir(), 'fakeframe-e2e-server.log')
 
 
 def require():
-    """Call at module level: skips the module unless the fake Frame is up."""
-    if not ENABLED:
-        raise unittest.SkipTest('needs the fake Frame: run scripts/e2e.sh (sets FRAME_E2E=1)')
+    """Skips (the module, at module level; the class, in setUpClass) unless this is
+    scripts/e2e.sh's container with the fake Frame up."""
+    if ENABLED:
+        return
+    if REQUESTED:
+        raise unittest.SkipTest('FRAME_E2E=1 outside the e2e container: these tests use the real home, ~/.ssh '
+                                'and app cache, so they only run in scripts/e2e.sh\'s throwaway container')
+    raise unittest.SkipTest('needs the fake Frame: run scripts/e2e.sh (sets FRAME_E2E=1)')
 
 
 # ---- the fake Frame's control port --------------------------------------------
@@ -97,6 +118,7 @@ class Server:
 
     @classmethod
     def start(cls):
+        require()  # never a server on this computer's real data
         if cls.proc and cls.proc.poll() is None:
             return
         with socket.socket() as s:
@@ -193,6 +215,7 @@ class FrameTestCase(unittest.TestCase):
 
     @classmethod
     def setUpClass(cls):
+        require()
         Server.start()
 
     def setUp(self):

tests/e2e/test_agents.py

@@ -6,6 +6,8 @@ import sys
 import harness
 from harness import api, ok, finished, ssh
 
+harness.require()
+
 sys.path.insert(0, str(harness.ROOT / 'ui'))
 import frame_mcp
 

tests/e2e/test_android.py

@@ -5,7 +5,7 @@ import unittest
 
 import harness
 from harness import HOME, exists, ok, state, upload, wait_for
-from test_frame_apk import apk, manifest, resources
+from apk_fixtures import apk, manifest, resources
 
 harness.require()
 

tests/fakeframe/compose.yaml

@@ -43,6 +43,7 @@ services:
       FAKEFRAME_CTL: http://fakeframe:9999
       FAKEFRAME_HOST: fakeframe
       FRAME_E2E: "1"
+      FRAME_E2E_CONTAINER: "1"  # tests/e2e/harness.py refuses to run anywhere else
     healthcheck:
       test: ["CMD", "test", "-f", "/home/tester/.ready"]
       interval: 1s

tests/fakegh/gh

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""A stand-in for the GitHub CLI's `gh api`, for tests/test_publish_release.py and
+tests/test_release_workflow.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. POST .../releases (release.yml's draft step) answers as release
+$FAKEGH_NEW_ID (default 9001) without adding it to the listing, like GitHub's list
+lagging a fresh draft. With jq installed, --jq filters a response the way gh does
+(raw strings, compact JSON)."""
+import json
+import os
+import shutil
+import subprocess
+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, jq, i = "GET", None, {}, 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 == "--jq":
+        jq = args[i + 1]; i += 2
+    elif a == "-H":
+        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/"
+
+
+def answer(response, fallback):
+    """Print response through --jq when jq is here, else the fixed fallback text."""
+    if jq and shutil.which("jq"):
+        out = subprocess.run(["jq", "-r", "-c", jq], input=json.dumps(response),
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
+        sys.stdout.write(out.stdout)
+        if out.returncode:
+            sys.exit("fakegh: jq failed: " + out.stderr)
+    else:
+        print(fallback)
+
+
+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?"):
+    # The fallback is what --jq '.[]' prints.
+    answer(releases, "\n".join(json.dumps(r) for r in releases))
+elif method == "POST" and endpoint == repo + "releases":
+    new = {"id": int(os.environ.get("FAKEGH_NEW_ID", "9001")), "tag_name": fields.get("tag_name"),
+           "name": fields.get("name"), "draft": fields.get("draft") == "true",
+           "body": fields.get("body"), "assets": [],
+           "html_url": "https://github.com/saphid/frame-control/releases/tag/untagged-be29e900f7855d794136"}
+    answer(new, json.dumps(new))
+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/"):
+    rid = endpoint[len(repo + "releases/"):]
+    if not rid.isdigit():  # what GitHub said to v0.4.2's PATCH of releases/ (an empty id)
+        sys.exit("gh: Not Found (HTTP 404)")
+    page = "https://github.com/saphid/frame-control/releases/tag/%s" % fields.get("tag_name")
+    answer({"id": int(rid), "tag_name": fields.get("tag_name"), "html_url": page},
+           "published %s at %s" % (fields.get("tag_name"), page))
+else:
+    sys.exit("fakegh: unhandled %s %s" % (method, endpoint))

tests/fakessh/ssh

@@ -3,10 +3,20 @@
 each step of a connection, and plays a ControlMaster. What each HostName does comes
 from $FAKESSH_HOSTS (JSON: host -> "ok", "wrong" (a different host key), "denied" or
 "slow" (hangs after connecting);
-every call is appended to $FAKESSH_LOG as a JSON line. POSIX only."""
+every call is appended to $FAKESSH_LOG as a JSON line. POSIX only.
+
+With $FAKESSH_PINS set, host keys are checked as OpenSSH does against UserKnownHostsFile under
+HostKeyAlias: "wrong" is then just a different key from the others' (a reinstalled headset),
+StrictHostKeyChecking=yes refuses a key not saved, accept-new saves a first one, and a saved key
+that differs is refused. "evil" is a device with its own key that lets anyone in without
+authentication ("none") and asks for the agent: it records in $FAKESSH_DIR what it got
+(agent-forwarded, command-ran). Like ssh, the first value of an option counts."""
+import base64
+import hashlib
 import json
 import os
 import signal
+import subprocess
 import sys
 import time
 
@@ -17,12 +27,12 @@ hosts = json.loads(os.environ.get("FAKESSH_HOSTS", "{}"))
 opts = {}
 i = 0
 while i < len(args) and args[i].startswith("-"):
-    if args[i] in ("-o", "-O", "-p", "-l"):
+    if args[i] in ("-o", "-O", "-p", "-l", "-F", "-W"):
         key = args[i]
         val = args[i + 1]
         if key == "-o":
             k, _, v = val.partition("=")
-            opts[k.lower()] = v
+            opts.setdefault(k.lower(), v)
         else:
             opts[key] = val
         i += 2
@@ -30,6 +40,12 @@ while i < len(args) and args[i].startswith("-"):
         opts[args[i]] = True
         i += 1
 alias = args[i] if i < len(args) else ""
+command = args[i + 1:]
+if opts.get("-F") != "none":
+    # $FAKESSH_CONFIG: what ~/.ssh/config says (JSON, lower-case option -> value), below the
+    # command line's options, as ssh has it; `-F none` reads no config.
+    for k, v in json.loads(os.environ.get("FAKESSH_CONFIG", "{}")).items():
+        opts.setdefault(k, v)
 host = opts.get("hostname", alias).replace("%%", "%")
 marker = os.path.join(os.environ["FAKESSH_DIR"], "master-" + host.replace("/", "_"))
 say = lambda s: (sys.stderr.write(s + "\n"), sys.stderr.flush())
@@ -44,6 +60,23 @@ if opts.get("-O") == "exit":
         os.unlink(marker)
     sys.exit(0)
 
+if "-W" in opts:  # a jump host's ssh, forwarding to the headset: the call is logged, that's all
+    sys.exit(0)
+if opts.get("proxycommand", "none") != "none":
+    # As OpenSSH: expand %-tokens, then `$SHELL -c "exec <line>"` (here /bin/sh).
+    line, out, n = opts["proxycommand"], "", 0
+    while n < len(line):
+        if line[n] == "%" and n + 1 < len(line):
+            out += {"%": "%", "h": host, "p": opts.get("port", "22"), "r": opts.get("user", "")}.get(
+                line[n + 1], line[n:n + 2])
+            n += 2
+        else:
+            out += line[n]
+            n += 1
+    if subprocess.run(["/bin/sh", "-c", "exec " + out], stdin=subprocess.DEVNULL,
+                      stdout=subprocess.DEVNULL).returncode:
+        say("kex_exchange_identification: Connection closed by remote host")
+        sys.exit(255)
 what = hosts.get(host)
 if what is None:
     say(f"ssh: Could not resolve hostname {host}: nodename nor servname provided, or not known")
@@ -53,6 +86,66 @@ say("debug1: Connection established.")
 if what == "slow":
     time.sleep(30)
 say(f"debug1: Authenticating to {host}:22 as '{opts.get('user', 'tester')}'")
+if os.environ.get("FAKESSH_PINS") and "hostkeyalias" in opts and "userknownhostsfile" in opts:
+    name, path = opts["hostkeyalias"], os.path.expanduser(opts["userknownhostsfile"])
+    blob = base64.b64encode(b"fake-" + {"wrong": b"other", "evil": b"evil"}.get(what, b"headset") + b"-key").decode()
+    fp = base64.b64encode(hashlib.sha256(base64.b64decode(blob)).digest()).decode().rstrip("=")
+    say(f"debug1: Server host key: ssh-ed25519 SHA256:{fp}")
+    try:
+        saved = [ln.split() for ln in open(path, errors="replace").read().splitlines() if ln.strip()]
+    except OSError:
+        saved = []
+    saved = [f[2] for f in saved if len(f) >= 3 and name in f[0].split(",")]
+    strict = opts.get("stricthostkeychecking", "ask")
+    if saved and blob not in saved:
+        say("@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@")
+        say("@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @")
+        say("Host key verification failed.")
+        sys.exit(255)
+    if not saved and strict != "accept-new":
+        say(f"No ED25519 host key is known for {name} and you have requested strict checking.")
+        say("Host key verification failed.")
+        sys.exit(255)
+    if not saved:
+        try:
+            with open(path, "a") as f:
+                f.write(f"{name} ssh-ed25519 {blob}\n")
+            say(f"Warning: Permanently added '{name}' (ED25519) to the list of known hosts.")
+        except OSError:  # ssh doesn't create the folder: it goes on, saving nothing
+            say(f"Failed to add the host to the list of known hosts ({path}).")
+    else:
+        say(f"debug1: Host '{name}' is known and matches the ED25519 host key.")
+    say("debug1: Next authentication method: publickey")
+    if what == "evil":
+        say(f'Authenticated to {host} ([127.0.0.1]:22) using "none".')
+        got = os.path.join(os.environ["FAKESSH_DIR"], "evil-")
+        if opts.get("forwardagent", "no") != "no" and opts.get("identityagent", "") != "none":
+            open(got + "agent-forwarded", "w").close()
+        if "-N" not in opts and (command or opts.get("remotecommand", "none") != "none"):
+            open(got + "command-ran", "w").close()
+            sys.exit(0)
+        time.sleep(30)  # -N: holds the session open
+        sys.exit(0)
+    if opts.get("preferredauthentications") == "none":
+        say(f"tester@{host}: Permission denied (publickey,password).")
+        sys.exit(255)
+    if what == "denied":
+        say(f"tester@{host}: Permission denied (publickey).")
+        sys.exit(255)
+    what = "ok"
+    say(f'Authenticated to {host} ([127.0.0.1]:22) using "publickey".')
+    if opts.get("controlmaster") != "yes":
+        sys.exit(0)
+    open(marker, "w").close()
+    def bye(*_):
+        if os.path.exists(marker):
+            os.unlink(marker)
+        sys.exit(0)
+    signal.signal(signal.SIGTERM, bye)
+    while True:
+        time.sleep(0.2)
+        if not os.path.exists(marker):
+            sys.exit(0)
 say("debug1: Server host key: ssh-ed25519 SHA256:fakefakefakefakefakefakefakefakefakefakefak")
 if what == "wrong":
     say("@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@")

tests/page/desk_panels.mjs

@@ -0,0 +1,82 @@
+// The live view's Desktop panel list (#73), run in node against the real functions from
+// ui/index.html with a fake server: the headset's reason when it lists no panels, a failed
+// listing shown (first time too) rather than "Finding…", and recovery after it.
+import { readFileSync } from "fs";
+const src = readFileSync(new URL("../../ui/index.html", import.meta.url), "utf8");
+const grab = name => {
+  const m = src.match(new RegExp(`(?:\\nconst ${name} = [^\\n]*\\n)|((?:async )?function ${name}\\([\\s\\S]*?\\n}\\n)`));
+  if (!m) throw new Error("not found: " + name);
+  return m[0];
+};
+// The page's scripts share one global scope, so a second loadPanels would silently replace
+// the Desktop view's (what broke #73 until #84): the one grabbed here must be the only one.
+for (const name of ["loadPanels", "noPanelWhy", "deskPanel", "ctrlTarget"]) {
+  const count = (src.match(new RegExp(`\\n(?:async )?function ${name}\\(`, "g")) || []).length;
+  if (count !== 1) { console.log(`FAIL ${name} is defined ${count} times`); process.exit(1); }
+}
+const code = ["desk", "panelKey", "noPanelWhy", "deskPanel", "loadPanels", "ctrlTarget"].map(grab).join("");
+const fail = msg => { console.log("FAIL " + msg); process.exit(1); };
+
+function page(answer) {
+  const calls = [], logged = [];
+  const env = {
+    view: "flat", live: false, ctrlMode: () => "abs", renderPanelPick: () => {}, toggleLive: () => {}, ctrlShow: () => {},
+    log: (m) => logged.push(m),
+    api: async (path, body) => { calls.push([path, body]); return answer(); },
+  };
+  const fns = new Function(...Object.keys(env), `${code}
+    return { desk, noPanelWhy, loadPanels, ctrlTarget };`)(...Object.values(env));
+  return { ...fns, calls, logged };
+}
+
+// The Desktop view asks for the headset's panels with a plain GET (no switcher action).
+{
+  const p = page(() => ({ panels: [], focus: null, why: "The headset's desktop is running, but SteamOS isn't listing it as a panel." }));
+  if (p.ctrlTarget().why !== "Finding the headset's panels…") fail("before loading: " + p.ctrlTarget().why);
+  await p.loadPanels();
+  if (!(p.calls.length === 1 && p.calls[0][0] === "/api/panels" && p.calls[0][1] === undefined))
+    fail("request " + JSON.stringify(p.calls));
+  if (!p.desk.loaded) fail("not marked loaded");
+  if (!p.noPanelWhy().startsWith("The headset's desktop is running")) fail("why for capture: " + p.noPanelWhy());
+  if (!p.ctrlTarget().why.startsWith("The headset's desktop is running")) fail("why for control: " + p.ctrlTarget().why);
+}
+// An older headset script without "why": the generic advice.
+{
+  const p = page(() => ({ panels: [], focus: null }));
+  await p.loadPanels();
+  if (!p.noPanelWhy().startsWith("No app panel is open in the headset. Open the desktop")) fail("generic: " + p.noPanelWhy());
+}
+// The first listing fails: Control and Capture say so (logged once), then recover.
+{
+  let broken = true;
+  const p = page(() => {
+    if (broken) throw new Error("Timed out talking to frame");
+    return { panels: [{ window: 7, display: ":0", name: "Desktop" }], focus: 7, focus_display: ":0" };
+  });
+  await p.loadPanels(); await p.loadPanels();
+  const why = p.ctrlTarget().why;
+  if (why !== "Couldn't list the headset's panels: Timed out talking to frame") fail("initial failure in Control: " + why);
+  if (p.noPanelWhy() !== why) fail("initial failure in Capture: " + p.noPanelWhy());
+  if (p.logged.length !== 1) fail("logged " + p.logged.length + " times");
+  broken = false;
+  await p.loadPanels();
+  if (p.desk.error) fail("error kept after recovery");
+  const t = p.ctrlTarget();
+  if (!t.why || t.why.includes("Couldn't list")) fail("after recovery: " + JSON.stringify(t));
+  if (p.desk.panels.length !== 1) fail("panels after recovery");
+}
+// Waiting for the Frame: shown in Control, not logged every poll. An answer about the
+// previous headset (stale) is ignored.
+{
+  let err;
+  const p = page(() => { throw err; });
+  err = Object.assign(new Error("Can't reach the Frame"), { offline: true });
+  await p.loadPanels(); await p.loadPanels();
+  if (p.logged.length) fail("offline logged: " + p.logged);
+  if (p.ctrlTarget().why !== "Couldn't list the headset's panels: Can't reach the Frame") fail("offline: " + p.ctrlTarget().why);
+  const q = page(() => { throw Object.assign(new Error("old headset"), { offline: true, stale: true }); });
+  await q.loadPanels();
+  if (q.logged.length || q.desk.error) fail("stale answer used: " + q.desk.error);
+  if (q.ctrlTarget().why !== "Finding the headset's panels…") fail("stale: " + q.ctrlTarget().why);
+}
+console.log("ok");

tests/page/store_detail.mjs

@@ -0,0 +1,93 @@
+// The Android store's app page, run in node against the real functions from ui/index.html.
+// Issue #68: clicking an app opened an empty dialog (a bare horizontal line), because the
+// Devices page's renderDetail replaced the store's. The store's is renderAppDetail now.
+// (tests/test_server.py PageScripts checks no top-level name is declared twice.)
+import { readFileSync } from "fs";
+const src = readFileSync(new URL("../../ui/index.html", import.meta.url), "utf8");
+const lines = src.split("\n");
+const fail = msg => { console.log("FAIL " + msg); process.exit(1); };
+
+// A top-level declaration, from its first line to where its braces balance.
+function grab(name) {
+  const start = lines.findIndex(l => new RegExp(`^(?:(?:async )?function ${name}\\(|const ${name} = )`).test(l));
+  if (start < 0) fail(`no top-level ${name} in index.html`);
+  let depth = 0;
+  for (let i = start; i < lines.length; i++) {
+    for (const c of lines[i]) depth += c === "{" ? 1 : c === "}" ? -1 : 0;
+    if (depth <= 0) return lines.slice(start, i + 1).join("\n") + "\n";
+  }
+  fail(`unbalanced ${name}`);
+}
+const names = ["esc", "storeName", "storeHue", "storeInitial", "storeText", "storeOpenSource", "sourcePage", "storeImage",
+               "storeArt", "storeIcon", "sourceMark", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
+               "updateInstall", "openStoreApp", "loadOfferDetails"];
+const code = names.map(grab).join("");
+
+// A fake page: elements by id. The install panel's elements exist only while
+// #detailBody holds the real app page, as in the browser.
+function page(api = async () => ({})) {
+  const els = { appDetail: { open: false, scrollTop: 0, showModal() { this.open = true; } } };
+  const inPage = id => ["detailInstall", "detailInstallNote", "detailProgress", "detailOffers"].includes(id);
+  const $ = id => inPage(id) && !(els.detailBody?.innerHTML || "").includes(`id="${id}"`) ? null
+    : (els[id] ||= { innerHTML: "", textContent: "", hidden: false, value: 0, removeAttribute() {}, querySelectorAll: () => [] });
+  const sourceState = { apps: [], detail: null, detailRequest: 0, jobs: new Map() };
+  const document = { activeElement: null, querySelector: () => null };
+  const console = { error() {} };
+  const calls = [];
+  const fns = new Function("$", "sourceState", "document", "console", "api", code + "; return { renderAppDetail, openStoreApp };")(
+    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); });
+  return { els, sourceState, calls, ...fns };
+}
+
+const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid", name: "Open Brush", summary: "Paint in VR",
+                description: "Paint in 3D.", version: "2.1", version_code: 21, package: "org.example.brush",
+                artwork: { icon: "/source-image/abc", screenshots: [] }, downloadable: true, verdict: { tone: "works", label: "Works" } };
+
+// An app from the catalogue: its page renders, with its name, install and sources.
+{
+  const p = page();
+  p.sourceState.detail = { app: { name: "Open Brush", offers: [{ ...offer }] }, choice: 0 };
+  if (p.renderAppDetail() !== true) fail("a good listing reported a render failure");
+  const html = p.els.detailBody.innerHTML;
+  if (!html.includes('id="detailTitle">Open Brush<')) fail("app page has no title: " + html.slice(0, 200));
+  if (!html.includes('id="detailInstall"') || !html.includes("Get it from")) fail("app page has no install panel");
+  if (html.includes('role="alert"')) fail("a good listing showed the error state");
+}
+
+// A listing that can't render (no offer to show) gets a clear message, not an empty dialog.
+{
+  const p = page();
+  p.sourceState.detail = { app: { name: "Broken <App>", offers: [] }, choice: 0 };
+  if (p.renderAppDetail() !== false) fail("a broken listing reported success");
+  const html = p.els.detailBody.innerHTML;
+  if (!html.includes('role="alert"') || !html.includes("We couldn't show Broken &lt;App&gt;")) fail("no error state: " + html);
+  if (!html.includes('data-close="appDetail"')) fail("error state has no way to close");
+}
+
+// Opening a listing that can't render: the error stays up, no details request, nothing thrown.
+{
+  const p = page(async () => { throw new Error("offline"); });
+  p.sourceState.apps = [{ name: "Broken", offers: [] }];
+  await p.openStoreApp(0);
+  if (!p.els.appDetail.open || !p.els.detailBody.innerHTML.includes('role="alert"')) fail("broken listing didn't open with the error");
+  if (p.calls.length) fail("asked for details of a listing that couldn't render");
+}
+
+// Opening a good listing: the dialog opens with its page, and fresher details fill it in.
+{
+  const p = page(async () => ({ description: "Fresh description." }));
+  p.sourceState.apps = [{ name: "Open Brush", offers: [{ ...offer }] }];
+  await p.openStoreApp(0);
+  if (!p.els.appDetail.open || !p.els.detailBody.innerHTML.includes("Fresh description.")) fail("details didn't fill in the page");
+  if (!String(p.calls[0]?.[0]).startsWith("/api/sources/details?")) fail("no details request: " + JSON.stringify(p.calls));
+}
+
+// A good listing whose details request fails keeps its page, with a note.
+{
+  const p = page(async () => { throw new Error("offline"); });
+  p.sourceState.apps = [{ name: "Open Brush", offers: [{ ...offer }] }];
+  await p.openStoreApp(0);
+  if (!p.els.detailBody.innerHTML.includes('id="detailTitle">Open Brush<')) fail("page lost after a failed details request");
+  if (!p.els.detailInstallNote.textContent.includes("couldn't be refreshed")) fail("no note after a failed details request");
+}
+console.log("ok");

tests/sandbox.py

@@ -1,12 +1,20 @@
 """Imported first by every test module: nothing a test does reaches this person's
-app data, their telemetry, or the shared compatibility database.
+app data, their ~/.ssh, their telemetry, or the shared compatibility database.
 
 Must run before any ui module is imported, since those read these at import time.
+The variables are set in os.environ, so servers and scripts the tests start
+inherit them too (they pass {**os.environ, ...}).
 """
 import atexit
 import os
 import shutil
 import tempfile
+from pathlib import Path
+
+# The environment and real ~/.ssh from before the changes below: test_sandbox
+# reruns tests from that environment and checks ~/.ssh is left alone.
+ORIGINAL_ENV = dict(os.environ)
+REAL_SSH_DIR = Path.home() / ".ssh"
 
 _dir = tempfile.mkdtemp(prefix="frame-control-tests-")
 atexit.register(shutil.rmtree, _dir, ignore_errors=True)
@@ -14,3 +22,25 @@ os.environ["FRAME_CONTROL_DATA_DIR"] = _dir
 os.environ["FRAME_CONTROL_TELEMETRY"] = "0"
 # A maintainer's machine holds the database key; send anything that slips through nowhere.
 os.environ["FRAME_COMPAT_DB_URL"] = "http://127.0.0.1:9"
+
+# A throwaway home, so Path.home() / "~" land here: ~/.ssh (config, host-key pins,
+# its lock file) and the other per-user folders some modules use. A server started
+# without FRAME_CONTROL_SSH_DIR used to import the real ~/.ssh/config and seed a pin
+# into the real ~/.ssh/frame-control-hosts on every run.
+#
+# tests/e2e must not import this (directly or through a test_* module): they run in
+# a throwaway container whose real ~/.ssh points `ssh frame` at the fake Frame, and
+# OpenSSH finds ~/.ssh from the password database, not $HOME. Shared helpers they
+# need live in sandbox-free modules such as apk_fixtures.py.
+HOME = os.path.join(_dir, "home")
+SSH_DIR = os.path.join(HOME, ".ssh")
+os.makedirs(SSH_DIR, mode=0o700)
+os.environ["HOME"] = HOME
+os.environ["USERPROFILE"] = HOME  # Path.home() on Windows
+os.environ["FRAME_CONTROL_SSH_DIR"] = SSH_DIR  # frame_devices.ssh_dir(), frame_connect.SSH_DIR
+# The per-user folders that don't follow HOME when these are set: frame_host.cache_dir()
+# (servers warm indexes there and sweep its staging folders) and data_dir()'s fallbacks.
+for _name, _sub in (("LOCALAPPDATA", "AppData/Local"), ("APPDATA", "AppData/Roaming"),
+                    ("XDG_CACHE_HOME", ".cache"), ("XDG_DATA_HOME", ".local/share"),
+                    ("XDG_STATE_HOME", ".local/state"), ("XDG_CONFIG_HOME", ".config")):
+    os.environ[_name] = os.path.join(HOME, *_sub.split("/"))

tests/test_agent.py

@@ -1,4 +1,5 @@
 """MCP protocol, exact-action approvals and explicit assistant data sharing."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import io
 import json
 import os

tests/test_apk_artwork.py

@@ -1,3 +1,4 @@
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import http.client
 import json
 from pathlib import Path
@@ -18,7 +19,9 @@ class ArtworkTests(unittest.TestCase):
     def setUp(self):
         with _images._lock:
             _images._urls.clear()
+            _images._tokens.clear()
             _images._cache.clear()
+            _images._dns.clear()
 
     def test_only_registered_source_images_are_fetchable(self):
         with patch.object(_images, 'fetch') as fetch:
@@ -70,9 +73,13 @@ class ArtworkTests(unittest.TestCase):
             _images.remember('https://example.com/a.png', PNG[:8] + b'x' * _images.MAX_IMAGE)
 
     def test_handles_are_bounded(self):
-        for i in range(4100):
-            _images.register('https://example.com/%d.png' % i)
-        self.assertEqual(len(_images._urls),4096)
+        with patch.object(_images, 'MAX_TOKENS', 50):
+            first = _images.register('https://example.com/0.png')
+            for i in range(1, 60):
+                _images.register('https://example.com/%d.png' % i)
+            self.assertEqual((len(_images._urls), len(_images._tokens)), (50, 50))
+            self.assertNotEqual(_images.register('https://example.com/0.png'), first)  # forgotten, so a new handle
+            self.assertEqual(_images.register('https://example.com/59.png'), _images.register('https://example.com/59.png'))
 
     def test_plain_language_verdict_is_evidence_based(self):
         self.assertEqual(search.verdict({})['label'], 'Not yet checked on the Frame')

tests/test_apk_more_sources.py

@@ -1,3 +1,4 @@
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import hashlib, io, json, os, sys, tempfile, time, unittest, urllib.error, urllib.request, zipfile
 from pathlib import Path
 from unittest.mock import patch

tests/test_apk_search.py

@@ -1,3 +1,4 @@
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import http.client
 import json
 from pathlib import Path
@@ -121,7 +122,7 @@ class SearchTests(SettingsTest):
                     break
                 time.sleep(.01)
             self.assertTrue(arrived[1]['event'].wait(2))
-        self.assertEqual(arrived[1]['query'], ('second', 50))
+        self.assertEqual(arrived[1]['query'][:2], ('second', 50))
 
     def test_set_enabled_does_not_hold_search_lock_in_source(self):
         free = []

tests/test_comfort.py

@@ -1,4 +1,5 @@
 """Fake-Frame session clock/actions plus real helper serialization and sensor probes."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import os
 import shutil
 import json
@@ -255,3 +256,47 @@ class SensorTests(unittest.TestCase):
                 self.assertIsNone(status.activity_level())
         with patch.object(status, 'run', return_value='[{"operation":"status","activity_level":3}]'):
             self.assertEqual(status.activity_level(), 3)
+
+
+class DesktopBundleTests(unittest.TestCase):
+    """server.comfort runs the copy cached on the headset; the sources go only when it's missing."""
+
+    @unittest.skipUnless(os.name == "posix", "checks POSIX permissions")
+    def test_sources_are_sent_once_per_version(self):
+        import server
+        with tempfile.TemporaryDirectory() as tmp:
+            here, home = Path(tmp) / 'ui', Path(tmp) / 'frame'
+            here.mkdir()
+            home.mkdir()
+            for name in server.COMFORT_FILES:
+                (here / name).write_text('# ' + name + '\n')
+            (here / 'frame_comfort.py').write_text('import json, sys\nprint(json.dumps({"active": False, "got": sys.argv[1]}))\n')
+            sent = []
+
+            def ssh(remote, *, stdin, timeout):  # the headset: the script run under its own home
+                sent.append(stdin)
+                return subprocess.run([sys.executable, '-'], input=stdin, capture_output=True, text=True, check=True,
+                                      env={**os.environ, 'HOME': str(home)}).stdout
+
+            with patch.object(server, 'HERE', here), patch.object(server, 'ssh', side_effect=ssh):
+                first = server.comfort({'action': 'status'})
+                self.assertEqual(json.loads(first['got']), {'action': 'status'})
+                self.assertEqual(len(sent), 2)  # the check, then the sources
+                self.assertNotIn('# frame_steam.py', sent[0])
+                self.assertIn('# frame_steam.py', sent[1])
+                self.assertEqual(server.comfort({'action': 'status'}), first)
+                self.assertEqual(len(sent), 3)
+                self.assertNotIn('# frame_steam.py', sent[2])
+                cached, = (home / '.cache/frame-control/comfort').iterdir()
+                self.assertEqual(sorted(p.name for p in cached.iterdir()), sorted(server.COMFORT_FILES))
+                self.assertEqual(cached.stat().st_mode & 0o777, 0o700)
+                self.assertTrue(all(p.stat().st_mode & 0o777 == 0o600 for p in cached.iterdir()))
+                # A copy cut short is completed; a changed helper is a new version.
+                (cached / 'frame_status.py').unlink()
+                server.comfort({'action': 'status'})
+                self.assertEqual(len(sent), 5)
+                self.assertTrue((cached / 'frame_status.py').exists())
+                (here / 'frame_steam.py').write_text('# frame_steam.py, changed\n')
+                server.comfort({'action': 'status'})
+                self.assertEqual(len(sent), 7)
+                self.assertEqual(len(list((home / '.cache/frame-control/comfort').iterdir())), 2)

tests/test_comfort_ui.py

@@ -1,4 +1,5 @@
 """Run the actual shared page's comfort renderer against a minimal DOM/bridge."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import pathlib
 import shutil
 import subprocess
@@ -58,3 +59,32 @@ const log = ()=>{}, toast = ()=>{};
 '''
         result = subprocess.run(['node', '-e', setup + code + checks], capture_output=True, text=True)
         self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_poll_waits_while_the_frame_is_unreachable(self):
+        page = (ROOT / 'ui/index.html').read_text(encoding='utf-8')
+        start = page.index('async function pollComfort()')
+        code = page[start:page.index('$("comfortForm").onsubmit', start)]
+        js = r'''
+const assert = require('node:assert/strict');
+const el = {textContent: 'Checking session…'};
+const $ = () => el;
+let online = false, comfortBusy = false, calls = 0, timers = 0;
+const api = async () => { calls++; return {}; };
+const renderComfort = () => {};
+const setTimeout = () => { timers++; };
+''' + code + r'''
+(async () => {
+  await pollComfort();
+  assert.equal(calls, 0);  // no ssh attempt while the status check can't reach the Frame
+  assert.match(el.textContent, /when the Frame is connected/);
+  assert.equal(timers, 1);  // still scheduled, to resume when it's back
+  online = true;
+  await pollComfort();
+  assert.equal(calls, 1);
+  online = null;  // a status check that failed for another reason: keep polling
+  await pollComfort();
+  assert.equal(calls, 2);
+})().catch(e => { console.error(e); process.exitCode = 1; });
+'''
+        result = subprocess.run(['node', '-e', js], capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stderr)

tests/test_contact.py

@@ -59,6 +59,16 @@ class Contact(Base):
         self.assertEqual(fc.load()["email"], "")
         self.assertEqual(self.got, [])
 
+    def test_only_a_real_true_counts_as_consent(self):
+        for wrong in ("false", "true", 1, 0, [], {}):
+            with self.assertRaisesRegex(ValueError, "true or false"):
+                fc.save({"email": "me@example.com", "updates": wrong, "followup": True})
+            with self.assertRaisesRegex(ValueError, "true or false"):
+                fr.send({**REPORT, "contact": "me@example.com", "contactFollowup": wrong})
+        self.assertEqual((fc.load()["email"], self.got), ("", []))
+        fc.save({"email": "me@example.com", "updates": True})  # left out is no
+        self.assertEqual((fc.load()["updates"], fc.load()["followup"]), (True, False))
+
     def test_each_choice_is_sent_privately_on_its_own(self):
         fc.save({"email": " me@example.com ", "updates": True})
         fc.save({"email": "me@example.com", "updates": False, "followup": True})
@@ -239,15 +249,121 @@ class Contact(Base):
 
     # ---- reports and the maintainer's list
 
+    def reports(self):
+        return [e["properties"] for e in self.events() if e["event"] == "problem_report"]
+
     def test_a_report_carries_the_address_only_with_follow_up_consent(self):
         fr.send({**REPORT, "contact": "me@example.com"})
+        self.assertFalse(fc.FILE.exists())  # no follow-up: nothing kept, nothing linked
         fr.send({**REPORT, "contact": "me@example.com", "contactFollowup": True})
-        without, with_ = (e["properties"] for e in self.events())
-        self.assertEqual((without["contact"], without["contact_followup"]), ("", False))
+        without, with_ = self.reports()
+        self.assertEqual((without["contact"], without["contact_followup"], without["contact_id"]), ("", False, ""))
         self.assertEqual((with_["contact"], with_["contact_followup"]), ("me@example.com", True))
+        self.assertEqual((with_["contact_id"], with_["contact_rev"]), (fc.load()["id"], fc.load()["rev"]))
+        self.assertNotEqual(with_["contact_id"], tm.settings()["id"])  # not the analytics id
         with self.assertRaisesRegex(ValueError, "email address"):
             fr.send({**REPORT, "contact": "discord:me", "contactFollowup": True})
 
+    def test_follow_up_given_with_a_report_is_kept_and_removed_in_settings(self):
+        fr.send({**REPORT, "contact": "me@example.com", "contactFollowup": True})
+        s = fc.state()
+        self.assertEqual((s["email"], s["updates"], s["followup"]), ("me@example.com", False, True))
+        consent = [e for e in self.events() if e["event"] == "contact_consent"]
+        self.assertEqual([(e["properties"]["action"], e["properties"]["rev"]) for e in consent], [("set", 1)])
+        self.assertEqual(consent[0]["distinct_id"], self.reports()[0]["contact_id"])
+        fr.send({**REPORT, "contact": "ME@example.com", "contactFollowup": True})  # already agreed
+        self.assertEqual(len([e for e in self.events() if e["event"] == "contact_consent"]), 1)
+        self.assertEqual(self.reports()[1]["contact_rev"], 1)
+        fc.save({"email": ""})  # Remove my email
+        last = self.events()[-1]
+        self.assertEqual((last["properties"]["action"], last["properties"]["email"], last["properties"]["rev"]),
+                         ("withdraw", "", 2))
+        logged = [e["properties"].get("contact") for e in tm._read_lines(tm.SENT) if e["event"] == "problem_report"]
+        self.assertEqual(logged, ["<removed>", "<removed>"])
+
+    def test_a_report_to_another_address_replaces_it_with_follow_up_only(self):
+        """Update notices were agreed for the old address, not the new one (the form says so)."""
+        fc.save({"email": "old@example.com", "updates": True})
+        fr.send({**REPORT, "contact": "new@example.com", "contactFollowup": True})
+        s = fc.state()
+        self.assertEqual((s["email"], s["updates"], s["followup"]), ("new@example.com", False, True))
+        self.assertEqual(self.reports()[0]["contact_rev"], 2)
+        fc.save({"email": "new@example.com", "updates": True, "followup": False})
+        fr.send({**REPORT, "contact": "NEW@example.com", "contactFollowup": True})  # same address: kept
+        s = fc.state()
+        self.assertEqual((s["email"], s["updates"], s["followup"]), ("new@example.com", True, True))
+
+    def test_a_removal_while_the_report_saves_its_address_still_counts(self):
+        """Removed while the report's own consent is on its way: the report keeps that consent's
+        rev (so the removal is newer) and is logged without the address."""
+        post, removed = tm.post, []
+
+        def slow_post(events, **kw):
+            post(events, **kw)
+            if not removed and events[0]["event"] == "contact_consent":
+                removed.append(fc.save({"email": ""}))  # Remove my email, mid-send
+        with mock.patch.object(tm, "post", side_effect=slow_post):
+            fr.send({**REPORT, "contact": "me@example.com", "contactFollowup": True})
+        report = self.reports()[0]
+        self.assertEqual((report["contact_rev"], fc.load()["rev"], fc.state()["email"]), (1, 2, ""))
+        consents = [[e["distinct_id"], e["properties"]["email"], e["properties"]["followup"], e["properties"]["rev"]]
+                    for e in self.events() if e["event"] == "contact_consent"]
+        row = self.report_row(cid=report["contact_id"], rev=report["contact_rev"])
+        fr.mark_withdrawn([row], consents)
+        self.assertEqual(row[10], "withdrawn")
+        logged = [e["properties"]["contact"] for e in tm._read_lines(tm.SENT) if e["event"] == "problem_report"]
+        self.assertEqual(logged, ["<removed>"])
+
+    def report_row(self, contact="me@example.com", followup=True, cid="copy", rev=1):
+        return ["2026-09-10T10:00:00Z", "AB12CD34", "bug", "RDP", "It never connects.", contact,
+                "0.4.0", "Windows", "", "", followup, cid, rev]
+
+    def test_a_later_change_takes_back_a_reports_follow_up_permission(self):
+        reports = [self.report_row(),                                   # removed later
+                   self.report_row(cid="other"),                        # another copy, still agrees
+                   self.report_row(rev=3),                              # sent after the removal
+                   self.report_row(cid="moved"),                        # address changed later
+                   self.report_row(cid="news-only"),                    # follow-up unticked later
+                   self.report_row(contact="Me@Example.com", cid="case"),  # same address, any case
+                   self.report_row(cid="", followup=True),              # no contact id: left alone
+                   self.report_row(cid="bad", rev="x")]                 # malformed rev: treated as 0
+        consents = [["copy", "me@example.com", True, 1], ["copy", "", False, 2],
+                    ["other", "me@example.com", True, 1], ["other", "me@example.com", True, 2],
+                    ["moved", "new@example.com", True, 2], ["news-only", "me@example.com", False, 2],
+                    ["case", "me@example.com", True, 2], ["bad", "", False, 1], ["short"], ["x", "", False, "?"]]
+        fr.mark_withdrawn(reports, consents)
+        self.assertEqual([r[10] for r in reports],
+                         ["withdrawn", True, True, "withdrawn", "withdrawn", True, True, "withdrawn"])
+
+    def test_the_change_number_decides_not_the_clock(self):
+        """The clock went back between the report and the removal: the removal still counts."""
+        fr.send({**REPORT, "contact": "me@example.com", "contactFollowup": True})
+        with mock.patch.object(fc.time, "gmtime", return_value=time.gmtime(0)):
+            fc.save({"email": ""})
+        report = self.reports()[0]
+        row = self.report_row(cid=report["contact_id"], rev=report["contact_rev"])
+        consents = [[e["distinct_id"], e["properties"]["email"], e["properties"]["followup"], e["properties"]["rev"]]
+                    for e in self.events() if e["event"] == "contact_consent"]
+        self.assertEqual(self.events()[-1]["timestamp"], "1970-01-01T00:00:00Z")
+        fr.mark_withdrawn([row], consents)
+        self.assertEqual(row[10], "withdrawn")
+
+    def test_the_inbox_shows_withdrawn_follow_up_without_the_address(self):
+        reports = [self.report_row(), ["short"]]
+        consents = [["copy", "", False, 2]]
+        with mock.patch.object(db, "_posthog_query", side_effect=[{"results": reports}, {"results": consents}]) as q, \
+             mock.patch.object(sys, "argv", ["frame_report.py", "inbox", "30"]), \
+             mock.patch("builtins.print") as out:
+            fr.main()
+        self.assertIn("properties.contact_rev", q.call_args_list[0].args[0])
+        self.assertIn("event = 'contact_consent'", q.call_args_list[1].args[0])
+        printed = " ".join(str(c.args[0]) for c in out.call_args_list if c.args)
+        self.assertIn("follow-up permission since withdrawn", printed)
+        self.assertNotIn("me@example.com", printed)
+        with mock.patch.object(db, "_posthog_query", return_value={"results": [self.report_row(followup=False)]}) as q:
+            fr.inbox()
+        self.assertEqual(q.call_count, 1)  # nothing to reconcile, no second query
+
     def test_contacts_lists_the_newest_choice_per_copy_by_consent(self):
         rows = [["a", "both@example.com", True, "true", "2026-09-01T10:00:00Z"],
                 ["b", "news@example.com", "true", False, "2026-09-02T10:00:00Z"],
@@ -272,6 +388,22 @@ class Contact(Base):
         self.assertIs(server.POST["/api/contact"], fc.save)
         self.assertIs(server.POST["/api/contact/prompt"], fc.prompt)
 
+    def test_saving_is_not_headset_work(self):
+        """A slow send mustn't hold up switching headsets, nor be refused after a switch."""
+        import io
+        import server
+        seen = []
+        for path in ("/api/contact", "/api/contact/prompt"):
+            h = server.Handler.__new__(server.Handler)
+            body = b'{"prompt": "shown"}' if path.endswith("prompt") else b'{"email": "me@example.com", "updates": true}'
+            h.path, h.rfile = path, io.BytesIO(body)
+            h.headers = {"Content-Length": str(len(body)), "X-Frame-Device": "a-headset-switched-away-from"}
+            h.local_request = lambda: True
+            h.send_json = lambda obj, status=200: seen.append((status, server._work[0]))
+            with mock.patch.object(fc, "_send_pending", side_effect=lambda block=True: seen.append(("send", server._work[0]))):
+                h.do_POST()
+        self.assertEqual(seen, [("send", 0), (200, 0), (200, 0)])
+
 
 # Run these once, in test_telemetry, not again through the import above.
 del Base, ReportProblem

tests/test_control_center.py

@@ -0,0 +1,89 @@
+"""Control Center API guards and shared-page behavior, without a real headset."""
+import sandbox  # noqa: F401 (first: isolates app state, SSH and telemetry)
+import importlib.util
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import unittest
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'ui'))
+import server
+import frame_status
+
+
+class AudioValidation(unittest.TestCase):
+    def test_invalid_values_do_not_touch_device_even_with_valid_mute(self):
+        invalid = [{}, {'level': None}, {'level': True}, {'level': '0.5'}, {'level': []},
+                   {'level': float('nan')}, {'level': float('inf')}, {'level': -1}, {'level': 2},
+                   {'muted': 'false'}, {'muted': 1}, {'muted': None}, {'action': 'mute'},
+                   {'level': -1, 'muted': True}, {'level': .5, 'muted': 'yes'}]
+        for body in invalid:
+            with self.subTest(body=body), mock.patch.object(server, 'ssh') as ssh:
+                with self.assertRaises(server.Failure) as raised:
+                    server.set_volume(body)
+                self.assertEqual(raised.exception.status, 400)
+                ssh.assert_not_called()
+
+    def test_supported_actions_use_wpctl_with_exact_values(self):
+        for body, commands in [({'level': 0}, ['wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.00']),
+                               ({'level': 1}, ['wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.00']),
+                               ({'muted': False}, ['wpctl set-mute @DEFAULT_AUDIO_SINK@ 0']),
+                               ({'level': .65, 'muted': True}, ['wpctl set-mute @DEFAULT_AUDIO_SINK@ 1',
+                                                              'wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.65'])]:
+            with self.subTest(body=body), mock.patch.object(server, 'ssh', return_value='') as ssh:
+                self.assertEqual(server.set_volume(body)['message'], 'Volume updated')
+                self.assertEqual([c.args[0] for c in ssh.call_args_list], commands)
+
+    def test_device_error_propagates_without_claiming_success(self):
+        with mock.patch.object(server, 'ssh', side_effect=server.Failure('Headset offline')):
+            with self.assertRaisesRegex(server.Failure, 'Headset offline'):
+                server.set_volume({'level': .5})
+
+
+class Coverage(unittest.TestCase):
+    @unittest.skipUnless(shutil.which('node'), 'Node exercises production page JS')
+    def test_control_center_behavior(self):
+        result = subprocess.run(['node', '--test', str(ROOT / 'tests/control_center.cjs')],
+                                capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_shared_assets_ship_to_iphone_and_desktop(self):
+        spec = importlib.util.spec_from_file_location('frame_bundle_cc', ROOT / 'ios/scripts/make_frame_bundle.py')
+        bundle = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(bundle)
+        files = set(bundle.files())
+        for name in ('control-center.js', 'control-center.css', 'artwork-settings.js'):
+            self.assertIn(ROOT / 'ui' / name, files)
+        config = json.loads((ROOT / 'app/package.json').read_text())
+        ui = next(item for item in config['build']['extraResources'] if item['from'] == '../ui')
+        self.assertIn('*.js', ui['filter'])
+        self.assertIn('*.css', ui['filter'])
+
+    def test_bundle_runs_the_server_on_its_own(self):
+        # The iPhone app and scripts/store-on-frame.sh start ui/server.py from this bundle alone.
+        import io, tarfile, tempfile
+        spec = importlib.util.spec_from_file_location('frame_bundle_run', ROOT / 'ios/scripts/make_frame_bundle.py')
+        bundle = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(bundle)
+        with tempfile.TemporaryDirectory() as tmp, tarfile.open(fileobj=io.BytesIO(bundle.build()), mode='r:gz') as tar:
+            tar.extractall(tmp)
+            result = subprocess.run([sys.executable, '-I', '-B', '-c',
+                                     'import sys; sys.path.insert(0, "ui"); import server, apk_sources.search; '
+                                     'apk_sources.search.modules()[1] and sys.exit("source modules failed: %r" % apk_sources.search.modules()[1])'],
+                                    cwd=tmp, capture_output=True, text=True, timeout=60)
+        self.assertEqual(result.returncode, 0, result.stderr[-2000:])
+
+    def test_status_exposes_kernel_thermal_trips_without_guessing_thresholds(self):
+        # Run the real aggregator with every external probe stubbed.
+        names = ('read', 'process_names', 'performance', 'os_release', 'battery', 'power_source',
+                 'disk', 'memory', 'max_temp', 'wifi', 'ip_addr', 'volume', 'port_listening', 'games', 'flatpaks')
+        with mock.patch.multiple(frame_status, **{name: mock.DEFAULT for name in names}) as probes, \
+             mock.patch.object(frame_status, 'thermal_alerts', return_value=[{'zone':'battery','tempC':45,'limitC':44}]):
+            probes['read'].return_value = '120 0'
+            probes['process_names'].return_value = set()
+            result = frame_status.status()
+        self.assertEqual(result['thermalAlerts'], [{'zone':'battery','tempC':45,'limitC':44}])

tests/test_devices.py

@@ -17,6 +17,7 @@ ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT / "ui"))
 
 import frame_devices as fd  # noqa: E402
+import frame_host  # noqa: E402
 
 CONFIG = """Host lxso1
   HostName 192.168.1.109
@@ -263,6 +264,30 @@ class Pins(Base):
         self.assertFalse(fd.pinned("d1"))
         self.assertFalse(fd.forget_pin("d1"))
 
+    def test_a_trusted_key_replaces_the_saved_one_and_fingerprints_match_ssh_keygen(self):
+        key = self.dir / "hostkey"
+        frame_host.run_ssh(["ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-f", str(key)], capture_output=True,
+                           stdin=subprocess.DEVNULL, check=True, timeout=20)
+        kind, blob = key.with_suffix(".pub").read_text().split()[:2]
+        want = frame_host.run_ssh(["ssh-keygen", "-l", "-E", "sha256", "-f", str(key.with_suffix(".pub"))],
+                                  capture_output=True, text=True, stdin=subprocess.DEVNULL, timeout=10).stdout.split()[1]
+        self.assertEqual(fd.fingerprint(blob), want)
+        self.assertIsNone(fd.fingerprint("not base64!"))
+        (self.ssh / "known_hosts").write_text(f"frame.local {KEY}\n")
+        fd.seed_pin("d1", ["frame.local"])
+        old = fd.pinned_keys("d1")
+        fd.pin_key("d1", kind, blob)
+        self.assertEqual(fd.known_hosts("d1").read_text(), f"frame-control-d1 {kind} {blob}\n")  # old key gone
+        self.assertEqual(fd.pinned_keys("d1"), [(kind, want)])
+        self.assertNotEqual(old, fd.pinned_keys("d1"))
+        self.assertTrue(fd.pinned("d1"))
+        for bad in (("ssh-ed25519\nHost *", blob), ("ssh-ed25519", "AAAA AAAA"), ("evil", blob)):
+            with self.assertRaises(fd.DeviceError):
+                fd.pin_key("d1", *bad)
+        # Only plain entries for this headset's alias count.
+        self.assertIsNone(fd.key_entry(f"frame-control-d2 {kind} {blob}", "frame-control-d1"))
+        self.assertIsNone(fd.key_entry(f"# frame-control-d1 {kind} {blob}", "frame-control-d1"))
+
     def test_each_headset_has_its_own_file(self):
         (self.ssh / "known_hosts").write_text(f"a.local {KEY}\nb.local {KEY}\n")
         fd.seed_pin("da", ["a.local"])
@@ -274,7 +299,8 @@ class Pins(Base):
     def test_hashed_and_non_default_port_entries(self):
         kh = self.ssh / "known_hosts"
         kh.write_text(f"[frame.local]:2222 {KEY}\n")
-        subprocess.run(["ssh-keygen", "-H", "-f", str(kh)], capture_output=True, check=True)
+        frame_host.run_ssh(["ssh-keygen", "-H", "-f", str(kh)], capture_output=True,
+                           stdin=subprocess.DEVNULL, check=True, timeout=10)
         self.assertFalse(fd.seed_pin("d3", ["frame.local"]))  # port 22: not that entry
         self.assertTrue(fd.seed_pin("d3", ["frame.local"], port=2222))
         self.assertIn(f"frame-control-d3 {KEY}", fd.known_hosts("d3").read_text())
@@ -283,7 +309,8 @@ class Pins(Base):
         target = fd.known_hosts("d4")
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(f"frame-control-d4 {KEY}\n")
-        subprocess.run(["ssh-keygen", "-H", "-f", str(target)], capture_output=True, check=True)
+        frame_host.run_ssh(["ssh-keygen", "-H", "-f", str(target)], capture_output=True,
+                           stdin=subprocess.DEVNULL, check=True, timeout=10)
         self.assertNotIn("frame-control-d4", target.read_text())
         self.assertTrue(fd.pinned("d4"))
         self.assertTrue(fd.forget_pin("d4"))

tests/test_fdroid_sources.py

@@ -1,4 +1,5 @@
 """Offline authenticated repository fixtures; no tests contact a server."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import io
 import json
 import os
@@ -256,6 +257,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_android_data.py

@@ -1,3 +1,4 @@
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import io
 import json
 import os
@@ -63,7 +64,7 @@ class ObbTests(unittest.TestCase):
                 with self.assertRaisesRegex(android.FrameError, 'start this app'):
                     data.install_obb(PKG, [path])
                 stream.assert_not_called()
-            with patch.object(subprocess, 'run', return_value=subprocess.CompletedProcess([], 1, b'', b'bad hash')):
+            with patch.object(data.frame_host, 'run_ssh', return_value=subprocess.CompletedProcess([], 1, b'', b'bad hash')):
                 with self.assertRaisesRegex(android.FrameError, 'bad hash'):
                     data._stream('command')
 

tests/test_frame_android_library.py

@@ -1,4 +1,5 @@
 """Offline artwork, Steam API and launcher supervision regressions."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import importlib.util
 import json
 import os
@@ -121,6 +122,11 @@ FIXTURES = ROOT / 'tests/fixtures/library'
 
 
 class ArtworkTests(unittest.TestCase):
+    def setUp(self):
+        from apk_sources import _images
+        _images._dns.clear()  # each test answers lookups its own way
+        self.addCleanup(_images._dns.clear)
+
     def test_source_inputs_and_url(self):
         from apk_sources import _images
         data = (FIXTURES / 'icon.png').read_bytes()
@@ -263,11 +269,14 @@ class ArtworkTests(unittest.TestCase):
     def test_steamgriddb_uses_the_bounded_fetch_without_redirects(self):
         import frame_steamgriddb as sgdb
         from apk_sources import _images
+        deadline = time.monotonic() + 5
         with patch.object(_images, 'get', return_value=b'{"success": true, "data": [1]}') as get:
-            self.assertEqual(sgdb._get('/search/x', 'secret', time.monotonic() + 5), [1])
+            self.assertEqual(sgdb._get('/search/x', 'secret', deadline), [1])
         self.assertEqual(get.call_args.kwargs['redirects'], 0)
         self.assertEqual(get.call_args.args[1]['Authorization'], 'Bearer secret')
-        self.assertLessEqual(get.call_args.kwargs['deadline'] - time.monotonic(), 5)
+        # The caller's deadline is passed on, never extended. (Comparing against a fresh
+        # time.monotonic() flaked on Windows, whose clock ticks coarsely.)
+        self.assertLessEqual(get.call_args.kwargs['deadline'], deadline)
 
     def test_supplied_jpeg(self):
         data = (FIXTURES / 'icon.jpg').read_bytes()
@@ -419,6 +428,19 @@ class InstallTests(unittest.TestCase):
         self.assertIn(('remove', '3346865537'), [c.args for c in api.call_args_list])
         self.assertTrue(any(c.args[0] == 'rm -rf Applications/Android/org.test.vr' for c in ssh.call_args_list))
 
+    def test_failed_update_removes_partial_apk_and_keeps_the_app(self):
+        with patch.object(android.frame_artwork, 'prepare', return_value=(self.images, [])), \
+                patch.object(android, 'read_meta', return_value=dict(self.existing)), \
+                patch.object(android, '_copy', side_effect=android.FrameError('copying x.apk to the Frame timed out')), \
+                patch.object(android, 'ssh', return_value='') as ssh, \
+                patch.object(android, 'shortcut_tool') as api:
+            with self.assertRaisesRegex(android.FrameError, 'timed out'):
+                android._install('x.apk', self.info, 'org.test.vr', False, None, None)
+        commands = [c.args[0] for c in ssh.call_args_list]
+        self.assertIn('rm -f Applications/Android/org.test.vr/app.apk.part', commands)
+        self.assertFalse(any(c.startswith('rm -rf') for c in commands))
+        api.assert_not_called()
+
     def test_remove_keeps_data_when_requested_and_survives_steam_failure(self):
         with patch.object(android, '_meta_or_fail', side_effect=lambda pkg: dict(self.existing)), \
                 patch.object(android, 'stop'), \
@@ -482,6 +504,49 @@ class InstallTests(unittest.TestCase):
         self.assertIn('podman stop -t 5 lepton-steamlaunch-2800000001', ssh.call_args.args[0])
 
 
+class CopyAndSshTests(unittest.TestCase):
+    """The commands behind an install fail as FrameErrors with readable words, and a large APK
+    gets the time it needs."""
+
+    def fake(self, stderr, code=1, stdout=b''):
+        """frame_host.run_ssh running a stand-in that writes these bytes, with the caller's options."""
+        script = (f'import sys; sys.stdout.buffer.write({stdout!r}); sys.stderr.buffer.write({stderr!r}); '
+                  f'sys.exit({code})')
+        return lambda argv, **kwargs: subprocess.run([sys.executable, '-c', script], **kwargs)
+
+    def test_large_apk_copy_timeout_grows_with_its_size(self):
+        seen = {}
+        with tempfile.NamedTemporaryFile(suffix='.apk') as f, \
+                patch.object(android.frame_host, 'run_ssh', side_effect=lambda argv, **kw: seen.update(kw)), \
+                patch.object(android.os.path, 'getsize', return_value=2 * 1024 ** 3):
+            android._copy(f.name, 'Applications/Android/x/app.apk.part')
+        # 2 GB at the slowest rate allowed: 4096 s, not the old fixed 600 (300 MB at 4 Mbit/s).
+        self.assertGreaterEqual(seen['timeout'], 2 * 1024 ** 3 / (512 * 1024))
+        with tempfile.NamedTemporaryFile(suffix='.apk') as f, \
+                patch.object(android.frame_host, 'run_ssh', side_effect=lambda argv, **kw: seen.update(kw)):
+            android._copy(f.name, 'x/launch.sh', timeout=120)
+        self.assertEqual(seen['timeout'], 120)  # a small file keeps the least time given
+
+    def test_copy_failure_in_another_encoding_is_a_frame_error(self):
+        # A message from a Windows code page, or a file name, isn't UTF-8.
+        with tempfile.NamedTemporaryFile(suffix='.apk') as f, \
+                patch.object(android.shutil, 'which', return_value=None), \
+                patch.object(android.frame_host, 'run_ssh', side_effect=self.fake(b'scp: Verbindung \x81ber\xff\n')):
+            with self.assertRaisesRegex(android.FrameError, r'\Acopying .* to the Frame failed: scp: Verbindung'):
+                android._copy(f.name, 'x/app.apk.part')
+
+    def test_ssh_failure_messages_are_text(self):
+        with patch.object(android.frame_host, 'run_ssh', side_effect=self.fake(b'mv: \xff cannot move\n')):
+            with self.assertRaisesRegex(android.FrameError, r'\Amv: .* cannot move\Z'):
+                android.ssh('mv a b')
+        with patch.object(android.frame_host, 'run_ssh', side_effect=self.fake(b'cat: write error: No space left on device\n')):
+            with self.assertRaises(android.FrameError) as caught:
+                android.ssh('cat > x', input=b'\x89PNG')  # bytes in, bytes out
+        self.assertEqual(str(caught.exception), 'cat: write error: No space left on device')
+        with patch.object(android.frame_host, 'run_ssh', side_effect=self.fake(b'', code=0, stdout=b'ok \xff\n')):
+            self.assertEqual(android.ssh('echo ok').strip(), 'ok �')
+
+
 class SteamAPITests(unittest.TestCase):
     def test_artwork_api_enums_and_safe_serialization(self):
         with patch.object(shortcuts, 'evaluate', return_value={'warnings': []}) as evaluate:

tests/test_frame_apk.py

@@ -11,82 +11,7 @@ import zipfile
 
 sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'ui'))
 import frame_apk  # noqa: E402
-
-
-def pool(strings, utf8=False):
-    """A ResStringPool chunk."""
-    data, offsets = b'', []
-    for s in strings:
-        offsets.append(len(data))
-        if utf8:
-            b = s.encode()
-            data += bytes([len(s), len(b)]) + b + b'\0'
-        else:
-            data += struct.pack('<H', len(s)) + s.encode('utf-16-le') + b'\0\0'
-    data += b'\0' * (-len(data) % 4)
-    start = 28 + 4 * len(strings)
-    body = struct.pack(f'<{len(strings)}I', *offsets) + data
-    return struct.pack('<HHIIIIII', 1, 28, 28 + len(body), len(strings), 0, 0x100 if utf8 else 0, start, 0) + body
-
-
-def manifest(package, label_ref, version_ref, min_sdk, package_raw=True, foreign_label=False):
-    """<manifest package versionName><uses-sdk minSdkVersion/><application label icon/></manifest>.
-
-    package_raw=False drops the package's raw string (as some repackers do);
-    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
-    resmap = struct.pack('<4I', 0x01010001, 0x01010002, 0x0101021c, 0x0101020c)
-    resmap = struct.pack('<HHI', 0x0180, 8, 8 + len(resmap)) + resmap
-
-    def element(name, attrs):
-        body = struct.pack('<IIHHHHHH', 0xffffffff, name, 20, 20, len(attrs), 0, 0, 0)
-        for aname, raw, dtype, value in attrs:
-            body += struct.pack('<IIIHBBI', 0xffffffff, aname, raw, 8, 0, dtype, value)
-        return struct.pack('<HHIII', 0x0102, 16, 16 + len(body), 1, 0xffffffff) + body
-
-    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),
-                            (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 [])))
-    return struct.pack('<HHI', 3, 8, 8 + len(chunks)) + chunks
-
-
-def resources(values):
-    """resources.arsc with package 0x7f; values: {(type id, entry, language, density): global string index}."""
-    strings = ['French label', 'App label', '2.1', 'res/icon_lo.png', 'res/icon_hi.png', 'res/icon.xml']
-    pkg_body = b''
-    for (tid, lang, density), entries in values.items():
-        cfg = struct.pack('<I4x2s4xH', 64, lang.encode().ljust(2, b'\0'), density).ljust(64, b'\0')
-        count = max(entries) + 1
-        offsets, data = [], b''
-        for i in range(count):
-            if i in entries:
-                offsets.append(len(data))
-                data += struct.pack('<HHI', 8, 0, 0) + struct.pack('<HBBI', 8, 0, frame_apk.T_STRING, entries[i])
-            else:
-                offsets.append(0xffffffff)
-        header = 20 + 64
-        estart = header + 4 * count
-        body = struct.pack(f'<{count}I', *offsets) + data
-        pkg_body += struct.pack('<HHIBBHII', 0x0201, header, header + len(body), tid, 0, 0, count, estart) + cfg + body
-    pkg_header = struct.pack('<HHII', 0x0200, 288, 288 + len(pkg_body), 0x7f).ljust(288, b'\0')
-    pkg = pkg_header + pkg_body
-    table = pool(strings, utf8=True) + pkg
-    return struct.pack('<HHII', 2, 12, 12 + len(table), 1) + table
-
-
-def apk(files):
-    buf = io.BytesIO()
-    with zipfile.ZipFile(buf, 'w') as z:
-        for name, data in files.items():
-            z.writestr(name, data)
-    return buf.getvalue()
+from apk_fixtures import apk, manifest, pool, resources  # noqa: E402,F401
 
 
 class ApkInfo(unittest.TestCase):
@@ -168,6 +93,20 @@ class ApkInfo(unittest.TestCase):
             frame_apk.MAX_MANIFEST = limit
         self.assertLess(peak, 8 * 1024**2)
 
+    def test_damaged_download_is_an_apk_error(self):
+        # Corrupt deflate data used to escape as zlib.error, which the upload path didn't catch
+        # (a 500, and no install report) and frame_android.install reported as 'other'.
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as z:
+            z.writestr('AndroidManifest.xml', manifest('com.example.bad', 0x7f010000, 0x7f010001, 21) * 20)
+        data = bytearray(buf.getvalue())
+        at = data.index(b'PK\x03\x04')
+        start = at + 30 + sum(struct.unpack_from('<HH', data, at + 26))  # past the name and extra field
+        for i in range(start, start + 40):
+            data[i] ^= 0x5a
+        with self.assertRaisesRegex(frame_apk.ApkError, 'could not read the APK manifest'):
+            self.read(bytes(data))
+
     def test_refuses_compression_android_cant_read(self):
         for method in (zipfile.ZIP_BZIP2, zipfile.ZIP_LZMA):
             buf = io.BytesIO()

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

@@ -1,4 +1,5 @@
 """Local-only VR manifest, raw ZIP and independent signature checks."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import io
 import os
 from pathlib import Path
@@ -15,7 +16,7 @@ import frame_apk
 import frame_apk_vr as vr
 import frame_apk_sign as signing
 import frame_android
-from test_frame_apk import pool
+from apk_fixtures import pool
 
 
 DEFAULT = 'android.intent.category.DEFAULT'
@@ -255,6 +256,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 +274,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_frame_host.py

@@ -0,0 +1,87 @@
+"""Captured OpenSSH output keeps working on Windows and POSIX hosts."""
+import sandbox  # noqa: F401
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ui"))
+import frame_host
+
+
+class CapturedSSH(unittest.TestCase):
+    def run_command(self, source, **kwargs):
+        with mock.patch.object(frame_host, "WINDOWS", True):
+            return frame_host.run_ssh([sys.executable, "-c", source], timeout=5, **kwargs)
+
+    def test_binary_output_and_input(self):
+        result = self.run_command("import sys; sys.stdout.buffer.write(sys.stdin.buffer.read()); "
+                                  "sys.stderr.buffer.write(b'error\\r\\n')",
+                                  capture_output=True, input=b"data\x00\xff")
+        self.assertEqual(result.stdout, b"data\x00\xff")
+        self.assertEqual(result.stderr, b"error\r\n")
+
+    def test_text_output_normalizes_newlines(self):
+        result = self.run_command("import sys; sys.stdout.write(sys.stdin.read()); "
+                                  "sys.stderr.buffer.write(b'first\\r\\nsecond\\rthird\\n')",
+                                  capture_output=True, input="hello\n", text=True)
+        self.assertEqual(result.stdout, "hello\n")
+        self.assertEqual(result.stderr, "first\nsecond\nthird\n")
+
+    def test_explicit_encoding_and_errors(self):
+        result = self.run_command("import sys; sys.stderr.buffer.write(b'\\xe9\\xff')",
+                                  capture_output=True, encoding="ascii", errors="replace")
+        self.assertEqual(result.stderr, "\ufffd\ufffd")
+
+    def test_check_preserves_error_output(self):
+        with self.assertRaises(subprocess.CalledProcessError) as caught:
+            self.run_command("import sys; print('out'); print('err', file=sys.stderr); sys.exit(7)",
+                             capture_output=True, text=True, check=True)
+        self.assertEqual(caught.exception.returncode, 7)
+        self.assertEqual(caught.exception.stdout, "out\n")
+        self.assertEqual(caught.exception.stderr, "err\n")
+
+    def test_timeout_preserves_partial_stderr(self):
+        with self.assertRaises(subprocess.TimeoutExpired) as caught:
+            with mock.patch.object(frame_host, "WINDOWS", True):
+                frame_host.run_ssh([sys.executable, "-c", "import sys, time; "
+                                    "sys.stderr.write('waiting'); sys.stderr.flush(); time.sleep(10)"],
+                                   capture_output=True, text=True, timeout=1)
+        self.assertEqual(caught.exception.stderr, b"waiting")
+
+    def test_streamed_stdout_is_kept_separate(self):
+        with tempfile.TemporaryFile() as output:
+            result = self.run_command("import sys; sys.stdout.buffer.write(b'file'); "
+                                      "sys.stderr.buffer.write(b'error')",
+                                      stdout=output, stderr=subprocess.PIPE)
+            output.seek(0)
+            self.assertEqual(output.read(), b"file")
+        self.assertIsNone(result.stdout)
+        self.assertEqual(result.stderr, b"error")
+
+    def test_uncaptured_windows_call_is_unchanged(self):
+        with mock.patch.object(frame_host, "WINDOWS", True), mock.patch.object(subprocess, "run") as run:
+            frame_host.run_ssh(["ssh", "-V"], stderr=subprocess.DEVNULL, timeout=5)
+        run.assert_called_once_with(["ssh", "-V"], stderr=subprocess.DEVNULL, timeout=5)
+
+    def test_posix_call_is_unchanged(self):
+        with mock.patch.object(frame_host, "WINDOWS", False), mock.patch.object(subprocess, "run") as run:
+            frame_host.run_ssh(["ssh", "-V"], capture_output=True, check=True, timeout=5)
+        run.assert_called_once_with(["ssh", "-V"], capture_output=True, check=True, timeout=5)
+
+    def test_capture_rejects_explicit_streams(self):
+        for stream in ("stdout", "stderr"):
+            with self.subTest(stream=stream), self.assertRaises(ValueError):
+                self.run_command("", capture_output=True, **{stream: subprocess.DEVNULL})
+
+    @unittest.skipUnless(shutil.which("ssh"), "needs OpenSSH")
+    def test_real_ssh_failure_returns_stderr_without_hanging(self):
+        result = frame_host.run_ssh(["ssh", "-F", os.devnull, "-o", "BatchMode=yes",
+                                    "-o", "ConnectTimeout=2", "frame-control-test.invalid", "true"],
+                                   capture_output=True, stdin=subprocess.DEVNULL, text=True, timeout=5)
+        self.assertEqual(result.returncode, 255)
+        self.assertIn("Could not resolve hostname", result.stderr)

tests/test_input.py

@@ -6,6 +6,7 @@ identity line, then starts TLS as the *client*.
 
 Run: python3 -m unittest discover -s tests
 """
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import json
 import os
 import shutil
@@ -630,194 +631,3 @@ class PageQueue(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
-
-
-class PadEvents(unittest.TestCase):
-    """The trackpad and key row go through gamescope; accents and emoji go the KDE Connect way."""
-
-    @classmethod
-    def setUpClass(cls):
-        import server
-        cls.pad = staticmethod(server.pad_events)
-
-    def test_moves_clicks_and_scroll(self):
-        out, extra = self.pad([{"dx": 3, "dy": -2}, {"singleclick": True}, {"singlehold": True},
-                               {"singlerelease": True}, {"scroll": True, "dy": 1}, {"rightclick": True}])
-        self.assertEqual(out[0], {"dx": 3, "dy": -2})
-        self.assertEqual(out[1:3], [{"button": "left", "down": True}, {"button": "left", "down": False}])
-        self.assertEqual(out[3:5], [{"button": "left", "down": True}, {"button": "left", "down": False}])
-        self.assertEqual(out[5], {"scroll": [0, -15]})  # up = content follows the finger
-        self.assertEqual(out[6:], [{"button": "right", "down": True}, {"button": "right", "down": False}])
-        self.assertEqual(extra, [])
-
-    def test_keys_and_modifiers(self):
-        out, _ = self.pad([{"specialKey": 12}, {"specialKey": 1, "ctrl": True}, {"key": "c", "ctrl": True}])
-        self.assertEqual(out[:2], [{"key": 28, "down": True}, {"key": 28, "down": False}])
-        self.assertEqual([e["key"] for e in out[2:6]], [29, 14, 14, 29])  # Ctrl+Backspace
-        self.assertEqual([(e["key"], e["down"]) for e in out[6:]],
-                         [(29, True), (46, True), (46, False), (29, False)])  # Ctrl+C
-
-    def test_text_stays_ascii_through_gamescope(self):
-        out, slow = self.pad([{"key": "Hi "}, {"key": "there"}])
-        self.assertEqual(out, [{"text": "Hi there"}])
-        self.assertEqual(slow, [])
-
-    def test_keyboard_goes_to_kde_whole_and_in_order(self):
-        events = [{"key": "a"}, {"key": "é"}, {"specialKey": 12}, {"key": "c", "ctrl": True}, {"dx": 2, "dy": 1}]
-        out, slow = self.pad(events, kde=True)
-        self.assertEqual(out, [{"dx": 2, "dy": 1}])  # the pointer still goes through gamescope
-        self.assertEqual(slow, events[:4])  # the keyboard as sent, in order
-
-    def test_shifted_key_with_modifier(self):
-        out, _ = self.pad([{"key": "A", "ctrl": True}])
-        self.assertEqual([e["key"] for e in out], [29, 42, 30, 30, 42, 29])
-
-
-class PadDelivery(unittest.TestCase):
-    """remote_input's promises: "sent" means the whole batch is taken; accents go once, in order."""
-
-    class Agent:
-        def __init__(self, sent=True, state="ready"):
-            self.sent, self.state, self.got = sent, state, []
-
-        def send(self, events):
-            if events and self.sent:
-                self.got.append(events)
-            return {"state": self.state, "sent": self.sent and bool(events)}
-
-    def setUp(self):
-        import server
-        self.s = server
-        self.saved = (server._touch, server._input, server.KDE_WAIT)
-        server._touch, server._input = self.Agent(), self.Agent()
-        self.reset()
-
-    def tearDown(self):
-        self.s._touch, self.s._input, self.s.KDE_WAIT = self.saved
-        self.settle()
-        self.reset()
-
-    def reset(self):
-        self.s._kde_queue.clear()
-        self.s._kde_until = self.s._typed_until = 0.0
-        self.s._kde_worker[0] = None
-
-    def settle(self):
-        worker = self.s._kde_worker[0]
-        if worker:
-            worker.join(5)
-
-    def typed(self):
-        return [e for batch in self.s._input.got for e in batch]
-
-    def test_accent_only_batch_is_acknowledged_and_typed_once(self):
-        status = self.s.remote_input({"events": [{"key": "é"}]})
-        self.assertTrue(status["sent"])  # so the page doesn't send it again
-        self.settle()
-        self.assertEqual(self.typed(), [{"key": "é"}])
-
-    def test_mixed_text_stays_in_one_ordered_stream(self):
-        self.s.remote_input({"events": [{"key": "aéb"}, {"specialKey": 12}]})
-        self.settle()
-        self.assertEqual(self.typed(), [{"key": "aéb"}, {"specialKey": 12}])
-        self.assertEqual(self.s._touch.got, [])  # none of it split off through gamescope
-
-    def test_batch_gamescope_didnt_take_is_not_queued(self):
-        self.s._touch = self.Agent(sent=False, state="starting")
-        status = self.s.remote_input({"events": [{"dx": 1, "dy": 1}, {"key": "é"}]})
-        self.assertFalse(status["sent"])  # the page tries the whole batch again...
-        self.assertEqual(self.s._kde_queue, [])  # ...so the accent isn't queued twice
-
-    def test_waits_for_kde_connect_then_sends_without_more_input(self):
-        self.s._input = self.Agent(sent=False, state="starting")
-        self.s.remote_input({"events": [{"key": "é"}]})
-        time.sleep(0.2)
-        self.assertEqual(self.s._kde_queue, [{"key": "é"}])
-        self.s._input.sent = True
-        self.settle()
-        self.assertEqual(self.typed(), [{"key": "é"}])
-        self.assertEqual(self.s._kde_queue, [])
-
-    def test_later_ascii_waits_behind_a_pending_accent(self):
-        self.s._input = self.Agent(sent=False, state="starting")
-        self.s.remote_input({"events": [{"key": "é"}]})
-        self.s.remote_input({"events": [{"key": "x"}]})
-        self.assertEqual(self.s._touch.got, [])  # "x" can't overtake the "é"
-        self.assertEqual(self.s._kde_queue, [{"key": "é"}, {"key": "x"}])
-        self.s._input.sent = True
-        self.settle()
-        self.assertEqual(self.typed(), [{"key": "é"}, {"key": "x"}])
-
-    def test_queue_is_bounded_and_dropped_on_error(self):
-        self.s._input = self.Agent(sent=False, state="error")
-        self.s.remote_input({"events": [{"key": "é"}] * 150})
-        self.s.remote_input({"events": [{"key": "é"}] * 150})
-        self.settle()
-        self.assertEqual(self.s._kde_queue, [])
-        self.s._input = self.Agent(sent=False, state="starting")
-        self.s.KDE_WAIT = 0.3
-        self.s.remote_input({"events": [{"key": "é"}] * 150})
-        self.s.remote_input({"events": [{"key": "é"}] * 150})
-        self.assertLessEqual(len(self.s._kde_queue), self.s.KDE_QUEUE_LIMIT)
-        self.settle()
-        self.assertEqual(self.s._kde_queue, [])
-
-    def test_ascii_just_after_an_accent_stays_behind_it(self):
-        self.s.remote_input({"events": [{"key": "é"}]})
-        self.settle()
-        self.s.remote_input({"events": [{"key": "x"}]})  # KDE Connect may still be typing the é
-        self.settle()
-        self.assertEqual(self.s._touch.got, [])
-        self.assertEqual(self.typed(), [{"key": "é"}, {"key": "x"}])
-
-    def test_accent_just_after_gamescope_text_waits_for_it(self):
-        self.s.remote_input({"events": [{"key": "x" * 50}]})
-        self.assertEqual(self.s._touch.got, [[{"text": "x" * 50}]])
-        start = time.time()
-        self.s.remote_input({"events": [{"key": "é"}]})
-        self.settle()
-        self.assertGreater(time.time() - start, 0.6)  # 50 keys at 16 ms, plus the margin
-        self.assertEqual(self.typed(), [{"key": "é"}])
-
-    def test_typing_time_counts_every_key_transition(self):
-        t = self.s.typing_seconds
-        self.assertAlmostEqual(t([{"text": "ab"}]), 4 * 0.008)
-        self.assertAlmostEqual(t([{"text": "A"}]), 4 * 0.008)  # shift down, key down, key up, shift up
-        self.assertAlmostEqual(t([{"text": "x" * 500}]), 8.0)  # a long paste
-        self.assertAlmostEqual(t([{"key": 29, "down": True}, {"dx": 3, "dy": 0}]), 0.008)
-
-    def test_the_margin_is_added_once_not_per_request(self):
-        for _ in range(10):
-            self.s.remote_input({"events": [{"key": "ab"}]})
-        # ten requests of 4 transitions each: the work queues up, with no margin added per request
-        self.assertLess(self.s._typed_until - time.time(), 10 * 4 * 0.008 + 0.05)
-
-    def test_trimming_while_sending_doesnt_drop_unsent_events(self):
-        slow = self.Agent()
-        gate = threading.Event()
-        send = slow.send
-
-        def held(events):
-            gate.wait(5)
-            return send(events)
-        slow.send = held
-        self.s._input = slow
-        self.s.remote_input({"events": [{"key": "é"}] * 150})
-        time.sleep(0.2)  # the worker has taken its 150 and is mid-send
-        self.s.remote_input({"events": [{"key": "ü"}] * 150})
-        gate.set()
-        self.settle()
-        sent = self.typed()
-        self.assertEqual(sent[:150], [{"key": "é"}] * 150)
-        self.assertEqual(sent[150:], [{"key": "ü"}] * 150)  # none of the new ones went missing
-
-    def test_input_queued_as_the_worker_finishes_is_still_sent(self):
-        for _ in range(40):
-            self.reset()
-            self.s._input.got.clear()
-            self.s.remote_input({"events": [{"key": "é"}]})
-            time.sleep(0.002)
-            self.s.remote_input({"events": [{"key": "ü"}]})
-            self.settle()
-            self.assertEqual(self.s._kde_queue, [])
-            self.assertEqual(self.typed(), [{"key": "é"}, {"key": "ü"}])

tests/test_library_entrypoints.py

@@ -1,4 +1,5 @@
 """Every public sideload entry point reaches the mandatory five-slot writer."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import contextlib
 import io
 import json

tests/test_link.py

@@ -6,8 +6,10 @@ Run: python3 -m unittest discover -s tests
 """
 import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import http.client
+import io
 import json
 import os
+import shlex
 import shutil
 import socket
 import subprocess
@@ -44,6 +46,17 @@ def explain(msg):
     return None
 
 
+class FailureDetail(unittest.TestCase):
+    def test_an_address_that_failed_says_why_in_a_few_words(self):
+        # #87: the banner put each address's detail after the headline, and with the whole
+        # message as the detail it said everything twice ("...may be answering here..").
+        self.assertEqual(fl.failure_detail({"message": "A long sentence.", "short": "SSH identity changed"}),
+                         "SSH identity changed")
+        self.assertEqual(fl.failure_detail({"message": "The connection to the Frame dropped. Try again."}),
+                         "The connection to the Frame dropped. Try again.")
+        self.assertEqual(fl.failure_detail(None), "SSH failed")
+
+
 class Probe(unittest.TestCase):
     def test_answers_refusals_and_unknown_names(self):
         with socket.socket() as srv:
@@ -198,7 +211,8 @@ class Connecting(unittest.TestCase):
         rows = {p["host"]: p for p in s["probes"]}
         self.assertEqual(rows["nothing.invalid"]["state"], "unresolved")
         self.assertEqual(rows["::1"]["state"], "sshfailed")
-        self.assertIn("different headset", rows["::1"]["detail"])
+        # Its row says why in a few words: the banner's headline already has the whole sentence (#87).
+        self.assertEqual(rows["::1"]["detail"], "SSH identity changed")
         # Every ssh command was pointed at the winner, with the host key pinned per device.
         alias, opts = self.routes[-1]
         self.assertEqual(alias, "frame-t")
@@ -207,9 +221,10 @@ class Connecting(unittest.TestCase):
         self.assertIn(f"Port={self.port}", opts)
         master = [c for c in self.calls() if "ControlMaster=yes" in c][-1]
         self.assertIn("StrictHostKeyChecking=accept-new", master)  # first connection: nothing pinned yet
-        # ssh takes an option's first value: accept-new must come before the commands' own "yes".
-        self.assertLess(master.index("StrictHostKeyChecking=accept-new"), master.index("StrictHostKeyChecking=yes"))
-        self.assertIn("StrictHostKeyChecking=yes", opts)  # every other command checks the pinned key
+        self.assertNotIn("StrictHostKeyChecking=yes", master)
+        # This stand-in ssh saved no key, so commands may still save the first one (accept-new);
+        # test_a_first_connection_pins_and_then_checks_strictly has real pins.
+        self.assertIn("StrictHostKeyChecking=accept-new", opts)
         self.assertTrue(fd.known_hosts(d["id"]).parent.is_dir())  # where ssh saves the key it accepts
         # It learned: 127.0.0.1 works on this network.
         learned = {a["host"]: a for a in self.reg.get(d["id"])["addresses"]}
@@ -256,6 +271,9 @@ class Connecting(unittest.TestCase):
         s = self.link.snapshot()
         self.assertEqual((s["phase"], s["error"]["stage"]), ("failed", "login"))
         self.assertIn("SSH key", s["error"]["message"])
+        self.assertEqual(s["error"]["auth"], "denied")  # the page offers Set Up Connection
+        self.assertEqual(s["error"]["short"], "This computer's key refused")  # the header pill's words (#87)
+        self.assertEqual(s["probes"][0]["detail"], "This computer's key refused")
 
     def test_pinned_identity_is_checked_strictly(self):
         d = self.device("localhost")
@@ -265,6 +283,428 @@ class Connecting(unittest.TestCase):
         master = [c for c in self.calls() if "ControlMaster=yes" in c][-1]
         self.assertIn("StrictHostKeyChecking=yes", master)
 
+    def pins(self):
+        """The stand-in ssh checks host keys as OpenSSH does (tests/fakessh/ssh)."""
+        p = mock.patch.dict(os.environ, {"FAKESSH_PINS": "1"})
+        p.start()
+        self.addCleanup(p.stop)
+
+    def command(self, device, host="127.0.0.1"):
+        """One ssh command as the server runs it, with the route the connector applied."""
+        return subprocess.run(["ssh", *self.link.host_opts(device, host), device["alias"], "true"],
+                              capture_output=True, text=True, timeout=20)
+
+    def test_a_first_connection_pins_and_then_checks_strictly(self):
+        # 0.4.2 on Windows: "No ED25519 host key is known for frame-control-<id> and you have
+        # requested strict checking." Every command said "yes" before anything was saved, so one
+        # that ran before the connector's handshake saved the key (or without it) failed.
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        r = self.command(d)
+        self.assertEqual(r.returncode, 0, r.stderr)  # the first contact saves the key...
+        self.assertIn("Permanently added", r.stderr)
+        self.assertTrue(fd.pinned(d["id"]))
+        self.assertIn("StrictHostKeyChecking=yes", self.link.host_opts(d, "127.0.0.1"))  # ...then it's checked
+        self.assertEqual(self.reg.get(d["id"])["identity"], [k[1] for k in fd.pinned_keys(d["id"])])  # and recorded
+        # The connector's first handshake, for another new headset.
+        self.reg.remove_device(d["id"])
+        d = self.device("localhost")
+        self.link.connect(["start"])
+        s = self.link.snapshot()
+        self.assertEqual(s["phase"], "connected", s["error"])
+        self.assertTrue(fd.pinned(d["id"]))
+        self.assertTrue(self.reg.get(d["id"])["identity"])
+        alias, opts = self.routes[-1]
+        self.assertIn("StrictHostKeyChecking=yes", opts)  # every command after it checks strictly
+        self.assertNotIn("StrictHostKeyChecking=accept-new", opts)
+
+    def lose_pin(self, device_id, how):
+        f = fd.known_hosts(device_id)
+        if how == "deleted":
+            f.unlink()
+        elif how == "empty":
+            f.write_text("")
+        elif how == "unreadable":
+            f.chmod(0)
+            self.addCleanup(lambda: f.exists() and f.chmod(0o600))
+        elif how == "another alias":
+            f.write_text(f.read_text().replace(f"frame-control-{device_id}", "frame-control-someone-else"))
+        elif how == "not utf-8":
+            f.write_bytes(b"\xff\xfe" + f.read_bytes())
+
+    def test_a_lost_or_unusable_pin_fails_closed(self):
+        # Review pr85-review-r1: accept-new can't tell a new headset from one whose saved key
+        # went missing; real OpenSSH then trusted a replacement key. Once a headset had an
+        # identity, nothing is trusted again until the person checks it.
+        self.pins()
+        cases = ["deleted", "empty", "another alias", "not utf-8"]
+        if os.name == "posix" and os.geteuid() != 0:
+            cases.append("unreadable")  # root reads anything
+        for n, how in enumerate(cases):
+            with self.subTest(how=how):
+                self.hosts({"localhost": "ok"})
+                d = self.reg.add_device(f"frame-l{n}", port=self.port, hosts=[])
+                self.reg.add_address(d["id"], "localhost", kind="lan")
+                self.link.override = None
+                self.reg.set_active(d["id"])
+                self.link.connect(["switch"])
+                self.assertEqual(self.link.snapshot()["phase"], "connected")
+                self.link.close_master()
+                d = self.reg.get(d["id"])
+                self.lose_pin(d["id"], how)
+                self.hosts({"localhost": "wrong"})  # another device, or a reinstalled headset
+                r = self.command(d)
+                self.assertEqual(r.returncode, 255, r.stderr)
+                self.assertIn("Host key verification failed", r.stderr)
+                self.assertNotIn("Permanently added", r.stderr)
+                self.link.connect(["dropped"])
+                s = self.link.snapshot()
+                self.assertEqual((s["phase"], s["error"]["stage"]), ("failed", "identity"))
+                self.assertEqual(s["error"]["hostkey"]["state"], "missing")
+                self.assertIn("missing or can't be read", s["error"]["message"])
+                self.assertEqual(s["error"]["short"], "Saved SSH identity missing")
+                view = next(x for x in fl.devices_view(self.link)["devices"] if x["id"] == d["id"])
+                self.assertTrue(view["identity_lost"])
+                scan = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)["scan"]
+                self.assertFalse(scan["matches"] or scan["recorded_match"])  # not the key it had
+                self.hosts({"localhost": "ok"})
+                scan = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)["scan"]
+                self.assertTrue(scan["recorded_match"])  # its own key, as recorded
+                self.assertFalse(scan["matches"])  # but not usable from the file: trusting restores it
+                fl.devices_action(self.link, {"action": "identity-trust", "id": d["id"],
+                                              "fingerprint": scan["fingerprint"]}, None)
+                self.link.connect(["switch"])
+                self.assertEqual(self.link.snapshot()["phase"], "connected", self.link.snapshot()["error"])
+                self.link.close_master()
+
+    def test_a_key_check_only_reads_the_key(self):
+        # Review pr85-review-r1: with ForwardAgent yes in ~/.ssh/config, a device that accepts
+        # "none" got the agent and ran a command before anyone trusted it.
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "evil"})
+        os.environ["FAKESSH_CONFIG"] = json.dumps({"forwardagent": "yes", "remotecommand": "touch /tmp/x",
+                                                   "permitlocalcommand": "yes", "requesttty": "force"})
+        self.addCleanup(os.environ.pop, "FAKESSH_CONFIG", None)
+        for proxied in (False, True):
+            route = ("jump", "me@jumpy:2222") if proxied else (None, None)
+            with self.subTest(proxied=proxied), mock.patch.object(fl, "proxy_route", return_value=route):
+                t0 = time.monotonic()
+                scan = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)["scan"]
+                self.assertLess(time.monotonic() - t0, 10)  # stopped once it had the key, not left open
+                self.assertTrue(scan["fingerprint"].startswith("SHA256:"))
+                self.assertEqual([p.name for p in self.dir.iterdir() if p.name.startswith("evil-")], [])
+                call = [c for c in self.calls() if "PreferredAuthentications=none" in c][-1]
+                self.assertEqual(call[call.index("-F") + 1], "none")  # never ~/.ssh/config for the device
+                self.assertIn("-N", call)
+                hop = [c for c in call if c.startswith("ProxyCommand=")]
+                if proxied:
+                    # Review pr85-review-r2: ProxyJump's own ssh inherits the config (ForwardAgent,
+                    # LocalCommand); the scan builds the jump host's ssh itself, hardened.
+                    self.assertEqual(len(hop), 1)
+                    words = shlex.split(hop[0][len("ProxyCommand="):])
+                    self.assertEqual(words[-7:], ["-l", "me", "-p", "2222", "-W", "[%h]:%p", "jumpy"])
+                    for o in fl.Link.HOP_OPTS:
+                        self.assertIn(o, words)
+                    self.assertLess(call.index(hop[0]), call.index("HostKeyAlias=frame-control-" + d["id"]))
+                else:
+                    self.assertEqual(hop, [])
+                for o in ("ForwardAgent=no", "IdentityAgent=none", "ClearAllForwardings=yes", "RemoteCommand=none",
+                          "PermitLocalCommand=no", "RequestTTY=no", "PubkeyAuthentication=no"):
+                    self.assertIn(o, call)
+                self.assertLess(call.index("StrictHostKeyChecking=accept-new"), call.index("HostKeyAlias=frame-control-"
+                                                                                          + d["id"]))
+        self.assertFalse(fd.pinned(d["id"]))
+        self.assertEqual(sorted(p.name for p in fd.known_hosts(d["id"]).parent.iterdir()), [])  # no scan files
+
+    @unittest.skipIf(os.name != "posix", "the stand-in ssh runs ProxyCommand with /bin/sh")
+    def test_the_jump_hosts_command_line_is_quoted_whatever_the_names(self):
+        # Review pr85-review-r3: the hop's words went into the ProxyCommand line unquoted, so an
+        # ssh at /tmp/x/bin$(:>INJECTED)/ssh ran shell code; and an IPv6 jump host broke.
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        for n, name in enumerate(["with space", "bin$(touch INJECTED-0)", "back`touch INJECTED-1`tick",
+                                  "quote'it\"s", "per%cent %h %%", "semi;touch INJECTED-2"]):
+            with self.subTest(name=name):
+                bindir = self.dir / f"b{n}" / name
+                bindir.mkdir(parents=True)
+                (bindir / "ssh").symlink_to(FAKESSH / "ssh")
+                for spec, at in (("me@jumpy:2222", "jumpy"), ("[::1]:2200", "::1")):
+                    before = len(self.calls())
+                    with mock.patch.dict(os.environ, {"PATH": f"{bindir}{os.pathsep}{os.environ['PATH']}"}), \
+                            mock.patch.object(fl, "proxy_route", return_value=("jump", spec)):
+                        scan = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)["scan"]
+                    self.assertTrue(scan["fingerprint"].startswith("SHA256:"))
+                    hops = [c for c in self.calls()[before:] if "-W" in c]
+                    self.assertEqual(len(hops), 1, self.calls()[before:])
+                    self.assertEqual(hops[0][-1], at)  # the jump host, bare
+                    self.assertEqual(hops[0][hops[0].index("-W") + 1], "[localhost]:%d" % self.port)
+                    outer = [c for c in self.calls()[before:] if "PreferredAuthentications=none" in c][-1]
+                    line = next(c for c in outer if c.startswith("ProxyCommand="))
+                    self.assertTrue(line[len("ProxyCommand="):].startswith(shlex.quote(str(bindir / "ssh")
+                                                                                       .replace("%", "%%"))))
+                self.assertEqual([p.name for p in self.dir.rglob("INJECTED*")], [])
+                self.assertFalse(list(Path.cwd().glob("INJECTED*")))
+
+    def test_a_key_check_refuses_routes_it_cant_harden(self):
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        before = len(self.calls())
+        for route in (("command", "nc %h %p"), ("jump", "a,b"), ("jump", "-oProxyCommand=x"), ("jump", "ssh://a"),
+                      ("jump", "a b"), ("jump", "a%h"), ("jump", "jumpy:99999")):
+            with self.subTest(route=route), mock.patch.object(fl, "proxy_route", return_value=route):
+                with self.assertRaises(fd.DeviceError) as caught:
+                    fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)
+                self.assertIn("can't make safe", str(caught.exception))
+        self.assertFalse(any("PreferredAuthentications=none" in c for c in self.calls()[before:]))
+
+    def test_a_key_read_before_the_address_or_port_changed_isnt_trusted(self):
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        for change in ({"action": "update", "id": d["id"], "port": self.port + 1},
+                       {"action": "address-remove", "id": d["id"], "host": "localhost"}):
+            with self.subTest(change=change["action"]):
+                scan = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)["scan"]
+                fl.devices_action(self.link, change, None)
+                with self.assertRaises(fd.DeviceError):
+                    fl.devices_action(self.link, {"action": "identity-trust", "id": d["id"],
+                                                  "fingerprint": scan["fingerprint"]}, None)
+                self.assertFalse(fd.pinned(d["id"]))
+                self.reg.update_device(d["id"], port=self.port)
+                if not self.reg.get(d["id"])["addresses"]:
+                    self.reg.add_address(d["id"], "localhost", kind="lan")
+
+    def test_terminals_judge_identity_by_the_registry_not_a_frozen_route(self):
+        # Review pr85-review-r2: named_route used the device as routed (before its first key was
+        # recorded), so a Terminal window fell back to accept-new once the pin was deleted.
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        self.link.connect(["start"])
+        self.assertEqual(self.link.snapshot()["phase"], "connected")
+        self.assertFalse(self.link.routed_device.get("identity"))  # the frozen copy knows nothing of it
+        fd.known_hosts(d["id"]).unlink()
+        alias, opts = self.link.named_route()
+        self.assertIn("StrictHostKeyChecking=yes", opts)
+        self.assertNotIn("StrictHostKeyChecking=accept-new", opts)
+        self.hosts({"localhost": "wrong"})
+        r = subprocess.run(["ssh", *opts, alias, "true"], capture_output=True, text=True, timeout=20)
+        self.assertEqual(r.returncode, 255, r.stderr)
+        self.assertFalse(fd.pinned(d["id"]))
+
+    def test_a_key_saved_before_a_refused_login_is_kept_and_checked(self):
+        # Review pr85-review-r2: ssh saves the key during the key exchange; if the login is then
+        # refused, it was neither recorded nor protected, and the route stayed accept-new.
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "denied"})
+        self.link.connect(["start"])
+        s = self.link.snapshot()
+        self.assertEqual((s["phase"], s["error"]["stage"]), ("failed", "login"))
+        got = self.reg.get(d["id"])
+        self.assertEqual(got["identity"], [f for _, f in fd.pinned_keys(d["id"])])
+        self.assertTrue(got["identity_established"])
+        if os.name == "posix":
+            self.assertEqual(fd.known_hosts(d["id"]).stat().st_mode & 0o777, 0o600)
+        self.assertIn("StrictHostKeyChecking=yes", self.routes[-1][1])
+        fd.known_hosts(d["id"]).unlink()
+        self.hosts({"localhost": "wrong"})
+        r = self.command(self.reg.get(d["id"]))
+        self.assertEqual(r.returncode, 255)
+        self.assertNotIn("Permanently added", r.stderr)
+
+    def test_a_key_a_command_saved_tightens_the_route(self):
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "denied"})
+        with self.link.route_lock:
+            self.link.routed_device = d
+            self.link.apply(d["alias"], self.link.host_opts(d, "127.0.0.1"))
+        opts = self.routes[-1][1]
+        self.assertIn("StrictHostKeyChecking=accept-new", opts)
+        r = subprocess.run(["ssh", *opts, d["alias"], "true"], capture_output=True, text=True, timeout=20)
+        self.assertIn("Permanently added", r.stderr)
+        self.assertEqual(r.returncode, 255)  # saved the key, then refused the login
+        self.link.settle_pin()  # what the connector's loop does every tick while accept-new is applied
+        self.assertIn("StrictHostKeyChecking=yes", self.routes[-1][1])
+        self.assertNotIn("StrictHostKeyChecking=accept-new", self.routes[-1][1])
+        self.assertTrue(self.reg.get(d["id"])["identity"])
+
+    def test_editing_the_address_that_worked_keeps_the_identity_history(self):
+        # Review pr85-review-r2: last_ok lives on the address, so editing or removing it made a
+        # headset whose pin was gone (and had no fingerprint recorded) new again.
+        path = self.dir / "legacy.json"
+        path.write_text(json.dumps({"version": 1, "active": "abcd1234", "networks": {}, "devices": [
+            {"id": "abcd1234", "name": "Old", "alias": "frame-old", "user": "steamos", "port": 22,
+             "identity_files": [], "addresses": [{"host": "10.0.0.5", "kind": "lan", "label": "",
+                                                  "networks": [], "last_ok": 1790000000.0, "last_rtt_ms": 3}]}]}))
+        reg = fd.Registry(path)
+        self.assertTrue(reg.get("abcd1234")["identity_established"])  # migrated from last_ok
+        reg.update_address("abcd1234", "10.0.0.5", new_host="10.0.0.6")
+        reg.remove_address("abcd1234", "10.0.0.6")
+        reg.add_address("abcd1234", "10.0.0.7")
+        d = fd.Registry(path).get("abcd1234")  # saved, too
+        self.assertFalse(any(a.get("last_ok") for a in d["addresses"]))
+        self.assertTrue(fd.identity_established(d))
+        self.assertEqual(self.link.strictness(d), "yes")
+        # A connection that works sets it as well, for a headset added since.
+        n = self.reg.add_device("frame-new", hosts=["10.0.0.8"])
+        self.reg.record_success(n["id"], "10.0.0.8", None, 1)
+        self.reg.remove_address(n["id"], "10.0.0.8")
+        self.assertTrue(self.reg.get(n["id"])["identity_established"])
+
+    def test_ssh_last_words_arrive_even_when_the_reader_lags(self):
+        # Review pr85-review-r2: ssh's exit with nothing queued yet was taken as the end, and a
+        # late reader lost "Permission denied" ("ssh stopped").
+        self.pins()
+        link = fl.Link(self.reg, env_alias=None, mux_base=["ssh", "-o", "BatchMode=yes"], control=None,
+                       apply=lambda *a: None, explain=explain)
+        self.addCleanup(link.stop)
+        real = threading.Thread
+
+        class Late(real):
+            def __init__(self, *a, target=None, **kw):
+                if target is not None and getattr(target, "__name__", "") == "tail":
+                    inner = target
+
+                    def target():
+                        time.sleep(1)
+                        inner()
+                super().__init__(*a, target=target, **kw)
+        self.device("localhost")
+        self.hosts({"localhost": "denied"})
+        with mock.patch.object(fl.threading, "Thread", Late):
+            link.connect(["start"])
+        s = link.snapshot()
+        self.assertEqual((s["error"]["stage"], s["error"].get("auth")), ("login", "denied"), s["error"])
+        self.assertIn("SSH key", s["error"]["message"])
+
+    def test_forgetting_an_identity_is_refused(self):
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        self.link.connect(["start"])
+        saved = fd.known_hosts(d["id"]).read_text()
+        with self.assertRaises(fd.DeviceError) as caught:
+            fl.devices_action(self.link, {"action": "forget-identity", "id": d["id"]}, None)
+        self.assertIn("identity-scan", str(caught.exception))
+        self.assertEqual(fd.known_hosts(d["id"]).read_text(), saved)
+
+    def test_without_a_shared_connection_ssh_writes_to_a_file_not_a_pipe(self):
+        # Windows: no ControlMaster, and its OpenSSH can block writing to a stderr pipe.
+        self.pins()
+        tmp = self.dir / "tmp"
+        tmp.mkdir()
+        link = fl.Link(self.reg, env_alias=None, mux_base=["ssh", "-o", "BatchMode=yes"], control=None,
+                       apply=lambda *a: None, explain=explain)
+        self.addCleanup(link.stop)
+        real = subprocess.Popen
+        seen = []
+
+        def popen(argv, **kw):
+            if "-v" in argv:  # the handshake (run_ssh calls go through Popen too)
+                seen.append(kw.get("stderr"))
+            return real(argv, **kw)
+        with mock.patch.object(tempfile, "tempdir", str(tmp)), mock.patch.object(fl.subprocess, "Popen", popen):
+            d = self.device("localhost")
+            self.hosts({"localhost": "ok"})
+            link.connect(["start"])
+            s = link.snapshot()
+            self.assertEqual(s["phase"], "connected", s["error"])
+            self.assertEqual([st["state"] for st in s["stages"]], ["done"] * 5)
+            self.assertIn("saved this headset's identity", next(st for st in s["stages"] if st["id"] == "identity")["detail"])
+            self.reg.update_device(d["id"], user="nobody")
+            self.hosts({"localhost": "denied"})
+            link.connect(["switch"])
+            s = link.snapshot()
+            self.assertEqual((s["phase"], s["error"]["stage"], s["error"].get("auth")), ("failed", "login", "denied"))
+        self.assertTrue(seen and all(isinstance(x, int) for x in seen))  # a file descriptor, never PIPE
+        self.assertNotIn(subprocess.PIPE, seen)
+        for _ in range(50):  # the reader removes its file once ssh has exited
+            if not list(tmp.iterdir()):
+                break
+            time.sleep(0.05)
+        self.assertEqual(list(tmp.iterdir()), [])
+
+    def test_a_changed_key_is_shown_never_accepted_and_trusted_on_request(self):
+        # 0.4.2 on Linux and Windows: "WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!", with
+        # "Run Set Up Connection again" as the advice, which can't replace the saved key.
+        self.pins()
+        d = self.device("localhost")
+        self.hosts({"localhost": "ok"})
+        self.link.connect(["start"])
+        self.assertEqual(self.link.snapshot()["phase"], "connected")
+        saved = fd.known_hosts(d["id"]).read_text()
+        old = fd.pinned_keys(d["id"])
+        self.link.close_master()
+        self.hosts({"localhost": "wrong"})  # SteamOS reinstalled: a new host key
+        self.link.connect(["dropped"])
+        s = self.link.snapshot()
+        self.assertEqual((s["phase"], s["error"]["stage"]), ("failed", "identity"))
+        shown = s["error"]["hostkey"]
+        self.assertEqual((shown["state"], shown["type"], shown["host"]), ("changed", "ssh-ed25519", "localhost"))
+        self.assertTrue(shown["fingerprint"].startswith("SHA256:"))
+        self.assertIn("Devices tab", s["error"]["message"])
+        self.assertEqual(s["error"]["short"], "SSH identity changed")
+        self.assertEqual(fd.known_hosts(d["id"]).read_text(), saved)  # never accepted on its own
+        r = self.command(d)
+        self.assertEqual(r.returncode, 255)
+        self.assertIn("REMOTE HOST IDENTIFICATION HAS CHANGED", r.stderr)  # nor by any command
+        # Trusting needs the key read first, and exactly the fingerprint shown.
+        with self.assertRaises(fd.DeviceError):
+            fl.devices_action(self.link, {"action": "identity-trust", "id": d["id"],
+                                          "fingerprint": shown["fingerprint"]}, None)
+        out = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)
+        scan = out["scan"]
+        self.assertEqual(scan["fingerprint"], shown["fingerprint"])
+        self.assertFalse(scan["matches"])
+        self.assertEqual(scan["saved"], [{"type": t, "fingerprint": f} for t, f in old])
+        self.assertEqual(fd.known_hosts(d["id"]).read_text(), saved)  # reading it saves nothing
+        self.assertEqual(sorted(p.name for p in fd.known_hosts(d["id"]).parent.iterdir()), [d["id"]])  # no scan files
+        call = [c for c in self.calls() if "PreferredAuthentications=none" in c][-1]  # no login offered
+        self.assertLess(call.index("StrictHostKeyChecking=accept-new"), call.index("StrictHostKeyChecking=yes"))
+        self.assertNotIn(f"UserKnownHostsFile={fd.known_hosts_opt(d['id'])}",
+                         call[:call.index("StrictHostKeyChecking=yes")])  # a throwaway file, first
+        with self.assertRaises(fd.DeviceError):
+            fl.devices_action(self.link, {"action": "identity-trust", "id": d["id"], "fingerprint": "SHA256:other"}, None)
+        self.link.scans[d["id"]]["at"] -= fl.SCAN_TTL + 1
+        with self.assertRaises(fd.DeviceError):  # shown too long ago
+            fl.devices_action(self.link, {"action": "identity-trust", "id": d["id"],
+                                          "fingerprint": shown["fingerprint"]}, None)
+        fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)
+        with mock.patch.object(self.link, "kick") as kick:
+            out = fl.devices_action(self.link, {"action": "identity-trust", "id": d["id"],
+                                                "fingerprint": shown["fingerprint"]}, None)
+        kick.assert_called_with("switch")
+        self.assertEqual(fd.pinned_keys(d["id"]), [("ssh-ed25519", shown["fingerprint"])])  # the old key is gone
+        self.assertEqual(next(x for x in out["devices"] if x["id"] == d["id"])["keys"],
+                         [{"type": "ssh-ed25519", "fingerprint": shown["fingerprint"]}])
+        self.link.connect(["switch"])
+        self.assertEqual(self.link.snapshot()["phase"], "connected", self.link.snapshot()["error"])
+        out = fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)
+        self.assertTrue(out["scan"]["matches"])
+
+    def test_test_now_never_saves_a_key(self):
+        self.pins()
+        d = self.device("127.0.0.1")
+        self.hosts({"127.0.0.1": "ok"})
+        self.link.test(d["id"])
+        rows = self.link.snapshot()["tests"][d["id"]]["rows"]
+        self.assertEqual(rows[0]["ssh"], "unpinned")
+        self.assertFalse(fd.pinned(d["id"]))
+
+    def test_reading_a_key_from_a_headset_that_doesnt_answer_says_why(self):
+        self.pins()
+        d = self.device("nothing.invalid")
+        with self.assertRaises(fd.DeviceError) as caught:
+            fl.devices_action(self.link, {"action": "identity-scan", "id": d["id"]}, None)
+        self.assertIn("Can't find the Frame", str(caught.exception))
+        self.assertEqual([p.name for p in fd.known_hosts(d["id"]).parent.iterdir()], [])
+
     def test_ssh_goes_to_the_ipv4_address_that_answered(self):
         self.device("localhost")
         self.hosts({"localhost": "ok"})
@@ -500,7 +940,7 @@ class Connecting(unittest.TestCase):
                      {"action": "update", "id": d["id"], "port": 2222},
                      {"action": "address-remove", "id": d["id"], "host": "localhost"},
                      {"action": "address-update", "id": d["id"], "host": "localhost", "newHost": "127.0.0.1"},
-                     {"action": "forget-identity", "id": d["id"]}):
+                     {"action": "identity-trust", "id": d["id"], "fingerprint": "SHA256:x"}):
             with self.assertRaises(fd.DeviceError, msg=body):
                 fl.devices_action(self.link, body, open_setup=None, busy=lambda: 1)
         # Renaming, or changing another headset, is fine.
@@ -599,6 +1039,260 @@ class Connecting(unittest.TestCase):
         (self.dir / "ssh" / "config").write_text("Host frame lab-*\n  HostName 10.0.0.7\n")  # someone's own `frame`
         self.assertEqual(fl.next_alias(self.link), "frame-2")
 
+    # ---- what a failure leaves for a problem report ----
+    def stderr(self):
+        return quiet_log(self)
+
+    def report(self):
+        import frame_report as fr
+        done = threading.Thread(target=lambda: None)
+        done.start()
+        done.join()
+        with mock.patch.object(fr, "link", self.link), \
+                mock.patch.dict(fr._ssh, {"thread": done, "line": "SSH: system OpenSSH, OpenSSH 9.9p1, LibreSSL 3.3.6"}):
+            return fr.diagnostics()
+
+    def test_each_failure_goes_to_the_server_log_scrubbed(self):
+        err = self.stderr()
+        self.device("steamdeck-jane.invalid", "localhost")
+        self.hosts({"localhost": "denied"})
+        self.link.connect(["start"])
+        line = err.getvalue()
+        self.assertIn("frame_link: login failed: The Frame didn't accept this computer's SSH key.", line)
+        self.assertIn("addresses: hostname unresolved; hostname->ipv4", line)
+        for leaked in ("steamdeck-jane", "127.0.0.1", "localhost"):
+            self.assertNotIn(leaked, line)
+        self.assertEqual(self.link.last_failure["stage"], "login")
+
+    def test_reports_carry_a_connection_summary_in_fixed_words(self):
+        self.stderr()
+        self.device("steamdeck-jane.invalid", "frame-t.invalid")
+        (self.dir / "ssh" / "config").write_text(
+            f"{fd.begin_mark('frame-t')}\nHost frame-t\n  HostName 192.168.1.50\n  User steamos\n{fd.end_mark('frame-t')}\n"
+            "Host frame-t\n  HostName 10.0.0.7\n")
+        self.link.connect(["start"])
+        text = self.report()
+        self.assertIn("Connection: failed at find, attempt 1 (Starting up)", text)
+        self.assertIn("Headsets: 1 saved; active alias custom (saved, 2 address(es))", text)
+        self.assertIn("Error: find, frame_not_set_up", text)
+        self.assertRegex(text, r"Last failure: find, frame_not_set_up, 0 min \d+ s ago")
+        self.assertIn("Addresses tried: hostname unresolved; hostname unresolved", text)
+        self.assertIn("Network: gateway yes, Tailscale not installed", text)
+        self.assertIn("SSH: system OpenSSH, OpenSSH 9.9p1", text)
+        self.assertIn("~/.ssh/config: managed block for the active alias yes (1 managed in all); "
+                      "hand-written Host for it yes", text)
+        # No free text from the error or ssh at all, and not the custom alias.
+        for leaked in ("steamdeck-jane", "Could not resolve", "Can't find", "192.168", "10.0.0.7", "steamos",
+                       "frame-t", str(self.dir)):
+            self.assertNotIn(leaked, text)
+
+    def test_a_failure_on_the_last_headset_leaves_nothing_of_it_after_switching(self):
+        self.stderr()
+        a = self.device("steamdeck-jane.invalid")
+        self.link.connect(["start"])
+        b = self.reg.add_device("frame-2", port=self.port, hosts=[])
+        self.reg.add_address(b["id"], "localhost", kind="lan")
+        self.hosts({"localhost": "ok"})
+        self.reg.set_active(b["id"])
+        self.link.connect(["switch"])
+        self.assertEqual(self.link.snapshot()["phase"], "connected")
+        text = self.report()
+        self.assertIn("Connection: connected via hostname->ipv4", text)
+        self.assertRegex(text, r"Last failure: find, frame_not_set_up, ")
+        self.assertNotIn("steamdeck-jane", text)
+        self.assertNotEqual(a["id"], b["id"])
+
+    def test_the_headsets_alias_and_name_stay_out_of_the_log(self):
+        import frame_report as fr
+        err = self.stderr()
+        d = self.reg.add_device("jane-office.example.com", name="Jane Doe's work headset", hosts=[])
+        self.reg.set_active(d["id"])
+        self.link.connect(["start"])
+        self.assertIn("find failed: The active headset has no addresses.", err.getvalue())
+        # A message that names it anyway (any case) goes too, in the log and so in a report's log.
+        self.link.note_failure("ssh", "JANE-OFFICE.EXAMPLE.COM: jane doe's work headset stopped answering")
+        log = self.dir / "server.log"
+        log.write_text(err.getvalue())
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_LOG": str(log)}):
+            with mock.patch.object(fr, "link", self.link), mock.patch.dict(fr._ssh, {"thread": None, "line": "SSH: x"}):
+                text = fr.diagnostics(include_logs=True)
+        self.assertIn("frame_link: ssh failed", text)
+        for leaked in ("jane", "Jane", "JANE"):
+            self.assertNotIn(leaked, err.getvalue())
+            self.assertNotIn(leaked, text)
+
+
+def quiet_log(test):
+    """Catch frame_link's log lines, starting with nothing remembered."""
+    fl._logged.clear()
+    err = io.StringIO()
+    p = mock.patch.object(sys, "stderr", err)
+    p.start()
+    test.addCleanup(p.stop)
+    return err
+
+
+class FailureLog(unittest.TestCase):
+    def test_the_same_failure_isnt_logged_every_retry(self):
+        err = quiet_log(self)
+        for _ in range(3):
+            fl.log_failure("find", "The Frame isn't answering.", "", [{"host": "frame.local", "state": "timeout"}])
+        self.assertEqual(err.getvalue().count("frame_link:"), 1)
+        for v in fl._logged.values():
+            v["at"] -= fl.LOG_REPEAT_EVERY + 1
+        fl.log_failure("find", "The Frame isn't answering.", "", [{"host": "frame.local", "state": "timeout"}])
+        self.assertIn("(and 2 more times)", err.getvalue())
+        self.assertNotIn("frame.local", err.getvalue())
+
+    def test_interleaved_failures_are_throttled_too(self):
+        err = quiet_log(self)
+        for _ in range(4):
+            fl.log_failure("find", "The Frame isn't answering.")
+            fl.log_failure("login", "The Frame didn't accept this computer's SSH key.")
+        self.assertEqual(err.getvalue().count("frame_link:"), 2)
+        for i in range(fl.LOG_REMEMBER + 10):  # many different failures: memory stays bounded
+            fl.log_failure("ssh", f"failure number {i}")
+        self.assertLessEqual(len(fl._logged), fl.LOG_REMEMBER)
+
+    def test_hosts_ssh_names_go_known_or_not_and_whatever_the_case(self):
+        err = quiet_log(self)
+        fl.log_failure("ssh", "ssh stopped", "ssh: Could not resolve hostname bastion-jane: Name or service not known")
+        fl.log_failure("ssh", "ssh stopped", "channel 0: open failed: connect to host jane-office.example.com port 22")
+        fl.log_failure("ssh", "ssh stopped", "kex_exchange_identification: Connection reset by steamdeck-jane",
+                       hosts=["STEAMDECK-JANE"])
+        fl.log_failure("ssh", "Timed out talking to frame-jane", "")
+        out = err.getvalue()
+        self.assertIn("hostname <host>", out)
+        self.assertIn("connect to host <host> port 22", out)
+        for leaked in ("bastion-jane", "jane-office", "steamdeck-jane", "frame-jane"):
+            self.assertNotIn(leaked, out)
+
+    def test_headsets_named_like_sshs_words_dont_shield_the_real_host(self):
+        err = quiet_log(self)
+        for saved in ("host", "hostname", "to"):
+            fl.log_failure("ssh", "ssh stopped", "ssh: connect to host bastion-jane port 22: Connection refused",
+                           hosts=[saved])
+            fl.log_failure("ssh", "ssh stopped", "ssh: Could not resolve hostname jane-office.example.com: not known",
+                           hosts=[saved])
+        out = err.getvalue()
+        self.assertIn("connect to host <host> port 22", out)
+        self.assertIn("hostname <host>", out)
+        for leaked in ("bastion-jane", "jane-office"):
+            self.assertNotIn(leaked, out)
+        self.assertEqual(fl.hide_hosts("<host> and frame", ["host", "frame"]), "<host> and <host>")
+
+    def test_whole_names_go_before_sshs_words_and_only_real_tokens_are_spared(self):
+        for name, said in (("Jane Doe's work headset", "Timed out talking to Jane Doe's work headset"),
+                           ("Jane to Doe headset", "Jane to Doe headset stopped answering"),
+                           ("<Jane Doe>", "<Jane Doe> stopped answering")):
+            out = fl.scrub_failure(said, [name])
+            self.assertTrue(out.startswith("<host>") or out == "Timed out talking to <host>", out)
+            for leaked in ("Jane", "Doe"):
+                self.assertNotIn(leaked, out)
+        self.assertEqual(fl.scrub_failure("Timed out talking to Jane Doe's work headset", ["Jane Doe's work headset"]),
+                         "Timed out talking to <host>")
+        self.assertEqual(fl.hide_hosts("<user>@<host>: <ip>", ["user", "host", "ip"]), "<user>@<host>: <ip>")
+
+    def test_windows_user_names_with_spaces_go_whole(self):
+        err = quiet_log(self)
+        with mock.patch.object(fl.frame_telemetry, "_user_names", return_value=set()):
+            fl.log_failure("ssh", r"Bad owner or permissions on C:\Users\Jane Doe/.ssh/config", "")
+            fl.log_failure("login", "The Frame didn't accept this computer's SSH key.",
+                           "Jane Doe@frame: Permission denied (publickey).")
+            fl.log_failure("login", "refused", r"debug | ssh said: CORP\jane@frame's password: denied")
+        out = err.getvalue()
+        self.assertIn(r"C:\Users\<user>/.ssh/config", out)
+        self.assertIn("<user>@<host>: Permission denied", out)
+        for leaked in ("Jane", "Doe", "jane", "CORP"):
+            self.assertNotIn(leaked, out)
+
+    def test_whole_ssh_user_at_host_fields_and_home_folders_go(self):
+        import frame_telemetry as tm
+        with mock.patch.object(tm, "_user_names", return_value=set()):
+            self.assertEqual(tm.scrub(r"CORP\Jane Doe@jane-office.example.com: Permission denied (publickey)."),
+                             "<user>@<host>: Permission denied (publickey).")
+            self.assertEqual(tm.scrub("jane@jane-office.example.com's password: "), "<user>@<host>'s password: ")
+            self.assertEqual(tm.scrub(r"Bad owner on C:\Users\O'Brien/.ssh/config"), r"Bad owner on C:\Users\<user>/.ssh/config")
+            self.assertEqual(tm.scrub(r"c:\users\Zoë Smith.Jr\.ssh\config"), r"c:\users\<user>\.ssh\config")
+            self.assertEqual(tm.scrub("/users/O'Brien/x and /HOME/jane doe/y"), "/users/<user>/x and /HOME/<user>/y")
+            self.assertEqual(tm.scrub("write to me@example.com today"), "write to <email> today")
+
+
+class ConnectionDiagnostics(unittest.TestCase):
+    def test_address_kinds_never_the_address(self):
+        self.assertEqual(fl.address_kind("frame.local", "fe80::1%eth0"), ".local->ipv6 link-local")
+        self.assertEqual(fl.address_kind("frame.local", "192.168.1.5"), ".local->ipv4")
+        self.assertEqual(fl.address_kind("frame.local"), ".local")
+        self.assertEqual(fl.address_kind("fe80::1%5"), "ipv6 link-local")
+        self.assertEqual(fl.address_kind("2001:db8::1"), "ipv6")
+        self.assertEqual(fl.address_kind("192.168.1.5", "192.168.1.5"), "ipv4")
+        self.assertEqual(fl.address_kind("100.101.102.103"), "tailscale")
+        self.assertEqual(fl.address_kind("frame.tail1234.ts.net", "100.101.102.103"), "tailscale")
+        self.assertEqual(fl.address_kind("steamdeck"), "hostname")
+        self.assertEqual(fl.probes_summary([{"host": "frame", "label": "from ~/.ssh/config", "state": "timeout"}]),
+                         "alias hostname timeout")
+
+    def test_hidden_hosts_leave_the_rest(self):
+        self.assertEqual(fl.hide_hosts("frame_link: Could not resolve hostname frame", ["frame"]),
+                         "frame_link: Could not resolve hostname <host>")
+        self.assertEqual(fl.hide_hosts("ssh frame to frame.local", ["frame.local", "frame"], keep=("frame",)),
+                         "ssh frame to <host>")
+        self.assertEqual(fl.hide_hosts("reset by SteamDeck", ["steamdeck"]), "reset by <host>")
+        self.assertEqual(fl.hide_operands("The headset took too long to answer."), "The headset took too long to answer.")
+
+    def test_ssh_version_is_rebuilt_from_its_numbers(self):
+        import frame_report as fr
+        for said, want in (("OpenSSH_for_Windows_9.5p1, LibreSSL 3.8.2\n", "OpenSSH for Windows 9.5p1, LibreSSL 3.8.2"),
+                           ("OpenSSH_9.9p1, LibreSSL 3.3.6\n", "OpenSSH 9.9p1, LibreSSL 3.3.6"),
+                           ("OpenSSH_8.9p1 Ubuntu-3ubuntu0.10, OpenSSL 3.0.2 15 Mar 2022\n", "OpenSSH 8.9p1"),
+                           ("OpenSSH_9.6p1, OpenSSL 3.0.13 30 Jan 2024\n", "OpenSSH 9.6p1, OpenSSL 3.0.13"),
+                           ("OpenSSH_9.9p1-Jane-Doe-Laptop, LibreSSL 3.3.6\n", "unknown"),
+                           ("OpenSSH_9.9p1, OpenSSL jane-laptop\n", "OpenSSH 9.9p1"),
+                           (r"C:\Users\Jane\OpenSSH-portable\ssh.exe: not found", "unknown"),
+                           ("", "unknown")):
+            with mock.patch.object(fr.frame_host, "run_ssh", return_value=subprocess.CompletedProcess([], 0, "", said)):
+                self.assertEqual(fr.ssh_version("ssh"), want, said)
+
+    def test_only_the_default_alias_is_named(self):
+        import frame_report as fr
+        self.assertEqual(fr.alias_kind("frame"), 'default ("frame")')
+        self.assertEqual(fr.alias_kind("jane-office.example.com"), "custom")
+
+    def test_a_slow_path_never_holds_up_a_report(self):
+        import frame_report as fr
+        release = threading.Event()
+
+        def slow():
+            release.wait(5)
+            return []
+        with mock.patch.dict(fr._ssh, {"thread": None, "line": None}), mock.patch.object(fr, "_ssh_on_path", slow), \
+                mock.patch.object(fr, "link", None), mock.patch.object(fr.shutil, "which", return_value="/usr/bin/ssh"), \
+                mock.patch.object(fr.frame_host, "run_ssh",
+                                  return_value=subprocess.CompletedProcess([], 0, "", "OpenSSH_9.9p1, LibreSSL 3.3.6\n")):
+            t0 = time.monotonic()
+            self.assertIn("Connection: no connector", fr.diagnostics())
+            self.assertIn("SSH: still being checked", fr.ssh_line())
+            self.assertLess(time.monotonic() - t0, 2)
+            thread = fr._ssh["thread"]
+            release.set()
+            thread.join(5)
+            self.assertTrue(fr._ssh["line"].startswith("SSH: "))
+            self.assertNotEqual(fr.ssh_line(), "SSH: still being checked")
+
+    def test_ssh_kinds(self):
+        import frame_report as fr
+        for path, kind in ((r"C:\WINDOWS\System32\OpenSSH\ssh.exe", "Windows OpenSSH (System32)"),
+                           (r"C:\Program Files\OpenSSH\ssh.exe", "OpenSSH in Program Files"),
+                           (r"C:\Program Files\Git\usr\bin\ssh.exe", "Git for Windows"),
+                           ("/usr/bin/ssh", "system OpenSSH"), ("/opt/homebrew/bin/ssh", "Homebrew or /usr/local"),
+                           ("/home/jane/bin/ssh", "other"), (None, "not found")):
+            self.assertEqual(fr.ssh_path_kind(path), kind)
+
+    def test_no_connector_says_so(self):
+        import frame_report as fr
+        with mock.patch.object(fr, "link", None):
+            self.assertIn("Connection: no connector", fr.diagnostics())
+
 
 @unittest.skipIf(os.name == "nt", "the stand-in ssh is a POSIX script")
 class ServerConnection(unittest.TestCase):

tests/test_link_ui.py

@@ -0,0 +1,136 @@
+"""The connection pill, the offline banner and the Devices tab's selection: the page's own
+functions from ui/index.html, run in Node against a minimal DOM (#87)."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import pathlib
+import re
+import shutil
+import subprocess
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+PAGE = (ROOT / "ui/index.html").read_text(encoding="utf-8")
+
+
+def between(start, end):
+    return PAGE[PAGE.index(start):PAGE.index(end)]
+
+
+SETUP = r'''
+const assert = require('node:assert/strict');
+const elements = new Map();
+const $ = id => {
+  if (!elements.has(id)) elements.set(id, {id, textContent: '', innerHTML: '', title: '', hidden: true, value: ''});
+  return elements.get(id);
+};
+const esc = s => String(s).replace(/[&<>"']/g, c => ({'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'}[c]));
+const serverNow = () => 1000;
+const activeStage = s => (s.stages || []).find(x => x.state === 'active');
+const ago = () => 'a minute ago';
+const openTrust = () => {};
+const window = {};
+let online = false;
+const link = {live: true, s: null};
+const dv = {list: [], sel: null, data: null, found: 'x', editing: 'y'};
+let rendered = 0;
+const renderDevices = () => { rendered++; };
+let refuse = false;
+const act = async (label, fn) => refuse ? undefined : fn();
+const api = async () => ({ok: true});
+const STAGES = [{id: 'find', label: 'Finding the headset', state: 'done'},
+                {id: 'identity', label: "Checking the headset's identity", state: 'failed'}];
+const changed = {phase: 'failed', retry_at: 1012, device: {id: 'd1', name: 'Office Frame'}, network: {name: 'Home'},
+  stages: STAGES, probes: [{host: 'frame.local', detail: 'SSH identity changed'}],
+  error: {stage: 'identity', short: 'SSH identity changed', hostkey: {state: 'changed'},
+          message: 'This address answered with a different SSH identity from the one saved for Office Frame. '
+                 + 'If not, a different device may be answering here.'}};
+'''
+
+
+@unittest.skipUnless(shutil.which("node"), "Node runs the page's own functions")
+class LinkUI(unittest.TestCase):
+    def run_page(self, checks):
+        code = (between("function netLabel(s) {", "function renderConnDlg() {")
+                + between("async function useDevice(id) {", "async function devAction(")
+                + between("function deviceStatus(d) {", "function renderDevices() {"))
+        script = SETUP + code + "\n(async () => {\n" + checks + "\n})().catch(e => { console.error(e); process.exitCode = 1; });"
+        r = subprocess.run(["node", "-e", script], capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stderr)
+
+    def test_the_pill_leads_with_the_reason(self):
+        # The header pill cut off "Offline: checking the headset's identity failed · retry in…":
+        # the reason comes first, in a few words, and only the countdown gets cut.
+        self.run_page(r'''
+  link.s = changed;
+  renderPill();
+  assert.match($('conn').innerHTML, /<b>Office Frame<\/b><span>SSH identity changed · retry in 12 s<\/span>/);
+  assert.equal($('conn').title, 'Office Frame is offline: SSH identity changed · retry in 12 s. Click for details.');
+  // Without a short reason: the stage that failed.
+  link.s = {...changed, retry_at: null, error: {stage: 'identity', message: 'Something.'}};
+  renderPill();
+  assert.match($('conn').innerHTML, /<span>Checking the headset&#39;s identity failed<\/span>/);
+''')
+
+    def test_the_banner_never_doubles_a_full_stop(self):
+        # "…may be answering here.." and "…(Developer Mode must be on).." (#87).
+        self.run_page(r'''
+  link.s = changed;
+  renderBanner();
+  assert.equal($('offDetail').textContent, 'Office Frame on Home. Tried frame.local: SSH identity changed. Trying again in 12 s.');
+  link.s = {...changed, probes: [
+    {host: 'frame.local', detail: "The Frame didn't accept this computer's SSH key. Set Up Connection pairs this computer with it again (Developer Mode must be on)."},
+    {host: '100.64.0.2', detail: 'No answer'}]};
+  renderBanner();
+  const text = $('offDetail').textContent;
+  assert.ok(!/\.\./.test(text), text);
+  assert.ok(text.includes("frame.local: the Frame didn't accept"), text);
+  assert.ok(text.includes('must be on); 100.64.0.2: no answer. Trying'), text);
+  assert.equal(asClause('SSH identity changed.'), 'SSH identity changed');  // abbreviations keep their case
+  assert.equal(asClause('Answered in 3 ms'), 'answered in 3 ms');
+''')
+
+    def test_the_devices_list_keeps_the_whole_message_within_reach(self):
+        self.run_page(r'''
+  link.s = changed;
+  const [dot, text, full] = deviceStatus({active: true, addresses: []});
+  assert.equal(dot, 'off');
+  assert.equal(text, 'SSH identity changed');
+  assert.equal(full, changed.error.message);  // the row's tooltip
+''')
+
+    def test_using_a_headset_selects_it(self):
+        # After "Use this headset" on Office Frame, the last headset's details stayed on show.
+        self.run_page(r'''
+  dv.list = [{id: 'd0', name: 'Living Room Frame', active: true}, {id: 'd1', name: 'Office Frame', active: false}];
+  dv.sel = 'd0';
+  await useDevice('d1');
+  assert.equal(dv.sel, 'd1');
+  assert.equal(dv.found, null);
+  assert.equal(dv.editing, null);
+  assert.equal(rendered, 1);
+  // Refused (an install is running): the selection stays, and the header shows the one in use.
+  dv.list = [{id: 'd0', name: 'Living Room Frame', active: true}, {id: 'd2', name: 'Spare', active: false}];
+  dv.sel = 'd0'; refuse = true;
+  await useDevice('d2');
+  assert.equal(dv.sel, 'd0');
+  assert.equal($('devSel').value, 'd0');
+''')
+
+
+class HeaderLayout(unittest.TestCase):
+    def test_the_devices_tab_explanation_wraps(self):
+        # It was cut to one line with no way to read the rest.
+        self.assertIn(".dev-problem .s { white-space: normal; }", PAGE)
+        self.assertEqual(len(re.findall(r'<div class="item dev-problem" role="alert">', PAGE)), 2)
+
+    def test_the_header_buttons_dont_give_way(self):
+        # Refresh overhung the right edge at 1280 px: the pill (and the headset picker) shrink, not the buttons.
+        header = between("<header>", "</header>")
+        end = header[header.index('<div class="hdr-end">'):]
+        for el in ('id="conn"', 'id="devSel"', 'id="battChip"', 'id="reportBtn"', 'id="refreshAll"'):
+            self.assertIn(el, end)
+        self.assertIn(".hdr-end > :not(.pill, .devsel) { flex: none; }", PAGE)
+        self.assertRegex(PAGE, r"\.hdr-end \{[^}]*min-width: 0;[^}]*margin-left: auto;")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_macview.py

@@ -7,6 +7,7 @@ input reaching the source, and closing.
 
 Run: python3 -m unittest discover -s tests
 """
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import base64
 import http.client
 import json

tests/test_media.py

@@ -1,4 +1,5 @@
 """Owned media planning, eye isolation, decoder choice and fake-Frame ownership."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import argparse
 import io
 import json

tests/test_panels.py

@@ -1,4 +1,5 @@
 """Fake-Frame panel responses and the headset page's real HTTP guards."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import http.client
 import json
 from pathlib import Path

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_rdp.py

@@ -0,0 +1,161 @@
+"""Remote desktop to the Frame (frame_host.open_rdp) on each computer, with the client
+launch stubbed and a real socket standing in for the Frame's xrdp. Also the server
+staying quiet when the page goes away mid-reply, which on Windows is
+ConnectionAbortedError (WinError 10053).
+
+Run: python3 -m unittest discover -s tests
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import email.message
+import io
+import socket
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "ui"))
+
+import frame_host  # noqa: E402
+import server  # noqa: E402
+
+
+def platform(name):
+    """Patches frame_host to behave as on `name` ("mac", "windows" or "linux")."""
+    return mock.patch.multiple(frame_host, MAC=name == "mac", WINDOWS=name == "windows",
+                               LINUX=name == "linux")
+
+
+class OpenRdp(unittest.TestCase):
+    def setUp(self):
+        self.xrdp = socket.socket()
+        self.xrdp.bind(("127.0.0.1", 0))
+        self.xrdp.listen(4)
+        self.addCleanup(self.xrdp.close)
+        port = mock.patch.object(frame_host, "RDP_PORT", self.xrdp.getsockname()[1])
+        port.start()
+        self.addCleanup(port.stop)
+        self.spawned = []
+        spawn = mock.patch.object(frame_host, "_spawn", self.spawned.append)
+        spawn.start()
+        self.addCleanup(spawn.stop)
+        cache = tempfile.TemporaryDirectory()
+        self.addCleanup(cache.cleanup)
+        self.cache = Path(cache.name)
+        where = mock.patch.object(frame_host, "cache_dir", lambda *p: self.cache.joinpath(*p))
+        where.start()
+        self.addCleanup(where.stop)
+
+    def test_windows_signs_in_as_steamos(self):
+        # The report: mstsc /v:HOST alone offers the Windows account, which xrdp rejects.
+        with platform("windows"):
+            message = frame_host.open_rdp("frame", "127.0.0.1")
+        self.assertEqual(len(self.spawned), 1)
+        argv = self.spawned[0]
+        self.assertEqual(argv[0], "mstsc.exe")
+        self.assertNotIn("/v:127.0.0.1", argv)
+        rdp = Path(argv[1])
+        self.assertEqual(rdp.suffix, ".rdp")
+        data = rdp.read_bytes()  # CRLF lines, as mstsc writes them, however this OS ends lines
+        self.assertNotIn(b"\r\r", data)
+        lines = data.decode("utf-8").split("\r\n")
+        self.assertIn("full address:s:127.0.0.1", lines)
+        self.assertIn("username:s:steamos", lines)
+        self.assertIn("steamos", message)
+        self.assertIn("Developer Mode password", message)
+        self.assertIn("certificate", message)
+        self.assertIn("Connect", message)
+
+    def test_nothing_listening_says_why_and_opens_nothing(self):
+        self.xrdp.close()
+        for name in ("windows", "mac", "linux"):
+            with self.subTest(name), platform(name), self.assertRaises(frame_host.Unreachable) as cm:
+                frame_host.open_rdp("frame", "127.0.0.1")
+            self.assertIn("Developer Mode", str(cm.exception))
+            self.assertIn(f"port {frame_host.RDP_PORT} refused", str(cm.exception))
+        self.assertEqual(self.spawned, [])
+
+    def test_says_which_way_it_failed(self):
+        # Only a refused port says xrdp is off; a wrong address or a silent network say so instead.
+        for error, says in ((socket.gaierror(8, "nodename nor servname provided"), "Devices tab"),
+                            (socket.timeout("timed out"), "didn't answer"),
+                            (OSError(65, "No route to host"), "didn't answer")):
+            with self.subTest(says), mock.patch.object(frame_host.socket, "create_connection", side_effect=error), \
+                    platform("windows"), self.assertRaises(frame_host.Unreachable) as cm:
+                frame_host.open_rdp("frame", "frame.local")
+            self.assertIn(says, str(cm.exception))
+            self.assertNotIn("refused", str(cm.exception))
+        self.assertEqual(self.spawned, [])
+
+    def test_server_says_it_as_the_persons_to_fix(self):
+        # A 400 with the message, not a 500 filed as an error diagnostic.
+        self.xrdp.close()
+        with mock.patch.multiple(server, LOCAL=False, LINK=None, HOST_OPTS=["-o", "HostName=127.0.0.1"]), \
+                self.assertRaises(server.Failure) as cm:
+            server.open_thing({"what": "rdp"})
+        self.assertEqual(cm.exception.status, 400)
+        self.assertIn("Developer Mode", str(cm.exception))
+
+    def test_one_file_per_address(self):
+        with platform("windows"):
+            a, b = frame_host.rdp_file("192.168.1.5"), frame_host.rdp_file("fe80::1%eth0")
+            c, d = frame_host.rdp_file("fe80::1%2"), frame_host.rdp_file("fe80::1:2")
+        self.assertEqual(len({a, b, c, d}), 4)
+        self.assertIn(b"full address:s:192.168.1.5\r\n", a.read_bytes())
+        self.assertIn(b"full address:s:fe80::1%eth0\r\n", b.read_bytes())
+
+    def test_address_cant_add_lines_to_the_file(self):
+        with platform("windows"), self.assertRaises(frame_host.HostError):
+            frame_host.rdp_file("frame\r\nusername:s:root")
+        self.assertEqual(list(self.cache.iterdir()), [])
+
+    def test_linux_clients_get_the_user(self):
+        with platform("linux"), mock.patch.object(frame_host, "which",
+                                                  lambda n, *e: "/usr/bin/xfreerdp" if n == "xfreerdp" else None):
+            message = frame_host.open_rdp("frame", "127.0.0.1")
+        self.assertEqual(self.spawned, [["xfreerdp", "/v:127.0.0.1", "/u:steamos", "/dynamic-resolution"]])
+        self.assertIn("steamos", message)
+
+
+class PageGoneAway(unittest.TestCase):
+    """The report's server log: the page closed while index.html was being sent, and the
+    server logged it as a 500, tried to answer anyway, and filed an error diagnostic."""
+
+    def handler(self, path="/"):
+        h = server.Handler.__new__(server.Handler)
+        h.command, h.path, h.request_version = "GET", path, "HTTP/1.1"
+        h.requestline, h.client_address = f"GET {path} HTTP/1.1", ("127.0.0.1", 1)
+        h.headers = email.message.Message()
+        h.headers["Host"] = "127.0.0.1:1"
+        h.wfile = mock.Mock(write=mock.Mock(side_effect=ConnectionAbortedError(10053, "aborted")))
+        h.close_connection = True
+        return h
+
+    def test_not_a_server_error(self):
+        h = self.handler()
+        with mock.patch.object(server.frame_telemetry, "diagnostic") as diagnostic, \
+                mock.patch.object(sys, "stderr", io.StringIO()), self.assertRaises(server.ClientGone):
+            h.do_GET()
+        diagnostic.assert_not_called()
+        self.assertEqual(h.wfile.write.call_count, 1)  # no second, 500 reply
+
+    def test_server_logs_nothing(self):
+        srv = server.LoopbackServer.__new__(server.LoopbackServer)
+        err = io.StringIO()
+        with mock.patch.object(sys, "stderr", err):
+            try:
+                raise server.ClientGone()
+            except server.ClientGone:
+                srv.handle_error(None, ("127.0.0.1", 1))
+            self.assertEqual(err.getvalue(), "")
+            try:
+                raise RuntimeError("real")
+            except RuntimeError:
+                srv.handle_error(None, ("127.0.0.1", 1))
+        self.assertIn("RuntimeError: real", err.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_release_workflow.py

@@ -0,0 +1,106 @@
+"""The "Create the draft release" step of .github/workflows/release.yml, taken out of
+the workflow and run with bash (as Actions runs it) against a stand-in gh
+(tests/fakegh/gh): a new draft's id comes straight from the POST even when the
+release list doesn't show it yet (v0.4.2's first run), a rerun reuses the draft
+found by tag_name, and a tag that isn't on GitHub stops it. 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 shutil
+import subprocess
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+WORKFLOW = ROOT / ".github" / "workflows" / "release.yml"
+FAKEGH = ROOT / "tests" / "fakegh"
+STEP = "- name: Create the draft release"
+
+
+def step_script():
+    """The step's `run: |` block, dedented."""
+    lines = WORKFLOW.read_text().splitlines()
+    i = next(n for n, line in enumerate(lines) if line.strip() == STEP)
+    while lines[i].strip() != "run: |":
+        i += 1
+    indent = len(lines[i]) - len(lines[i].lstrip())
+    body = []
+    for line in lines[i + 1:]:
+        if line.strip() and len(line) - len(line.lstrip()) <= indent:
+            break
+        body.append(line)
+    return textwrap.dedent("\n".join(body)).strip() + "\n"
+
+
+def release(rid, tag_name, name="Frame Control 9.8.7", draft=True):
+    return {"id": rid, "tag_name": tag_name, "name": name, "draft": draft, "assets": []}
+
+
+# The step only runs on ubuntu-latest. On Windows `bash` is often the WSL launcher
+# (with no distribution on GitHub's runners), not a bash that can run tests/fakegh.
+@unittest.skipUnless(os.name != "nt" and shutil.which("bash") and shutil.which("jq"),
+                     "needs a POSIX bash and jq (for gh --jq); the step runs on ubuntu only")
+class DraftStep(unittest.TestCase):
+    def run_step(self, releases, tags="v9.8.7", tag="v9.8.7"):
+        d = Path(tempfile.mkdtemp())
+        (d / "step.sh").write_text(step_script())
+        (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"), GITHUB_REF_NAME=tag, GH_REPO="saphid/frame-control")
+        p = subprocess.run(["bash", "--noprofile", "--norc", "-eo", "pipefail", str(d / "step.sh")],
+                           env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                           universal_newlines=True, timeout=30)
+        log = [json.loads(line) for line in (d / "log").read_text().splitlines()] if (d / "log").exists() else []
+        return p, log
+
+    def posts(self, log):
+        return [c for c in log if c[1:4] == ["-X", "POST", "repos/saphid/frame-control/releases"]]
+
+    def patches(self, log):
+        return [c for c in log if c[1:3] == ["-X", "PATCH"]]
+
+    def test_new_draft_uses_the_id_the_post_returns(self):
+        # The list doesn't show the fresh draft (it never does in the fake): v0.4.2's case.
+        p, log = self.run_step([])
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        [post] = self.posts(log)
+        for f in ("tag_name=v9.8.7", "name=Frame Control 9.8.7", "draft=true"):
+            self.assertIn(f, post)
+        self.assertIn(["api", "repos/saphid/frame-control/git/ref/tags/v9.8.7"], log)
+        [patch] = self.patches(log)
+        self.assertEqual(patch[3], "repos/saphid/frame-control/releases/9001")
+        self.assertIn("tag_name=v9.8.7", patch)
+        self.assertIn("release 9001 tag_name v9.8.7", p.stdout)
+        self.assertTrue(all(c[0] == "api" for c in log))  # never `gh release ...`
+
+    def test_a_rerun_reuses_the_draft_with_the_tag(self):
+        p, log = self.run_step([release(7, "v9.8.6", "Frame Control 9.8.6"), release(42, "v9.8.7")])
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(self.posts(log), [])
+        [patch] = self.patches(log)
+        self.assertEqual(patch[3], "repos/saphid/frame-control/releases/42")
+
+    def test_other_releases_alone_mean_a_new_draft(self):
+        p, log = self.run_step([release(7, "v9.8.6", "Frame Control 9.8.6", draft=False),
+                                release(8, "v9.8.70", "Frame Control 9.8.70")])
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(len(self.posts(log)), 1)
+        self.assertEqual(self.patches(log)[0][3], "repos/saphid/frame-control/releases/9001")
+
+    def test_stops_when_the_tag_is_not_on_github(self):
+        p, log = self.run_step([], tags="")
+        self.assertNotEqual(p.returncode, 0)
+        self.assertIn("tag v9.8.7 isn't on GitHub", p.stderr)
+        self.assertEqual(self.posts(log), [])
+        self.assertEqual(self.patches(log), [])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_sandbox.py

@@ -0,0 +1,122 @@
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "ui"))
+import frame_connect  # noqa: E402
+import frame_devices  # noqa: E402
+import frame_host  # noqa: E402
+
+
+def inside(path, folder):
+    path, folder = os.path.realpath(path), os.path.realpath(folder)
+    return path == folder or path.startswith(folder + os.sep)
+
+
+def snapshot(folder):
+    """{relative path: (size, mtime)} for everything under FOLDER."""
+    out = {}
+    for base, dirs, files in os.walk(folder):
+        for name in dirs + files:
+            p = os.path.join(base, name)
+            try:
+                st = os.lstat(p)
+            except OSError:
+                continue
+            out[os.path.relpath(p, folder)] = (st.st_size, st.st_mtime_ns)
+    return out
+
+
+class Sandbox(unittest.TestCase):
+    """Tests once wrote a host-key pin into the real ~/.ssh/frame-control-hosts on every
+    run (a server started without FRAME_CONTROL_SSH_DIR imported the real ~/.ssh/config)."""
+
+    def test_home_and_ssh_dir_are_throwaway(self):
+        tmp = tempfile.gettempdir()
+        self.assertTrue(inside(Path.home(), tmp), Path.home())
+        self.assertTrue(inside(os.path.expanduser("~"), tmp))
+        for d in (frame_devices.ssh_dir(), frame_devices.pin_dir(), frame_connect.SSH_DIR,
+                  os.environ["FRAME_CONTROL_SSH_DIR"], frame_host.cache_dir(), frame_host.data_dir()):
+            self.assertTrue(inside(d, tmp), d)
+            self.assertFalse(inside(d, sandbox.REAL_SSH_DIR), d)
+
+    def test_cache_folders_on_every_platform_are_throwaway(self):
+        """cache_dir() reads LOCALAPPDATA on Windows and XDG_CACHE_HOME on Linux, which a
+        moved HOME alone doesn't cover: servers sweep staging folders there."""
+        tmp = tempfile.gettempdir()
+        for platform in ("MAC", "WINDOWS", None):
+            with mock.patch.object(frame_host, "MAC", platform == "MAC"), \
+                    mock.patch.object(frame_host, "WINDOWS", platform == "WINDOWS"):
+                self.assertTrue(inside(frame_host.cache_dir("apk-sources"), tmp), platform)
+        for name in ("LOCALAPPDATA", "APPDATA", "XDG_CACHE_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"):
+            self.assertTrue(inside(os.environ[name], tmp), name)
+
+    def test_end_to_end_tests_stay_out_of_it(self):
+        """tests/e2e keeps the container's real home (OpenSSH reads ~/.ssh from the password
+        database, not $HOME), so nothing there may import sandbox, even through a test_* module."""
+        here = Path(__file__).resolve().parent
+        pattern = re.compile(r"^\s*(import sandbox|from sandbox |import test_|from test_)", re.M)
+        for f in [*(here / "e2e").glob("*.py"), *(here / "smoke").glob("*.py"), here / "apk_fixtures.py"]:
+            self.assertIsNone(pattern.search(f.read_text(encoding="utf-8")), f)
+
+    def test_end_to_end_tests_start_no_server_outside_their_container(self):
+        """Plain discovery over tests/e2e, with or without FRAME_E2E=1, must skip everything
+        and never start ui/server.py: outside scripts/e2e.sh's container it would run on
+        this computer's real app data, ~/.ssh and cache."""
+        e2e = str(Path(__file__).resolve().parent / "e2e")
+        code = ("import io, sys, unittest; sys.path.insert(0, sys.argv[1]); import harness; calls = []\n"
+                "harness.Server.start = classmethod(lambda cls: calls.append(cls))\n"
+                "suite = unittest.defaultTestLoader.discover(sys.argv[1], top_level_dir=sys.argv[1])\n"
+                "r = unittest.TextTestRunner(stream=io.StringIO()).run(suite)\n"
+                "print(len(calls), r.testsRun, len(r.skipped), len(r.errors) + len(r.failures))")
+        for extra in ({}, {"FRAME_E2E": "1"}):
+            env = {k: v for k, v in os.environ.items() if not k.startswith("FRAME_E2E")}
+            env.update(extra, PYTHONDONTWRITEBYTECODE="1")
+            out = subprocess.run([sys.executable, "-c", code, e2e], env=env, capture_output=True, text=True,
+                                 timeout=120)
+            self.assertEqual(out.returncode, 0, out.stderr[-2000:])
+            started, ran, skipped, broken = map(int, out.stdout.split())
+            self.assertEqual((started, broken), (0, 0), (extra, out.stdout))
+            self.assertEqual(ran, skipped, (extra, out.stdout))
+            self.assertGreater(skipped, 0, extra)
+
+    def test_child_processes_inherit_it(self):
+        out = subprocess.run(
+            [sys.executable, "-c", "import sys; sys.path.insert(0, sys.argv[1]); import frame_devices, frame_connect;"
+             " from pathlib import Path; print(Path.home()); print(frame_devices.ssh_dir()); print(frame_connect.SSH_DIR)",
+             str(ROOT / "ui")], env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+            capture_output=True, text=True, check=True).stdout.split("\n")
+        for d in filter(None, out):
+            self.assertFalse(inside(d, sandbox.REAL_SSH_DIR), d)
+            self.assertTrue(inside(d, tempfile.gettempdir()), d)
+
+    def test_real_ssh_folder_untouched_by_tests_that_start_servers(self):
+        """Reruns, from the environment the suite was started in, the tests that used to
+        leak (servers started without FRAME_CONTROL_SSH_DIR) plus the device and connect
+        tests, and checks nothing under the real ~/.ssh changed."""
+        real = sandbox.REAL_SSH_DIR
+        if inside(real, tempfile.gettempdir()):
+            self.skipTest("this run's HOME is already a temporary folder")
+        before = snapshot(real)
+        env = {k: v for k, v in sandbox.ORIGINAL_ENV.items() if k != "FRAME_CONTROL_SSH_DIR"}
+        env["PYTHONDONTWRITEBYTECODE"] = "1"
+        r = subprocess.run([sys.executable, "-m", "unittest", "-q", "test_server.OneServer", "test_server.LocalMode",
+                            "test_devices", "test_connect"],
+                           cwd=str(Path(__file__).resolve().parent), env=env, capture_output=True, text=True,
+                           timeout=300)
+        self.assertEqual(r.returncode, 0, r.stderr[-3000:])
+        after = snapshot(real)
+        changed = sorted(k for k in set(before) | set(after) if before.get(k) != after.get(k)
+                         and not k.startswith("agent"))  # ssh-agent sockets come and go on their own
+        self.assertEqual(changed, [], f"tests changed the real {real}")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_server.py

@@ -10,6 +10,7 @@ import http.client
 import io
 import json
 import os
+import shutil
 import socket
 import struct
 import subprocess
@@ -78,6 +79,21 @@ class ServerGuards(unittest.TestCase):
         self.assertEqual(headers["X-Frame-Options"], "DENY")
         self.assertIn(b"<html", payload.lower())
 
+    def test_control_center_assets_served_with_correct_types(self):
+        for path, mime, marker in (('/control-center.js', 'text/javascript', b'createController'),
+                                   ('/control-center.css', 'text/css', b'.cc-workspace')):
+            with self.subTest(path=path):
+                status, headers, payload = self.request('GET', path)
+                self.assertEqual(status, 200)
+                self.assertIn(mime, headers['Content-Type'])
+                self.assertIn(marker, payload)
+
+    def test_store_page_served_with_anti_framing_headers(self):
+        status, headers, payload = self.request("GET", "/store")
+        self.assertEqual(status, 200)
+        self.assertEqual(headers["X-Frame-Options"], "DENY")
+        self.assertIn(b"<title>APK Store</title>", payload)
+
     def test_foreign_host_rejected(self):
         # DNS rebinding: a hostile name pointed at 127.0.0.1.
         for path in ("/", "/api/status"):
@@ -287,15 +303,77 @@ class OneServer(unittest.TestCase):
 
     @unittest.skipIf(os.name == "nt", "no SIGTERM on Windows")
     def test_sigterm_while_the_app_holds_stdin_exits_cleanly(self):
-        """The app keeps stdin open; a stop signal used to abort Python (SIGABRT) at exit."""
-        env = {**os.environ, "FRAME_CONTROL_DATA_DIR": tempfile.mkdtemp(prefix="frame-one-server-"),
-               "FRAME_ALIAS": "frame-control-test.invalid"}
-        proc = subprocess.Popen([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0", "--exit-on-eof"],
-                                env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
-        self.addCleanup(lambda: (proc.stdin.close(), proc.stdout.close()))
-        self.assertIn("Frame Control on", proc.stdout.readline())
-        proc.terminate()
-        self.assertEqual(proc.wait(30), 0, proc.stdout.read())
+        """The app keeps stdin open; a stop signal used to abort Python (SIGABRT) at exit,
+        and later, now and then, crash it (SIGSEGV) while background threads were still
+        loading TLS certificates. Run a few times: that crash came about 1 run in 100."""
+        for attempt in range(5):
+            with self.subTest(attempt=attempt):
+                env = {**os.environ, "FRAME_CONTROL_DATA_DIR": tempfile.mkdtemp(prefix="frame-one-server-"),
+                       "FRAME_ALIAS": "frame-control-test.invalid", "PYTHONFAULTHANDLER": "1"}
+                proc = subprocess.Popen([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0", "--exit-on-eof"],
+                                        env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                        stderr=subprocess.STDOUT, text=True)
+                try:
+                    self.assertIn("Frame Control on", proc.stdout.readline())
+                    proc.terminate()
+                    self.assertEqual(proc.wait(30), 0, proc.stdout.read())
+                finally:
+                    if proc.poll() is None:
+                        proc.kill()
+                        proc.wait()
+                    proc.stdin.close()
+                    proc.stdout.close()
+                    shutil.rmtree(env["FRAME_CONTROL_DATA_DIR"], ignore_errors=True)
+
+    def test_staging_folders_cleared_when_stopped_mid_transfer(self):
+        """The server leaves without interpreter teardown, so TemporaryDirectory cleanup
+        doesn't run for work still in progress: its own staging folders go on the way out,
+        and a dead server's at the next start."""
+        dead = subprocess.Popen([sys.executable, "-c", "pass"])
+        dead.wait()
+        home = tempfile.mkdtemp(prefix="frame-stop-home-")
+        self.addCleanup(shutil.rmtree, home, ignore_errors=True)
+        env = {**os.environ, "FRAME_CONTROL_DATA_DIR": os.path.join(home, "data"),
+               "FRAME_ALIAS": "frame-control-test.invalid", "HOME": home, "XDG_CACHE_HOME": os.path.join(home, ".cache"),
+               "LOCALAPPDATA": home, "APPDATA": home}
+        index_dir = Path(subprocess.run(
+            [sys.executable, "-c", "import sys; sys.path.insert(0, sys.argv[1]); import frame_host; "
+                                   "print(frame_host.cache_dir('apk-sources'))", str(ROOT / "ui")],
+            env=env, capture_output=True, text=True, check=True).stdout.strip())
+        index_dir.mkdir(parents=True)
+        tmp = Path(tempfile.gettempdir())
+
+        def staged(folder, prefix, pid):
+            d = Path(tempfile.mkdtemp(prefix=f"{prefix}{pid}-", dir=folder))
+            self.addCleanup(shutil.rmtree, d, ignore_errors=True)
+            (d / "app.apk").write_bytes(b"\0" * 4096)
+            return d
+
+        # Stopped as the app stops it: by closing stdin (the only way on Windows,
+        # where terminate() is a hard kill) and, elsewhere, by SIGTERM too.
+        for stop in ["stdin"] + (["sigterm"] if os.name != "nt" else []):
+            with self.subTest(stop=stop):
+                left_by_dead = [staged(tmp, "frame-vr-", dead.pid), staged(index_dir, ".download-", dead.pid)]
+                proc = subprocess.Popen([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0", "--exit-on-eof"],
+                                        env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                        stderr=subprocess.STDOUT, text=True)
+                try:
+                    self.assertIn("Frame Control on", proc.stdout.readline())
+                    self.assertEqual([d for d in left_by_dead if d.exists()], [])
+                    in_flight = [staged(tmp, "frame-vr-", proc.pid), staged(tmp, "frame-agent-", proc.pid),
+                                 staged(index_dir, ".download-", proc.pid)]
+                    if stop == "stdin":
+                        proc.stdin.close()
+                    else:
+                        proc.terminate()
+                    self.assertEqual(proc.wait(30), 0, proc.stdout.read())
+                    self.assertEqual([d for d in in_flight if d.exists()], [])
+                finally:
+                    if proc.poll() is None:
+                        proc.kill()
+                        proc.wait()
+                    proc.stdin.close()
+                    proc.stdout.close()
 
 
 class ArtworkSettings(unittest.TestCase):
@@ -348,6 +426,59 @@ class ArtworkSettings(unittest.TestCase):
         self.assertLess(page.index("async function api("), page.index('<script src="/artwork-settings.js">'))
 
 
+@unittest.skipUnless(shutil.which("node"), "needs node")
+class PageScripts(unittest.TestCase):
+    """A page's scripts share one global scope, where a later function declaration
+    silently replaces an earlier one of the same name. Issue #68: the Devices page's
+    renderDetail replaced the Android store's, so every app opened as an empty
+    dialog (a bare horizontal line). Compiled together as one module, any top-level
+    name declared twice is a SyntaxError; node's parser handles nested scopes,
+    comments and strings."""
+
+    PAGES = ("index.html", "assistant.html", "mac-view.html")
+
+    @staticmethod
+    def page_scripts(html):
+        """A page's inline scripts, then its /*.js scripts, in one source."""
+        import re
+        parts = re.findall(r"<script>([\s\S]*?)</script>", html)
+        parts += [(ROOT / "ui" / src).read_text(encoding="utf-8") for src in re.findall(r'<script src="/([\w.-]+\.js)">', html)]
+        return "\n;\n".join(parts)
+
+    @staticmethod
+    def module_check(source):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "page.mjs"
+            path.write_text(source, encoding="utf-8")
+            r = subprocess.run(["node", "--check", str(path)], capture_output=True, text=True)
+        return r.returncode, r.stderr
+
+    def test_the_check_catches_top_level_duplicates_only(self):
+        dup = "<script>function a() {}\nfunction a() {}</script>"
+        across = "<script>function a() {}</script><p>x</p><script>  async function a() {}</script>"
+        same_line = "<script>function a() {} function a() {}</script>"
+        const_and_function = "<script>const a = 1, b = 2;\nfunction b() {}</script>"
+        for html in (dup, across, same_line, const_and_function):
+            rc, err = self.module_check(self.page_scripts(html))
+            self.assertNotEqual(rc, 0, html)
+            self.assertIn("has already been declared", err, html)
+        nested = ("<script>function a() {}\nfunction f() { function a() {} if (1) { const a = 2; } }\n"
+                  "// function a() {}\nconst s = `function a() {}`;</script>")
+        self.assertEqual(self.module_check(self.page_scripts(nested)), (0, ""))
+
+    def test_no_top_level_name_is_declared_twice(self):
+        for name in self.PAGES:
+            source = self.page_scripts((ROOT / "ui" / name).read_text(encoding="utf-8"))
+            self.assertIn("function", source, name)
+            rc, err = self.module_check(source)
+            self.assertEqual(rc, 0, f"{name}: {err}")
+
+    def test_store_app_page_renders(self):
+        """tests/page/store_detail.mjs runs the real store functions from index.html."""
+        r = subprocess.run(["node", str(ROOT / "tests" / "page" / "store_detail.mjs")], capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+
+
 @unittest.skipIf(os.name == "nt", "runs on the Frame (Linux); local-bin/ssh is a POSIX shell script")
 class LocalMode(unittest.TestCase):
     """FRAME_LOCAL=1, as the iPhone app starts the server on the Frame: its own key
@@ -419,7 +550,11 @@ class UnreachableMessages(unittest.TestCase):
             "ssh: connect to host 192.168.1.9 port 22: No route to host": "isn't answering",
             "ssh: connect to host 192.168.1.9 port 22: Connection refused": "refused",
             "steamos@192.168.1.9: Permission denied (publickey,password).": "SSH key",
-            "Host key verification failed.": "identity changed",
+            "Host key verification failed.": "identity has changed",
+            "@@@@\n@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @\nHost key verification failed.":
+                "Check the new key on the Devices tab",
+            "No ED25519 host key is known for frame-control-f7b4e9ac and you have requested strict checking.\n"
+            "Host key verification failed.": "isn't saved yet",
             "kex_exchange_identification: read: Connection reset by peer": "dropped",
             "Timed out talking to frame": "too long",
         }
@@ -435,6 +570,47 @@ class UnreachableMessages(unittest.TestCase):
             self.assertEqual(self.server.error_body(raw), ({"error": raw}, None), raw)
 
 
+class ClipboardDesktopClosed(unittest.TestCase):
+    """The headset's desktop being closed is the person's to fix: a 409, not a 5xx fault for telemetry."""
+
+    @classmethod
+    def setUpClass(cls):
+        sys.path.insert(0, str(ROOT / "ui"))
+        import server
+        cls.server = server
+
+    def paste_failing_with(self, message):
+        s = self.server
+        saved = s.ssh
+
+        def fake_ssh(remote, **kw):
+            raise s.Failure(message)
+        s.ssh = fake_ssh
+        try:
+            s.clipboard({"text": "hello"})
+        finally:
+            s.ssh = saved
+
+    def test_desktop_closed_is_a_409(self):
+        with self.assertRaises(self.server.Failure) as cm:
+            self.paste_failing_with("The headset's desktop isn't open (plasmashell is not running). "
+                                    "Open the desktop in the headset, then try again.")
+        self.assertEqual(cm.exception.status, 409)
+        self.assertIn("Open the desktop", str(cm.exception))
+        # Older wording (scripts/paste-to-frame.sh) is recognised too.
+        with self.assertRaises(self.server.Failure) as cm:
+            self.paste_failing_with("plasmashell is not running: open the desktop in the headset first.")
+        self.assertEqual(cm.exception.status, 409)
+
+    def test_other_failures_stay_faults(self):
+        with self.assertRaises(self.server.Failure) as cm:
+            self.paste_failing_with("Klipper call failed (bus: none)")
+        self.assertEqual(cm.exception.status, 502)
+
+    def test_paste_script_says_it(self):
+        self.assertIn(self.server.DESKTOP_CLOSED, self.server.PASTE)
+
+
 class StatusProbe(unittest.TestCase):
     # frame_status.py only ever runs on the Frame (Linux); it needs os.statvfs.
     @unittest.skipIf(os.name == "nt", "Frame-side script; POSIX only")

tests/test_sidequest.py

@@ -1,3 +1,4 @@
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import json
 from pathlib import Path
 import sys

tests/test_store_categories.py

@@ -0,0 +1,361 @@
+"""The store's Frame categories (ui/apk_sources/_categories.py): which apps go where, which are
+phone-only and hidden, and how the browse, search and library artwork use them. Offline."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import json
+from pathlib import Path
+import sys
+import tempfile
+import types
+import unittest
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
+from apk_sources import SourceError, _categories, _images, fdroid, search  # noqa: E402
+import test_fdroid_sources as fixtures  # noqa: E402  (a module, so its tests don't run twice)
+FIXTURES, PIN, URL = fixtures.FIXTURES, fixtures.PIN, fixtures.URL
+
+
+def kind(**entry):
+    return _categories.classify(dict({'name': 'App', 'summary': ''}, **entry))
+
+
+class Classify(unittest.TestCase):
+    def test_vr_first_whatever_else_it_is(self):
+        self.assertEqual(kind(vr=True, categories=['Phone & SMS']), {'category': 'vr', 'phone_only': False})
+
+    def test_fine_categories_decide(self):
+        self.assertEqual(kind(categories=['Games', 'Puzzle Game'])['category'], 'games')
+        self.assertEqual(kind(categories=['Games', 'Emulator'])['category'], 'emulators')
+        # A chat app is in Multimedia too; the finer Social Network wins.
+        self.assertEqual(kind(categories=['Multimedia', 'Internet', 'Social Network'])['category'], 'web')
+        self.assertEqual(kind(categories=['Reading', 'Ebook Reader'])['category'], 'read')
+        self.assertEqual(kind(categories=['Multimedia', 'Podcast'])['category'], 'watch')
+
+    def test_broad_categories_alone(self):
+        self.assertEqual(kind(categories=['Multimedia']), {'category': 'watch', 'phone_only': False})
+        self.assertEqual(kind(categories=['Writing']), {'category': 'work', 'phone_only': False})
+
+    def test_phone_only(self):
+        for categories in (['System', 'Launcher'], ['Internet', 'VPN & Proxy'], ['Theming', 'Wallpaper'],
+                           ['Sports & Health'], ['Connectivity'], ['Time', 'Alarm Clock'], ['Habit Tracker']):
+            with self.subTest(categories=categories):
+                self.assertTrue(kind(categories=categories)['phone_only'])
+        self.assertTrue(kind(name='[ROOT] Night Light', categories=['Development'])['phone_only'])
+        self.assertTrue(kind(name='5G Proxy Client', summary='Routes traffic')['phone_only'])
+
+    def test_games_and_media_keep_phone_words(self):
+        # 'Battery' in a game's name or a widget in a music player doesn't hide a game or a player.
+        self.assertFalse(kind(name='Widget Wars', categories=['Strategy Game'])['phone_only'])
+        self.assertFalse(kind(name='Music', summary='with a home screen widget', categories=['Local Media Player'])['phone_only'])
+
+    def test_emulators_by_name_without_categories(self):
+        self.assertEqual(kind(name='RetroArch', summary='Frontend for emulators')['category'], 'emulators')
+
+    def test_unknown_is_neither_hidden_nor_guessed(self):
+        self.assertEqual(kind(name='Thing'), {'category': None, 'phone_only': False})
+        self.assertEqual(kind(categories=['Something New']), {'category': None, 'phone_only': False})
+
+    def test_matches(self):
+        phone = {'category': 'tools', 'phone_only': True}
+        self.assertFalse(_categories.matches(phone))
+        self.assertTrue(_categories.matches(phone, phone=True))
+        self.assertTrue(_categories.matches({'category': 'games', 'phone_only': False}, 'games'))
+        self.assertFalse(_categories.matches({'category': 'watch', 'phone_only': False}, 'games'))
+
+    def test_every_store_category_has_a_label(self):
+        self.assertEqual({c for c, _ in _categories.CATEGORIES}, _categories.IDS)
+        targets = set(_categories.FINE) | {c for c in _categories.BROAD.values() if c}
+        self.assertLessEqual(targets, _categories.IDS)
+        self.assertLessEqual(set(_categories.PRIORITY), _categories.IDS)
+
+
+class FDroidCategories(unittest.TestCase):
+    setUp, fetch, add = fixtures.Repositories.setUp, fixtures.Repositories.fetch, fixtures.Repositories.add
+
+    def index(self, version, categories):
+        raw = json.loads((FIXTURES / ('artwork-' + version + '.json')).read_text())
+        if version == 'v2':
+            raw['packages']['org.example.app']['metadata']['categories'] = categories
+        else:
+            raw['apps'][0]['categories'] = categories
+        path = self.root / ('index-' + version + '.json')
+        path.write_text(json.dumps(raw))
+        if version == 'v1':
+            fdroid._v1(path.read_bytes(), path)
+        return path
+
+    def test_categories_survive_v1_and_v2(self):
+        source = self.add()
+        for version in ('v1', 'v2'):
+            with self.subTest(version=version):
+                apps = fdroid._reduce(self.index(version, ['Games', 'Puzzle Game', 7]), source)
+                self.assertEqual(apps['org.example.app']['categories'], ['Games', 'Puzzle Game'])
+
+    def save(self, source, apps):
+        fdroid._write(fdroid.frame_host.cache_dir('apk-sources', source['id'] + '.json'),
+                      {'version': fdroid.CACHE_VERSION, 'url': URL, 'fingerprint': PIN, 'apps': apps})
+
+    def app(self, pkg, name, updated, categories=(), banner=None):
+        return {'source': 'x', 'id': pkg, 'package': pkg, 'name': name, 'summary': '', 'updated': updated,
+                'categories': list(categories), 'images': {'icon': None, 'banner': banner, 'screenshots': []}}
+
+    def test_browse_shows_artwork_then_newest_and_filters_before_the_limit(self):
+        source = self.add()
+        self.save(source, {a['id']: a for a in (
+            self.app('a.old', 'Aaa', '2020-01-01', ['Puzzle Game']),
+            self.app('b.new', 'Bbb', '2026-01-01', ['Puzzle Game']),
+            self.app('c.art', 'Ccc', '2019-01-01', ['Puzzle Game'], banner=URL + 'b.png'),
+            self.app('d.sms', 'Ddd', '2026-02-01', ['Phone & SMS']))})
+        self.assertEqual([a['id'] for a in fdroid.search(source, '', limit=10)], ['c.art', 'd.sms', 'b.new', 'a.old'])
+        keep = lambda e: _categories.matches(dict(e, **_categories.classify(e)))
+        self.assertEqual([a['id'] for a in fdroid.search(source, '', limit=1, keep=keep)], ['c.art'])
+        self.assertEqual([a['id'] for a in fdroid.search(source, 'a', limit=10)], ['a.old', 'c.art'])  # a query sorts by name
+
+    def test_lookup_reads_the_saved_index_only(self):
+        source = self.add()
+        self.assertEqual(fdroid.lookup(dict(source, id='never-loaded'), ['org.example.app']), {})
+        self.save(source, {'a.b': self.app('a.b', 'A', None)})
+        before = self.fetch_mock.call_count
+        self.assertEqual(list(fdroid.lookup(source, ['a.b', 'missing'])), ['a.b'])
+        self.assertEqual(self.fetch_mock.call_count, before)
+        self.assertEqual(fdroid.lookup(dict(source, enabled=False), ['a.b']), {})
+
+
+def fake_source(entries, kind_='fake', lookup=None):
+    mod = types.SimpleNamespace(KIND=kind_)
+    mod.sources = lambda: [{'id': kind_, 'kind': kind_, 'name': kind_.title(), 'url': 'https://example.org/',
+                            'builtin': True, 'enabled': True, 'trust': 'community'}]
+    mod.search = lambda source, query, limit=50: [dict(e) for e in entries][:limit]
+    mod.details = lambda source, entry_id: next(dict(e) for e in entries if e['id'] == entry_id)
+    if lookup is not None:
+        mod.lookup = lookup
+    return mod
+
+
+ENTRY = {'source': 'fake', 'package': None, 'summary': '', 'free': True, 'downloadable': True,
+         'min_sdk': 24, 'abis': ['arm64-v8a'], 'vr': None}
+
+
+class Search(unittest.TestCase):
+    def setUp(self):
+        tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        p = patch.object(search, 'settings_path', return_value=Path(tmp.name) / 'sources.json')
+        p.start()
+        self.addCleanup(p.stop)
+        for state in (search._running, search._pending, search._status):
+            state.clear()
+            self.addCleanup(state.clear)
+
+    def run_search(self, entries, **kwargs):
+        with patch.object(search, 'modules', return_value=([fake_source(entries)], [])):
+            return search.search(**kwargs)
+
+    def test_category_and_phone_filters(self):
+        entries = [dict(ENTRY, id='g', name='Game', categories=['Puzzle Game']),
+                   dict(ENTRY, id='s', name='Texts', categories=['Phone & SMS']),
+                   dict(ENTRY, id='v', name='Video', categories=['Local Media Player'])]
+        result = self.run_search(entries)
+        self.assertEqual(sorted(a['name'] for a in result['apps']), ['Game', 'Video'])
+        self.assertEqual({a['name']: a['category'] for a in result['apps']}, {'Game': 'games', 'Video': 'watch'})
+        self.assertIn({'id': 'emulators', 'label': 'Emulators'}, result['categories'])
+        self.assertEqual([a['name'] for a in self.run_search(entries, category='games')['apps']], ['Game'])
+        self.assertEqual(len(self.run_search(entries, phone=True)['apps']), 3)
+        with self.assertRaisesRegex(SourceError, 'Unknown category'):
+            self.run_search(entries, category='phones')
+
+    def test_listing_offers_three_screenshots_details_all(self):
+        shots = ['https://example.org/%d.png' % i for i in range(8)]
+        entry = dict(ENTRY, id='g', name='Game', images={'icon': None, 'banner': None, 'screenshots': shots})
+        listed = self.run_search([entry])['apps'][0]['offers'][0]
+        self.assertEqual(len(listed['artwork']['screenshots']), 3)
+        self.assertEqual(len(search.decorate(entry)['artwork']['screenshots']), 8)
+
+    def test_browse_asks_sources_for_more_than_a_search(self):
+        seen = []
+        mod = fake_source([])
+        mod.search = lambda source, query, limit=50: seen.append((query, limit)) or []
+        with patch.object(search, 'modules', return_value=([mod], [])):
+            search.search('')
+            search.search('chess')
+        self.assertEqual(seen, [('', search.BROWSE_LIMIT), ('chess', 50)])
+
+
+class LibraryArtwork(unittest.TestCase):
+    def setUp(self):
+        tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        p = patch.object(search, 'settings_path', return_value=Path(tmp.name) / 'sources.json')
+        p.start()
+        self.addCleanup(p.stop)
+
+    def test_by_package_from_saved_indexes_then_by_name_for_curated_apps(self):
+        icon = {'images': {'icon': 'https://example.org/icon.png', 'banner': None, 'screenshots': []}}
+        repo = fake_source([], 'fdroid', lookup=lambda source, packages: {
+            p: dict(icon, name='x') for p in packages if p == 'org.antennapod'})
+        github = fake_source([dict(icon, id='icosa/open-brush', name='Open Brush')], 'github')
+        bare = fake_source([dict(icon, id='x', name='Elsewhere', package='org.elsewhere')], 'itch')
+        apps = [{'package': 'org.antennapod', 'label': 'AntennaPod'}, {'package': 'com.Icosa.OpenBrush', 'label': 'Open Brush'},
+                {'package': 'org.elsewhere', 'label': 'Elsewhere'}, {'package': 'org.none', 'label': 'None'}]
+        with patch.object(search, 'modules', return_value=([repo, github, bare], [])):
+            found = search.artwork_for(apps)
+        self.assertEqual(sorted(found), ['com.Icosa.OpenBrush', 'org.antennapod'])
+        self.assertTrue(found['org.antennapod']['icon'].startswith('/source-image/'))
+
+    def test_a_failing_source_is_skipped(self):
+        def broken(source, packages):
+            raise SourceError('no')
+        with patch.object(search, 'modules', return_value=([fake_source([], 'fdroid', lookup=broken)], [])):
+            self.assertEqual(search.artwork_for([{'package': 'a.b', 'label': 'A'}]), {})
+
+
+class ImageHandles(unittest.TestCase):
+    def test_same_url_same_handle_without_scanning(self):
+        with _images._lock:
+            _images._urls.clear()
+            _images._tokens.clear()
+        a = _images.register('https://example.org/a.png')
+        self.assertEqual(_images.register('https://example.org/a.png'), a)
+        self.assertNotEqual(_images.register('https://example.org/b.png'), a)
+
+
+
+class Route(unittest.TestCase):
+    def test_search_filters_are_checked(self):
+        import server
+        with patch.object(server.apk_search, 'search', return_value={'apps': []}) as run:
+            server.source_search('q=&category=games&phone=1')
+            self.assertEqual(run.call_args.kwargs['category'], 'games')
+            self.assertIs(run.call_args.kwargs['phone'], True)
+            server.source_search('q=chess')
+            self.assertEqual((run.call_args.kwargs['category'], run.call_args.kwargs['phone']), (None, False))
+            for bad in ('phone=maybe', 'category=' + 'x' * 41):
+                with self.subTest(bad=bad), self.assertRaises(server.Failure):
+                    server.source_search(bad)
+
+
+
+class ReviewCases(unittest.TestCase):
+    """Real index entries (October 2026) that the first rules got wrong."""
+    def test_useful_apps_with_a_phone_side_stay(self):
+        for categories, category in ((['Connectivity', 'Email', 'Internet', 'Writing'], 'web'),  # Thunderbird
+                                     (['Connectivity', 'Internet', 'Multimedia', 'Podcast'], 'watch'),  # FocusPodcast
+                                     (['Contact', 'Email'], 'web'),
+                                     (['Cloud Storage & File Sync', 'File Manager', 'System'], 'tools')):
+            with self.subTest(categories=categories):
+                self.assertEqual(kind(categories=categories), {'category': category, 'phone_only': False})
+
+    def test_phone_side_alone_or_with_a_broad_category_is_hidden(self):
+        for categories in (['Internet', 'VPN & Proxy'], ['App Manager', 'Development', 'System'], ['Navigation']):
+            with self.subTest(categories=categories):
+                self.assertTrue(kind(categories=categories)['phone_only'])
+        self.assertTrue(kind(categories=['Launcher', 'Games'])['phone_only'])  # system ones always
+
+    def test_no_root_needed_is_not_a_root_tool(self):
+        for summary in ('Linux on Android, no root required', 'Linux Without Root Access', 'SSH server without root',
+                        'Works on non-rooted phones', 'Rootless and simple'):
+            with self.subTest(summary=summary):
+                self.assertFalse(kind(summary=summary, categories=['Development'])['phone_only'])
+        self.assertTrue(kind(summary='Needs root to tune the kernel', categories=['Development'])['phone_only'])
+
+    def test_izzyondroid_names(self):
+        self.assertEqual(kind(categories=['Office'])['category'], 'work')
+        self.assertTrue(kind(categories=['Xposed'])['phone_only'])
+
+
+
+class ReviewCasesTwo(unittest.TestCase):
+    """Round two of real entries (October 2026)."""
+    def test_messengers_with_phone_or_push_stay(self):
+        for categories in (['Internet', 'Messaging', 'Phone & SMS'], ['Internet', 'Messaging', 'Push'],
+                           ['Connectivity', 'Messaging', 'Phone & SMS', 'Voice & Video Chat']):
+            with self.subTest(categories=categories):
+                self.assertEqual(kind(categories=categories), {'category': 'web', 'phone_only': False})
+
+    def test_broad_only_sources_can_escape_a_phone_side(self):
+        self.assertEqual(kind(categories=['System', 'Development']), {'category': 'tools', 'phone_only': False})
+        self.assertEqual(kind(categories=['Connectivity', 'Internet']), {'category': 'web', 'phone_only': False})
+        self.assertTrue(kind(categories=['VPN & Proxy', 'Internet'])['phone_only'])  # it has finer ones, none useful
+
+    def test_summary_features_dont_make_a_phone_app(self):
+        self.assertFalse(kind(name='OSS Weather', summary='Forecasts with home screen widgets', categories=['Weather'])['phone_only'])
+        self.assertFalse(kind(name='Digital Calculator', summary='Hardware keyboard support', categories=['Calculator', 'System'])['phone_only'])
+        self.assertTrue(kind(name='Clock Widget', categories=['Clock'])['phone_only'])  # but the name says what it is
+
+    def test_saying_root_isnt_needed(self):
+        for summary in ('VNC server app that does not require root privileges', "Backups that don't need root access",
+                        "It doesn't need root", 'Linux without root', 'Works on non-rooted phones', 'Rootless'):
+            with self.subTest(summary=summary):
+                self.assertFalse(kind(summary=summary, categories=['Remote Access'])['phone_only'])
+        for summary in ('Requires root', 'Needs root access to change the kernel', 'For rooted devices'):
+            with self.subTest(summary=summary):
+                self.assertTrue(kind(summary=summary, categories=['Remote Access'])['phone_only'])
+
+    def test_hardware_the_frame_lacks(self):
+        self.assertTrue(kind(name='IR Blaster Remote', categories=['Multimedia', 'Remote Controller', 'System'])['phone_only'])
+        self.assertTrue(kind(name='Wear Sync for Breezy', summary='Weather on your Wear OS watch', categories=['Connectivity', 'Weather'])['phone_only'])
+
+
+class SearchFindsPhoneApps(unittest.TestCase):
+    setUp, run_search = Search.setUp, Search.run_search
+
+    def test_a_search_finds_what_browsing_hides(self):
+        entries = [dict(ENTRY, id='s', name='Texts', categories=['Phone & SMS'])]
+        self.assertEqual(self.run_search(entries)['apps'], [])
+        found = self.run_search(entries, query='texts')['apps']
+        self.assertEqual([(a['name'], a['offers'][0]['phone_only']) for a in found], [('Texts', True)])
+
+
+
+class ArtworkLookups(unittest.TestCase):
+    """A page of cards asks for dozens of images at once; they mustn't fail for want of a lookup slot."""
+    def setUp(self):
+        _images._dns.clear()
+        self.addCleanup(_images._dns.clear)
+
+    def test_public_answers_are_kept_private_ones_are_not(self):
+        public = [(2, 1, 6, '', ('93.184.216.34', 443))]
+        with patch.object(_images.socket, 'getaddrinfo', return_value=public) as lookup:
+            for _ in range(3):
+                self.assertEqual(_images._resolve('example.org', 443, 5), public)
+        self.assertEqual(lookup.call_count, 1)
+        private = [(2, 1, 6, '', ('10.0.0.5', 443))]
+        with patch.object(_images.socket, 'getaddrinfo', return_value=private) as lookup:
+            _images._resolve('inside.example', 443, 5)
+            _images._resolve('inside.example', 443, 5)
+        self.assertEqual(lookup.call_count, 2)
+
+    def test_waiting_for_a_slot_counts_against_the_budget(self):
+        import threading, time
+        gate = threading.Event()
+        for _ in range(4):  # every slot busy for the whole test
+            _images._resolvers.acquire()
+        threading.Timer(0.06, lambda: [_images._resolvers.release() for _ in range(4)]).start()
+        with patch.object(_images.socket, 'getaddrinfo', side_effect=lambda *a, **k: gate.wait(2) and []):
+            start = time.monotonic()
+            with self.assertRaises(SourceError):
+                _images._resolve('slow.example', 443, 0.1)
+            self.assertLess(time.monotonic() - start, 0.16)
+        gate.set()
+
+    def test_many_at_once_wait_for_a_slot(self):
+        import threading, time
+        public = [(2, 1, 6, '', ('93.184.216.34', 443))]
+        def slow(*a, **k):
+            time.sleep(0.05)
+            return public
+        errors = []
+        def one(i):
+            try:
+                _images._resolve('host%d.example' % i, 443, 5)
+            except SourceError as e:
+                errors.append(e)
+        with patch.object(_images.socket, 'getaddrinfo', side_effect=slow):
+            threads = [threading.Thread(target=one, args=(i,)) for i in range(12)]
+            [t.start() for t in threads]
+            [t.join() for t in threads]
+        self.assertEqual(errors, [])
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_telemetry.py

@@ -6,6 +6,7 @@ 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 sys
 import tempfile
 import threading
@@ -20,9 +21,15 @@ sys.path.insert(0, str(ROOT / "ui"))
 
 import frame_compat_db as db  # noqa: E402
 import frame_report as fr  # noqa: E402
+import frame_host  # noqa: E402
 import frame_telemetry as tm  # noqa: E402
 
 
+def link_error(message, kind=RuntimeError):
+    """An error as an ssh helper raises it when ssh couldn't reach the headset."""
+    return frame_host.link_failure(kind(message))
+
+
 class Base(unittest.TestCase):
     """A packaged build with a key, its state in a temp folder."""
 
@@ -92,6 +99,47 @@ class Gates(Base):
             tm.diagnostic("POST /api/android install", RuntimeError("boom"))
         self.assertEqual(len(self.queued()), 1)
 
+    def test_connection_failures_are_sent_once_per_session(self):
+        # The status poll meets an asleep or absent headset every few seconds (638 timeouts from
+        # six people in two weeks): one event per kind per session, whatever the address or route,
+        # for errors marked where ssh ran as ssh failing to reach the headset.
+        tm.update_settings({"diagnostics": True})
+        with mock.patch.object(tm.time, "time", return_value=1000.0):
+            for ip in ("192.168.1.20", "192.168.1.21", "10.0.0.5"):
+                for where in ("POST /api/comfort status", "job steam"):
+                    tm.diagnostic(where, link_error(f"ssh: connect to host {ip} port 22: Connection timed out"))
+                    tm.diagnostic(where, link_error(f"ssh: connect to host {ip} port 22: Host is down"))
+                    tm.diagnostic(where, link_error("Timed out talking to frame"))
+            tm.diagnostic("POST /api/comfort status",
+                          link_error("ssh: Could not resolve hostname frame: No such host is known."))
+        with mock.patch.object(tm.time, "time", return_value=1000.0 + 10 * tm.REPEAT_WINDOW):
+            tm.diagnostic("POST /api/comfort status", link_error("client_loop: send disconnect: Connection reset"))
+            tm.diagnostic("POST /api/comfort status", link_error("ssh: Could not resolve hostname frame"))
+        sent = [e["properties"] for e in self.queued()]
+        self.assertEqual([p["error_category"] for p in sent], ["frame_unreachable", "frame_not_set_up"])
+        self.assertTrue(all(p["$exception_message"].startswith("ssh: ") for p in sent))
+
+    def test_only_marked_errors_are_held_for_the_session(self):
+        # The same words without the mark (from a download, a file name, anything not ssh) keep
+        # the usual 10-minute window.
+        tm.update_settings({"diagnostics": True})
+        tm.diagnostic("POST /api/comfort status", link_error("ssh: connect to host 10.0.0.5 port 22: Connection timed out"))
+        tm.diagnostic("job web", RuntimeError("ssh: connect to host 10.0.0.5 port 22: Connection timed out"))
+        tm.diagnostic("job web", RuntimeError("ssh: connect to host 10.0.0.5 port 22: Connection timed out"))
+        tm.diagnostic("job web", RuntimeError("download failed: [Errno 54] Connection reset by peer"))
+        tm.diagnostic("job web", RuntimeError("urlopen error [Errno 60] Operation timed out"))
+        self.assertEqual([e["properties"]["error_category"] for e in self.queued()],
+                         ["frame_unreachable", "frame_unreachable", "download_failed", "frame_unreachable"])
+
+    def test_real_errors_are_still_sent_beside_connection_failures(self):
+        tm.update_settings({"diagnostics": True})
+        tm.diagnostic("POST /api/comfort status", link_error("ssh: connect to host 10.0.0.5 port 22: Connection timed out"))
+        tm.diagnostic("POST /api/comfort status", KeyError("battery"))
+        tm.diagnostic("POST /api/android install", RuntimeError("boom"))
+        tm.diagnostic("POST /api/comfort status", RuntimeError("ssh exited 255"))  # the command's own exit code?
+        self.assertEqual([e["properties"]["error_category"] for e in self.queued()],
+                         ["frame_unreachable", "internal_error", "other", "other"])
+
     def test_page_events_are_checked(self):
         self.assertTrue(tm.page_event({"event": "tab_viewed", "properties": {"tab": "android", "extra": "x"}})["queued"])
         self.assertEqual(self.queued()[0]["properties"].get("extra"), None)
@@ -111,11 +159,79 @@ class Lifecycle(Base):
         e = self.queued()[-1]
         self.assertEqual((e["event"], e["properties"]["from_version"]), ("app_updated", "9.9.9"))
 
+    def test_opens_installs_and_updates_carry_the_country(self):
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_TIMEZONE": "Europe/Berlin"}):
+            tm.app_started()
+            with mock.patch.dict(os.environ, {"FRAME_CONTROL_VERSION": "10.0.0"}):
+                tm.app_started()
+        self.assertEqual([(e["event"], e["properties"].get("country")) for e in self.queued()],
+                         [("app_installed", "DE"), ("app_opened", "DE"), ("app_updated", "DE")])
+        self.assertNotIn("Europe/Berlin", tm.OUTBOX.read_text())
+
+    def test_only_zones_in_the_tz_table_give_a_country(self):
+        for tz, want in (("America/Argentina/Buenos_Aires", "AR"), ("Asia/Calcutta", "IN"), ("US/Pacific", "US"),
+                         ("Europe/Vaduz", "LI"), ("Africa/Asmera", "ER"), ("Africa/Asmara", "ER"), ("Pacific/Truk", "FM"),
+                         ("Pacific/Ponape", "FM"), ("America/Montreal", "CA"), ("America/Nassau", "BS"),
+                         ("Europe/Amsterdam", "NL"), ("Etc/GMT+10", None), ("CET", None),
+                         ("EET", None), ("WET", None), ("PST8PDT", None), ("HST", None), ("Pacific/Johnston", "UM"),
+                         ("Japan", "JP"), ("UTC", None), ("alice", None),
+                         ("home/alex/private", None), ("America/alex", None), ("../etc/passwd", None)):
+            with mock.patch.dict(os.environ, {"FRAME_CONTROL_TIMEZONE": tz}):
+                self.assertEqual(tm.country(), want, tz)
+
+    def test_country_from_tz_or_localtime_in_a_checkout(self):
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_TIMEZONE": "", "TZ": ":Asia/Tokyo"}):
+            self.assertEqual(tm.country(), "JP")
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_TIMEZONE": "", "TZ": ""}):
+            for target, want in (("/usr/share/zoneinfo/Europe/Paris", "FR"),
+                                 ("/var/db/timezone/zoneinfo/Australia/Sydney", "AU"),
+                                 ("/home/alex/zoneinfo/alex/private", None), ("/etc/mytime", None)):
+                with mock.patch.object(tm.os.path, "realpath", return_value=target):
+                    self.assertEqual(tm.country(), want, target)
+
+    def test_a_new_user_who_opens_settings_first_still_gets_the_notice(self):
+        tm.update_settings({"compat": True})
+        self.assertFalse(tm.state()["noticeShown"])
+        tm.update_settings({"noticeShown": True})
+        self.assertTrue(tm.state()["noticeShown"])
+
     def test_frame_build_once(self):
         tm.frame_seen("20260922.1", "3.8")
         tm.frame_seen("20260922.1", "3.8")
         self.assertEqual(len(self.queued()), 1)
 
+    def test_frame_once_per_headset_with_saved_count(self):
+        tm.frame_seen("20260922.1", "3.8", "0123456789abcdef", 2)
+        tm.frame_seen("20260922.1", "3.8", "0123456789abcdef", 2)
+        tm.frame_seen("20260922.1", "3.8", "fedcba9876543210", 2)
+        props = [e["properties"] for e in self.queued()]
+        self.assertEqual([(p["headset_id"], p["headsets_saved"]) for p in props],
+                         [("0123456789abcdef", 2), ("fedcba9876543210", 2)])
+
+    def test_frame_many_headsets_are_not_sent_twice(self):
+        ids = ["%016x" % n for n in range(25)]
+        for _ in range(2):
+            for h in ids:
+                tm.frame_seen("20260922.1", "3.8", h, 25)
+        self.assertEqual(len(self.queued()), 25)
+
+    def test_frame_headset_id_must_be_the_hash(self):
+        tm.frame_seen("20260922.1", "3.8", "/etc/machine-id contents", None)
+        p = self.queued()[0]["properties"]
+        self.assertNotIn("headset_id", p)
+        self.assertNotIn("headsets_saved", p)
+
+
+class HeadsetId(unittest.TestCase):
+    def test_hash_of_machine_id_and_none_without_one(self):
+        import hashlib
+        import frame_status
+        with mock.patch.object(frame_status, "read", return_value="abc123"):
+            self.assertEqual(frame_status.headset_id(),
+                             hashlib.sha256(b"frame-control-headset:abc123").hexdigest()[:16])
+        with mock.patch.object(frame_status, "read", return_value=None):
+            self.assertIsNone(frame_status.headset_id())
+
 
 class Sending(Base):
     def serve(self, status=200):
@@ -150,6 +266,39 @@ class Sending(Base):
         self.assertEqual(self.queued(), [])
         self.assertEqual([e["event"] for e in tm.state()["sent"]], ["app_opened"])
 
+    def test_an_older_notice_still_sends(self):
+        got = self.serve()
+        tm._save({**tm._defaults(), "notice_shown": True, "notice_version": 1})
+        tm.capture("app_opened")
+        self.assertEqual(tm.flush(), 1)
+        self.assertEqual(len(got), 1)
+
+    def test_an_older_notice_is_shown_again_and_holds_back_the_country(self):
+        got = self.serve()
+        tm.SETTINGS.write_text(json.dumps({"id": "x", "notice_shown": True, "installed_sent": True,
+                                           "last_version": "9.9.9"}))  # as 0.4.5 saved it
+        self.assertFalse(tm.state()["noticeShown"])
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_TIMEZONE": "Europe/Berlin"}):
+            tm.app_started()
+            self.assertEqual(tm.flush(), 1)  # the usual statistics still go
+            tm.update_settings({"noticeShown": True})
+            self.assertTrue(tm.state()["noticeShown"])
+            tm._save({**tm.settings(), "last_open_day": None})  # the next day
+            tm.app_started()
+            self.assertEqual(tm.flush(), 1)
+        self.assertEqual([b["batch"][0]["properties"].get("country") for _, b in got], [None, "DE"])
+
+    def test_turning_usage_on_still_waits_for_the_new_notice(self):
+        got = self.serve()
+        tm.SETTINGS.write_text(json.dumps({"id": "x", "usage": False, "notice_shown": True, "installed_sent": True,
+                                           "last_version": "9.9.9"}))  # 0.4.5, usage off
+        tm.update_settings({"usage": True})
+        self.assertFalse(tm.state()["noticeShown"])  # so the page shows it
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_TIMEZONE": "Europe/Berlin"}):
+            tm.app_started()
+        self.assertEqual(tm.flush(), 1)
+        self.assertNotIn("country", got[0][1]["batch"][0]["properties"])
+
     def test_a_failed_send_keeps_the_events(self):
         self.serve(status=500)
         tm.update_settings({"noticeShown": True})
@@ -180,6 +329,107 @@ class Scrub(unittest.TestCase):
                          "frame_unreachable")
         self.assertEqual(tm.categorize("something new")[0], "other")
 
+    def test_connection_failures_seen_from_released_versions(self):
+        # Wording from 0.4.0's error reports (addresses replaced), on Windows, macOS and Linux.
+        unreachable = [
+            "ssh: connect to host 192.168.1.20 port 22: Connection timed out",
+            "ssh: connect to host 192.168.1.20 port 22: Operation timed out",
+            "ssh: connect to host 192.168.1.20 port 22: No route to host",
+            "ssh: connect to host 192.168.1.20 port 22: Host is down",
+            "ssh: connect to host 192.168.1.20 port 22: Unknown error",
+            "mux_client_request_session: read from master failed: Broken pipe\n"
+            "ssh: connect to host 192.168.1.20 port 22: Host is down",
+            "client_loop: send disconnect: Connection reset",
+            "banner exchange: Connection to UNKNOWN port -1: Connection refused",
+            "Timed out talking to frame",
+        ]
+        for message in unreachable:
+            self.assertEqual(tm.categorize(message)[0], "frame_unreachable", message)
+        for message in ("ssh: Could not resolve hostname frame: No such host is known.",
+                        "ssh: Could not resolve hostname fe80::1%wireless_32773: No such host is known."):
+            self.assertEqual(tm.categorize(message)[0], "frame_not_set_up", message)
+        self.assertEqual(tm.categorize("ssh exited 1")[0], "other")
+        self.assertEqual(tm.categorize("ssh exited 255")[0], "other")  # may be the command's own exit code
+        self.assertEqual(tm.categorize("download failed: [Errno 54] Connection reset by peer")[0], "download_failed")
+        self.assertEqual(tm.categorize("frame@10.0.0.2: Permission denied (publickey).")[0], "frame_auth")
+
+    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")
+
+    def test_apk_install_failures_that_were_other(self):
+        """What frame_android.install can raise, worded as it is, that 0.4.x sent as 'other'
+        (or as frame_unreachable, when it was the Steam client or a slow copy)."""
+        tail = 'Traceback (most recent call last):\n  File "<stdin>", line 19, in target_ws\n'
+        cases = {
+            "steam_not_running": [
+                "SharedJSContext not found: is the Steam client running?",
+                tail + "urllib.error.URLError: <urlopen error [Errno 111] Connection refused>",
+                tail + "ConnectionRefusedError: [Errno 111] Connection refused",
+            ],
+            "steam_not_responding": [
+                "websocket handshake failed",
+                tail + "TimeoutError: timed out",
+                tail + "socket.timeout: timed out",
+                tail + '  File "<stdin>", line 45, in _read\nEOFError',
+            ],
+            "steam_js_error": ['JS error: {"exceptionId": 1, "text": "Uncaught", "exception": '
+                               '{"description": "Error: Steam artwork API unavailable; installation is incomplete"}}'],
+            "artwork_failed": [
+                "Steam artwork renderer did not produce every slot",
+                tail + "ValueError: incomplete artwork render",
+                tail + "ValueError: hero render is 0 bytes of png",
+                "could not prepare artwork: unknown artwork slot",
+                tail + "ValueError: all five Steam artwork slots are required",
+            ],
+            "copy_timeout": ["copying Big Game (timed out).apk to the Frame timed out",
+                             "copying launch.sh to the Frame timed out"],
+            "copy_failed": [
+                "copying game.apk to the Frame failed: rsync: connection unexpectedly closed (0 bytes received "
+                "so far) [sender]\nrsync error: error in rsync protocol data stream (code 12) at io.c(231)",
+                "copying game.apk to the Frame failed: ",
+            ],
+            "apk_unreadable": [
+                "x.apk: not a readable APK: [Errno 2] No such file or directory: 'x.apk'",
+                "x.apk: could not read the APK manifest: Error -3 while decompressing data: invalid block type",
+                "x.apk: the APK manifest has no package name",
+                "x.apk: lib/arm64-v8a/libx.so in the APK uses a compression Android does not",
+                "x.apk: AndroidManifest.xml in the APK is 40 MB, more than a real one (16 MB)",
+            ],
+        }
+        for category, messages in cases.items():
+            for message in messages:
+                self.assertEqual(tm.categorize(message)[0], category, message)
+        # Still where they were: ssh's own failures, and a full disk during a copy.
+        self.assertEqual(tm.categorize("timed out talking to frame")[0], "frame_unreachable")
+        self.assertEqual(tm.categorize("copying a.apk to the Frame failed: ssh: connect to host 10.0.0.2 "
+                                       "port 22: Connection refused")[0], "frame_unreachable")
+        self.assertEqual(tm.categorize("copying a.apk to the Frame failed: rsync: write failed on "
+                                       "\"app.apk.part\": No space left on device (28)")[0], "frame_disk_full")
+        self.assertEqual(tm.categorize("download failed: timed out")[0], "download_failed")
+
+    def test_python_errors_are_internal_whatever_they_say(self):
+        import json as _json
+        for error in (KeyError("paths"), TypeError("'NoneType' object is not subscriptable"),
+                      AttributeError("x"), _json.JSONDecodeError("Expecting value", "", 0),
+                      UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte"),
+                      KeyError("timed out")):
+            self.assertEqual(tm.categorize(error)[0], "internal_error", repr(error))
+        self.assertEqual(tm.categorize("KeyError: 'paths'")[0], "other")  # only the exception itself
+        self.assertEqual(tm.categorize(OSError(28, "No space left on device"))[0], "frame_disk_full")
+
+    def test_privacy_doc_lists_every_category(self):
+        doc = (ROOT / "docs" / "privacy.md").read_text()
+        for name in {n for n, _ in tm.CATEGORIES} | {"internal_error", "other"}:
+            self.assertIn(f"`{name}`", doc)
+
 
 class Compat(Base):
     def test_reports_are_shared_only_after_opting_in_without_file_names(self):
@@ -205,6 +455,278 @@ class Compat(Base):
         self.assertEqual([e["properties"]["id"] for e in self.queued() if e["event"] == "compat_report"], ["old1"])
 
 
+class LinkFailureProvenance(Base):
+    """Only ssh, where it runs, decides that it couldn't reach the headset; the error report
+    then holds that back for the session. Nothing in a message can claim it."""
+
+    def setUp(self):
+        super().setUp()
+        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, "LINK", {"new": None}),
+                                 (server, "repair_ssh_config", {"return_value": False})):
+            p = mock.patch.object(target, name, **kw)
+            p.start()
+            self.addCleanup(p.stop)
+        tm.update_settings({"diagnostics": True})
+
+    def ssh_fails(self, module, returncode, stderr, stdout=""):
+        """Run module.ssh with ssh exiting `returncode`; -> the exception, as the route handler gets it."""
+        done = subprocess.CompletedProcess(["ssh"], returncode, stdout, stderr)
+        with mock.patch.object(frame_host, "run_ssh", return_value=done):
+            try:
+                module.ssh("true")
+            except Exception as e:  # noqa: BLE001
+                return e
+        self.fail("ssh did not raise")
+
+    def poll_fails(self):
+        e = self.ssh_fails(self.server, 255, "ssh: connect to host 10.0.0.5 port 22: Connection timed out\r\n")
+        tm.diagnostic("POST /api/comfort status", e)
+
+    def test_a_status_poll_that_cannot_reach_the_frame_is_sent_once(self):
+        for _ in range(5):
+            self.poll_fails()
+        for stderr in ("Warning: Permanently added '10.0.0.5' (ED25519) to the list of known hosts.\r\n"
+                       "kex_exchange_identification: read: Connection reset by peer\r\n",
+                       "banner exchange: Connection to UNKNOWN port -1: Connection refused\r\n",
+                       "\x1b[0mssh: connect to host 10.0.0.5 port 22: Unknown error\n"):
+            tm.diagnostic("POST /api/comfort status", self.ssh_fails(self.server, 255, stderr))
+        with mock.patch.object(frame_host, "run_ssh", side_effect=subprocess.TimeoutExpired("ssh", 30)):
+            with self.assertRaises(self.server.Failure) as caught:
+                self.server.ssh("true")
+        tm.diagnostic("POST /api/comfort status", caught.exception)
+        e = self.ssh_fails(self.android, 255, "ssh: connect to host 10.0.0.5 port 22: Host is down\n")
+        tm.diagnostic("job steam", e)
+        self.assertEqual([p["properties"]["error_category"] for p in self.queued()], ["frame_unreachable"])
+
+    def test_host_key_and_login_refusals_are_sent_once(self):
+        # 0.4.2: each of these came in as a $exception from the status poll, again every 10 minutes.
+        for _ in range(3):
+            for stderr in ("@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\r\n"
+                           "@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @\r\n"
+                           "IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!\r\nHost key verification failed.\r\n",
+                           "No ED25519 host key is known for frame-control-f7b4e9ac and you have requested strict "
+                           "checking.\r\nHost key verification failed.\r\n",
+                           "jane doe@frame-control-f7b4e9ac: Permission denied (publickey,password).\r\n",
+                           "steamos@192.168.1.9: Permission denied (publickey,password).\n"):
+                e = self.ssh_fails(self.server, 255, stderr)
+                self.assertTrue(getattr(e, "frame_link_failed", False), stderr)
+                tm.diagnostic("POST /api/comfort status", e)
+        self.assertEqual([p["properties"]["error_category"] for p in self.queued()], ["frame_auth"])
+        # A command on the Frame that was refused something isn't ssh refusing the headset.
+        for code, stderr in ((1, "steamos@frame: Permission denied (publickey).\n"),
+                             (255, "cat: /root/x: Permission denied\n"),
+                             (255, "scp: /home/steamos/x: Permission denied\n")):
+            self.assertFalse(getattr(self.ssh_fails(self.server, code, stderr), "frame_link_failed", False), stderr)
+
+    def test_a_command_that_fails_on_the_frame_is_not_marked(self):
+        self.poll_fails()
+        for module in (self.server, self.android):
+            for code, stderr in ((255, ""), (255, "x: ssh: connect to host frame port 22: Connection timed out\n"),
+                                 (1, "ssh: connect to host 10.0.0.5 port 22: Connection timed out\n")):
+                e = self.ssh_fails(module, code, stderr)
+                self.assertFalse(getattr(e, "frame_link_failed", False), (module.__name__, code, stderr))
+            # Review round 4: the command's own output (stdout) isn't ssh speaking.
+            e = self.ssh_fails(module, 255, "", stdout="ssh: connect to host frame port 22: Connection timed out\n")
+            self.assertFalse(getattr(e, "frame_link_failed", False), module.__name__)
+
+    def request(self, path, body):
+        """POST to the real server, as the page does."""
+        import http.client
+        c = http.client.HTTPConnection("127.0.0.1", self.httpd.server_port)
+        c.request("POST", path, json.dumps(body), {"X-Frame-UI": self.server.UI_KEY, "Content-Type": "application/json"})
+        r = c.getresponse()
+        result = r.status, json.loads(r.read())
+        c.close()
+        return result
+
+    def serve(self):
+        self.httpd = self.server.ThreadingHTTPServer(("127.0.0.1", 0), self.server.Handler)
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+        self.addCleanup(self.httpd.server_close)
+        self.addCleanup(self.httpd.shutdown)
+
+    def test_routes_that_rewrap_a_link_failure_keep_its_mark(self):
+        # Review round 4: /api/android and /api/titles re-raise frame_android's FrameError as a
+        # Failure; after the first connection failure, theirs are held back too, also past the
+        # 10-minute window.
+        self.serve()
+        down = subprocess.CompletedProcess(["ssh"], 255, "", "ssh: connect to host 10.0.0.5 port 22: Connection timed out\r\n")
+        meta = {"label": "Test App", "game_id": 5, "shortcut": None}
+        with mock.patch.object(frame_host, "run_ssh", return_value=down), \
+                mock.patch.object(self.android, "_meta_or_fail", return_value=meta), \
+                mock.patch.object(self.server.frame_titles, "ensure_utils"):
+            self.assertEqual(self.request("/api/comfort", {"action": "status"})[0], 503)  # the page shows its offline message
+            for t in (1000.0, 1000.0 + 2 * tm.REPEAT_WINDOW):
+                with mock.patch.object(tm.time, "time", return_value=t):
+                    self.assertEqual(self.request("/api/android", {"action": "launch", "package": "org.test"})[0], 503)
+                    self.assertEqual(self.request("/api/titles", {"action": "launch", "id": "mygame"})[0], 503)
+            # Not a link failure: still reported, through the same re-wrap.
+            with mock.patch.object(self.android, "_meta_or_fail", side_effect=self.android.FrameError("boom")):
+                self.assertEqual(self.request("/api/android", {"action": "launch", "package": "org.test"})[0], 502)
+        sent = [(e["properties"]["where"], e["properties"]["error_category"]) for e in self.queued()
+                if e["event"] == "$exception"]
+        # The comfort poll's own failure isn't one (see the next test).
+        self.assertEqual(sent, [("POST /api/android launch", "frame_unreachable"), ("POST /api/android launch", "other")])
+
+    def test_the_comfort_poll_meeting_an_unreachable_frame_is_not_sent(self):
+        # 0.4.2: most reports were this poll (every 5 s) finding the headset asleep, away or
+        # refusing ssh. Like GET /api/status, it isn't reported; a session started or cancelled
+        # by hand still is, once, and a real failure of the poll is too.
+        self.serve()
+        for stderr in ("ssh: connect to host 10.0.0.5 port 22: Connection timed out\r\n",
+                       "banner exchange: Connection to UNKNOWN port -1: Connection refused\r\n",
+                       "ssh: Could not resolve hostname frame: nodename nor servname provided\r\n",
+                       "@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @\r\nHost key verification failed.\r\n",
+                       "No ED25519 host key is known for frame-control-f7b4e9ac and you have requested strict "
+                       "checking.\r\nHost key verification failed.\r\n",
+                       "steamos@192.168.1.9: Permission denied (publickey,password).\r\n"):
+            down = subprocess.CompletedProcess(["ssh"], 255, "", stderr)
+            with mock.patch.object(frame_host, "run_ssh", return_value=down):
+                self.assertGreaterEqual(self.request("/api/comfort", {"action": "status"})[0], 500, stderr)
+        self.assertEqual(self.queued(), [])
+        down = subprocess.CompletedProcess(["ssh"], 255, "", "ssh: connect to host 10.0.0.5 port 22: Host is down\r\n")
+        with mock.patch.object(frame_host, "run_ssh", return_value=down):
+            self.request("/api/comfort", {"action": "cancel"})
+        broken = subprocess.CompletedProcess(["ssh"], 1, "", "Traceback (most recent call last):\nOSError: boom\n")
+        with mock.patch.object(frame_host, "run_ssh", return_value=broken):
+            self.assertEqual(self.request("/api/comfort", {"action": "status"})[0], 502)
+        sent = [(e["properties"]["where"], e["properties"]["error_category"]) for e in self.queued()
+                if e["event"] == "$exception"]
+        self.assertEqual(sent, [("POST /api/comfort cancel", "frame_unreachable"), ("POST /api/comfort status", "other")])
+
+    def test_download_failures_after_a_poll_failure_are_still_sent(self):
+        # Review round 3: these file names, in the real checksum message through the web-link worker,
+        # were held back with the poll's connection failures.
+        self.poll_fails()
+        names = ("Connection closed by frame port 22.zip", "Connection reset by frame port 22.apk",
+                 "kex_exchange_identification: read.zip", "banner exchange: payload.zip",
+                 "ssh: connect to host frame port 22: x.zip", "Timed out talking to frame")
+        for name in names:
+            job = {"phase": "download", "done": 0, "total": None, "detail": "", "message": None, "error": None,
+                   "cancel": False}
+            plan = {"name": None, "exe": None, "url": "https://example.com/x.zip", "kind": "zip"}
+            error = self.web.WebInstallError(f"{name} doesn't match the manifest's sha256; not installing it")
+            with mock.patch.object(self.web, "download", side_effect=error):
+                self.server._webinstall_run(plan, job)
+            self.assertEqual(job["phase"], "error")
+        exceptions = [e["properties"] for e in self.queued() if e["event"] == "$exception"]
+        self.assertEqual([p["error_category"] for p in exceptions], ["frame_unreachable"] + ["download_failed"] * len(names))
+        finished = [e["properties"] for e in self.queued() if e["event"] == "install_finished"]
+        self.assertEqual({p["error_category"] for p in finished}, {"download_failed"})
+
+
+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 +746,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)
@@ -391,15 +919,16 @@ class ReportProblem(Base):
     def test_send_is_a_private_posthog_event_whatever_the_settings(self):
         got = self.serve()
         tm.update_settings({"usage": False})  # analytics off: a deliberate report still goes
-        res = fr.send({"kind": "idea", "title": "Live view stops", "message": "It stops after a minute.",
-                       "contact": "me@example.com", "contactFollowup": True})
+        with mock.patch.object(fr.frame_contact, "from_report", return_value=("contact-id", 1)):  # test_contact
+            res = fr.send({"kind": "idea", "title": "Live view stops", "message": "It stops after a minute.",
+                           "contact": "me@example.com", "contactFollowup": True})
         path, body = got[0]
         event = body["batch"][0]
         self.assertEqual((path, body["api_key"], event["event"]), ("/batch/", "phc_test", "problem_report"))
         props = event["properties"]
         self.assertEqual((props["kind"], props["title"], props["message"], props["contact"], props["report_id"]),
                          ("idea", "Live view stops", "It stops after a minute.", "me@example.com", res["id"]))
-        self.assertIs(props["contact_followup"], True)
+        self.assertEqual((props["contact_followup"], props["contact_id"], props["contact_rev"]), (True, "contact-id", 1))
         self.assertEqual((props["$process_person_profile"], props["$geoip_disable"]), (False, True))
         self.assertNotEqual(event["distinct_id"], tm.settings()["id"])  # not linked to the analytics
         self.assertIn(res["id"], res["message"])
@@ -422,8 +951,8 @@ class ReportProblem(Base):
 
     def test_the_inbox_skips_malformed_reports(self):
         good = ["2026-09-28T09:50:00Z", "AB12CD34", "bug", "Live view stops", "It stops.", None,
-                "0.4.0", "macOS", "", "", None]
-        rows = [["2026-09-28T10:00:00Z", "X", "bug", "Hand-made", None, None, None, None, None, None, None],
+                "0.4.0", "macOS", "", "", None, None, None]
+        rows = [["2026-09-28T10:00:00Z", "X", "bug", "Hand-made", None, None, None, None, None, None, None, None, None],
                 ["short"], good]
         with mock.patch.object(db, "_posthog_query", return_value={"results": rows}), \
              mock.patch.object(sys, "argv", ["frame_report.py", "inbox"]), \

tests/test_touch.py

@@ -2,9 +2,15 @@
 
 Run: python3 -m unittest discover -s tests
 """
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import io
+import json
+import os
 import shutil
 import subprocess
 import sys
+import tempfile
+import time
 import unittest
 from pathlib import Path
 
@@ -51,12 +57,9 @@ class Mapping(unittest.TestCase):
         self.assertEqual(t.locate(5, None)["display"], ":0")
 
     def test_focus_display_is_decoded(self):
-        t = self.t
-        saved = t.xprop_root
-        self.addCleanup(lambda: setattr(t, "xprop_root", saved))
         for values, want in (([12602, 0, 58], ":1"), ([12346], ":0"), ([], None), ([0x41], None)):
-            t.xprop_root = lambda d, n, v=values: v
-            self.assertEqual(t.focus_display(), want)
+            self.assertEqual(self.t.focus_display({"GAMESCOPE_FOCUS_DISPLAY": values}), want)
+        self.assertIsNone(self.t.focus_display({}))
 
     def test_ascii_table_covers_printable_characters(self):
         for code in range(0x20, 0x7F):
@@ -147,14 +150,6 @@ class Apply(unittest.TestCase):
         self.assertFalse(self.t.STALE[0])
         self.assertEqual(self.said[-1][1].get("stale"), None)
 
-    def test_stale_survives_a_bare_release(self):
-        gs = FakeGamescope()
-        panel = self.t.apply(gs, {"button": "left", "down": True, "window": 99, "display": ":1"}, None)
-        self.assertTrue(self.t.STALE[0])
-        self.t.apply(gs, {"button": "left", "down": False}, panel)  # the page's release names no panel
-        self.assertTrue(self.t.STALE[0])
-        self.assertEqual(self.said[-1][1].get("stale"), True)
-
     def test_same_window_id_on_the_other_display_is_another_panel(self):
         gs = FakeGamescope()
         self.t.apply(gs, {"fx": 0.5, "fy": 0.5, "window": 7, "display": ":0"}, None)
@@ -267,6 +262,236 @@ class ServerChecks(unittest.TestCase):
             self.s.remote_touch({"events": [{"dx": 1}] * (self.s.INPUT_BATCH_LIMIT + 1)})
 
 
+class FindingPanels(unittest.TestCase):
+    """panels() with faked headset probes: where gamescope's properties are, and why nothing was found (#73)."""
+
+    @classmethod
+    def setUpClass(cls):
+        import frame_touch
+        cls.t = frame_touch
+
+    def setUp(self):
+        t = self.t
+        names = ("read_props", "window_info", "window_pid", "displays", "desktop_running")
+        saved = {n: getattr(t, n) for n in names}
+        saved_which = t.shutil.which
+        self.real_displays = saved["displays"]
+        self.real_read_props = saved["read_props"]
+
+        def restore():
+            for n, v in saved.items():
+                setattr(t, n, v)
+            t.shutil.which = saved_which
+            t._ROOT.clear()
+        self.addCleanup(restore)
+        t._ROOT.clear()
+        self.props = {}  # (display, property) -> values
+        self.windows = {}  # (display, window) -> info
+        self.reads = []  # displays whose gamescope properties were read
+        t.read_props = lambda d, limit=5.0: self.reads.append(d) or {n: list(v) for (dd, n), v in self.props.items() if dd == d}
+        t.window_info = lambda d, w: self.windows.get((d, w))
+        t.window_pid = lambda d, w: None
+        t.displays = lambda: [":0", ":1", ":2"]
+        t.desktop_running = lambda: False
+        t.shutil.which = lambda tool: "/usr/bin/" + tool
+
+    def plasma_on(self, display):
+        # SteamOS 0.4.1: the nested Plasma desktop (kwin_wayland, app id 0) is a window on :0.
+        self.props[(display, "GAMESCOPE_FOCUSABLE_WINDOWS")] = [4194307, 0, 2222]
+        self.props[(display, "GAMESCOPE_FOCUSED_WINDOW")] = [4194307]
+        self.props[(display, "GAMESCOPE_FOCUS_DISPLAY")] = [0x303A]  # ":0"
+        self.windows[(":0", 4194307)] = {"name": "KDE Wayland Compositor", "x": 0, "y": 0, "width": 1280, "height": 800}
+        self.windows[(":0", "root")] = {"width": 1280, "height": 720}
+
+    def test_desktop_panel_on_display_0(self):
+        self.plasma_on(":0")
+        out = self.t.panels()
+        self.assertEqual([(p["window"], p["display"], p["focused"]) for p in out["panels"]], [(4194307, ":0", True)])
+        self.assertNotIn("why", out)
+
+    def test_display_0_costs_one_read(self):
+        # The layout of every build seen so far: one read of :0's properties for the whole run.
+        self.plasma_on(":0")
+        self.t.panels()
+        self.assertEqual(self.reads, [":0"])
+
+    def test_gamescope_properties_on_another_display_are_found(self):
+        # A build that numbers its displays differently: :0 has no gamescope properties.
+        self.plasma_on(":1")
+        self.assertEqual(self.t.gamescope()[0], ":1")
+        self.reads.clear()
+        self.t._ROOT.clear()
+        self.assertEqual(len(self.t.panels()["panels"]), 1)
+        self.assertEqual(self.reads, [":0", ":1"])  # read once, then reused by focus() and focusable()
+
+    def test_other_displays_are_probed_briefly(self):
+        limits = []
+        self.t.read_props = lambda d, limit=5.0: limits.append((d, limit)) or {}
+        self.assertEqual(self.t.gamescope(), (":0", {}))
+        self.assertEqual(limits, [(":0", 5.0), (":1", self.t.ROOT_PROBE_TIMEOUT), (":2", self.t.ROOT_PROBE_TIMEOUT)])
+
+    def test_input_helper_remembers_the_display(self):
+        # The input helper lives for a session: a found display is kept, a failed search retried later.
+        t = self.t
+        self.plasma_on(":1")
+        t.gamescope(); t.gamescope()
+        self.assertEqual(self.reads, [":0", ":1", ":1"])
+        self.props.clear()
+        self.reads.clear()
+        t._ROOT.clear()
+        t.gamescope(); t.gamescope()
+        self.assertEqual(self.reads, [":0", ":1", ":2", ":0"])  # given up: :0 for ROOT_RETRY
+        t._ROOT[1] -= t.ROOT_RETRY
+        self.reads.clear()
+        t.gamescope()
+        self.assertEqual(self.reads, [":0", ":1", ":2"])
+
+    def test_read_props_parses_xprop(self):
+        t = self.t
+        saved = t.subprocess.run
+        self.addCleanup(setattr, t.subprocess, "run", saved)
+        out = ("GAMESCOPE_FOCUSABLE_WINDOWS(CARDINAL) = 1, 0, 2, 3, 769, 4\n"
+               "GAMESCOPE_FOCUSED_WINDOW(CARDINAL) = 0\nGAMESCOPE_FOCUS_DISPLAY:  not found.\n")
+        t.subprocess.run = lambda *a, **k: subprocess.CompletedProcess(a, 0, out, "")
+        self.assertEqual(self.real_read_props(":0"), {"GAMESCOPE_FOCUSABLE_WINDOWS": [1, 0, 2, 3, 769, 4],
+                                                      "GAMESCOPE_FOCUSED_WINDOW": [0]})
+        t.subprocess.run = lambda *a, **k: subprocess.CompletedProcess(a, 0, "GAMESCOPE_FOCUSED_WINDOW:  not found.\n", "")
+        self.assertEqual(self.real_read_props(":0"), {})
+
+        def hang(*a, **k):
+            raise subprocess.TimeoutExpired(a[0], k.get("timeout"))
+        t.subprocess.run = hang
+        self.assertEqual(self.real_read_props(":0"), {})
+
+    def test_deadline_returns_what_was_found(self):
+        t, clock = self.t, [0.0]
+        self.plasma_on(":0")
+        self.props[(":0", "GAMESCOPE_FOCUSABLE_WINDOWS")] = [4194307, 0, 2222, 5, 0, 1, 6, 0, 1]
+        saved = t.time.monotonic
+        self.addCleanup(setattr, t.time, "monotonic", saved)
+        t.time.monotonic = lambda: clock[0]
+        info = self.windows.get
+
+        def slow(d, w):  # every xwininfo takes 1 s: the run is out of time after a few
+            t.budget()
+            clock[0] += 1
+            return info((d, w))
+        t.window_info = slow
+        out = t.panels(limit=7)  # focus: 2 reads; the first panel: 3 displays and its root
+        self.assertEqual([p["window"] for p in out["panels"]], [4194307])
+        self.assertIn("took too long", out["why"])
+        self.assertIn("Some may be missing", out["why"])
+        self.assertIsNone(t.DEADLINE[0])  # the next run (or the input helper) has no deadline left over
+
+    def test_listed_window_that_isnt_x11_explains_itself(self):
+        self.plasma_on(":0")
+        del self.windows[(":0", 4194307)]  # say, a desktop drawn as a Wayland window
+        out = self.t.panels()
+        self.assertEqual(out["panels"], [])
+        self.assertIn("can't find its window", out["why"])
+        self.assertIn("Headset view", out["why"])
+
+    def test_desktop_running_but_not_listed(self):
+        self.t.desktop_running = lambda: True
+        out = self.t.panels()
+        self.assertEqual(out["panels"], [])
+        self.assertIn("desktop is running", out["why"])
+
+    def test_nothing_open(self):
+        out = self.t.panels()
+        self.assertEqual(out, {"focus": None, "focus_display": None, "panels": [],
+                               "why": "No app panel is open in the headset. Open the desktop or an app in "
+                                      "the headset, then try again."})
+
+    def test_missing_x_tools_are_named(self):
+        self.plasma_on(":0")
+        self.t.shutil.which = lambda tool: None if tool == "xwininfo" else "/usr/bin/" + tool
+        self.windows.clear()  # xwininfo can't run, so nothing resolves
+        self.assertIn("no xwininfo", self.t.panels()["why"])
+
+    def test_displays_include_abstract_sockets(self):
+        # /tmp/.X11-unix not visible to the SSH session: the abstract sockets still name the displays.
+        import builtins
+        t = self.t
+        real_open, real_listdir = builtins.open, t.os.listdir
+
+        def fake_open(path, *a, **k):
+            if path == "/proc/net/unix":
+                return io.StringIO("0000: 00000002 0 ... @/tmp/.X11-unix/X1\n0000: ... @/tmp/.X11-unix/X0\n"
+                                   "0000: ... /run/user/1000/wayland-0\n")
+            return real_open(path, *a, **k)
+
+        def fake_listdir(path):
+            if path == "/tmp/.X11-unix":
+                raise FileNotFoundError(path)
+            return real_listdir(path)
+        builtins.open, t.os.listdir = fake_open, fake_listdir
+        try:
+            self.assertEqual(self.real_displays(), [":0", ":1"])
+        finally:
+            builtins.open, t.os.listdir = real_open, real_listdir
+
+
+FAKE_XPROP = """#!/bin/sh
+sleep "${FAKE_X_DELAY:-0}"
+if [ "$1" = "-root" ] && [ "$DISPLAY" = ":0" ]; then
+  echo "GAMESCOPE_FOCUSABLE_WINDOWS(CARDINAL) = 11, 0, 101, 12, 769, 102"
+  echo "GAMESCOPE_FOCUSED_WINDOW(CARDINAL) = 11"
+  echo "GAMESCOPE_FOCUS_DISPLAY(CARDINAL) = 12346"
+fi
+"""
+FAKE_XWININFO = """#!/bin/sh
+sleep "${FAKE_X_DELAY:-0}"
+[ "$DISPLAY" = ":0" ] || exit 1
+echo 'xwininfo: Window id: 0xb "Desktop"'
+echo '  Absolute upper-left X:  0'
+echo '  Absolute upper-left Y:  0'
+echo '  Width: 1280'
+echo '  Height: 800'
+echo '  Map State: IsViewable'
+"""
+
+
+@unittest.skipIf(sys.platform == "win32", "fake X tools are shell scripts; frame_touch.py runs on the Frame")
+class PanelsAsAFreshProcess(unittest.TestCase):
+    """`frame_touch.py panels` the way the server runs it: a new process each request, with
+    fake xprop and xwininfo first on PATH (two displays, :0 and :1)."""
+
+    def run_panels(self, delay):
+        with tempfile.TemporaryDirectory() as bin_dir:
+            for name, body in (("xprop", FAKE_XPROP), ("xwininfo", FAKE_XWININFO)):
+                path = Path(bin_dir) / name
+                path.write_text(body)
+                path.chmod(0o755)
+            env = dict(os.environ, PATH=bin_dir + os.pathsep + os.environ.get("PATH", ""), FAKE_X_DELAY=str(delay),
+                       PYTHONDONTWRITEBYTECODE="1")
+            code = ("import sys; sys.path.insert(0, sys.argv[1]); import frame_touch as t; "
+                    "t.displays = lambda: [':0', ':1']; t.desktop_running = lambda: False; "
+                    "sys.argv = ['frame_touch.py', 'panels']; sys.exit(t.main())")
+            start = time.monotonic()
+            r = subprocess.run([sys.executable, "-c", code, str(ROOT / "ui")], env=env, capture_output=True,
+                               text=True, timeout=60)
+            took = time.monotonic() - start
+        self.assertEqual(r.returncode, 0, r.stderr)
+        return json.loads(r.stdout), took
+
+    def test_lists_panels(self):
+        out, _ = self.run_panels(0)
+        self.assertEqual(out["focus"], 11)
+        self.assertEqual(out["focus_display"], ":0")
+        self.assertEqual([(p["window"], p["display"], p["focused"]) for p in out["panels"]],
+                         [(11, ":0", True), (12, ":0", False)])
+        self.assertNotIn("why", out)
+
+    def test_slow_x_tools_stay_inside_the_servers_timeout(self):
+        # Review of #83: X tools answering in 4.6 s each would take well over the server's
+        # 20 s; one deadline for the run (PANELS_DEADLINE, 12 s) returns in time, saying why.
+        out, took = self.run_panels(4.6)
+        self.assertLess(took, 15, out)
+        self.assertEqual(out["panels"], [])
+        self.assertIn("took too long", out["why"])
+
+
 @unittest.skipUnless(shutil.which("node"), "needs node")
 class PageGestures(unittest.TestCase):
     """Control's gestures and queue (tests/page/ctrl_gestures.mjs runs the real functions from index.html)."""
@@ -276,6 +501,12 @@ class PageGestures(unittest.TestCase):
                            timeout=60)
         self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
 
+    def test_desktop_panel_list(self):
+        # #73: the headset's reason for no panels, and a failed listing, reach Capture and Control.
+        r = subprocess.run(["node", str(ROOT / "tests" / "page" / "desk_panels.mjs")], capture_output=True, text=True,
+                           timeout=60)
+        self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+
 
 class Script(unittest.TestCase):
     def test_helper_compiles_on_the_frames_python(self):

tests/test_vr.py

@@ -1,4 +1,5 @@
 """Own VR telemetry, optional catalogue and entitlement guards; no headset needed."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import ctypes
 import json
 from pathlib import Path

tests/test_webinstall.py

@@ -386,17 +386,28 @@ class ServerJobs(unittest.TestCase):
     def test_dead_servers_leftovers_swept(self):
         dead = subprocess.Popen([sys.executable, "-c", "pass"])
         dead.wait()
-        # Downloads and title staging (unzipped titles) are both swept.
-        for prefix in (self.server.WEB_TMP_PREFIX, self.server.frame_titles.TMP_PREFIX):
-            gone = tempfile.mkdtemp(prefix=f"{prefix}{dead.pid}-")
-            live = tempfile.mkdtemp(prefix=f"{prefix}{os.getpid()}-")
-            try:
-                self.server.sweep_tmp()
-                self.assertFalse(os.path.exists(gone), prefix)
-                self.assertTrue(os.path.exists(live), prefix)
-            finally:
-                shutil.rmtree(gone, ignore_errors=True)
-                shutil.rmtree(live, ignore_errors=True)
+        s = self.server
+        with tempfile.TemporaryDirectory() as cache, \
+                mock.patch.object(s.frame_host, "cache_dir", lambda *parts: Path(cache).joinpath(*parts)):
+            # Downloads, title staging, patched VR APKs, files staged for the
+            # assistant, and app-index downloads (in the cache folder).
+            places = s._tmp_places()
+            self.assertEqual({p for _, p in places}, {s.WEB_TMP_PREFIX, s.frame_titles.TMP_PREFIX,
+                                                      s.frame_android.TMP_PREFIX, s.frame_agent.TMP_PREFIX,
+                                                      s.apk_fdroid.TMP_PREFIX})
+            for folder, prefix in places:
+                folder.mkdir(parents=True, exist_ok=True)
+                gone = tempfile.mkdtemp(prefix=f"{prefix}{dead.pid}-", dir=folder)
+                live = tempfile.mkdtemp(prefix=f"{prefix}{os.getpid()}-", dir=folder)
+                try:
+                    s.sweep_tmp()
+                    self.assertFalse(os.path.exists(gone), prefix)
+                    self.assertTrue(os.path.exists(live), prefix)
+                    s.sweep_tmp(own=True)  # on the way out: this server's own go too
+                    self.assertFalse(os.path.exists(live), prefix)
+                finally:
+                    shutil.rmtree(gone, ignore_errors=True)
+                    shutil.rmtree(live, ignore_errors=True)
 
     def test_temp_dir_failure_ends_the_job(self):
         job, dispatch = self.run_job(mkdtemp_error=OSError("disk full"))

tests/test_windows_fixes.py

@@ -0,0 +1,162 @@
+"""Windows-only paths, faked on any OS: ~/.ssh/config's ACL and link-local IPv6 zones.
+
+Run: python3 -m unittest discover -s tests
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "ui"))
+
+import frame_host  # noqa: E402
+import frame_devices as fd  # noqa: E402
+
+REFUSED = ("Bad permissions. Try removing permissions for user: UNKNOWN\\UNKNOWN (S-1-5-21-1-2-3-1000) "
+           "on file C:/Users/bob/.ssh/config.\r\nBad owner or permissions on C:\\Users\\bob/.ssh/config\r\n")
+
+
+def ran(*results):
+    """subprocess.run stand-in answering whoami, then icacls."""
+    calls = []
+
+    def run(argv, **kw):
+        calls.append(argv)
+        return results[len(calls) - 1]
+    return run, calls
+
+
+class MakePrivate(unittest.TestCase):
+    def test_windows_sets_owner_only_acl_by_sid(self):
+        run, calls = ran(subprocess.CompletedProcess([], 0, '"desktop\\björn","S-1-5-21-9-8-7-1001"\r\n'.encode("cp850")),
+                         subprocess.CompletedProcess([], 0))
+        with mock.patch.object(frame_host, "WINDOWS", True), mock.patch.object(frame_host.subprocess, "run", run):
+            self.assertTrue(frame_host.make_private(Path("C:/x/config")))
+        self.assertEqual(calls[1][1:], [str(Path("C:/x/config")), "/inheritance:r", "/grant:r",
+                                        "*S-1-5-21-9-8-7-1001:F", "*S-1-5-18:F", "*S-1-5-32-544:F"])
+
+    def test_windows_falls_back_to_username_and_reports_failure(self):
+        run, calls = ran(subprocess.CompletedProcess([], 1, b""), subprocess.CompletedProcess([], 5))
+        with mock.patch.object(frame_host, "WINDOWS", True), mock.patch.object(frame_host.subprocess, "run", run), \
+                mock.patch.dict(os.environ, {"USERNAME": "bob"}):
+            self.assertFalse(frame_host.make_private(Path("config")))
+        self.assertIn("bob:F", calls[1])
+
+    @unittest.skipIf(os.name == "nt", "POSIX modes")
+    def test_posix_chmods_600(self):
+        with tempfile.NamedTemporaryFile() as f:
+            os.chmod(f.name, 0o644)
+            self.assertTrue(frame_host.make_private(f.name))
+            self.assertEqual(os.stat(f.name).st_mode & 0o777, 0o600)
+
+
+class ConfigWrites(unittest.TestCase):
+    def setUp(self):
+        self.ssh = Path(tempfile.mkdtemp(prefix="frame-acl-"))
+        self.addCleanup(shutil.rmtree, self.ssh, ignore_errors=True)
+        self.config = self.ssh / "config"
+
+    def test_devices_and_connect_writes_make_the_file_private(self):
+        import frame_connect as fc
+        self.config.write_text("Host other\n  User me\n", encoding="utf-8")
+        with mock.patch.object(frame_host, "make_private", return_value=True) as private, \
+                mock.patch.object(fc, "SSH_DIR", self.ssh), mock.patch.object(fc, "CONFIG", self.config):
+            fc.write_config("10.0.0.5")
+            self.assertTrue(fd.repair_permissions(self.config))
+            fd.rewrite_block("frame", path=self.config, user="deck")
+        self.assertEqual(private.call_count, 3)
+        self.assertIn("User deck", self.config.read_text(encoding="utf-8"))
+        self.assertTrue(all(Path(c.args[0]).parent == self.ssh for c in private.call_args_list))
+        self.assertIn("Host other", self.config.read_text(encoding="utf-8"))
+
+    def test_setup_runs_isolated_as_the_app_starts_it(self):
+        r = subprocess.run([sys.executable, "-I", "-B", str(ROOT / "ui" / "frame_connect.py"), "--help"],
+                           capture_output=True, text=True, stdin=subprocess.DEVNULL, timeout=30)
+        self.assertNotIn("ModuleNotFoundError", r.stderr)
+        self.assertIn("frame_connect.py", r.stdout + r.stderr)
+
+    def test_repair_keeps_the_bytes_and_skips_a_missing_file(self):
+        self.assertFalse(fd.repair_permissions(self.config))
+        data = "# caf\xe9 (ANSI, not UTF-8)\r\nHost a\r\n".encode("cp1252")
+        self.config.write_bytes(data)
+        with mock.patch.object(frame_host, "make_private", return_value=True):
+            self.assertTrue(fd.repair_permissions(self.config))
+        self.assertEqual(self.config.read_bytes(), data)
+
+    def test_repair_fails_without_the_acl_and_leaves_the_file(self):
+        self.config.write_bytes(b"Host a\n")
+        before = self.config.stat().st_ino
+        with mock.patch.object(frame_host, "make_private", return_value=False):
+            self.assertFalse(fd.repair_permissions(self.config))
+        self.assertEqual((self.config.read_bytes(), self.config.stat().st_ino), (b"Host a\n", before))
+        self.assertEqual(sorted(f.name for f in self.ssh.iterdir()), ["config", fd.LOCK_NAME])
+
+
+class ServerRepair(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        import server
+        cls.server = server
+
+    def setUp(self):
+        self.ssh = Path(tempfile.mkdtemp(prefix="frame-acl-"))
+        self.addCleanup(shutil.rmtree, self.ssh, ignore_errors=True)
+        (self.ssh / "config").write_text("Host a\n", encoding="utf-8")
+        patches = [mock.patch.dict(os.environ, {"FRAME_CONTROL_SSH_DIR": str(self.ssh)}),
+                   mock.patch.object(frame_host, "WINDOWS", True),
+                   mock.patch.object(self.server, "_config_repaired", False)]
+        for p in patches:
+            p.start()
+            self.addCleanup(p.stop)
+
+    def test_repairs_the_refused_config_once(self):
+        with mock.patch.object(fd, "repair_permissions", return_value=True) as repair:
+            self.assertTrue(self.server.repair_ssh_config(REFUSED))
+            self.assertFalse(self.server.repair_ssh_config(REFUSED))
+        repair.assert_called_once()
+
+    def test_leaves_other_files_and_errors_alone(self):
+        key = REFUSED.replace(".ssh/config", ".ssh/id_ed25519_frame")
+        with mock.patch.object(fd, "repair_permissions") as repair:
+            self.assertFalse(self.server.repair_ssh_config(key))
+            self.assertFalse(self.server.repair_ssh_config("ssh: connect to host frame port 22: timed out"))
+            with mock.patch.object(frame_host, "WINDOWS", False):
+                self.assertFalse(self.server.repair_ssh_config(REFUSED))
+        repair.assert_not_called()
+
+    def test_ssh_retries_after_repairing(self):
+        results = iter([subprocess.CompletedProcess([], 255, "", REFUSED), subprocess.CompletedProcess([], 0, "ok", "")])
+        with mock.patch.object(frame_host, "run_ssh", lambda *a, **k: next(results)), \
+                mock.patch.object(fd, "repair_permissions", return_value=True), \
+                mock.patch.object(self.server, "LINK", None):
+            self.assertEqual(self.server.ssh("true"), "ok")
+
+
+class LinkLocalZone(unittest.TestCase):
+    """A .local name answering on fe80::: Windows' ssh needs fe80::1%12, not %wireless_32768."""
+
+    def probe(self, windows):
+        import frame_link as fl
+        info = [(fl.socket.AF_INET6, fl.socket.SOCK_STREAM, 6, "", ("fe80::1", 22, 0, 12))]
+        sock = mock.MagicMock()
+        with mock.patch.object(frame_host, "WINDOWS", windows), \
+                mock.patch.object(fl.socket, "getaddrinfo", return_value=info), \
+                mock.patch.object(fl.socket, "socket", return_value=sock), \
+                mock.patch.object(fl.socket, "if_indextoname", return_value="wireless_32768", create=True):
+            return fl.probe("frame.local", 22)["ip"]
+
+    def test_windows_uses_the_numeric_zone(self):
+        self.assertEqual(self.probe(True), "fe80::1%12")
+
+    def test_elsewhere_uses_the_interface_name(self):
+        self.assertEqual(self.probe(False), "fe80::1%wireless_32768")
+
+
+if __name__ == "__main__":
+    unittest.main()

ui/apk_sources/_categories.py

@@ -0,0 +1,116 @@
+"""Store categories that make sense on a Steam Frame, and which apps only make sense on a phone.
+
+Sources describe apps in their own terms (F-Droid's categories, a VR flag). The store groups
+them for a headset instead: VR first, then games and the flat apps worth having in a panel
+(video, reading, making things). Apps built around a phone's hardware or system (calls and
+SMS, launchers, widgets, keyboards, fitness, root tools) are marked phone_only; the store
+hides them unless asked, since Lepton can run them but they do nothing useful on the Frame.
+"""
+import re
+
+# (id, label), in the order the store shows them.
+CATEGORIES = (
+    ('vr', 'VR'),
+    ('games', 'Games'),
+    ('emulators', 'Emulators'),
+    ('watch', 'Watch & listen'),
+    ('read', 'Read & learn'),
+    ('create', 'Create'),
+    ('work', 'Work'),
+    ('web', 'Web & chat'),
+    ('tools', 'Tools'),
+)
+IDS = {c for c, _ in CATEGORIES}
+
+# F-Droid's category names -> a store category; None = only useful on a phone.
+# F-Droid has broad categories ('Multimedia') and, since 2025, finer ones ('Podcast'); an app
+# usually has both. A finer one decides, since 'Social Network' + 'Multimedia' is a chat app.
+BROAD = {
+    'Games': 'games', 'Multimedia': 'watch', 'Reading': 'read', 'Science & Education': 'read',
+    'Graphics': 'create', 'Writing': 'work', 'Money': 'work', 'Time': 'work', 'Internet': 'web',
+    'Development': 'tools', 'Security': 'tools',
+    'Office': 'work', 'Food': 'read',  # IzzyOnDroid's own names
+    'Connectivity': None, 'Navigation': None, 'Phone & SMS': None, 'Sports & Health': None,
+    'System': None, 'Theming': None,
+}
+FINE = {
+    'emulators': ('Emulator',),
+    'games': ('Action Game', 'Board Game', 'Card Game', 'Casual Game', 'Dice', 'Educational Game', 'Party Game',
+              'Platformer Game', 'Puzzle Game', 'Role-Playing Game', 'Shooter Game', 'Sport Game',
+              'Strategy Game', 'Visual Novel', 'Word Game'),
+    'watch': ('Local Media Player', 'Online Media Player', 'Podcast', 'Radio', 'Cast', 'Lyrics', 'Gallery',
+              'Ambient Sound'),
+    'read': ('Ebook Reader', 'Audiobook', 'News', 'Translation & Dictionary', 'Religion', 'Recipe Manager'),
+    'create': ('Draw', 'Music Practice Tool', 'Recorder'),
+    'web': ('Browser', 'Email', 'Messaging', 'Social Network', 'Forum', 'Voice & Video Chat', 'AI Chat',
+            'Bookmark'),
+    'work': ('Note', 'Task', 'Text Editor', 'Calendar & Agenda', 'Calculator', 'Unit Convertor',
+             'Finance Manager', 'Time Tracker', 'Schedule', 'Inventory'),
+    'tools': ('Code & Forge', 'Password & 2FA', 'File Manager', 'File Encryption & Vault', 'Text Encryption',
+              'Remote Access', 'Remote Controller', 'Cloud Storage & File Sync', 'Network Analyzer',
+              'File Transfer', 'Text to Speech', 'Speech Recognizer', 'Download', 'Game Helper', 'Weather'),
+}
+FINE_TARGET = {name: target for target, names in FINE.items() for name in names}
+# Only make sense as part of a phone's own system: any one of these makes an app phone-only.
+PHONE_SYSTEM = {
+    'Launcher', 'Keyboard & IME', 'Wallpaper', 'Icon Pack', 'Flashlight', 'Battery', 'Notification', 'Volume',
+    'Theming', 'Emergency Action', 'Xposed', 'Automation',
+}
+# Phone things that are often a side of a useful app (Thunderbird is in Contact, FluffyChat in
+# Phone & SMS, Nextcloud in Connectivity, a file manager in System): phone-only unless a useful
+# category says otherwise. A finer one when the source has them; a broad one when it only has
+# broad ones (IzzyOnDroid often does).
+PHONE_SIDE = {
+    'Phone & SMS', 'Push', 'Contact', 'Camera', 'OCR', 'Location Tracker & Sharer', 'Navigation',
+    'Public Transport', 'Workout', 'Diet', 'Medication', 'Health Manager', 'Alarm Clock', 'Pass Wallet',
+    'Wallet', 'VPN & Proxy', 'DNS & Hosts', 'Firewall', 'App Manager', 'App Store & Updater', 'System',
+    'Connectivity',
+}
+PHONE_CATEGORIES = PHONE_SYSTEM | PHONE_SIDE
+# Fine categories that aren't useful on a headset either, but don't make an app phone-only on their own.
+PHONE_LEANING = {'Clock', 'Timer', 'Stopwatch', 'Habit Tracker', 'Shopping List', 'Market & Price',
+                 'Meditation', 'Mental Health', 'Sports & Health'}
+# When an app has several, the one that best describes it on a headset wins.
+PRIORITY = ('emulators', 'games', 'watch', 'read', 'create', 'web', 'work', 'tools')
+
+EMULATOR = re.compile(r'\bemulat(or|ion|es)\b|\b(retroarch|ppsspp|dolphin|dosbox|scummvm|mame|mupen64|melonds|citra|duckstation|flycast)\b', re.I)
+# What an app is, from its name: these are phone parts, whatever the categories say.
+PHONE_NAME = re.compile(r'\b(launcher|home ?screen|widgets?|keyboard|wallpapers?|ringtones?|dialer|sms|mms|'
+                        r'caller id|lock ?screen|status ?bar|step counter|pedometer|5g|4g|lte|hotspot|tethering|'
+                        r'magisk|xposed|battery)\b|\[root\]', re.I)
+# "Doesn't need root" isn't a root tool; taken out before HARDWARE looks for "needs root".
+NOT_ROOT = re.compile(r"\b(no|non|without|not|never|doesn.?t (need|require)|does not (need|require)|don.?t (need|require))[- ]+(the )?root(ed|ing)?\b"
+                      r"|\broot(less|[- ]free| (is )?not (required|needed))\b", re.I)
+# Needs hardware or a device the Frame doesn't have, from the name or summary.
+HARDWARE = re.compile(r'\b(infra-?red|ir (blaster|remote|transmitter)|wear ?os|smart ?watch(es)?|nfc|sim card|'
+                      r'(requires?|needs?|for) (a )?root(ed)?( (access|device|phone))?)\b', re.I)
+
+
+def classify(entry):
+    """{'category': one of IDS or None, 'phone_only': bool} for a store entry."""
+    if entry.get('vr') is True:
+        return {'category': 'vr', 'phone_only': False}
+    name, summary = str(entry.get('name') or ''), str(entry.get('summary') or '')
+    names = [c for c in entry.get('categories') or () if isinstance(c, str)]
+    fine = {FINE_TARGET[c] for c in names if c in FINE_TARGET}
+    broad = {BROAD[c] for c in names if BROAD.get(c)}
+    category = next((c for c in PRIORITY if c in fine), None) or next((c for c in PRIORITY if c in broad), None)
+    if category is None and EMULATOR.search(name + ' ' + summary):
+        category = 'emulators'
+    only_broad = all(c in BROAD for c in names)  # this source has no finer categories for it
+    useful = fine or (broad if only_broad else set())
+    phone = any(c in PHONE_SYSTEM for c in names) or (not useful and any(c in PHONE_SIDE for c in names))
+    if names and category is None and all(c in PHONE_CATEGORIES or c in PHONE_LEANING or BROAD.get(c, 1) is None
+                                          for c in names):
+        phone = True
+    if category not in ('games', 'emulators', 'watch', 'read', 'create'):
+        phone = phone or bool(PHONE_NAME.search(name)) or bool(HARDWARE.search(NOT_ROOT.sub(' ', name + ' ' + summary)))
+    return {'category': category, 'phone_only': phone}
+
+
+def matches(entry, category=None, phone=False):
+    """Whether a classified entry belongs in a browse for this category ('' or None = any). A search
+    shows phone-only apps too (search passes phone=True), so a wrong guess never hides an app."""
+    if entry.get('phone_only') and not phone:
+        return False
+    return not category or entry.get('category') == category

ui/apk_sources/_images.py

@@ -12,7 +12,9 @@ from urllib.parse import urljoin, urlsplit
 from apk_sources import SourceError
 
 _lock = threading.Lock()
-_urls = OrderedDict()
+_urls = OrderedDict()  # token -> URL, oldest first
+_tokens = {}  # URL -> token
+MAX_TOKENS = 16384
 _cache = OrderedDict()
 MAX_IMAGE = 8 * 1024 * 1024
 MAX_CACHE = 64 * 1024 * 1024
@@ -31,24 +33,24 @@ def register(url):
     if not isinstance(url, str) or not valid_url(url):
         return None
     with _lock:
-        for token, known in _urls.items():
-            if known == url:
-                _urls.move_to_end(token)
-                return '/source-image/' + token
+        token = _tokens.get(url)
+        if token in _urls:
+            _urls.move_to_end(token)
+            return '/source-image/' + token
         token = secrets.token_urlsafe(24)
-        _urls[token] = url
-        while len(_urls) > 4096:
-            _urls.popitem(last=False)
+        _urls[token], _tokens[url] = url, token
+        while len(_urls) > MAX_TOKENS:  # a store browse lists a few thousand images
+            _tokens.pop(_urls.popitem(last=False)[1], None)
     return '/source-image/' + token
 
 
-def artwork(entry):
+def artwork(entry, shots=12):
     images = entry.get('images') or {}
     if not isinstance(images, dict):
         images = {}
     return {'icon': register(images.get('icon') or entry.get('icon')),
             'banner': register(images.get('banner')),
-            'screenshots': [path for path in (register(u) for u in (images.get('screenshots') or [])[:12]) if path]}
+            'screenshots': [path for path in (register(u) for u in (images.get('screenshots') or [])[:min(shots, 12)]) if path]}
 
 
 def image_type(data):
@@ -71,12 +73,37 @@ def fetch(url, redirects=3, deadline=None, limit=MAX_IMAGE):
 
 # Lookups that outlast their deadline keep running; cap them so they can't pile up.
 _resolvers = threading.BoundedSemaphore(4)
+# A page of store cards asks for dozens of images from the same few hosts at once: their public
+# addresses are kept for a few minutes, so most requests don't need a lookup (or a slot) at all.
+_dns = {}  # (host, port) -> (addresses, expires)
+DNS_TTL = 300
 
 
 def _resolve(host, port, timeout):
+    with _lock:
+        known = _dns.get((host, port))
+    if known and known[1] > time.monotonic():
+        return known[0]
+    found = _lookup(host, port, timeout)
+    try:
+        public = bool(found) and all(ipaddress.ip_address(a[4][0]).is_global for a in found)
+    except (TypeError, ValueError, IndexError):
+        public = False
+    if public:  # private answers are refused by the caller, and never kept
+        with _lock:
+            _dns[(host, port)] = (found, time.monotonic() + DNS_TTL)
+            while len(_dns) > 256:
+                _dns.pop(next(iter(_dns)))
+    return found
+
+
+def _lookup(host, port, timeout):
     # getaddrinfo has no timeout of its own; a thread keeps a slow resolver inside the budget.
-    if not _resolvers.acquire(blocking=False):
+    # A request waits for a free slot within its own budget rather than failing at once.
+    started = time.monotonic()
+    if not _resolvers.acquire(timeout=max(0, min(timeout, 10))):
         raise SourceError('Too many slow artwork name lookups are still running; try again shortly')
+    timeout -= time.monotonic() - started  # the wait for a slot comes out of the same budget
     found = {}
 
     def run():

ui/apk_sources/fdroid.py

@@ -26,7 +26,8 @@ from frame_apk_sign import _der_parts, _cert_key, der
 from frame_catalog import _IndexReader, _reduce_index, _sha256
 
 KIND = 'fdroid'
-CACHE_VERSION = 2
+CACHE_VERSION = 3  # 3: categories
+TMP_PREFIX = '.download-'  # in the cache folder, then the server's PID, so server.sweep_tmp can clear a stopped run's
 _LOCK = threading.RLock()  # settings only; never held while downloading
 _load_locks = {}
 _refreshing = {}  # source id -> background refresh thread
@@ -431,6 +432,7 @@ def _reduce(path, source):
                     name=_text(meta.get('name')) or pkg, summary=_summary(meta.get('summary')),
                     icon=images['icon'], images=images, developer=_text(meta.get('authorName')) or None,
                     page=meta.get('webSite') or source['url'], vr=None, free=True,
+                    categories=[c for c in meta.get('categories') or [] if isinstance(c, str)][:8],
                     license=meta.get('license'), downloadable=bool(latest.get('sha256')),
                     versions=versions, **{k: latest[k] for k in ('version', 'version_code', 'min_sdk', 'abis', 'size', 'updated')})
     return result
@@ -449,6 +451,7 @@ def _v1(content, path):
         localized = app.get('localized', {})
         meta = {k: _text({locale: fields[k] for locale, fields in localized.items() if fields.get(k)}) or app.get(k)
                 for k in ('name', 'summary', 'license', 'webSite', 'authorName')}
+        meta['categories'] = app.get('categories') or []
         for field in ('icon', 'featureGraphic', 'phoneScreenshots', 'sevenInchScreenshots'):
             images = {}
             for locale, fields in localized.items():
@@ -530,7 +533,7 @@ def _load(source, force=False):
             return found[:2]
         cache.parent.mkdir(parents=True, exist_ok=True)
         try:
-            with tempfile.TemporaryDirectory(dir=str(cache.parent)) as tmp:
+            with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-', dir=str(cache.parent)) as tmp:
                 jar, raw = Path(tmp) / 'index.jar', Path(tmp) / 'index.json'
                 v2 = True
                 try:
@@ -624,16 +627,39 @@ def set_enabled(source_id, enabled):
         _write(_storage(), settings)
 
 
-def search(source, query, limit=50):
+def _showcase(a):
+    """Browse order without a query: apps with real artwork first, then the most recently updated."""
+    images = a.get('images') or {}
+    return (not images.get('banner'), not images.get('screenshots'), not images.get('icon'),
+            ''.join(chr(0x10ffff - ord(c)) for c in str(a.get('updated') or '')))
+
+
+def search(source, query, limit=50, keep=None):
+    """keep: optional filter applied before the limit (the store's category browse)."""
     if not source.get('enabled', True):
         return []
     apps, _ = _load(source)
     words = query.casefold().split()
-    found = [a for a in apps.values() if all(w in (a['id'] + ' ' + a['name'] + ' ' + a['summary']).casefold() for w in words)]
-    found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
+    found = [a for a in apps.values() if all(w in (a['id'] + ' ' + a['name'] + ' ' + a['summary']).casefold() for w in words)
+             and (keep is None or keep(a))]
+    if words:
+        found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
+    else:
+        found.sort(key=_showcase)
     return [{k: v for k, v in a.items() if k != 'versions'} for a in found[:max(0, limit)]]
 
 
+def lookup(source, packages):
+    """Entries for these packages from the saved index only (never downloads); missing ones are left out."""
+    if not source.get('enabled', True):
+        return {}
+    found = _cached(source, frame_host.cache_dir('apk-sources', source['id'] + '.json'))
+    if not found:
+        return {}
+    apps = found[0]
+    return {p: {k: v for k, v in apps[p].items() if k != 'versions'} for p in packages if p in apps}
+
+
 def details(source, entry_id):
     if not source.get('enabled', True):
         raise SourceError('repository is disabled')

ui/apk_sources/search.py

@@ -15,7 +15,7 @@ import time
 import unicodedata
 
 import frame_host
-from apk_sources import SourceError, SourceLimited
+from apk_sources import SourceError, SourceLimited, _categories as categories
 
 _lock = threading.RLock()
 _running = {}
@@ -23,6 +23,7 @@ _pending = {}  # source id -> newest query waiting for the running one
 _game_data = {}  # package -> downloaded OBB paths waiting for "Add game data"
 _status = {}
 TIMEOUT = 12
+BROWSE_LIMIT = 300  # apps per source when browsing without a query, before grouping
 
 
 def modules():
@@ -158,9 +159,11 @@ def verdict(entry):
     return {'label': 'Not yet checked on the Frame', 'tone': 'unknown'}
 
 
-def decorate(entry):
+def decorate(entry, shots=12):
+    """shots: screenshots to offer; a listing card shows three, the detail page all of them."""
     from apk_sources import _images
-    return dict(entry, fit=fit(entry), verdict=verdict(entry), artwork=_images.artwork(entry))
+    return dict(entry, fit=fit(entry), verdict=verdict(entry), artwork=_images.artwork(entry, shots),
+                **categories.classify(entry))
 
 
 def details(source_id, entry_id):
@@ -178,10 +181,12 @@ def offer_rank(entry):
             entry.get('trust') == 'official')
 
 
-def group(entries, query='', vr=None, installable=False):
+def group(entries, query='', vr=None, installable=False, category=None, phone=False):
     groups = {}
     for entry in entries:
-        entry = decorate(entry)
+        entry = decorate(entry, shots=3)
+        if not categories.matches(entry, category, phone):
+            continue
         if vr is not None and (entry.get('vr') is True) != vr:  # unknown counts as flat
             continue
         if installable and entry['fit']['installable'] is not True:
@@ -195,7 +200,7 @@ def group(entries, query='', vr=None, installable=False):
         offers.sort(key=offer_rank, reverse=True)
         best = offers[0]
         result.append({'name': best.get('name'), 'package': best.get('package'),
-                       'summary': best.get('summary'), 'offers': offers})
+                       'summary': best.get('summary'), 'category': best.get('category'), 'offers': offers})
     q = normalise(query)
 
     def browse(a):  # a headset store: VR first, then apps with artwork, newest first
@@ -215,10 +220,10 @@ def group(entries, query='', vr=None, installable=False):
     return result
 
 
-def _launch(module, source, query, limit):
+def _launch(module, source, query, limit, category=None, phone=False):
     """One search per source at a time; the newest different query runs next."""
     key = source['id']
-    task = {'event': threading.Event(), 'query': (query, limit), 'started': time.monotonic(),
+    task = {'event': threading.Event(), 'query': (query, limit, category or None, bool(phone)), 'started': time.monotonic(),
             'job': (module, source)}
     with _lock:
         old = _running.get(key)
@@ -237,13 +242,17 @@ def _launch(module, source, query, limit):
 
 def _start(key, task):
     module, source = task['job']
-    query, limit = task['query']
+    query, limit, category, phone = task['query']
+    kwargs = {}
+    if (category or not phone) and 'keep' in inspect.signature(module.search).parameters:
+        # Large sources filter before their limit, so a category browse isn't cut to the first few hundred.
+        kwargs['keep'] = lambda e: categories.matches(dict(e, **categories.classify(e)), category, phone)
 
     def run():
         queued = None
         try:
             task['entries'] = [dict(e, source=key, source_name=source['name'], trust=source.get('trust'))
-                               for e in module.search(source, query, limit=limit) if e.get('free') is True]
+                               for e in module.search(source, query, limit=limit, **kwargs) if e.get('free') is True]
             task['stale'] = bool(getattr(module, 'stale', lambda s: False)(source))
         except Exception as e:
             task['error'] = str(e)
@@ -259,14 +268,20 @@ def _start(key, task):
     threading.Thread(target=run, daemon=True).start()
 
 
-def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, limit=50):
+def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, limit=50, category=None, phone=False):
     items, errors = registry()
     if source and source not in [s['id'] for _, s in items]:
         raise SourceError('Unknown source')
+    if category and category not in categories.IDS:
+        raise SourceError('Unknown category')
+    if not query.strip():
+        limit = max(limit, BROWSE_LIMIT)
+    else:
+        phone = True  # the phone-only guess hides apps from browsing, never from a search for them
     chosen = [(m, s) for m, s in items if s['enabled'] and (not source or s['id'] == source)]
     # Page-only sources (SideQuest) can't be searched; offer a link to browse them instead.
     elsewhere = [{'name': s['name'], 'url': s['url']} for m, s in chosen if s.get('page_only')]
-    tasks = [(s, _launch(m, s, query, limit)) for m, s in chosen if not s.get('page_only')]
+    tasks = [(s, _launch(m, s, query, limit, category, phone)) for m, s in chosen if not s.get('page_only')]
     entries, statuses = [], list(errors)
     for s, task in tasks:
         status = {'id': s['id'], 'name': s['name']}
@@ -281,7 +296,8 @@ def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, l
         statuses.append(status)
         with _lock:
             _status[s['id']] = {k: v for k, v in status.items() if k not in ('id', 'name')}
-    return {'apps': group(entries, query, vr, installable), 'sources': statuses, 'elsewhere': elsewhere}
+    return {'apps': group(entries, query, vr, installable, category, phone), 'sources': statuses, 'elsewhere': elsewhere,
+            'categories': [{'id': c, 'label': label} for c, label in categories.CATEGORIES]}
 
 
 def warm():
@@ -291,7 +307,35 @@ def warm():
     items, _ = registry()
     for m, s in items:
         if s['enabled'] and not s.get('page_only'):
-            _launch(m, s, '', 50)  # same as the first browse, so that search reuses it
+            _launch(m, s, '', BROWSE_LIMIT)  # same as the first browse, so that search reuses it
+
+
+def artwork_for(apps):
+    """Store artwork for installed apps ({'package', 'label'} each), from saved indexes only:
+    by package where a source has one, else by name (curated GitHub apps). {package: artwork}."""
+    from apk_sources import _images
+    items, _ = registry()
+    wanted = {a['package']: normalise(a.get('label')) for a in apps if a.get('package')}
+    found = {}
+    for module, source in items:
+        if not source['enabled'] or source.get('page_only'):
+            continue
+        try:
+            if hasattr(module, 'lookup'):
+                hits = module.lookup(source, [p for p in wanted if p not in found])
+            elif module.KIND == 'github':  # a small local list; its entries have names, not packages
+                names = {n: p for p, n in wanted.items() if n and p not in found}
+                hits = {names[normalise(e['name'])]: e for e in module.search(source, '', limit=100)
+                        if normalise(e.get('name')) in names}
+            else:
+                continue
+        except (SourceError, OSError, ValueError, KeyError, TypeError):
+            continue
+        for package, entry in hits.items():
+            art = _images.artwork(entry)
+            if art['icon'] or art['banner'] or art['screenshots']:
+                found.setdefault(package, art)
+    return found
 
 
 def install(source_id, entry_id, version_code=None, progress=None):

ui/control-center.css

@@ -0,0 +1,49 @@
+/* Local to the sixth tab: the existing Home, Games, Android and Tools keep
+   their layouts. The same Steam palette gives the dashboard a quieter rhythm. */
+.cc { gap:24px; }
+.cc :focus-visible { outline:2px solid var(--link); outline-offset:4px; }
+.cc-hero { display:flex; justify-content:space-between; align-items:center; gap:24px; padding:28px 30px;
+  border:1px solid #66c0f421; border-radius:12px; background:radial-gradient(ellipse at 90% 0%,#1a9fff19,transparent 65%),linear-gradient(125deg,#21364a,#152230); }
+.cc-eyebrow { font-size:11px; font-weight:700; letter-spacing:2px; text-transform:uppercase; color:var(--link); margin-bottom:7px; }
+.cc-hero h1 { font-size:clamp(25px,3vw,36px); font-weight:500; letter-spacing:-.7px; margin:0 0 8px; color:white; }
+.cc-hero p { color:#adb9c5; margin:0; max-width:580px; }
+.cc-hero > div { min-width:0; }
+.cc-hero-mark { flex:none; width:114px; height:82px; color:var(--link); opacity:.85; }
+.cc-topline { display:flex; gap:14px; align-items:center; flex-wrap:wrap; margin-bottom:14px; }
+.cc-topline h2 { font-size:17px; font-weight:500; margin:0; color:var(--bright); min-width:0; max-width:100%; overflow-wrap:anywhere; }
+.cc-topline button { margin-left:auto; border-radius:6px; }
+.cc-sample { font-size:12px; color:var(--muted); }.cc-offline { color:#cfb787; }
+.cc-summary { display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:14px; }
+.cc-metric { border:1px solid #ffffff0c; border-radius:9px; padding:18px 20px; background:linear-gradient(145deg,#25374a80,#18232f); min-width:0; }
+.cc-metric > span { color:#a7b8c8; font-size:12px; }.cc-metric > strong { display:block; color:white; font-size:clamp(20px,2.2vw,30px); font-weight:500; margin:7px 0 3px; font-variant-numeric:tabular-nums; overflow-wrap:anywhere; }
+.cc-metric > small { color:var(--muted); display:block; font-size:11.5px; }
+.cc-device-facts { margin:14px 0 0; padding:16px 20px; border:1px solid #ffffff0a; border-radius:9px; background:#10192366; }
+.cc-device-facts summary { cursor:pointer; color:#b8cbd9; font-size:12px; }.cc-device-facts dl { margin:18px 0 0; }
+.cc-readings { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:12px 18px; padding:0; }
+.cc-readings div { min-width:0; }.cc-readings dt { color:var(--muted); font-size:11px; }.cc-readings dd { margin:3px 0 0; color:#d9e7f2; font-size:13px; font-variant-numeric:tabular-nums; overflow-wrap:anywhere; }
+.cc-device-facts .cc-readings { grid-template-columns:repeat(4,minmax(0,1fr)); }
+.cc-services { display:flex; flex-wrap:wrap; gap:12px 22px; border-top:1px solid #ffffff0b; margin-top:18px; padding-top:14px; }
+.cc-services > span { display:flex; gap:7px; align-items:center; font-size:11px; color:#b3c5d4; }.cc-services b { color:var(--muted); font-weight:400; }
+.cc-workspace { display:grid; grid-template-columns:220px minmax(0,1fr); gap:26px; align-items:start; }
+.cc-workspace > * { min-width:0; width:100%; max-width:100%; }
+.cc-sidebar { position:sticky; top:90px; }.cc-sidebar > p { margin:0 0 12px 12px; color:var(--muted); font-size:10px; text-transform:uppercase; letter-spacing:1.5px; }
+.cc-categories { display:flex; flex-direction:column; gap:5px; min-width:0; max-width:100%; }.cc-categories button { display:flex; align-items:center; text-align:left; gap:10px; border-radius:7px; background:transparent; min-height:43px; padding:10px 12px; color:#a8b8c8; font-size:12px; }
+.cc-categories svg { width:17px; height:17px; flex:none; }.cc-category-count { margin-left:auto; font-size:11px; opacity:.65; }
+.cc-categories button:hover { background:#66c0f40a; color:white; }.cc-categories button[aria-pressed=true] { background:#1a9fff1a; color:var(--link); box-shadow:inset 2px 0 var(--blue); }
+.cc-status { margin-top:24px; padding:18px 14px; border-top:1px solid #ffffff10; }.cc-status > div { display:flex; align-items:center; gap:8px; font-size:12px; color:#c4d2dc; }.cc-status p { margin:10px 0 0; color:var(--muted); font-size:11.5px; line-height:1.6; }
+.cc-search-row { display:flex; align-items:center; gap:14px; margin-bottom:18px; }.cc-search { display:flex; align-items:center; gap:10px; border:1px solid #66c0f426; border-radius:8px; padding:0 12px; background:#0e1824; flex:1; min-width:0; }
+.cc-search:focus-within { border-color:var(--blue); }.cc-search svg { width:18px; color:var(--muted); flex:none; }.cc-search input { width:100%; min-width:0; padding:13px 0; border:0; background:transparent; font-size:13px; }.cc-search input:focus { outline:none; }.cc-search button { padding:3px 7px; background:transparent; color:var(--muted); font-size:18px; }.cc-results { color:var(--muted); font-size:11px; white-space:nowrap; }
+.cc-cards { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:16px; }.cc-card { display:flex; flex-direction:column; min-width:0; padding:22px; background:linear-gradient(150deg,#202e3d,#17212c); border:1px solid #ffffff0e; border-radius:10px; }
+.cc-card-head { display:flex; gap:10px; align-items:center; justify-content:space-between; margin-bottom:16px; }.cc-icon { width:34px; height:34px; display:grid; place-items:center; background:#66c0f40c; border-radius:8px; color:#85bfe2; }.cc-icon svg { width:20px; height:20px; }
+.cc-kind { font-size:10px; padding:3px 7px; border-radius:4px; color:#a2b3c2; background:#ffffff06; letter-spacing:.2px; }.cc-kind-control { color:#92cdeb; background:#1a9fff12; }.cc-kind-headset { color:#d3c095; background:#d9a23a0b; }.cc-kind-read { color:#9fceb9; background:#59bf4009; }
+.cc-card h2 { font-size:17px; font-weight:500; color:white; margin:0 0 8px; }.cc-card > p { font-size:12.5px; color:#a4b4c3; line-height:1.65; margin:0 0 14px; }
+.cc-guidance { padding:11px 12px; border-left:2px solid #9e876544; border-radius:0 4px 4px 0; background:#ffffff03; color:#bcb7aa; font-size:11.5px; line-height:1.6; margin-bottom:14px; }
+.cc-links { display:flex; flex-wrap:wrap; gap:10px 18px; margin-top:auto; padding-top:8px; }.cc-links a { display:inline-flex; gap:8px; align-items:center; color:var(--link); font-size:12px; text-decoration:none; }.cc-links a:hover { color:white; text-decoration:underline; }.cc-links a span { font-size:14px; opacity:.65; }
+.cc-note { font-size:11px; line-height:1.6; color:var(--muted); }.cc-card p.cc-note { margin:10px 0 0; }.cc-audio label { display:flex; justify-content:space-between; font-size:12px; color:#b7c8d6; }.cc-audio output { color:var(--link); font-variant-numeric:tabular-nums; }.cc-audio input { width:100%; margin:15px 0; }.cc-audio-actions { display:flex; gap:8px; flex-wrap:wrap; align-items:center; }.cc-audio-actions button { border-radius:5px; }.cc-audio-actions span { flex-basis:100%; margin-top:4px; }.cc-audio input:disabled { opacity:.35; }
+.cc-empty { padding:40px 24px; border:1px dashed #66c0f433; border-radius:10px; text-align:center; color:var(--muted); }.cc-empty h2 { color:white; font-size:18px; font-weight:500; }.cc-empty button { margin-top:12px; border-radius:5px; }
+@media (min-width:641px) and (max-width:1250px) { .brand b { display:none; } header { gap:14px; } nav a { padding:0 9px; font-size:13px; } .pill { min-width:120px; } }
+@media (min-width:641px) and (max-width:900px) { html { scroll-padding-top:116px; } header { flex-wrap:wrap; height:auto; min-height:64px; padding-top:8px; padding-bottom:8px; gap:6px 12px; } nav { order:3; width:100%; height:36px; } nav a { flex:1; justify-content:center; padding:0 6px; } .hdr-end { flex:1; justify-content:flex-end; } .cc-sidebar { top:115px; } }
+@media (max-width:1100px) { .cc-workspace { grid-template-columns:185px minmax(0,1fr); gap:18px; }.cc-card { padding:18px; }.cc-device-facts .cc-readings { grid-template-columns:repeat(3,minmax(0,1fr)); } }
+@media (max-width:900px) { .cc-workspace { grid-template-columns:minmax(0,1fr); }.cc-sidebar { position:static; }.cc-sidebar > p,.cc-status { display:none; }.cc-categories { flex-direction:row; overflow-x:auto; padding-bottom:6px; }.cc-categories button { flex:none; white-space:nowrap; }.cc-category-count { margin-left:2px; }.cc-categories button[aria-pressed=true] { box-shadow:inset 0 -2px var(--blue); }.cc-summary { gap:10px; }.cc-metric { padding:15px; } }
+@media (max-width:640px) { .cc { gap:20px; }.cc-hero { padding:22px 20px; }.cc-hero p { font-size:12px; }.cc-hero-mark { width:72px; height:55px; }.cc-summary { grid-template-columns:repeat(2,minmax(0,1fr)); }.cc-metric > strong { font-size:24px; }.cc-topline { gap:8px; }.cc-sample { order:3; width:100%; }.cc-device-facts { padding:14px; }.cc-device-facts .cc-readings { grid-template-columns:repeat(2,minmax(0,1fr)); }.cc-cards { grid-template-columns:minmax(0,1fr); gap:12px; }.cc-search-row { gap:8px; }.cc-results { font-size:10px; }.cc-card { padding:20px; }.cc-card h2 { font-size:18px; } }
+@media (max-width:640px), (max-height:500px) and (hover:none) { .cc-links a { min-height:44px; }.cc-audio-actions button,.cc-topline button { min-height:44px; }.cc-search button { min-width:36px; min-height:44px; } }

ui/control-center.js

@@ -0,0 +1,318 @@
+/* The Control Center uses the shared page's guarded api() and status poll.
+ * Browsing never starts a stream, installs a helper or changes the headset. */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.FrameControlCenter = factory();
+})(typeof window === 'object' ? window : globalThis, function () {
+  'use strict';
+  const categories = [
+    ['all', 'Everything', 'grid'], ['device', 'Device & audio', 'device'],
+    ['vr', 'VR & comfort', 'eye'], ['apps', 'Apps & files', 'apps'],
+    ['network', 'Connection & remote', 'network'], ['companion', 'Frame Control', 'settings'],
+  ];
+  // Each destination is an existing workflow, with its own guards and confirmations.
+  const catalog = [
+    {id:'audio', category:'device', icon:'audio', title:'Audio', kind:'control', label:'Available here',
+      description:'Set the default headset output volume or mute it. Changes apply only when you choose Apply or Mute.',
+      keywords:'sound speakers headphones loud quiet', special:'audio'},
+    {id:'health', category:'device', icon:'pulse', title:'Battery & thermal health', kind:'read', label:'Read-only metrics',
+      description:'Inspect charge, signed battery power, charger capability, battery temperature and health. Heat warnings use the kernel’s own hot and critical trip points.',
+      keywords:'battery charging charger charge time estimate remaining power watts usb health heat temperature thermal sensor', special:'health', links:[['#comfort','Configure battery & heat alerts']]},
+    {id:'storage', category:'device', icon:'files', title:'Storage & memory', kind:'read', label:'Read-only metrics',
+      description:'Check free user and system storage plus available RAM. Manage installed apps in their existing libraries, or use SFTP for files.',
+      keywords:'disk space root home free total ram memory capacity cleanup usage storage', special:'storage', links:[['#library','Installed games'],['#apps','Linux apps'],['#power','SFTP & remote tools']]},
+    {id:'microphone', category:'device', icon:'audio', title:'Microphone & audio routing', kind:'headset', label:'In the headset',
+      description:'Frame Control controls the default output volume only. Microphone mute, input gain, output selection, balance and per-app mixers have no verified API here.',
+      keywords:'mic input microphone audio sink output device gain mute eq equalizer spatial audio balance headphones',
+      guidance:'Check the headset’s audio controls or the app’s own audio settings for these adjustments.'},
+    {id:'power', category:'device', icon:'power', title:'Power & sleep', kind:'flow', label:'Existing controls',
+      description:'Sleep, restart or shut down with confirmation and your Developer Mode password. A sleeping Frame must be woken on the device.',
+      keywords:'battery suspend reboot off awake idle timeout keep awake inhibitor', links:[['#power','Power controls']],
+      guidance:'Set automatic sleep in the headset: Steam Settings → Power → Sleep after inactivity. Keep-awake is available through the existing script/MCP tools; there is no switch here.'},
+    {id:'system', category:'device', icon:'device', title:'SteamOS & hardware', kind:'headset', label:'In the headset',
+      description:'Check your current OS build above. Manage system updates, Developer Mode and hardware settings in Steam Settings on the Frame.',
+      keywords:'firmware update beta stable channel developer password bluetooth controller battery pairing calibration brightness refresh rate display IPD lenses passthrough camera eye hand tracking foveation recovery factory reset',
+      guidance:'Brightness, refresh rate, optics, controllers, Bluetooth and passthrough have no verified remote controls here. Check the headset’s own controls. Recovery and factory reset are manual procedures.'},
+    {id:'performance', category:'vr', icon:'pulse', title:'Performance monitor', kind:'read', label:'Read-only metrics',
+      description:'CPU, GPU clock, app and compositor timings come from the Frame. Unavailable timings stay empty, including when SteamVR is in standby.',
+      keywords:'fps frame rate gpu cpu heat temperature thermal sensor render memory', special:'performance', links:[['#vrTools','HUD & performance tools']]},
+    {id:'view', category:'vr', icon:'eye', title:'Headset view & casting', kind:'flow', label:'Existing controls',
+      description:'Capture the lenses or desktop, stream live video, and control a focused panel. Casting can reveal private content.',
+      keywords:'screenshot camera video capture live stream desktop mirror control eye', links:[['#view','Open headset view'],['#shots','Screenshots']]},
+    {id:'comfort', category:'vr', icon:'clock', title:'Family & comfort', kind:'flow', label:'Existing controls',
+      description:'Set a session limit, breaks and check-ins, with battery and heat alerts. Headset reminders continue if your companion disconnects.',
+      keywords:'parent child timer minutes notifications health break low battery', links:[['#comfort','Configure a session']],
+      guidance:'A reminder, not a parental lock. Save and pause before the session returns to Steam Home.'},
+    {id:'playspace', category:'vr', icon:'space', title:'Playspace & movement', kind:'headset', label:'In the headset',
+      description:'Use SteamVR’s recenter and room setup. Choose seated play, snap-turn, teleport and vignettes in each game’s own settings.',
+      keywords:'boundary guardian tracking origin floor standing seated motion sickness locomotion turn recenter room',
+      guidance:'No verified universal locomotion switch or remote tracking-origin control is available.'},
+    {id:'panels', category:'vr', icon:'grid', title:'Panels & workspace', kind:'flow', label:'Existing controls',
+      description:'Find an open panel and bring it forward, or open the panel switcher in the headset. Move, size and dock panels with SteamVR’s dashboard.',
+      keywords:'overlay window layout float world curvature docking theatre multitasking', links:[['#panels','Open panel switcher']],
+      guidance:'Saved spatial layouts are not available. Panel placement stays in SteamVR.'},
+    {id:'steam', category:'apps', icon:'game', title:'Steam library', kind:'flow', label:'Existing controls',
+      description:'Browse owned games and Frame ratings, install with progress, or launch an installed game. Purchases and license prompts use Steam.',
+      keywords:'games download install store owned compatibility rating verified proton', links:[['#library','Installed games'],['#getgames','Library & store']]},
+    {id:'android', category:'apps', icon:'apps', title:'Android apps', kind:'flow', label:'Existing controls',
+      description:'Discover apps, manage Lepton instances, and launch, stop, test or remove installed apps. View compatibility reports before installing.',
+      keywords:'apk fdroid lepton application sideload sources repository reports', links:[['#appStore','Discover apps'],['#androidLibrary','Manage installed apps']]},
+    {id:'sources', category:'apps', icon:'shield', title:'App sources & compatibility', kind:'flow', label:'Existing controls',
+      description:'Choose catalogue sources or add a signed F-Droid repository from Sources. Review install availability and compatibility reports for the exact app.',
+      keywords:'fdroid f-droid repository source fingerprint trust signature compatibility report apk sidequest data backup restore', links:[['#appStore','Catalogue & sources'],['#androidLibrary','Apps & reports']],
+      guidance:'Android data backup and restore are script-only. This interface does not provide an app-data recovery workflow.'},
+    {id:'display', category:'apps', icon:'display', title:'Android display & text', kind:'flow', label:'Existing controls',
+      description:'Choose a running Android instance, then set resolution, UI density and text size, or reset to its defaults.',
+      keywords:'dpi scaling font scale sharp native 1920 1080 2560 1440 resolution screen text accessibility', links:[['#display','Configure app display']],
+      guidance:'Applies to that Lepton instance, not the headset’s lenses. Persistence after relaunch is unverified.'},
+    {id:'sideload', category:'apps', icon:'game', title:'Sideloaded games', kind:'flow', label:'Existing controls',
+      description:'Send a game folder, ZIP or executable. Frame Control selects Proton or the Linux runtime and adds a Steam library entry.',
+      keywords:'windows exe zip linux devkit runtime shortcuts launch remove', links:[['#sideloaded','Manage titles'],['#transfer','Send a game']]},
+    {id:'files', category:'apps', icon:'files', title:'Files & clipboard', kind:'flow', label:'Existing controls',
+      description:'Send files to ~/Downloads, or send text to the Frame’s clipboard. Clipboard transfer needs the desktop panel open.',
+      keywords:'upload transfer downloads paste copy text sftp storage', links:[['#transfer','Send files & text']]},
+    {id:'media', category:'apps', icon:'play', title:'Video & stereo photos', kind:'flow', label:'Preview feature',
+      description:'Send and play H.264/H.265 video, SBS/OU photos or small splats with the built-in player. Choose a layout and theatre surround.',
+      keywords:'movie photo sbs ou 3d splat gaussian theatre media player', links:[['#media','Open media player']],
+      guidance:'Seeking, subtitles, native HEIC/MPO and large splat scenes are not supported yet.'},
+    {id:'flatpak', category:'apps', icon:'apps', title:'Linux desktop apps', kind:'flow', label:'Existing controls',
+      description:'Install user Flatpaks by Flathub ID, choose quick picks like VLC and Moonlight, and manage installed apps.',
+      keywords:'flatpak firefox vlc remmina moonlight flathub install remove', links:[['#apps','Manage Linux apps']]},
+    {id:'connection', category:'network', icon:'network', title:'Headsets & addresses', kind:'flow', label:'Existing controls',
+      description:'Manage headsets, LAN, USB-C, mDNS and Tailscale addresses. Inspect connection attempts and choose the device you want to control.',
+      keywords:'wifi wi-fi network ip ssh pairing keys discovery alias tailscale usb offline reconnect', links:[['#devices','Manage headsets','desktop'],['#connection','Connection details']],
+      guidance:'Join Wi-Fi networks on the headset. Frame Control manages connection addresses; it does not change Wi-Fi credentials.'},
+    {id:'remote', category:'network', icon:'display', title:'Remote access', kind:'flow', label:'Existing controls',
+      description:'Open SSH, SFTP, Steam Link or remote desktop using the host’s existing tools. Developer Mode enables headset SSH and xrdp.',
+      keywords:'terminal shell remote desktop rdp xrdp streaming steam link sftp', links:[['#power','Open remote tools']]},
+    {id:'input', category:'network', icon:'keyboard', title:'Keyboard & trackpad', kind:'flow', label:'Existing controls',
+      description:'Type and point in the Frame’s apps with KDE Connect, or use Control on the live panel view. First use sets up the input helper.',
+      keywords:'mouse pointer keyboard trackpad touch click kde input', links:[['#pad','Open keyboard & trackpad'],['#view','Panel control']]},
+    {id:'mac', category:'network', icon:'display', title:'Mac in the headset', kind:'flow', label:'macOS only', platform:'mac',
+      description:'Stream Mac screens or individual windows into headset panels. Choose quality and give each window its own display.',
+      keywords:'macos mac window screen sharing stream quality sharp balanced light permissions', links:[['#macview','Configure Mac streaming']],
+      guidance:'Requires Frame Control running on a Mac. It is unavailable when the server runs on Windows, Linux or the headset.'},
+    {id:'privacy', category:'companion', icon:'shield', title:'Privacy & sharing', kind:'flow', label:'Companion settings',
+      description:'Choose anonymous usage statistics, compatibility sharing and error details separately. Inspect what was sent and manage your optional contact email.',
+      keywords:'telemetry analytics diagnostics consent data tracking email contact opt out', links:[['#privacy','Privacy settings']]},
+    {id:'artwork', category:'companion', icon:'image', title:'Library artwork', kind:'flow', label:'Companion settings',
+      description:'Configure an optional SteamGridDB key or refresh artwork. Without a key, source images and generated art remain available.',
+      keywords:'cover image steamgriddb api key library art refresh', links:[['#artworkSettings','Artwork settings']]},
+    {id:'assistant', category:'companion', icon:'spark', title:'Assistant & agents', kind:'flow', label:'Opt-in tools',
+      description:'Use your own model endpoint and review proposed actions. Nothing goes to a model until you opt in; protected actions need approval.',
+      keywords:'ai mcp model endpoint agent approvals chat assistant', links:[['/assistant','Open assistant']]},
+    {id:'support', category:'companion', icon:'help', title:'Updates & diagnostics', kind:'flow', label:'Companion settings',
+      description:'Check Frame Control updates in the desktop app or prepare a private problem report. Review the diagnostic preview before sending.',
+      keywords:'app version bug feedback support update log error report licenses', links:[['#privacy','Updates & problem reports']]},
+  ];
+  const paths = {
+    grid:'M3 3h7v7H3z M14 3h7v7h-7z M3 14h7v7H3z M14 14h7v7h-7z',
+    device:'M3 7h18v10H3z M8 11v2 M16 11v2', eye:'M2 12s4-7 10-7 10 7 10 7-4 7-10 7S2 12 2 12z M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0',
+    apps:'M4 4h6v6H4z M14 4h6v6h-6z M4 14h6v6H4z M17 14v6 M14 17h6',
+    network:'M2 8a16 16 0 0 1 20 0 M5 12a11 11 0 0 1 14 0 M8 16a6 6 0 0 1 8 0 M12 20h.01',
+    settings:'M4 6h16 M4 12h16 M4 18h16 M8 3v6 M16 9v6 M10 15v6',
+    audio:'M3 9h4l5-4v14l-5-4H3z M16 8a6 6 0 0 1 0 8 M19 5a10 10 0 0 1 0 14',
+    power:'M12 2v10 M6 5a9 9 0 1 0 12 0', pulse:'M2 12h5l3-8 4 16 3-8h5',
+    clock:'M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0 M12 7v5l3 2',
+    space:'M3 8l9-5 9 5v8l-9 5-9-5z M3 8l9 5 9-5 M12 13v8',
+    game:'M6 8h12l3 9-3 2-4-4h-4l-4 4-3-2z M7 10v4 M5 12h4 M16 11h.01 M18 13h.01',
+    display:'M3 4h18v13H3z M8 21h8 M12 17v4', files:'M3 5h7l2 3h9v12H3z',
+    play:'M8 4l12 8-12 8z', keyboard:'M2 6h20v12H2z M6 10h.01 M10 10h.01 M14 10h.01 M18 10h.01 M6 14h12',
+    shield:'M12 2l8 4v6c0 5-8 10-8 10S4 17 4 12V6z M8 12l3 3 5-6',
+    image:'M3 3h18v18H3z M3 17l6-6 5 5 3-3 4 4 M16 7h.01',
+    spark:'M12 2l3 7 7 3-7 3-3 7-3-7-7-3 7-3z',
+    help:'M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0 M9 8a3 3 0 0 1 6 1c0 2-3 2-3 5 M12 17h.01',
+  };
+  const icon = name => `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="${paths[name] || paths.settings}"/></svg>`;
+  function matches(item, query, category) {
+    const text = [item.title, item.description, item.keywords, item.guidance, item.label,
+      categories.find(([id])=>id === item.category)?.[1]].join(' ').toLowerCase();
+    return (category === 'all' || item.category === category) && query.toLowerCase().trim().split(/\s+/).every(word => text.includes(word));
+  }
+  const number = (value, suffix = '', digits = 0) => Number.isFinite(value) ? value.toLocaleString(undefined, {maximumFractionDigits:digits}) + suffix : 'Unavailable';
+  const gib = value => Number.isFinite(value) ? number(value / 1073741824, ' GiB', 1) : 'Unavailable';
+  const duration = seconds => Number.isFinite(seconds) && seconds >= 0 ? seconds < 3600 ? `${Math.floor(seconds / 60)} min` : `${Math.floor(seconds / 3600)} h ${Math.floor(seconds % 3600 / 60)} min` : 'Unavailable';
+  function metrics(sample) {
+    const s = sample || {}, b = s.battery || {}, p = s.performance || {}, h = s.disk?.home, m = s.memory;
+    const capacity = b.percent;
+    const idle = !!s.power && Number.isFinite(b.watts) && Math.abs(b.watts) < .5;
+    const charging = b.status === 'Charging';
+    const full = b.status === 'Full' || (!!s.power && capacity >= 100);
+    const batteryState = !sample ? 'Connect to read charge and power' : !s.battery ? 'Battery sensor unavailable' :
+      full ? 'Fully charged' : charging ? 'Charging' : idle ? 'Plugged in · not charging' : s.power ? 'Plugged in · on battery' : 'On battery';
+    return {
+      battery:number(capacity, '%'), batteryDetail:batteryState,
+      storage:h ? gib(h.free) : 'Unavailable', storageDetail:h ? `${gib(h.total)} total · user storage` : 'User storage unavailable',
+      memory:m && Number.isFinite(m.total) && Number.isFinite(m.available) ? gib(m.total - m.available) : 'Unavailable',
+      memoryDetail:m ? `${gib(m.total)} total · system memory used` : 'Memory sensor unavailable',
+      rootFree:gib(s.disk?.root?.free), rootTotal:gib(s.disk?.root?.total), memoryAvailable:gib(m?.available),
+      fps:number(p.compositorFps, '', 1), fpsDetail:'Compositor FPS · not game FPS',
+      power:number(b.watts, ' W', 1), charger:s.power ? `${s.power.type || 'Connected'} · ${number(s.power.watts, ' W', 1)}` : sample ? 'No charger reported' : 'Unavailable',
+      batteryTemp:number(b.tempC, ' °C', 1), batteryHealth:b.health || 'Unavailable',
+      estimate:charging ? (b.timeToFull > 0 ? `${duration(b.timeToFull)} to full` : 'Unavailable') : !full && !idle && b.timeToEmpty > 0 && b.timeToEmpty < 86400 ? `${duration(b.timeToEmpty)} remaining` : 'Unavailable',
+      wifi:s.wifi?.ssid || 'Unavailable', signal:number(s.wifi?.signal, '%'), ip:s.ip || 'Unavailable',
+      uptime:duration(s.uptime), os:s.os?.version || 'Unavailable', build:s.os?.build || 'Unavailable',
+      temperature:number(s.temp, ' °C', 1), cpu:number(p.cpuPercent, '%', 1), gpu:number(p.gpuMHz, ' MHz', 1),
+      appFps:number(p.appFps, '', 1), frame:number(p.frameMs, ' ms', 2), render:number(p.gpuMs, ' ms', 2), compositorCpu:number(p.compositorCpuMs, ' ms', 2),
+      thermal:!Array.isArray(s.thermalAlerts) ? 'Trip data unavailable' : s.thermalAlerts.length ? s.thermalAlerts.map(a => `${a.zone || 'Sensor'} ${number(a.tempC, ' °C')} ≥ ${number(a.limitC, ' °C')}`).join('; ') : 'No hot / critical trip reported',
+    };
+  }
+  // Strict validation and captured device identity apply even if a stale enabled
+  // button is clicked during a disconnect, headset switch, or pending request.
+  function createController({api, getContext}) {
+    let busy = false;
+    return {
+      get busy() { return busy; },
+      async audio(change) {
+        if (busy) throw new Error('An audio change is still in progress.');
+        const context = getContext();
+        if (context.online !== true || !context.fresh || !context.sample?.volume) throw new Error('Connect and refresh the Frame before changing audio.');
+        const keys = Object.keys(change);
+        if (!keys.length || keys.some(k => !['level','muted'].includes(k)) ||
+            ('level' in change && (typeof change.level !== 'number' || !Number.isFinite(change.level) || change.level < 0 || change.level > 1)) ||
+            ('muted' in change && typeof change.muted !== 'boolean')) throw new Error('Use a volume from 0 to 100% and a valid mute state.');
+        busy = true;
+        try {
+          const result = await api('/api/volume', change, context.device);
+          if (getContext().generation !== context.generation) return null;
+          return result;
+        } finally { busy = false; }
+      },
+    };
+  }
+  function mount({document, api, refresh, refreshAudio = refresh, getContext, openConnection, platform}) {
+    const get = id => document.getElementById(id), page = get('controlCenter');
+    let category = 'all', sample = null, receivedAt = null, available = false, error = '', dirty = false, sampleGeneration = null, audioPending = false;
+    const metric = (id, label) => `<div><dt>${label}</dt><dd data-cc-metric="${id}">Unavailable</dd></div>`;
+    const perf = `<dl class="cc-readings">${[['appFps','Application FPS'],['frame','Compositor period'],['render','Render GPU time'],['compositorCpu','Compositor CPU'],['cpu','System CPU'],['gpu','GPU clock'],['temperature','Hottest sensor']].map(([id,label])=>metric(id,label)).join('')}</dl><p class="cc-note">GPU time is render time, not utilisation. The hottest sensor is not necessarily CPU temperature.</p><p class="cc-note" data-cc-metric="thermal">Trip data unavailable</p>`;
+    const audio = `<div class="cc-audio"><label for="ccVolume">Output volume <output id="ccVolumeValue" for="ccVolume">—</output></label><input id="ccVolume" type="range" min="0" max="100" step="1" value="0" disabled><div class="cc-audio-actions"><button class="action small" id="ccApplyVolume" disabled>Apply volume</button><button class="small" id="ccMute" disabled>Mute</button><span id="ccAudioReadback" class="cc-note">Waiting for an audio reading</span></div><p class="cc-note" id="ccAudioResult" role="status"></p></div>`;
+    const health = `<dl class="cc-readings">${[['battery','Charge'],['power','Battery power · signed'],['charger','Charger'],['estimate','Battery estimate'],['batteryTemp','Battery temperature'],['batteryHealth','Battery health']].map(([id,label])=>metric(id,label)).join('')}</dl>`;
+    const storage = `<dl class="cc-readings">${[['storage','User storage free'],['rootFree','System storage free'],['rootTotal','System storage total'],['memoryAvailable','Memory available']].map(([id,label])=>metric(id,label)).join('')}</dl>`;
+    get('ccCategories').innerHTML = categories.map(([id,label,symbol])=>`<button type="button" data-cc-category="${id}" aria-pressed="${id === 'all'}">${icon(symbol)}<span>${label}</span><span class="cc-category-count"></span></button>`).join('');
+    const specials = {audio, performance:perf, health, storage};
+    get('ccCards').innerHTML = catalog.map(item=>`<section class="cc-card" data-cc-card="${item.id}"><div class="cc-card-head"><span class="cc-icon">${icon(item.icon)}</span><span class="cc-kind cc-kind-${item.kind}">${item.label}</span></div><h2>${item.title}</h2><p>${item.description}</p>${specials[item.special] || ''}${item.guidance ? `<div class="cc-guidance">${item.guidance}</div>` : ''}${item.links ? `<div class="cc-links">${item.links.map(([href,label,desktop])=>`<a href="${href}"${desktop ? ' class="desk-only"' : ''}${item.platform === 'mac' ? ' data-cc-mac-link' : ''}>${label}<span aria-hidden="true">↗</span></a>`).join('')}</div>` : ''}</section>`).join('');
+    // Host-only features stay searchable with a reason; only their unsupported
+    // action disappears. The host API, rather than viewport/UA, decides availability.
+    let macSupported = platform === 'darwin';
+    const visibleCatalog = catalog;
+    function filter() {
+      const query = get('ccSearch').value;
+      let count = 0;
+      catalog.forEach(item => {
+        const visible = visibleCatalog.includes(item) && matches(item, query, category);
+        page.querySelector(`[data-cc-card="${item.id}"]`).hidden = !visible;
+        if (visible) count++;
+      });
+      get('ccResultCount').textContent = `${count} ${count === 1 ? 'section' : 'sections'}`;
+      get('ccEmpty').hidden = count > 0;
+      get('ccClear').hidden = !query;
+      page.querySelectorAll('[data-cc-category]').forEach(button => {
+        button.setAttribute('aria-pressed', String(button.dataset.ccCategory === category));
+        button.querySelector('.cc-category-count').textContent = visibleCatalog.filter(item=>matches(item, query, button.dataset.ccCategory)).length;
+      });
+      page.querySelectorAll('[data-cc-mac-link]').forEach(link=>{link.hidden = !macSupported;});
+    }
+    get('ccSearch').addEventListener('input', filter);
+    function resetFilter() { get('ccSearch').value = ''; category = 'all'; filter(); get('ccSearch').focus(); }
+    get('ccClear').onclick = () => { get('ccSearch').value = ''; filter(); get('ccSearch').focus(); };
+    get('ccResetFilter').onclick = resetFilter;
+    get('ccCategories').onclick = event => {
+      const button = event.target.closest('[data-cc-category]');
+      if (!button) return;
+      category = button.dataset.ccCategory; filter();
+    };
+    page.querySelector('[href="#connection"]').onclick = event => { event.preventDefault(); openConnection(); };
+    // The headset clock can differ from this client's. Age uses the client
+    // receipt time, retained by the shared poll when it buffers an early sample.
+    const isFresh = () => available && Number.isFinite(receivedAt) && Date.now() >= receivedAt && Date.now() - receivedAt <= 90000;
+    const context = () => ({...getContext(), sample, fresh:isFresh() && sampleGeneration === getContext().generation});
+    const controller = createController({api, getContext:context});
+    function audioAvailability() {
+      const enabled = context().online === true && context().fresh && !!sample?.volume && !controller.busy && !audioPending;
+      ['ccVolume','ccApplyVolume','ccMute'].forEach(id=>{get(id).disabled = !enabled;});
+    }
+    function renderSample() {
+      const values = metrics(isFresh() ? sample : null);
+      page.querySelectorAll('[data-cc-metric]').forEach(el=>{el.textContent = values[el.dataset.ccMetric];});
+      get('ccDeviceName').textContent = isFresh() ? sample.hostname || 'Steam Frame' : 'Steam Frame';
+      const sampledAt = Number.isFinite(sample?.time) && sample.time > 0 && sample.time * 1000 <= 8640000000000000 ? new Date(sample.time * 1000) : null;
+      get('ccSampleState').textContent = isFresh() ? `${sampledAt ? 'Sampled ' + sampledAt.toLocaleTimeString() : 'Received ' + new Date(receivedAt).toLocaleTimeString()} · updates every 30 seconds` :
+        error || (receivedAt !== null ? 'Sample expired · refresh to read current metrics' : 'Connect your Frame to read live metrics');
+      get('ccSampleState').classList.toggle('cc-offline', !isFresh());
+      get('ccStatusLabel').textContent = isFresh() ? 'Connected' : 'No live sample';
+      get('ccStatusDot').classList.toggle('on', isFresh());
+      get('ccStatusNote').textContent = isFresh() ? 'Read-only status over SSH. Browse freely; controls run only when you use them.' :
+        'Settings guides and companion tools remain available. Wake the Frame on the device, then reconnect.';
+      get('ccBuild').textContent = isFresh() ? `SteamOS ${values.os} · build ${values.build}` : 'System information unavailable';
+      const services = isFresh() ? sample.services || {} : {};
+      get('ccServices').innerHTML = [['steamvr','SteamVR'],['desktop','Desktop'],['lepton','Lepton · port 5555'],['rdp','RDP process']].map(([key,label])=>`<span><i class="dot ${services[key] === true ? 'on' : ''}"></i>${label}<b>${typeof services[key] === 'boolean' ? services[key] ? 'Running' : 'Not detected' : 'Unavailable'}</b></span>`).join('');
+      if (sample?.volume && isFresh()) {
+        const pct = Math.round(sample.volume.level * 100);
+        if (!dirty && !controller.busy && !audioPending) get('ccVolume').value = Math.min(100,Math.max(0,pct));
+        get('ccVolumeValue').textContent = `${get('ccVolume').value}%`;
+        get('ccAudioReadback').textContent = `Reported ${pct}% · ${sample.volume.muted ? 'muted' : 'unmuted'}`;
+        get('ccMute').textContent = sample.volume.muted ? 'Unmute' : 'Mute';
+      } else {
+        get('ccAudioReadback').textContent = isFresh() ? 'Audio reading unavailable' : 'Waiting for an audio reading';
+        get('ccVolumeValue').textContent = '—';
+      }
+      audioAvailability();
+    }
+    async function changeAudio(change) {
+      if (audioPending) return;
+      const generation = getContext().generation;
+      audioPending = true;
+      get('ccAudioResult').textContent = 'Applying…';
+      try {
+        const pending = controller.audio(change);
+        audioAvailability();
+        const result = await pending;
+        if (!result || generation !== getContext().generation) return;
+        if ('level' in change) dirty = false;
+        get('ccAudioResult').textContent = `${result.message || 'Audio updated'}. Refreshing the reading…`;
+        await refreshAudio();
+        if (generation !== getContext().generation) return;
+        if (!isFresh() || !sample?.volume) {
+          get('ccAudioResult').textContent = 'Audio command sent; current output could not be confirmed. Reconnect and refresh.';
+        } else {
+          const reported = sample.volume;
+          const matched = (!('level' in change) || Math.round(reported.level * 100) === Math.round(change.level * 100)) &&
+            (!('muted' in change) || reported.muted === change.muted);
+          get('ccAudioResult').textContent = `${matched ? 'Confirmed' : 'Command sent · reported output differs'}: ${Math.round(reported.level * 100)}%, ${reported.muted ? 'muted' : 'unmuted'}.${matched ? '' : ' Refresh to check again.'}`;
+        }
+      } catch (e) {
+        if (generation !== getContext().generation) return;
+        get('ccAudioResult').textContent = `Couldn’t apply audio: ${e.message}`;
+      } finally { audioPending = false; renderSample(); }
+    }
+    get('ccVolume').oninput = () => { dirty = true; get('ccVolumeValue').textContent = `${get('ccVolume').value}%`; };
+    get('ccApplyVolume').onclick = () => changeAudio({level:Number(get('ccVolume').value) / 100});
+    get('ccMute').onclick = () => changeAudio({muted:!sample?.volume?.muted});
+    get('ccRefresh').onclick = async () => {
+      get('ccRefresh').disabled = true;
+      try { await refresh(); } finally { get('ccRefresh').disabled = false; }
+    };
+    filter(); renderSample();
+    // Expire UI readings even when the shared poll is paused in a hidden tab.
+    const timer = setInterval(()=>{if (receivedAt !== null && available && !isFresh()) { available = false; renderSample(); }}, 5000);
+    return {
+      host(value) { macSupported = !value.mobile && value.os === 'macOS'; filter(); },
+      status(value, receipt = Date.now(), read = {valid: true, error: null}) {
+        // A redraw is not a successful read: preserve receipt age and any local
+        // invalidation. Shared validity also carries failures across late mount.
+        const replay = sample === value;
+        receivedAt = replay ? (Number.isFinite(receivedAt) && Number.isFinite(receipt) ? Math.min(receivedAt, receipt) : receivedAt) : receipt;
+        sample = value;
+        if (!read.valid) {
+          available = false; error = `No live sample${read.error?.message ? ' · ' + read.error.message : ''}`;
+        } else if (!replay) { available = true; error = ''; }
+        sampleGeneration = getContext().generation; renderSample();
+      },
+      unavailable(reason) { if (reason?.stale) return; available = false; error = `No live sample${reason?.message ? ' · ' + reason.message : ''}`; renderSample(); },
+      connection(ok) { if (!ok) { available = false; renderSample(); } else audioAvailability(); },
+      reset() { sample = null; receivedAt = null; available = false; error = ''; dirty = false; get('ccVolume').value = 0; get('ccAudioResult').textContent = ''; renderSample(); },
+      destroy() { clearInterval(timer); },
+    };
+  }
+  return {catalog, categories, matches, metrics, createController, mount};
+});

ui/frame_agent.py

@@ -9,6 +9,8 @@ import subprocess
 import threading
 import time
 
+TMP_PREFIX = 'frame-agent-'  # then the server's PID, so server.sweep_tmp can clear a stopped run's
+
 
 class Approvals:
     def __init__(self):
@@ -109,7 +111,7 @@ def call(server, body):
     if name == 'send_file':
         # Stage the reviewed bytes before the existing transfer helper reads them.
         import tempfile
-        with tempfile.TemporaryDirectory(prefix='frame-agent-') as tmp:
+        with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-') as tmp:
             source = Path(action['arguments']['path'])
             with source.open('rb') as stream:
                 data = stream.read(16 * 1024**2 + 1)

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
@@ -23,6 +23,7 @@ from frame_apk_sign import repack
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 FRAME = os.environ.get('FRAME_ALIAS', 'frame')
+TMP_PREFIX = 'frame-vr-'  # then the server's PID, so server.sweep_tmp can clear a stopped run's patched APK
 APPS_DIR = 'Applications/Android'          # relative to the Frame's $HOME
 COMPAT = '.local/share/Steam/steamapps/compatdata'
 SHADERS = '.local/share/Steam/steamapps/shadercache'
@@ -33,7 +34,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,16 +45,37 @@ 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.
         feed = {'input': input} if input is not None else {'stdin': subprocess.DEVNULL}
-        p = subprocess.run(['ssh', *SSH_OPTS, FRAME, cmd], capture_output=True, **feed,
-                           timeout=timeout, text=isinstance(input, str) or input is None)
+        # The Frame writes UTF-8, whatever this computer's code page (Windows would decode it as
+        # cp1252). errors='replace': stray bytes (a file name) mustn't turn a failed command, or
+        # one that worked, into a UnicodeDecodeError.
+        text = ({'text': True, 'encoding': 'utf-8', 'errors': 'replace'}
+                if isinstance(input, str) or input is None else {})
+        p = frame_host.run_ssh(['ssh', *SSH_OPTS, FRAME, cmd], capture_output=True, **feed,
+                               timeout=timeout, **text)
     except subprocess.TimeoutExpired:
-        raise FrameError(f'timed out talking to {FRAME}')
+        raise frame_host.link_failure(FrameError(f'timed out talking to {FRAME}'))
     if p.returncode != 0:
-        raise FrameError((p.stderr or p.stdout or f'ssh exited {p.returncode}').strip()[-600:])
+        # Bytes input gives bytes output: decode it, so the message isn't "b'...'".
+        stderr, stdout = (v if isinstance(v, str) else (v or b'').decode(errors='replace')
+                          for v in (p.stderr, p.stdout))
+        error = FrameError((stderr or stdout or f'ssh exited {p.returncode}').strip()[-600:])
+        raise frame_host.link_failure(error) if frame_host.ssh_link_failed(p.returncode, stderr) else error
     return p.stdout
 
 
@@ -94,25 +117,45 @@ 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
+# The slowest transfer a copy is allowed before it times out, in bytes a second (about 4 Mbit/s,
+# a slow or busy Wi-Fi link). A fixed 10 minutes failed any APK over about 300 MB at that rate.
+COPY_MIN_RATE = 512 * 1024
 
 
 def _copy(src, dest, executable=False, timeout=600):
-    """Copy a local file to the Frame: rsync where installed (not on Windows), else scp."""
+    """Copy a local file to the Frame: rsync where installed (not on Windows), else scp.
+    timeout is the least time allowed; a large file gets longer (COPY_MIN_RATE)."""
     name = os.path.basename(src)
+    try:
+        timeout = max(timeout, os.path.getsize(src) / COPY_MIN_RATE)
+    except OSError:
+        pass  # rsync or scp says what's wrong with the file
     rsync = None if frame_host.WINDOWS else shutil.which('rsync')  # see server.push_file
     if rsync:
         cmd = ['rsync', '-a', *(['--chmod=u+x'] if executable else []),
@@ -120,7 +163,8 @@ def _copy(src, dest, executable=False, timeout=600):
     else:
         cmd = ['scp', *SSH_OPTS, src, f'{FRAME}:{dest}']
     try:
-        subprocess.run(cmd, check=True, capture_output=True, stdin=subprocess.DEVNULL, text=True, timeout=timeout)
+        frame_host.run_ssh(cmd, check=True, capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                           errors='replace', timeout=timeout)
     except subprocess.TimeoutExpired:
         raise FrameError(f'copying {name} to the Frame timed out')
     except subprocess.CalledProcessError as e:
@@ -159,18 +203,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:
+                with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-') 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)
@@ -238,6 +295,13 @@ def _install(apk_path, info, pkg, flatscreen, name, source, artwork=None):
                 ssh(f'rm -rf {d}', timeout=30)
             except FrameError:
                 pass
+        elif not ok:
+            # An update that failed: the app still works, but a partial copy of the new APK
+            # (scp leaves one; it can be gigabytes) mustn't stay beside it.
+            try:
+                ssh(f'rm -f {d}/app.apk.part', timeout=30)
+            except FrameError:
+                pass
 
 
 

ui/frame_android_data.py

@@ -11,16 +11,17 @@ import tempfile
 import uuid
 
 import frame_android as android
+import frame_host
 
 REMOTE = Path(android.ROOT) / 'frame/android/app-data.py'
 
 
 def _stream(command, src=None, dst=None):
     try:
-        result = subprocess.run(['ssh', *android.SSH_OPTS, android.FRAME, command],
-                                stdin=src if src else subprocess.DEVNULL,
-                                stdout=dst if dst else subprocess.PIPE,
-                                stderr=subprocess.PIPE, timeout=1800)
+        result = frame_host.run_ssh(['ssh', *android.SSH_OPTS, android.FRAME, command],
+                                    stdin=src if src else subprocess.DEVNULL,
+                                    stdout=dst if dst else subprocess.PIPE,
+                                    stderr=subprocess.PIPE, timeout=1800)
     except subprocess.TimeoutExpired:
         raise android.FrameError('app-data transfer timed out')
     except OSError as error:

ui/frame_apk.py

@@ -7,6 +7,7 @@ the resource table in resources.arsc.
 """
 import struct
 import zipfile
+import zlib
 
 # android: attribute resource ids; names can be stripped by shrinkers, ids can't.
 ATTR = {0x01010001: 'label', 0x01010002: 'icon', 0x01010003: 'name',
@@ -221,7 +222,9 @@ def apk_info(path):
             res = Resources(_read(z, 'resources.arsc', MAX_ARSC) if 'resources.arsc' in names else b'')
             from frame_apk_vr import detection
             vr_info = detection(manifest_data, names)
-        except (struct.error, IndexError, zipfile.BadZipFile) as e:
+        # A damaged download: corrupt deflate data (zlib.error), a member cut short (EOFError),
+        # undecodable text (UnicodeDecodeError) or an encrypted entry (RuntimeError).
+        except (struct.error, IndexError, zipfile.BadZipFile, zlib.error, EOFError, ValueError, RuntimeError) as e:
             raise ApkError(f'could not read the APK manifest: {e}')
         tags = {}
         for tag, attrs in elements:

ui/frame_connect.py

@@ -24,10 +24,15 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 
+# The app runs this with python -I, which leaves the script's folder off sys.path.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import frame_host  # noqa: E402
+
 FRAME_USER = os.environ.get("FRAME_USER", "steamos")
 USER_FROM_ENV = "FRAME_USER" in os.environ
 FRAME_ALIAS = os.environ.get("FRAME_ALIAS", "frame")
-SSH_DIR = Path.home() / ".ssh"
+# $FRAME_CONTROL_SSH_DIR in tests, as frame_devices.ssh_dir(), so they never touch the real one.
+SSH_DIR = Path(os.environ.get("FRAME_CONTROL_SSH_DIR") or Path.home() / ".ssh")
 KEY = SSH_DIR / "id_ed25519_frame"
 # The devkit service only accepts ssh-rsa keys (write_key in Valve's
 # steamos-devkit-service), so pairing uses a second key next to the ed25519 one.
@@ -330,8 +335,9 @@ def _write_config(host, port, user):
     block = config_block(host, port, user)
     tmp = CONFIG.with_name(f"config.frame-control.{os.getpid()}.tmp")
     tmp.write_text("\n".join(block + kept) + "\n", encoding="utf-8")
-    if os.name != "nt":
-        tmp.chmod(0o600)
+    if not frame_host.make_private(tmp):
+        say("    couldn't make ~/.ssh/config private; if ssh says \"Bad owner or permissions\", "
+            "Frame Control repairs it when it next connects")
     # On Windows a running ssh.exe (Frame Control's own, say) keeps the config open
     # and locked, so the swap can fail for a moment; keep trying for a while.
     for attempt in range(60):
@@ -349,9 +355,9 @@ def _write_config(host, port, user):
 
 def key_login_works():
     # accept-new: trust a first-seen host key (as the copy step does); a changed one still fails.
-    return subprocess.run(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
-                           "-o", "StrictHostKeyChecking=accept-new", FRAME_ALIAS, "true"],
-                          capture_output=True).returncode == 0
+    return frame_host.run_ssh(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
+                               "-o", "StrictHostKeyChecking=accept-new", FRAME_ALIAS, "true"],
+                              capture_output=True).returncode == 0
 
 
 def configured_user():

ui/frame_contact.py

@@ -71,6 +71,31 @@ def valid_email(email):
     return len(email) <= EMAIL_MAX and bool(EMAIL_RE.fullmatch(email))
 
 
+def flag(body, key):
+    """A consent choice: true only when it really is true (not "false" or 1), left out is no."""
+    v = body.get(key)
+    if v is not None and not isinstance(v, bool):
+        raise ValueError(f'{key} must be true or false')
+    return v is True
+
+
+def from_report(email):
+    """Follow-up questions agreed to with a problem report: the address becomes the contact
+    email with that choice ticked, so it shows in Settings and is removed the same way. Update
+    notices stay on only for the same address: a different one replaces the old address with
+    follow-up questions only (the report form says so before sending). Returns (contact id,
+    rev) for the report to carry, read together with the change itself: a later change from
+    this copy has a higher rev, and the newest such change decides whether the report's
+    follow-up permission still stands, whatever the clocks say."""
+    with _lock:
+        s = load()
+        same = s['email'].lower() == email.lower()
+        changed, cid, rev = _apply({'email': s['email'] if same else email,
+                                    'updates': s['updates'] and same, 'followup': True})
+    _deliver(changed)
+    return cid, rev
+
+
 def state():
     """What the page shows. showPrompt: the one-time prompt hasn't been shown or answered yet,
     and the Frame has connected at least once (setup worked), so it never greets a new install."""
@@ -155,8 +180,14 @@ def redact_removed(event, started):
 def save(body):
     """Set, change or remove the address and the two choices. An address needs at least one
     choice ticked; an empty address (or neither ticked) removes it and withdraws both."""
+    _deliver(_apply(body)[0])
+    return state()
+
+
+def _apply(body):
+    """save()'s change, kept here and waiting to send. Returns (changed, contact id, rev)."""
     email = str(body.get('email') or '').strip()
-    updates, followup = bool(body.get('updates')), bool(body.get('followup'))
+    updates, followup = flag(body, 'updates'), flag(body, 'followup')
     if email and not valid_email(email):
         raise ValueError("that doesn't look like an email address")
     if email and not (updates or followup):
@@ -181,9 +212,12 @@ def save(body):
                 _forget_locally(old)
             except OSError:
                 pass
+        return changed, s['id'], s['rev']
+
+
+def _deliver(changed):
     if changed and not _send_pending(block=False):
         _wake.set()  # offline, or a send under way that will take this change with it
-    return state()
 
 
 def prompt(body):

ui/frame_devices.py

@@ -28,8 +28,10 @@ remembered IP is caught.
 
 Python stdlib only.
 """
+import base64
 import contextlib
 import copy
+import hashlib
 import json
 import os
 import re
@@ -241,8 +243,7 @@ def _write_config(path, text, expected):
     try:
         with os.fdopen(fd_, "w", encoding="utf-8") as fh:
             fh.write(text)
-        if not frame_host.WINDOWS:
-            tmp.chmod(0o600)
+        frame_host.make_private(tmp)  # best effort: an edit still beats none (repair_permissions insists)
         for attempt in range(20):  # Windows: a running ssh.exe can hold the file for a moment
             if read_config(path) != expected:
                 return False
@@ -271,6 +272,37 @@ def _edit_config(path, change):
         raise OSError(f"{path} kept changing while Frame Control tried to update it")
 
 
+def repair_permissions(path=None):
+    """Give ~/.ssh/config make_private's ACL by swapping in a byte-for-byte copy: for a
+    file Windows' OpenSSH refuses ("Bad owner or permissions"). -> True only if the copy
+    got that ACL and replaced the file."""
+    path = Path(path or ssh_config())
+    with _config_lock, file_lock(path.with_name(LOCK_NAME)):
+        try:
+            data = path.read_bytes()
+        except OSError:
+            return False
+        fd_, tmp = tempfile.mkstemp(prefix="config.frame-control.", dir=str(path.parent))
+        tmp = Path(tmp)
+        try:
+            with os.fdopen(fd_, "wb") as fh:
+                fh.write(data)
+            if not frame_host.make_private(tmp):
+                return False
+            for attempt in range(20):  # a running ssh.exe can hold the file for a moment
+                if path.read_bytes() != data:
+                    return False
+                try:
+                    os.replace(tmp, path)
+                    return True
+                except PermissionError:
+                    time.sleep(0.25)
+            return False
+        finally:
+            if tmp.exists():
+                tmp.unlink()
+
+
 def rewrite_block(alias, path=None, hostname=None, user=None, port=None, expect=None):
     """Change HostName, User or Port inside ALIAS's managed block, leaving the rest of the
     file alone. -> True if the file changed. Does nothing if there's no such block, or
@@ -333,8 +365,8 @@ def remove_block(alias, path=None):
 def effective_port(alias, config):
     """The port ssh uses for ALIAS with this config file (`ssh -F FILE -G ALIAS`), else 22."""
     try:
-        out = subprocess.run(["ssh", "-F", str(config), "-G", alias], capture_output=True, text=True,
-                             stdin=subprocess.DEVNULL, timeout=10).stdout
+        out = frame_host.run_ssh(["ssh", "-F", str(config), "-G", alias], capture_output=True, text=True,
+                                 stdin=subprocess.DEVNULL, timeout=10).stdout
     except (OSError, subprocess.TimeoutExpired):
         return 22
     m = re.search(r"^port (\d+)$", out, re.M)
@@ -346,8 +378,8 @@ def effective_port(alias, config):
 
 def _keygen(*args):
     try:
-        return subprocess.run(["ssh-keygen", *args], capture_output=True, stdin=subprocess.DEVNULL, text=True,
-                              timeout=10)
+        return frame_host.run_ssh(["ssh-keygen", *args], capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                                  timeout=10)
     except (OSError, subprocess.TimeoutExpired):
         return None
 
@@ -388,19 +420,100 @@ def seed_pin(device_id, hosts, port=22, sources=None):
                 if len(f) >= 3 and not line.startswith("#") and not f[0].startswith("@"):
                     keys.append(f"{name} {f[1]} {f[2]}")
         if keys:
-            target = known_hosts(device_id)
-            target.parent.mkdir(**({} if frame_host.WINDOWS else {"mode": 0o700}), parents=True, exist_ok=True)
-            fd_, tmp = tempfile.mkstemp(prefix=".seed-", dir=str(target.parent))
-            with os.fdopen(fd_, "w", encoding="utf-8") as fh:
-                fh.write("\n".join(dict.fromkeys(keys)) + "\n")
-            os.replace(tmp, target)  # whole file at once: ssh never sees half of it
+            _write_pin(device_id, keys)
             return True
     return False
 
 
+def pin_dir():
+    """Where the per-headset files go, created private: ssh won't create it itself."""
+    d = ssh_dir() / PIN_DIR
+    d.mkdir(**({} if frame_host.WINDOWS else {"mode": 0o700}), parents=True, exist_ok=True)
+    return d
+
+
+def _write_pin(device_id, lines):
+    target = known_hosts(device_id)
+    fd_, tmp = tempfile.mkstemp(prefix=".seed-", dir=str(pin_dir()))
+    with os.fdopen(fd_, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(dict.fromkeys(lines)) + "\n")
+    frame_host.make_private(tmp)  # Windows: this user only, not the folder's inherited ACL
+    os.replace(tmp, target)  # whole file at once: ssh never sees half of it
+
+
+# The host key types OpenSSH writes to known_hosts.
+KEY_TYPE_RE = re.compile(r"ssh-ed25519|ssh-rsa|ssh-dss|ecdsa-sha2-nistp(?:256|384|521)|"
+                         r"sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com")
+
+
+def fingerprint(blob):
+    """OpenSSH's SHA256 fingerprint of a base64 key blob (what `ssh-keygen -l` and ssh -v print),
+    or None if it isn't base64."""
+    try:
+        raw = base64.b64decode(blob, validate=True)
+    except (ValueError, TypeError):
+        return None
+    return "SHA256:" + base64.b64encode(hashlib.sha256(raw).digest()).decode().rstrip("=")
+
+
+def key_entry(line, name):
+    """(type, blob, fingerprint) from a known_hosts line for `name`, or None."""
+    f = (line or "").split()
+    if len(f) < 3 or line.startswith("#") or name not in f[0].split(",") or not KEY_TYPE_RE.fullmatch(f[1]):
+        return None
+    fp = fingerprint(f[2])
+    return (f[1], f[2], fp) if fp else None
+
+
+def pinned_keys(device_id):
+    """[(type, fingerprint)] of the keys saved for a headset (plain entries only)."""
+    try:
+        lines = known_hosts(device_id).read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return []
+    name = host_key_alias(device_id)
+    return [(e[0], e[2]) for e in (key_entry(line, name) for line in lines) if e]
+
+
+def pin_key(device_id, key_type, blob):
+    """Save one key as the headset's whole identity, replacing whatever was saved: what the
+    person confirmed after seeing its fingerprint (see frame_link.Link.trust_identity)."""
+    if not KEY_TYPE_RE.fullmatch(key_type or "") or not fingerprint(blob):
+        raise DeviceError("That isn't an SSH host key")
+    _write_pin(device_id, [f"{host_key_alias(device_id)} {key_type} {blob}"])
+
+
+def scan_file(device_id):
+    """(path, how ssh is told) for a throwaway known_hosts file that a key check writes the
+    headset's key to, without touching the saved one. `~` as in known_hosts_opt."""
+    name = f".scan-{device_id}-{secrets.token_hex(4)}"
+    path = pin_dir() / name
+    path.touch(**({} if frame_host.WINDOWS else {"mode": 0o600}))
+    frame_host.make_private(path)
+    return path, (str(path) if os.environ.get("FRAME_CONTROL_SSH_DIR") else f"~/.ssh/{PIN_DIR}/{name}")
+
+
+def identity_established(device):
+    """Whether this headset ever had an SSH identity here: the device's own flag (set once it
+    had a key or a connection that worked, and never cleared, whatever happens to its
+    addresses), a fingerprint recorded in devices.json, a pin file at all (even empty,
+    unreadable or not parseable), or an address that worked. Then a missing or unusable pin
+    fails closed, needing Check its key; only a headset with none of these may save the
+    first key it meets (accept-new)."""
+    if device.get("identity_established") or device.get("identity"):
+        return True
+    try:
+        if os.path.lexists(known_hosts(device["id"])):
+            return True
+    except OSError:
+        return True
+    return any(a.get("last_ok") for a in device.get("addresses") or ())
+
+
 def forget_pin(device_id):
-    """Drop a headset's saved key, e.g. after SteamOS was reinstalled. The next connection
-    trusts whatever key the headset shows, as a first connection does."""
+    """Drop a headset's saved key (the headset was removed, or the API's forget-identity).
+    The next connection trusts whatever key the headset shows, as a first connection does;
+    the page's Trust a new key flow (frame_link) shows the key first instead."""
     try:
         known_hosts(device_id).unlink()
         return True
@@ -480,6 +593,10 @@ class Registry:
             for a in d["addresses"]:
                 a.setdefault("networks", [])
                 a.setdefault("label", "")
+            if d.get("identity") or any(a.get("last_ok") for a in d["addresses"]):
+                # Files from before the flag existed: it had an identity (or a connection that
+                # worked, which saved one). Kept from now on, whatever happens to its addresses.
+                d["identity_established"] = True
             return NAME_RE.fullmatch(d.get("id", "")) is not None
         except (KeyError, TypeError, DeviceError):
             return False
@@ -682,8 +799,25 @@ class Registry:
                 a["networks"] = (a["networks"] + [network_id])[-16:]
             a["last_ok"] = time.time()
             a["last_rtt_ms"] = rtt_ms
+            self._find(device_id)["identity_established"] = True  # survives editing the address away
             self.save()
 
+    def record_identity(self, device_id, fingerprints):
+        """Remember the fingerprints of the key saved for a headset, so that losing the pin
+        file later can't turn into trusting whatever answers (identity_established)."""
+        fingerprints = [f for f in fingerprints if isinstance(f, str) and f.startswith("SHA256:")][:8]
+        if not fingerprints:
+            return
+        with self._changing():
+            try:
+                d = self._find(device_id)
+            except DeviceError:
+                return
+            if d.get("identity") != fingerprints or not d.get("identity_established"):
+                d["identity"] = fingerprints
+                d["identity_established"] = True
+                self.save()
+
     def undismiss(self, alias):
         """Set Up Connection is about to run for this alias: import its block again."""
         with self._changing():
@@ -767,15 +901,17 @@ class Registry:
                         d["addresses"].append(dict(new_address(host), label="From Set Up Connection"))
                     d["config_host"] = host
                     changed = True
-                    if seed and host:
-                        seed_pin(d["id"], [host], b["port"])
+                    if seed and host and seed_pin(d["id"], [host], b["port"]):
+                        d["identity"] = [f for _, f in pinned_keys(d["id"])][:8] or d.get("identity")
+                        d["identity_established"] = True
                 elif host and host != d.get("config_host"):
                     # Set Up Connection ran again and found the headset somewhere new.
                     d["config_host"] = host
                     if not any(a["host"] == host for a in d["addresses"]):
                         d["addresses"].insert(0, dict(new_address(host), label="From Set Up Connection"))
-                    if seed:
-                        seed_pin(d["id"], [host], b["port"])
+                    if seed and seed_pin(d["id"], [host], b["port"]) and not d.get("identity"):
+                        d["identity"] = [f for _, f in pinned_keys(d["id"])][:8] or None
+                        d["identity_established"] = True
                     changed = True
                 if d.get("config_login") != [user, b["port"]]:
                     # Set Up Connection (or an edit) changed who to log in as, or the port.

ui/frame_host.py

@@ -5,12 +5,17 @@ Everything here runs on your computer, not the Frame. Python stdlib only.
 CLI (used by the Electron app, so terminal handling lives in one place):
   python3 ui/frame_host.py terminal -- CMD [ARG...]   # open CMD in a terminal window
 """
+import hashlib
+import io
 import os
+import re
 import shlex
 import shutil
+import socket
 import ssl
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 MAC = sys.platform == "darwin"
@@ -32,6 +37,68 @@ class HostError(RuntimeError):
     pass
 
 
+# The start of a line in which ssh itself says the link to the headset failed (not the command it ran).
+# That includes ssh refusing the headset's host key, and the headset refusing this computer's
+# key ("user@host: Permission denied (publickey,...)."): either way no command ran.
+SSH_LINK_FAILED = re.compile(r"^(?:ssh: connect to host |ssh: Could not resolve hostname |banner exchange: |"
+                             r"kex_exchange_identification: |mux_client_\w+: |client_loop: |"
+                             r"Connection (?:closed|reset) by \S+ port \d+|Connection timed out during banner exchange|"
+                             r"Host key verification failed\.|No \S+ host key is known for |"
+                             r"[^\n@:]{1,64}@\S+: Permission denied \()",  # a Windows user name may have spaces
+                             re.M)
+
+
+def ssh_link_failed(returncode, stderr):
+    """Whether an ssh run failed to reach the headset: ssh's own exit code (255) and its own words."""
+    return returncode == 255 and bool(SSH_LINK_FAILED.search(stderr or ""))
+
+
+def link_failure(error):
+    """Mark an exception as ssh failing to reach the headset, judged where ssh ran (so error
+    reports can tell it from a message that only looks like one: a file name, say)."""
+    error.frame_link_failed = True
+    return error
+
+
+class Unreachable(HostError):
+    """The Frame, or a service on it, didn't answer: the person's to sort out, not a fault here."""
+
+
+def run_ssh(argv, **kwargs):
+    """Run an OpenSSH tool without Windows' redirected-stderr pipe hang.
+
+    A real temporary file avoids OpenSSH's blocked asynchronous stderr writes,
+    while keeping subprocess.run's captured output, text, check and timeout API.
+    """
+    if not WINDOWS:
+        return subprocess.run(argv, **kwargs)
+    if kwargs.pop("capture_output", False):
+        if kwargs.get("stdout") is not None or kwargs.get("stderr") is not None:
+            raise ValueError("stdout and stderr arguments may not be used with capture_output")
+        kwargs.update(stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if kwargs.get("stderr") != subprocess.PIPE:
+        return subprocess.run(argv, **kwargs)
+    check = kwargs.pop("check", False)
+    text = any(kwargs.get(key) for key in ("text", "universal_newlines", "encoding", "errors"))
+    with tempfile.TemporaryFile() as stderr:
+        kwargs["stderr"] = stderr
+        try:
+            result = subprocess.run(argv, **kwargs)
+        except subprocess.TimeoutExpired as error:
+            stderr.seek(0)
+            error.stderr = stderr.read()
+            raise
+        stderr.seek(0)
+        if text:
+            with io.TextIOWrapper(stderr, encoding=kwargs.get("encoding"), errors=kwargs.get("errors")) as reader:
+                result.stderr = reader.read()
+        else:
+            result.stderr = stderr.read()
+    if check:
+        result.check_returncode()
+    return result
+
+
 def data_dir(*parts):
     """Per-user app data: ~/Library/Application Support, %APPDATA% or $XDG_DATA_HOME
     (or $FRAME_CONTROL_DATA_DIR, which the tests point at a throwaway directory)."""
@@ -241,10 +308,46 @@ def clipboard_text():
     raise HostError("Can't read the clipboard")
 
 
+# What Windows' OpenSSH says when it refuses ~/.ssh/config (or a key) for its ACL.
+BAD_PERMISSIONS = "Bad owner or permissions on "
+
+
+def make_private(path):
+    """Leave only this user able to open PATH, as ssh insists for ~/.ssh/config.
+    Windows: an ACL of just this user, SYSTEM and Administrators, inherited nothing.
+    A file written into ~/.ssh otherwise takes the folder's ACL, and Windows' OpenSSH
+    refuses it if that grants anyone else, even an account deleted long ago
+    ("Bad owner or permissions"). Best effort: -> False if it couldn't."""
+    if not WINDOWS:
+        try:
+            os.chmod(path, 0o600)
+            return True
+        except OSError:
+            return False
+    me = os.environ.get("USERNAME", "")
+    try:  # "desktop\me","S-1-5-21-..."
+        # Bytes: the account name is in the console's code page, the SID is ASCII.
+        out = subprocess.run(["whoami", "/user", "/fo", "csv", "/nh"], capture_output=True,
+                             stdin=subprocess.DEVNULL, timeout=10).stdout
+        sid = out.decode("ascii", "replace").strip().rsplit(",", 1)[-1].strip('"')
+        if sid.startswith("S-1-"):
+            me = "*" + sid
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    if not me:
+        return False
+    try:
+        return subprocess.run(["icacls", str(path), "/inheritance:r", "/grant:r", f"{me}:F",
+                               "*S-1-5-18:F", "*S-1-5-32-544:F"], capture_output=True,
+                              stdin=subprocess.DEVNULL, timeout=10).returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
 def ssh_hostname(alias):
     """The real host name an ssh alias points at (`ssh -G`), for non-SSH clients like RDP."""
     try:
-        out = subprocess.run(["ssh", "-G", alias], capture_output=True, stdin=subprocess.DEVNULL, text=True, timeout=10).stdout
+        out = run_ssh(["ssh", "-G", alias], capture_output=True, stdin=subprocess.DEVNULL, text=True, timeout=10).stdout
     except (OSError, subprocess.TimeoutExpired):
         return alias
     for line in out.splitlines():
@@ -277,24 +380,65 @@ def open_steam_link():
     return "Steam Link isn't installed; opened its download page"
 
 
+RDP_PORT = 3389
+RDP_USER = "steamos"  # xrdp signs in with the Developer Mode password, not this computer's
+# xrdp's certificate is its own, so every client warns about it first.
+RDP_LOGIN = (f"accept the warning about the Frame's certificate, then sign in as {RDP_USER} "
+             "with your Developer Mode password")
+
+
+def check_rdp(host, timeout=3):
+    """Raise Unreachable, saying why, unless the Frame's RDP port takes a connection."""
+    try:
+        with socket.create_connection((host, RDP_PORT), timeout=timeout):
+            return
+    except ConnectionRefusedError:
+        raise Unreachable(f"The Frame at {host} is on but isn't accepting remote desktop (port {RDP_PORT} "
+                          "refused). Turn on Developer Mode in Steam Settings > System on the headset, "
+                          "then restart it and try again.") from None
+    except socket.gaierror:
+        raise Unreachable(f"Can't find {host} on the network for remote desktop. Check the headset's "
+                          "address on the Devices tab.") from None
+    except OSError as e:
+        raise Unreachable(f"The Frame didn't answer remote desktop at {host} ({e}). It may be asleep, "
+                          "switched off or on another network; if it's on, check Developer Mode is on "
+                          "in Steam Settings > System.") from None
+
+
+def rdp_file(host):
+    """A Remote Desktop connection file for the Frame. mstsc /v: alone offers this
+    computer's Windows account, which xrdp turns away; the file names steamos instead."""
+    if any(c in host for c in "\r\n"):
+        raise HostError("That headset address can't be used for remote desktop")
+    # One file per address, so two launches close together can't swap headsets.
+    path = cache_dir(f"frame-{hashlib.sha256(host.encode()).hexdigest()[:16]}.rdp")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\r\n") as f:  # Path.write_text(newline=) is 3.10+
+        f.write(f"full address:s:{host}\nusername:s:{RDP_USER}\n")
+    return path
+
+
 def open_rdp(alias, host=None):
     """Remote desktop to the Frame's xrdp (user steamos), at `host` or where the alias points."""
     host = host or ssh_hostname(alias)
+    # The client would open either way and then fail on its own, with nothing said here.
+    check_rdp(host)
     if MAC:
         if subprocess.run(["open", "-a", "Windows App"], capture_output=True).returncode == 0:
-            return "Opened Windows App"
+            return f"Opened Windows App: connect to {host} and {RDP_LOGIN}"
         open_url("https://apps.apple.com/app/windows-app/id1295203466")
         return "Windows App isn't installed; opened its App Store page"
     if WINDOWS:
-        _spawn(["mstsc.exe", f"/v:{host}"])
-        return f"Opened Remote Desktop to {host}"
+        _spawn(["mstsc.exe", str(rdp_file(host))])
+        # Windows asks about the unsigned connection file first.
+        return f"Opened Remote Desktop to {host}: choose Connect, {RDP_LOGIN}"
     if which("remmina"):
-        _spawn(["remmina", "-c", f"rdp://steamos@{host}"])
-        return f"Opened Remmina to {host}"
+        _spawn(["remmina", "-c", f"rdp://{RDP_USER}@{host}"])
+        return f"Opened Remmina to {host}: {RDP_LOGIN}"
     for name in ("xfreerdp3", "xfreerdp"):
         if which(name):
-            _spawn([name, f"/v:{host}", "/u:steamos", "/dynamic-resolution"])
-            return f"Opened FreeRDP to {host}"
+            _spawn([name, f"/v:{host}", f"/u:{RDP_USER}", "/dynamic-resolution"])
+            return f"Opened FreeRDP to {host}: {RDP_LOGIN}"
     raise HostError("No RDP client found: install Remmina or FreeRDP")
 
 

ui/frame_link.py

@@ -28,16 +28,21 @@ Python stdlib only. Runs on this computer, never on the Frame.
 import copy
 import hashlib
 import ipaddress
+import os
 import queue
 import re
+import shlex
 import socket
 import subprocess
+import sys
+import tempfile
 import threading
 import time
 
 import frame_devices
 import frame_host
 import frame_network
+import frame_telemetry
 
 PROBE_TIMEOUT = 4      # seconds for a TCP answer on port 22
 RESOLVE_GRACE = 6      # ...after however long the name lookup took, up to this much
@@ -48,6 +53,7 @@ NETWORK_EVERY = 5      # how often the network fingerprint is read
 TAILSCALE_EVERY = 30
 RETRY = (5, 10, 20, 30)  # seconds before automatic retries after a failure
 REQUEST_GAP = 5        # a request may start a new attempt this long after the last one
+SCAN_TTL = 600         # a key shown for "Trust a new key" may be trusted this long after it was read
 
 STAGES = [("network", "Checking this computer's network"), ("find", "Finding the headset"),
           ("ssh", "Opening SSH"), ("identity", "Checking the headset's identity"),
@@ -74,8 +80,8 @@ def ssh_g(alias):
     """(hostname, port, user, proxied) from `ssh -G ALIAS`, for a headset that's only an
     ssh alias. proxied: it goes through ProxyJump or ProxyCommand, so only ssh can reach it."""
     try:
-        out = subprocess.run(["ssh", "-G", alias], capture_output=True, stdin=subprocess.DEVNULL, text=True,
-                             timeout=10).stdout
+        out = frame_host.run_ssh(["ssh", "-G", alias], capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                                 timeout=10).stdout
     except (OSError, subprocess.TimeoutExpired):
         out = ""
     got = {}
@@ -88,6 +94,32 @@ def ssh_g(alias):
     return got.get("hostname") or alias, port, got.get("user"), proxied
 
 
+def proxy_route(alias):
+    """How ~/.ssh/config sends ALIAS: (None, None) directly, ("jump", spec) through
+    ProxyJump, or ("command", text) through a ProxyCommand."""
+    try:
+        out = frame_host.run_ssh(["ssh", "-G", alias], capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                                 timeout=10).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        out = ""
+    got = {}
+    for line in out.splitlines():
+        k, _, v = line.partition(" ")
+        if k in ("proxyjump", "proxycommand") and k not in got:
+            got[k] = v.strip()
+    if got.get("proxyjump") not in (None, "", "none"):
+        return "jump", got["proxyjump"]
+    if got.get("proxycommand") not in (None, "", "none"):
+        return "command", got["proxycommand"]
+    return None, None
+
+
+# One jump host, as ProxyJump names it: [user@]host[:port], nothing that could start an
+# option, split a shell word or carry an ssh % token.
+JUMP_RE = re.compile(r"(?:([A-Za-z0-9][A-Za-z0-9._-]{0,63})@)?"
+                     r"(\[[0-9A-Fa-f:.]{2,45}\]|[A-Za-z0-9][A-Za-z0-9.-]{0,252})(?::(\d{1,5}))?")
+
+
 def probe(host, port, timeout=PROBE_TIMEOUT, update=None):
     """Try a TCP connection to host:port. -> {"state", "detail", "ip", "rtt_ms"}.
 
@@ -108,7 +140,8 @@ def probe(host, port, timeout=PROBE_TIMEOUT, update=None):
         ip = addr[0]
         if family == socket.AF_INET6 and len(addr) > 3 and addr[3] and "%" not in ip:
             try:  # a link-local IPv6 address only works with its interface
-                ip = f"{ip}%{socket.if_indextoname(addr[3])}"
+                # Windows' ssh takes only the number: its names ("wireless_32768") don't resolve.
+                ip = f"{ip}%{addr[3] if frame_host.WINDOWS else socket.if_indextoname(addr[3])}"
             except (OSError, AttributeError):
                 pass
         left = deadline - now()
@@ -135,6 +168,122 @@ def probe(host, port, timeout=PROBE_TIMEOUT, update=None):
     return last or {"state": "timeout", "detail": "No answer"}
 
 
+def _ip_kind(text):
+    """ipv4, ipv6, ipv6 link-local or tailscale for an IP address (zone allowed), else None."""
+    try:
+        ip = ipaddress.ip_address((text or "").strip("[]").split("%")[0])
+    except ValueError:
+        return None
+    if frame_network.is_tailscale(str(ip)):
+        return "tailscale"
+    return "ipv4" if ip.version == 4 else "ipv6 link-local" if ip.is_link_local else "ipv6"
+
+
+def address_kind(host, ip=None):
+    """What sort of address a probe row is, for diagnostics, never the address itself:
+    ".local", "ipv4", "ipv6", "ipv6 link-local", "tailscale" or "hostname", plus what a
+    name resolved to (".local->ipv6 link-local") when the probe got that far."""
+    h = (host or "").lower().rstrip(".")
+    kind = _ip_kind(h) or (".local" if h.endswith(".local") else
+                           "tailscale" if frame_network.is_tailscale(h) else "hostname")
+    got = _ip_kind(ip) if ip and not _ip_kind(h) else None
+    return f"{kind}->{got}" if got and got != kind else kind
+
+
+def probes_summary(probes):
+    """Each address tried, as its kind and how the probe went: "alias .local->ipv4 timeout"."""
+    out = []
+    for row in probes or ():
+        lead = "alias " if row.get("label") == "from ~/.ssh/config" else ""
+        out.append(f"{lead}{address_kind(row.get('host'), row.get('ip'))} {row.get('state') or '?'}")
+    return "; ".join(out)
+
+
+# Exactly the tokens the scrubbers write (here and frame_telemetry.scrub), nothing else in <...>.
+PLACEHOLDER = re.compile(r"(<(?:host|user|email|ip|mac|steamid|hex|token|ssh-key|pem|url|redacted)>)")
+
+
+def hide_hosts(text, hosts, keep=()):
+    """text with each of `hosts` (the headset's own addresses and names) replaced by <host>,
+    longest first and whatever the case, so a bare name like "steamdeck" that the scrubber
+    can't recognise goes too."""
+    keep = {k.lower() for k in keep if k} | KEYWORDS  # a headset called "host" mustn't eat ssh's wording
+    names = sorted({h for h in hosts if h and h.lower() not in keep}, key=len, reverse=True)
+    parts = PLACEHOLDER.split(text)  # never inside a scrubber's own <token> already there
+    for i in range(0, len(parts), 2):
+        for h in names:
+            parts[i] = re.sub(r"(?<![\w.:-])%s(?![\w-]|[:.%%]\w)" % re.escape(h), "<host>", parts[i], flags=re.I)
+    return "".join(parts)
+
+
+# ssh names the host it was going to after these words ("Could not resolve hostname X",
+# "connect to host X port 22", "Timed out talking to X"): whatever follows goes, known or not.
+OPERAND = re.compile(r"(?i)\b(hostname|host|to(?:\s+host)?)\s+(?!<)([^\s:,;'\"()|]+)")
+PLAIN_WORDS = {"answer", "the", "a", "an", "this", "it", "its", "be", "connect", "find", "work", "try"}
+KEYWORDS = {"host", "hostname", "to", "port"} | PLAIN_WORDS
+
+
+def hide_operands(text):
+    def one(m):
+        word = m.group(2).rstrip(".")
+        dots = m.group(2)[len(word):]
+        return m.group(0) if word.lower() in PLAIN_WORDS else f"{m.group(1)} <host>{dots}"
+    return OPERAND.sub(one, text)
+
+
+def scrub_failure(text, hosts=()):
+    """Free text about a failed attempt, for the log: the attempt's own names, whole and
+    longest first (case-insensitively, never ssh's own words), then anything ssh names as a
+    host, then the shared scrubber (addresses, paths, user names)."""
+    return frame_telemetry.scrub(hide_operands(hide_hosts(str(text or ""), hosts)), 600)
+
+
+def failure_detail(error):
+    """What an address that answered but failed SSH shows: the short reason when there is one
+    (the whole message is the banner's headline already), else the message."""
+    error = error or {}
+    return error.get("short") or error.get("message") or "SSH failed"
+
+
+def failure_category(message, raw=""):
+    """The telemetry error category (frame_unreachable, frame_auth, ...) for a failure: a fixed
+    word, never its text."""
+    return frame_telemetry.categorize(f"{message or ''}\n{raw or ''}")[0]
+
+
+_logged = {}            # failure line -> {"at": when last written, "repeats": since then}
+LOG_REPEAT_EVERY = 300  # the same failure, retried every 30 s, goes in the log at most this often
+LOG_REMEMBER = 32       # different failures remembered for that
+
+
+def log_failure(stage, message, raw="", probes=(), hosts=()):
+    """One failed connection attempt to stderr (the app's server.log), scrubbed when written,
+    with the hosts of that attempt (so a later switch of headset can't let them through)."""
+    hosts = list(hosts) + [r.get(k) for r in probes or () for k in ("host", "ip")]
+    bits = [f"frame_link: {stage} failed: {scrub_failure(message, hosts)}"]
+    last = [ln.strip() for ln in (raw or "").splitlines() if ln.strip()][-1:]
+    if last and last[0] != message:
+        bits.append(f"ssh said: {scrub_failure(last[0][:300], hosts)}")
+    tried = probes_summary(probes)
+    if tried:
+        bits.append(f"addresses: {tried}")
+    line = " | ".join(bits)[:900]
+    t = time.monotonic()
+    seen = _logged.get(line)
+    if seen and t - seen["at"] < LOG_REPEAT_EVERY:
+        seen["repeats"] += 1
+        return
+    more = f" (and {seen['repeats']} more times)" if seen and seen["repeats"] else ""
+    _logged.pop(line, None)
+    _logged[line] = {"at": t, "repeats": 0}
+    while len(_logged) > LOG_REMEMBER:
+        _logged.pop(next(iter(_logged)))  # the least recently written
+    try:
+        print(line + more, file=sys.stderr, flush=True)
+    except (OSError, ValueError, AttributeError):
+        pass  # no stderr (a closed pipe): the page still shows the failure
+
+
 def ssh_target(host, ip):
     """Where ssh should go for an address whose probe answered from `ip`: that IP, so ssh
     doesn't look the name up again and try an address that didn't answer."""
@@ -145,6 +294,43 @@ def ssh_target(host, ip):
         return host
 
 
+def _unlink(path):
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
+def _scanned_key(path, name):
+    """The first whole, valid known_hosts line for `name` that a key check wrote, or None.
+    Only lines ssh has finished (ending in a newline): a half-written key mustn't count."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            text = fh.read()
+    except (OSError, UnicodeDecodeError):
+        return None
+    for line in text.splitlines(True):
+        if line.endswith("\n"):
+            entry = frame_devices.key_entry(line.strip(), name)
+            if entry:
+                return entry
+    return None
+
+
+def proxy_command(literal):
+    """A ProxyCommand that runs `literal` (argv, ending with the jump host) with `-W` to the
+    headset, each word exactly as given. ssh first expands its %-tokens in the line, so every
+    % of ours is doubled; then it hands the line to a shell (`$SHELL -c` on macOS and Linux)
+    or, on Windows, starts it as a command line, so every word is quoted for that: a path
+    with spaces, $(...), backticks or quotes stays one plain word. The forward is
+    [%h]:%p, so an IPv6 address (with a zone) reads as one host."""
+    words = [w.replace("%", "%%") for w in literal]
+    target = "[%h]:%p"
+    if frame_host.WINDOWS:
+        return subprocess.list2cmdline([*words[:-1], "-W", target, words[-1]])
+    return " ".join(shlex.quote(w) for w in [*words[:-1], "-W", target, words[-1]])
+
+
 def probe_raw(host, port, result):
     """ssh's own wording for a failed probe, so the server's UNREACHABLE table explains it."""
     return {"unresolved": f"ssh: Could not resolve hostname {host}: not found",
@@ -163,7 +349,8 @@ class Link:
         self.session_alias = env_alias  # ...and stays selectable after switching away
         self.mux_base = list(mux_base)  # ["ssh", "-o", "BatchMode=yes", ControlPath...]
         self.control = control          # ControlPath, or None where ssh can't share connections
-        self.apply = apply              # apply(alias, host_opts): point every ssh command at the headset
+        self._apply = apply             # apply(alias, host_opts): point every ssh command at the headset
+        self.applied = (None, [])       # what it was last given
         self.explain = explain          # ssh error text -> plain reason, or None
         self.cond = threading.Condition()
         self.version = 0
@@ -187,6 +374,9 @@ class Link:
         self.route_lock = threading.Lock()
         self.routed = None              # the device id every ssh command points at
         self.routed_device = None
+        self.last_failure = None        # {"stage", "category", "at"}: for report diagnostics, no free text
+        self.attempt_device = None      # the headset the current attempt is for
+        self.scans = {}                 # device id -> the host key it showed for "Trust a new key"
 
     # ---- publishing ----
     def publish(self, **fields):
@@ -391,13 +581,76 @@ class Link:
             return [*mux, *(device.get("frozen") or [])]  # what ~/.ssh/config said when it was routed
         if not host:  # a headset with no addresses: reach nothing, not whatever ~/.ssh/config says
             return ["-o", "HostName=no-address.invalid"]
-        # StrictHostKeyChecking=yes: whatever ~/.ssh/config says for Host *, every command
-        # checks the headset's pinned key (only the connector's first handshake may save one).
-        return [*mux, "-o", "StrictHostKeyChecking=yes", "-o", f"HostName={frame_devices.ssh_host(host)}",
+        # Whatever ~/.ssh/config says for Host *, every command checks the headset's pinned key:
+        # StrictHostKeyChecking=yes. Only a headset that never had an identity here (just
+        # added, never connected) gets accept-new: the first contact saves its key, as Set Up
+        # Connection and the connector's first handshake do, rather than every command failing
+        # with "No host key is known" until the connector gets there. Once it had one, a pin
+        # file that's gone, empty or unreadable fails closed (identity_established): accept-new
+        # can't tell that from a new headset and would trust whatever answers.
+        strict = self.strictness(device)
+        if strict == "accept-new":
+            try:
+                frame_devices.pin_dir()  # ssh won't create the folder its known_hosts file goes in
+            except OSError:
+                pass  # ssh then says it couldn't save the key, and goes on
+        return [*mux, "-o", f"StrictHostKeyChecking={strict}", "-o", f"HostName={frame_devices.ssh_host(host)}",
                 "-o", f"HostKeyAlias={frame_devices.host_key_alias(device['id'])}",
                 "-o", f"UserKnownHostsFile={frame_devices.known_hosts_opt(device['id'])}", "-o", "HashKnownHosts=no",
                 "-o", f"User={device['user']}", "-o", f"Port={device['port']}"]
 
+    def apply(self, alias, opts):
+        self.applied = (alias, list(opts))
+        self._apply(alias, opts)
+
+    def strictness(self, device):
+        """yes, or accept-new for a headset that never had an identity. Judged on what the
+        registry says now, not only the copy handed in (a route frozen at connect, say, from
+        before its first key was recorded). A key saved since is recorded on the way."""
+        try:
+            current = self.reg.get(device["id"])
+        except frame_devices.DeviceError:
+            current = {}
+        if not (frame_devices.identity_established(device) or
+                (current and frame_devices.identity_established(current))):
+            return "accept-new"
+        self.settle_pin(dict(device, **current) if current else device, tighten=False)
+        return "yes"
+
+    def settle_pin(self, device=None, tighten=True):
+        """A key ssh saved on a first contact, whatever happened next (logged in or refused,
+        by the handshake or any command): record it, make the file private, and from then on
+        route every command strictly. Idempotent and cheap when there's nothing to do."""
+        device = device or self.routed_device
+        if not device or device.get("transient") or device.get("none") or not device.get("id"):
+            return
+        did = device["id"]
+        if frame_devices.pinned(did):
+            fps = [f for _, f in frame_devices.pinned_keys(did)]
+            if fps and (device.get("identity") != fps or not device.get("identity_established")):
+                try:
+                    current = self.reg.get(did)
+                except frame_devices.DeviceError:
+                    return
+                if current.get("identity") != fps or not current.get("identity_established"):
+                    frame_host.make_private(frame_devices.known_hosts(did))  # ssh wrote it
+                    self.reg.record_identity(did, fps)
+        if not tighten:
+            return
+        with self.route_lock:
+            alias, opts = self.applied
+            if alias == device.get("alias") and "StrictHostKeyChecking=accept-new" in opts and \
+                    frame_devices.identity_established(dict(device, **self._current(did))):
+                self.opts = [("StrictHostKeyChecking=yes" if o == "StrictHostKeyChecking=accept-new" else o)
+                             for o in opts]
+                self.apply(alias, self.opts)
+
+    def _current(self, device_id):
+        try:
+            return self.reg.get(device_id)
+        except frame_devices.DeviceError:
+            return {}
+
     def public_device(self, d):
         return {k: d.get(k) for k in ("id", "name", "alias", "user", "port", "transient")}
 
@@ -427,6 +680,8 @@ class Link:
                 if t - last_ts >= TAILSCALE_EVERY and self.state["network"] and not reasons:
                     last_ts = t
                     self.refresh_network()
+                if "StrictHostKeyChecking=accept-new" in self.applied[1]:
+                    self.settle_pin()  # a command's first contact may have saved the key
                 phase = self.state["phase"]
                 if phase == "connected" and not self.alive():
                     reasons.append("dropped")
@@ -435,7 +690,9 @@ class Link:
                 if reasons:
                     self.connect(reasons)
             except Exception as e:  # keep the loop alive whatever happens; say what went wrong
-                self.publish(phase="failed", error={"stage": "network", "message": f"{type(e).__name__}: {e}",
+                message = f"{type(e).__name__}: {e}"
+                self.note_failure("network", message, str(e))
+                self.publish(phase="failed", error={"stage": "network", "message": message,
                                                     "raw": str(e)}, retry_at=now() + RETRY[-1])
             finally:
                 with self.cond:
@@ -511,6 +768,7 @@ class Link:
             self.cond.notify_all()
         ok = False
         try:
+            self.attempt_device = device  # its names, for scrubbing this attempt's log lines
             ok = self.attempt(device)
         finally:
             self.finish(gen, ok, device)
@@ -539,6 +797,7 @@ class Link:
                                   now() + RETRY[min(self.fails, len(RETRY)) - 1])
                 if not self.state["error"]:
                     self.state["error"] = {"stage": "find", "message": "Couldn't connect", "raw": ""}
+                    self.note_failure("find", "Couldn't connect", "", self.state["probes"])
             self.version += 1
             self.cond.notify_all()
 
@@ -557,17 +816,33 @@ class Link:
             return "Starting up"
         return "Connecting"
 
-    def fail(self, sid, message, raw=""):
+    def fail(self, sid, message, raw="", **more):
+        """A stage failed. `more`: what the page can offer to fix it (hostkey, auth), and `short`:
+        the reason in a few words, for the places a whole sentence doesn't fit (the header pill,
+        the address that failed)."""
         self.stage(sid, "failed", message)
         with self.cond:
-            self.state["error"] = {"stage": sid, "message": message, "raw": raw}
+            self.state["error"] = dict({"stage": sid, "message": message, "raw": raw}, **more)
+            probes = copy.deepcopy(self.state["probes"])
+        self.note_failure(sid, message, raw, probes)
+
+    def note_failure(self, stage, message, raw="", probes=()):
+        """Keep a failure for report diagnostics as fixed values only (its stage and error
+        category, decided now), and write it to the log scrubbed with this attempt's hosts."""
+        self.last_failure = {"stage": stage, "category": failure_category(message, raw), "at": now()}
+        hosts = []
+        for d in (self.attempt_device, self.routed_device):  # the headset tried, and where commands go
+            d = d or {}
+            hosts += [a.get("host") for a in d.get("addresses") or ()]
+            hosts += [d.get("frozen_host"), d.get("alias"), d.get("name")]
+        log_failure(stage, message, raw, probes, hosts)
 
     def attempt(self, device):
         if device.get("none"):
             self.fail("find", "No headset is set up. Add one on the Devices tab.")
             return False
         if not device.get("transient") and not device["addresses"]:
-            self.fail("find", f"{device['name']} has no addresses. Add one on the Devices tab.")
+            self.fail("find", "The active headset has no addresses. Add one on the Devices tab.")
             return False
         # 1. this computer's network
         self.stage("network", "active")
@@ -630,7 +905,7 @@ class Link:
                         self.learn(device, a["host"], net, None)
                         return True
                     with self.cond:
-                        why_not = (self.state["error"] or {}).get("message") or "SSH failed"
+                        why_not = failure_detail(self.state["error"])
                     self.probe_update(i, state="sshfailed", detail=why_not)
                     if outcome != "next":
                         return False
@@ -680,7 +955,7 @@ class Link:
                 self.learn(device, a["host"], net, results[pick]["rtt_ms"])
                 return True
             with self.cond:
-                why_not = (self.state["error"] or {}).get("message") or "SSH failed"
+                why_not = failure_detail(self.state["error"])
             self.probe_update(pick, state="sshfailed", detail=why_not)
             if outcome != "next":
                 return False
@@ -736,6 +1011,7 @@ class Link:
         if device.get("transient"):
             return
         self.reg.record_success(device["id"], host, net.get("id"), rtt)
+        self.reg.record_identity(device["id"], [f for _, f in frame_devices.pinned_keys(device["id"])])
         # Set Up Connection may have changed the block while this attempt ran: take that
         # in (and reconnect) rather than writing this attempt's older settings over it.
         self.watch_config()
@@ -765,8 +1041,8 @@ class Link:
         if not self.control:
             return False
         try:
-            return subprocess.run([*self.mux_base, *opts, "-O", "check", alias or self.alias], capture_output=True,
-                                  stdin=subprocess.DEVNULL, timeout=5).returncode == 0
+            return frame_host.run_ssh([*self.mux_base, *opts, "-O", "check", alias or self.alias], capture_output=True,
+                                      stdin=subprocess.DEVNULL, timeout=5).returncode == 0
         except (OSError, subprocess.TimeoutExpired):
             return False
 
@@ -777,8 +1053,8 @@ class Link:
             pending.kill()
         if self.control and self.alias:
             try:
-                subprocess.run([*self.mux_base, *self.opts, "-O", "exit", self.alias], capture_output=True,
-                               stdin=subprocess.DEVNULL, timeout=5)
+                frame_host.run_ssh([*self.mux_base, *self.opts, "-O", "exit", self.alias], capture_output=True,
+                                   stdin=subprocess.DEVNULL, timeout=5)
             except (OSError, subprocess.TimeoutExpired):
                 pass
         if proc and proc.poll() is None:
@@ -790,7 +1066,17 @@ class Link:
 
     def handshake(self, device, a, found, user):
         """SSH to one address, following ssh -v through stages 3-5.
-        -> "ok", "next" (try another address) or "stop"."""
+        -> "ok", "next" (try another address) or "stop". A key ssh saved is recorded and
+        protected however it ends: a login refused after the key was saved, a timeout, a stop."""
+        try:
+            return self._handshake(device, a, found, user)
+        finally:
+            if not device.get("transient"):
+                with self.route_lock:
+                    current = self.attempt_gen == self.gen
+                self.settle_pin(device, tighten=current)
+
+    def _handshake(self, device, a, found, user):
         # The IP that answered (with a link-local IPv6 address's zone), so ssh doesn't
         # look the name up again and stall on an address that didn't answer.
         opts = self.host_opts(device, ssh_target(a["host"], found.get("ip")))
@@ -808,15 +1094,9 @@ class Link:
             return "ok"
         extra = []
         if not device.get("transient"):
-            if frame_devices.pinned(device["id"]):
-                extra = ["-o", "StrictHostKeyChecking=yes"]
-            else:
-                # First connection since this headset was added: trust what it shows
-                # (as Set Up Connection does), and pin it from now on. ssh won't create
-                # the folder its known_hosts file goes in.
-                extra = ["-o", "StrictHostKeyChecking=accept-new"]
-                pins = frame_devices.known_hosts(device["id"]).parent
-                pins.mkdir(**({} if frame_host.WINDOWS else {"mode": 0o700}), parents=True, exist_ok=True)
+            # A headset's first connection trusts what it shows (as Set Up Connection does) and
+            # pins it; any later one checks the pin strictly (see host_opts).
+            extra = ["-o", f"StrictHostKeyChecking={self.strictness(device)}"]
         if self.control:
             # No ConnectTimeout: with it, OpenSSH's master takes ~5s to open its socket.
             # `extra` first: ssh takes the first value of an option, and it may say accept-new.
@@ -824,27 +1104,70 @@ class Link:
                     "-o", "ServerAliveCountMax=2", "-N", alias]
         else:
             argv = [*self.mux_base, *extra, *opts, "-v", "-o", "ConnectTimeout=10", alias, "true"]
+        lines = queue.Queue()
+        collecting = [True]
+        reader_done = threading.Event()
+        errfile = None
         try:
-            proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
-                                    stderr=subprocess.PIPE, **frame_host.DETACHED)
+            if self.control:
+                proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                                        stderr=subprocess.PIPE, **frame_host.DETACHED)
+            else:
+                # No master (Windows): ssh runs `true` and exits. Its stderr goes to a file read
+                # as it grows, not a pipe: Windows' OpenSSH can block writing to a redirected
+                # pipe (see frame_host.run_ssh), and the handshake would never finish.
+                fd_, errfile = tempfile.mkstemp(prefix="frame-ssh-")
+                try:
+                    proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                                            stderr=fd_, **frame_host.DETACHED)
+                finally:
+                    os.close(fd_)
         except OSError as e:
+            if errfile:
+                _unlink(errfile)
             self.fail("ssh", f"Couldn't run ssh: {e}", str(e))
             return "stop"
         self.pending = proc  # so stop() can end it mid-handshake
-        lines = queue.Queue()
-        collecting = [True]
 
         def read():
             for raw in iter(proc.stderr.readline, b""):
                 if collecting[0]:
                     lines.put(raw.decode("utf-8", "replace").rstrip())
+            reader_done.set()
             lines.put(None)
             proc.stderr.close()
-        threading.Thread(target=read, daemon=True).start()
+
+        def tail():
+            buf = b""
+            try:
+                with open(errfile, "rb") as fh:
+                    while True:
+                        chunk = fh.read()
+                        if not chunk:
+                            if proc.poll() is None:
+                                time.sleep(0.05)
+                                continue
+                            chunk = fh.read()  # whatever it wrote just before exiting
+                            if not chunk:
+                                break
+                        buf += chunk
+                        *done, buf = buf.split(b"\n")
+                        for raw in done:
+                            lines.put(raw.decode("utf-8", "replace").rstrip())
+            except OSError:
+                pass
+            if buf:
+                lines.put(buf.decode("utf-8", "replace").rstrip())
+            reader_done.set()
+            lines.put(None)
+            _unlink(errfile)
+        threading.Thread(target=read if errfile is None else tail, daemon=True).start()
 
         step, said, authed = "ssh", [], False
         deadline = time.monotonic() + HANDSHAKE_TIMEOUT
         mismatch = False
+        shown = None  # (type, fingerprint) of the key the headset showed
+        exited = None  # when ssh was first seen to have exited
         while True:
             left = deadline - time.monotonic()
             if self.stopped:
@@ -862,7 +1185,14 @@ class Link:
                 if authed and self.control and self.check(opts, alias):
                     break
                 if proc.poll() is not None and lines.empty():
-                    line = None
+                    # ssh exited: its last words (Permission denied…) may still be on their way.
+                    # The reader's end marker says when they're all in; a pipe that something
+                    # else holds open (a ProxyCommand's child) gets a short grace instead.
+                    exited = exited or time.monotonic()
+                    if reader_done.is_set() and lines.empty() or time.monotonic() - exited > 2:
+                        line = None
+                    else:
+                        continue
                 else:
                     continue
             if line is None:  # ssh exited
@@ -871,7 +1201,7 @@ class Link:
                     break
                 if authed and self.control and self.check(opts, alias):
                     break
-                return self.failed(step, said, mismatch, alias)
+                return self.failed(step, said, mismatch, alias, shown, a["host"], device)
             if not line.startswith("debug"):
                 said.append(line)
             m = CONNECTING.search(line)
@@ -884,12 +1214,15 @@ class Link:
                 self.stage("identity", "active", "Waiting for the headset's host key")
             elif HOSTKEY.search(line):
                 m = HOSTKEY.search(line)
+                shown = (m.group(1), m.group(2))
                 self.stage("identity", "active", f"It shows {m.group(1)} key {m.group(2)[:20]}…")
             elif KNOWN.search(line):
                 self.stage("identity", "done", "Matches the identity saved for this headset")
                 step = "login"
                 self.stage("login", "active", f"Logging in as {user}")
             elif ADDED.search(line):
+                if not device.get("transient"):
+                    self.settle_pin(device, tighten=False)  # now, before the login can fail
                 self.stage("identity", "done", "First connection: saved this headset's identity")
                 step = "login"
                 self.stage("login", "active", f"Logging in as {user}")
@@ -928,18 +1261,36 @@ class Link:
         # OpenSSH lower-cases host names (FRAME.LOCAL logs as frame.local).
         return not m or m.group(1).lower() in (host.lower(), alias.lower()) or "Authentication succeeded" in line
 
-    def failed(self, step, said, mismatch, alias):
+    def failed(self, step, said, mismatch, alias, shown=None, host=None, device=None):
         text = "\n".join(said).strip()
         if mismatch:
-            self.fail("identity", "This address answered as a different headset (its SSH identity doesn't match). "
-                      "If SteamOS was reinstalled, use Forget Identity on the Devices tab.", text)
+            # A key that differs from the saved one, or (strict, pinned) none of the saved key's
+            # type any more: either way not the identity saved. Never accepted here: the page
+            # shows the new key's fingerprint and the person decides (Trust a new key).
+            name = (device or {}).get("name") or alias
+            lost = bool(device) and not frame_devices.pinned(device["id"]) and \
+                frame_devices.identity_established(device)
+            if lost:
+                message = (f"The SSH identity saved for {name} is missing or can't be read, so Frame Control won't "
+                           "trust whatever answers. Check its key and trust it on the Devices tab.")
+            else:
+                message = (f"This address answered with a different SSH identity from the one saved for {name}. "
+                           "If SteamOS was reinstalled or reset, or this is a new headset, check its new key and trust "
+                           "it on the Devices tab. If not, a different device may be answering here.")
+            self.fail("identity", message, text,
+                      short="Saved SSH identity missing" if lost else "SSH identity changed",
+                      hostkey={"state": "missing" if lost else "changed", "type": shown[0] if shown else None,
+                               "fingerprint": shown[1] if shown else None, "host": host})
             return "next"
         # A refused key is the same at every address: stop. (Judged by ssh's own words, not
         # the step: a jump host's progress lines look like the headset's.) A forward that
         # a jump host couldn't open is about this address only: try the next.
         forward = re.search(r"open failed|forwarding failed|Connection refused|Connection closed|timed out", text)
         if re.search(r"Permission denied", text) and not forward:
-            self.fail("login", self.explain(text) or "The headset didn't accept this computer's key.", text)
+            # Not something a retry fixes: the headset needs this computer's key (Set Up Connection).
+            self.fail("login", self.explain(text) or "The headset didn't accept this computer's key. Run Set Up "
+                      "Connection: it pairs this computer with the headset again.", text, auth="denied",
+                      short="This computer's key refused")
             return "stop"
         if step == "connected":
             self.fail("login", "Logged in, but the shared SSH connection didn't start.", text)
@@ -979,12 +1330,14 @@ class Link:
             lead = f"Answered in {res['rtt_ms']:g} ms" if res.get("rtt_ms") is not None else "Through the jump host"
             rows[i]["ssh"] = "checking"
             put()
+            # "yes" before host_opts (ssh takes an option's first value): a test only looks, so
+            # it reports a key not saved yet rather than saving it as host_opts' accept-new would.
             argv = [*self.mux_base[:3], "-o", "ControlPath=none", "-o", "ConnectTimeout=8",
-                    *self.host_opts(device, ssh_target(a["host"], res.get("ip"))),
-                    "-o", "StrictHostKeyChecking=yes", device["alias"], "true"]
+                    "-o", "StrictHostKeyChecking=yes",
+                    *self.host_opts(device, ssh_target(a["host"], res.get("ip"))), device["alias"], "true"]
             try:
-                r = subprocess.run(argv, capture_output=True, stdin=subprocess.DEVNULL, text=True,
-                                   errors="replace", timeout=20)
+                r = frame_host.run_ssh(argv, capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                                       errors="replace", timeout=20)
                 err = r.stderr.strip()
                 if r.returncode == 0:
                     rows[i].update(ssh="ok", detail=f"{lead} · SSH works")
@@ -1009,6 +1362,156 @@ class Link:
         put(done=True, finished=now())
         self.devices_changed()
 
+    # ---- Trust a new key ----
+    # Every way a key check could do more than read the key: no login of any kind, no agent
+    # (nor forwarding it), no X11, port or tunnel forwarding, no local or remote command, no
+    # terminal, no shared connection, no learning keys. Given first, so ssh takes these over
+    # anything ~/.ssh/config (or host_opts) says. -N: no command, even if a device accepts "none".
+    SCAN_OPTS = ["BatchMode=yes", "ControlMaster=no", "ControlPath=none", "ConnectTimeout=8",
+                 "StrictHostKeyChecking=accept-new", "UpdateHostKeys=no", "HashKnownHosts=no",
+                 "PreferredAuthentications=none", "PubkeyAuthentication=no", "PasswordAuthentication=no",
+                 "KbdInteractiveAuthentication=no", "HostbasedAuthentication=no", "IdentityAgent=none",
+                 "ForwardAgent=no", "ForwardX11=no", "ForwardX11Trusted=no", "ClearAllForwardings=yes",
+                 "Tunnel=no", "PermitLocalCommand=no", "RemoteCommand=none", "RequestTTY=no"]
+    SCAN_TIMEOUT = 20
+
+    def scan_identity(self, device_id):
+        """Read the headset's host key without trusting it or logging in. ssh writes it to a
+        throwaway known_hosts file during the key exchange, before any authentication, and is
+        stopped as soon as it has (or when it gives up); SCAN_OPTS and -N rule out anything else.
+        `-F none` too, unless ~/.ssh/config sends the alias through a jump host (then it's
+        needed for that, and SCAN_OPTS still win). The address that showed the changed key goes
+        first, then the rest in order. -> {"type", "fingerprint", "host", "saved", "recorded",
+        "matches", "recorded_match"}; the key is kept (SCAN_TTL) for trust_identity, which pins
+        exactly it."""
+        device = self.reg.get(device_id)
+        if not device["addresses"]:
+            raise frame_devices.DeviceError("This headset has no addresses to ask")
+        hosts = [a["host"] for a in device["addresses"]]
+        with self.cond:
+            err = self.state.get("error") or {}
+            mine = (self.state.get("device") or {}).get("id") == device_id
+        first = (err.get("hostkey") or {}).get("host") if mine else None
+        if first in hosts:
+            hosts.remove(first)
+            hosts.insert(0, first)
+        route = self.scan_route(device)
+        reasons = []
+        for host in hosts:
+            key, err_text = self._scan_one(device, host, route)
+            if key:
+                saved = frame_devices.pinned_keys(device_id)
+                recorded = [f for f in device.get("identity") or [] if isinstance(f, str)]
+                scan = {"type": key[0], "blob": key[1], "fingerprint": key[2], "host": host,
+                        "port": device["port"], "user": device["user"], "at": now()}
+                with self.cond:
+                    self.scans[device_id] = scan
+                return {"type": key[0], "fingerprint": key[2], "host": host,
+                        "saved": [{"type": t, "fingerprint": f} for t, f in saved], "recorded": recorded,
+                        "matches": any(f == key[2] for _, f in saved), "recorded_match": key[2] in recorded}
+            text = err_text.strip()
+            reasons.append(f"{host}: " + (self.explain(text) or (text.splitlines() or ["no answer"])[-1]))
+        raise frame_devices.DeviceError("Couldn't read the headset's key. " + "; ".join(reasons))
+
+    # The jump host's own ssh (a ProxyCommand the scan builds itself): it may log in to the jump
+    # host as configured (keys, the agent), but it never forwards the agent, X11 or ports, runs
+    # no local or remote command, has no terminal, shares no connection and goes no further.
+    HOP_OPTS = ["BatchMode=yes", "ForwardAgent=no", "ForwardX11=no", "ForwardX11Trusted=no",
+                "ClearAllForwardings=yes", "Tunnel=no", "PermitLocalCommand=no", "RemoteCommand=none",
+                "RequestTTY=no", "ControlMaster=no", "ControlPath=none", "ProxyCommand=none", "ProxyJump=none"]
+
+    def scan_route(self, device):
+        """The options that take a key check to the headset: `-F none` and nothing else when
+        it's reached directly. Through a jump host (ProxyJump), `-F none` and a ProxyCommand
+        built here, whose ssh gets HOP_OPTS ahead of ~/.ssh/config: config options can't be
+        overridden for ProxyJump's own ssh, which inherits ForwardAgent, LocalCommand and the
+        rest. Through a ProxyCommand from ~/.ssh/config, or several jump hosts, it refuses:
+        those can't be made safe from here."""
+        kind, spec = proxy_route(device["alias"])
+        if kind is None:
+            return ["-F", "none"]
+        m = JUMP_RE.fullmatch(spec or "") if kind == "jump" else None
+        if not m or (m.group(3) and not 1 <= int(m.group(3)) <= 65535):
+            how = "a ProxyCommand" if kind == "command" else "this jump host setting"
+            raise frame_devices.DeviceError(
+                f"{device['name']} is reached through {how} in ~/.ssh/config, which Frame Control can't make safe "
+                "for talking to a device it doesn't trust yet, so it won't read the key that way. Add an address "
+                "it can reach directly (or through a single ProxyJump host) and check its key again; or compare "
+                "the key by hand (on the headset, in Konsole: ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub)")
+        user, host, port = m.groups()
+        # The ssh this server runs, by its full path: the shell that runs a ProxyCommand may set
+        # up another PATH.
+        ssh = frame_host.which(self.mux_base[0])
+        if not ssh:
+            raise frame_devices.DeviceError(f"Couldn't find {self.mux_base[0]} to reach the jump host with")
+        hop = [ssh, *(a for o in self.HOP_OPTS for a in ("-o", o)), *(["-l", user] if user else []),
+               *(["-p", port] if port else []), host.strip("[]")]  # ssh takes a bare IPv6 address here
+        return ["-F", "none", "-o", "ProxyCommand=" + proxy_command(hop)]
+
+    def _scan_one(self, device, host, route):
+        """-> ((type, blob, fingerprint) or None, what ssh said)."""
+        name = frame_devices.host_key_alias(device["id"])
+        path, opt = frame_devices.scan_file(device["id"])
+        opts = [a for o in [*self.SCAN_OPTS, f"UserKnownHostsFile={opt}"] for a in ("-o", o)]
+        argv = [self.mux_base[0], *route, *opts, *self.host_opts(device, host), "-N", device["alias"]]
+        fd_, errfile = tempfile.mkstemp(prefix="frame-scan-")  # a file, not a pipe (see frame_host.run_ssh)
+        key, proc = None, None
+        try:
+            try:
+                proc = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=fd_,
+                                        **frame_host.DETACHED)
+            finally:
+                os.close(fd_)
+            deadline = time.monotonic() + self.SCAN_TIMEOUT
+            while key is None:
+                ended = proc.poll() is not None
+                key = _scanned_key(path, name)
+                if key or ended or self.stopped or time.monotonic() > deadline:
+                    break
+                time.sleep(0.05)
+        except OSError as e:
+            return None, str(e)
+        finally:
+            if proc and proc.poll() is None:
+                proc.kill()  # it has the key (or gave up): nothing more to do with that device
+            if proc:
+                try:
+                    proc.wait(5)
+                except subprocess.TimeoutExpired:
+                    pass
+            try:
+                with open(errfile, "rb") as fh:
+                    said = fh.read().decode("utf-8", "replace")
+            except OSError:
+                said = ""
+            _unlink(errfile)
+            _unlink(path)
+        if key is None and not said.strip() and proc and proc.returncode is not None and proc.returncode < 0:
+            said = f"Timed out talking to {device['alias']}"
+        return key, said
+
+    def trust_identity(self, device_id, fingerprint):
+        """Pin the key scan_identity read, and only if `fingerprint` is the one it showed (what
+        the person saw and confirmed), replacing whatever was saved; and only while the headset
+        is still reached as it was then (same port and user, the address still one of its own).
+        -> the scan."""
+        with self.cond:
+            scan = self.scans.get(device_id)
+            if not scan or now() - scan["at"] > SCAN_TTL:
+                self.scans.pop(device_id, None)
+                raise frame_devices.DeviceError("Check the headset's key again first: the one shown has expired")
+            if not isinstance(fingerprint, str) or fingerprint != scan["fingerprint"]:
+                raise frame_devices.DeviceError("That isn't the key the headset showed. Check its key again")
+            self.scans.pop(device_id)
+        d = self.reg.get(device_id)  # still a headset here
+        if (d["port"], d["user"]) != (scan["port"], scan["user"]) or \
+                scan["host"] not in [a["host"] for a in d["addresses"]]:
+            raise frame_devices.DeviceError("The headset's address, port or user changed since its key was read. "
+                                            "Check its key again")
+        frame_devices.pin_key(device_id, scan["type"], scan["blob"])
+        self.reg.record_identity(device_id, [scan["fingerprint"]])
+        return scan
+
 
 # ---- the page's API: /api/devices -------------------------------------------------
 
@@ -1027,6 +1530,9 @@ def devices_view(link):
         view = {k: v for k, v in d.items() if k not in ("config_host", "addresses")}
         view["active"] = d["id"] == active["id"]
         view["pinned"] = frame_devices.pinned(d["id"])
+        view["keys"] = [{"type": t, "fingerprint": f} for t, f in frame_devices.pinned_keys(d["id"])]
+        # It had an identity, but the saved key is gone or unusable: nothing is trusted until checked.
+        view["identity_lost"] = not view["pinned"] and frame_devices.identity_established(d)
         view["addresses"] = [dict(a, network_names=[names.get(n, "an unnamed network") for n in a["networks"]])
                              for a in d["addresses"]]
         devices.append(view)
@@ -1059,7 +1565,7 @@ def devices_action(link, body, open_setup, busy=lambda: 0):
     is_active = did == active["id"]
     moves = action == "use" or (action == "retry" and link.alive()) or (is_active and (
         # (a retry while connected would cut the install's connection)
-        action in ("remove", "address-remove", "forget-identity")
+        action in ("remove", "address-remove", "identity-trust")
         or (action == "update" and login_change(reg, did, body))
         or (action == "address-update" and body.get("newHost") not in (None, body.get("host")))))
     if moves and busy():
@@ -1139,11 +1645,25 @@ def devices_action(link, body, open_setup, busy=lambda: 0):
         threading.Thread(target=link.test, args=(did,), daemon=True).start()
         msg = f"Testing {len(d['addresses'])} address{'es' * (len(d['addresses']) != 1)}"
     elif action == "forget-identity":
+        # Dropping the pin used to let the next contact save whatever key answered, unseen.
+        # A new key is now always shown first: identity-scan, then identity-trust.
+        reg.get(did)
+        raise frame_devices.DeviceError("Forgetting a headset's identity is no longer supported: use Check its key "
+                                        "on the Devices tab (identity-scan, then identity-trust), which shows the "
+                                        "new key before saving it")
+    elif action == "identity-scan":
         d = reg.get(did)
-        frame_devices.forget_pin(did)
+        scan = link.scan_identity(did)
+        msg = (f"{d['name']} shows the key already saved for it" if scan["matches"]
+               else f"{d['name']} shows a {scan['type']} key, {scan['fingerprint']}")
+        link.devices_changed()
+        return dict(devices_view(link), message=msg, scan=scan)
+    elif action == "identity-trust":
+        d = reg.get(did)
+        link.trust_identity(did, body.get("fingerprint"))
         if is_active:
-            link.kick("switch")
-        msg = f"Forgot {d['name']}'s SSH identity; the next connection saves the one it shows"
+            link.kick("switch")  # reconnect with the key now saved
+        msg = f"Saved {d['name']}'s new SSH identity; reconnecting"
     elif action == "name-network":
         reg.name_network(body.get("network"), body.get("name"))
         if link.state["network"]:

ui/frame_report.py

@@ -13,12 +13,18 @@ frame_contact.py's `contact_consent` events; `contacts` lists them.
 """
 import os
 import platform
+import re
+import shutil
+import subprocess
 import sys
+import threading
 import time
 import uuid
 
 import frame_contact
+import frame_devices
 import frame_host
+import frame_link
 import frame_telemetry
 
 KINDS = ('bug', 'idea', 'question', 'other')
@@ -28,6 +34,7 @@ LOG_LINES = 60
 ACTIVITY_LINES = 25
 
 frame = {}  # the Frame's last known SteamOS build, set by server.status()
+link = None  # the connector (frame_link.Link), set by server.main; None on the Frame itself
 
 
 def u16(s):
@@ -59,9 +66,174 @@ def _log_tail():
     return list(reversed(keep[-LOG_LINES:]))
 
 
+def ssh_path_kind(path):
+    """What sort of ssh a path is, never the path itself (it can hold a user name)."""
+    if not path:
+        return "not found"
+    p = str(path).replace("\\", "/").lower()
+    for marks, kind in ((("/system32/openssh/", "/sysnative/openssh/"), "Windows OpenSSH (System32)"),
+                        (("/program files/openssh",), "OpenSSH in Program Files"),
+                        (("/git/",), "Git for Windows"), (("msys", "cygwin"), "MSYS2/Cygwin"),
+                        (("/opt/homebrew/", "/usr/local/", "linuxbrew"), "Homebrew or /usr/local"),
+                        (("/nix/",), "Nix")):
+        if any(m in p for m in marks):
+            return kind
+    if p in ("/usr/bin/ssh", "/bin/ssh"):
+        return "system OpenSSH"
+    return "other"
+
+
+def _ssh_on_path():
+    """Every ssh on PATH, in the order they're found; the first is the one the app runs."""
+    names = ("ssh.exe", "ssh") if frame_host.WINDOWS else ("ssh",)
+    found, seen = [], set()
+    for d in os.get_exec_path():
+        for name in names:
+            cand = os.path.join(d, name)
+            key = os.path.normcase(os.path.abspath(cand))
+            if key not in seen and os.path.isfile(cand):
+                seen.add(key)
+                found.append(cand)
+                break
+    return found
+
+
+# Only a real banner at the very start ("OpenSSH_9.9p1, LibreSSL 3.3.6",
+# "OpenSSH_for_Windows_9.5p1, LibreSSL 3.8.2"): rebuilt from fixed names and its numbers.
+BANNER_RE = re.compile(r"OpenSSH_(for_Windows_)?(\d+)\.(\d+)(p\d+)?(?=[,\s]|$)")
+LIBRARY_RE = re.compile(r",?\s*(LibreSSL|OpenSSL) (\d+\.\d+\.\d+[a-z]?)(?=[,\s]|$)")
+
+
+def parse_ssh_version(said):
+    """"OpenSSH 9.9p1, LibreSSL 3.3.6"-style text from `ssh -V`'s output, or "unknown"."""
+    said = (said or "").lstrip()
+    m = BANNER_RE.match(said)
+    if not m:
+        return "unknown"
+    out = f"OpenSSH{' for Windows' if m.group(1) else ''} {m.group(2)}.{m.group(3)}{m.group(4) or ''}"
+    lib = LIBRARY_RE.match(said, m.end())
+    return out + (f", {lib.group(1)} {lib.group(2)}" if lib else "")
+
+
+def ssh_version(path):
+    """The version from `ssh -V` (it prints to stderr), nothing else it says."""
+    try:
+        r = frame_host.run_ssh([path, "-V"], capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                               errors="replace", timeout=5)
+    except (OSError, subprocess.SubprocessError) as e:
+        return f"couldn't run it ({type(e).__name__})"
+    return parse_ssh_version(r.stderr or r.stdout)
+
+
+def _ssh_check():
+    path = shutil.which("ssh")
+    if not path:
+        return "SSH: no ssh on PATH"
+    others = [ssh_path_kind(p) for p in _ssh_on_path()
+              if os.path.normcase(os.path.abspath(p)) != os.path.normcase(os.path.abspath(path))]
+    others = [k for i, k in enumerate(others) if k not in others[:i]]
+    return f"SSH: {ssh_path_kind(path)}, {ssh_version(path)}" + (f"; also on PATH: {', '.join(others)}" if others else "")
+
+
+_ssh = {"thread": None, "line": None}
+_ssh_lock = threading.Lock()
+SSH_WAIT = 0.3  # how long a report preview waits for the ssh check (PATH can hold slow network drives)
+
+
+def start_ssh_check():
+    """Look for ssh once, in the background (server.main starts it), so a report never waits
+    on PATH folders on slow or mapped drives."""
+    def run():
+        try:
+            line = _ssh_check()
+        except Exception as e:  # a report must still go out
+            line = f"SSH: couldn't check ({type(e).__name__})"
+        _ssh["line"] = line
+    with _ssh_lock:
+        if _ssh["thread"] is None:
+            _ssh["thread"] = threading.Thread(target=run, name="report-ssh-check", daemon=True)
+            _ssh["thread"].start()
+        return _ssh["thread"]
+
+
+def ssh_line():
+    start_ssh_check().join(SSH_WAIT)
+    return _ssh["line"] or "SSH: still being checked"
+
+
+def config_line(alias):
+    """Whether ~/.ssh/config has the managed block for the alias, and a hand-written Host for it."""
+    try:
+        text = frame_devices.ssh_config().read_text(encoding="utf-8", errors="replace")
+    except FileNotFoundError:
+        return "~/.ssh/config: missing"
+    except OSError as e:
+        return f"~/.ssh/config: can't read it ({type(e).__name__})"
+    blocks = [b["alias"] for b in frame_devices.parse_blocks(text)]
+    outside, inside = [], None
+    for line in text.splitlines():
+        m = frame_devices.BLOCK_RE.fullmatch(line.strip())
+        if m:
+            inside = m.group(1)
+        elif inside and line.strip() == frame_devices.end_mark(inside):
+            inside = None
+        elif not inside:
+            outside.append(line)
+    own = any(alias in re.split(r"[\s=]+", ln.strip())[1:] for ln in outside
+              if re.match(r"(?i)\s*host[\s=]", ln))
+    return (f"~/.ssh/config: managed block for the active alias {'yes' if alias in blocks else 'no'} "
+            f"({len(blocks)} managed in all); hand-written Host for it {'yes' if own else 'no'}")
+
+
+def alias_kind(alias):
+    """`default ("frame")` or `custom`: a name someone chose can say who they are."""
+    return 'default ("frame")' if alias == "frame" else "custom"
+
+
+def connection_lines():
+    """A short summary of the connector in fixed words only: states, stages, error categories,
+    kinds of address, counts. No text from errors or ssh, no custom alias, never an address."""
+    if link is None:
+        return ["Connection: no connector (this server doesn't reach a headset over SSH)"]
+    snap = link.snapshot()
+    active = link.active_device()
+    alias = active.get("alias") or "?"
+    phase, err, via = snap.get("phase") or "idle", snap.get("error"), snap.get("via")
+    head = f"Connection: {phase}"
+    if phase == "connected" and via:
+        rtt = via.get("rtt_ms")
+        head += f" via {frame_link.address_kind(via.get('host'), via.get('ip'))}" + (f" ({rtt:g} ms)" if rtt is not None else "")
+    elif err:
+        head += f" at {err.get('stage')}"
+    head += f", attempt {snap.get('attempt') or 0}" + (f" ({snap['reason']})" if snap.get("reason") else "")
+    lines = [head]
+    kind = ("none set up" if active.get("none") else "a bare ssh alias" if active.get("transient")
+            else f"saved, {len(active.get('addresses') or [])} address(es)")
+    lines.append(f"Headsets: {len(link.reg.devices())} saved; active alias {alias_kind(alias)} ({kind})")
+    if err:
+        lines.append(f"Error: {err.get('stage')}, {frame_link.failure_category(err.get('message'), err.get('raw'))}")
+    last = link.last_failure
+    if last:
+        ago = max(0, int(frame_link.now() - last.get("at", 0)))
+        lines.append(f"Last failure: {last.get('stage')}, {last.get('category')}, {ago // 60} min {ago % 60} s ago")
+    lines.append(f"Addresses tried: {frame_link.probes_summary(snap.get('probes')) or 'none yet'}")
+    net = snap.get("network")
+    if net:
+        ts = net.get("tailscale") or {}
+        lines.append(f"Network: gateway {'yes' if net.get('gateway') else 'no'}, Tailscale "
+                     f"{'on' if ts.get('up') else 'off' if ts.get('installed') else 'not installed'}")
+    for part in (ssh_line, lambda: config_line(alias)):
+        try:
+            lines.append(part())
+        except Exception as e:  # a report must still go out
+            lines.append(f"({type(e).__name__} while checking SSH)")
+    return lines
+
+
 def diagnostics(activity=(), include_logs=False, limit=DIAG_MAX):
     """What a report includes, scrubbed and at most `limit` UTF-16 units. Always the versions
-    and builds; recent activity and the server log only when asked for, since they can name
+    and builds, and a connection summary (connection_lines: kinds of address and states, never
+    the addresses, so "the app can't find the headset" can be told apart); recent activity and the server log only when asked for, since they can name
     files. Sections are filled in order of use, newest lines first, so trimming drops the oldest."""
     t = frame_telemetry.state()
     levels = ', '.join(f"{name} {'on' if on else 'off'}" for name, on in
@@ -74,7 +246,11 @@ def diagnostics(activity=(), include_logs=False, limit=DIAG_MAX):
         f"Analytics: {levels}",
         f"Report time: {time.strftime('%Y-%m-%d %H:%M %Z')}",
     ]
-    out = frame_telemetry.scrub('\n'.join(env), limit=limit)
+    try:
+        conn = connection_lines()
+    except Exception as e:  # never stop a report over its diagnostics
+        conn = [f"Connection: summary unavailable ({type(e).__name__})"]
+    out = frame_telemetry.scrub('\n'.join(env) + '\n\n' + '\n'.join(conn), limit=limit)
     if not include_logs:
         return cut(out, limit)
     sections = [('Recent activity (newest first):', [str(a)[:300] for a in list(activity)[:ACTIVITY_LINES] if isinstance(a, str)]),
@@ -112,18 +288,22 @@ def send(body):
     """Send the report to PostHog. Returns {"id", "message"}; raises ReportError."""
     kind = body.get('kind') if body.get('kind') in KINDS else 'bug'
     title, text, diag = compose(body)
-    followup = bool(body.get('contactFollowup'))
+    followup = frame_contact.flag(body, 'contactFollowup')
     contact = str(body.get('contact') or '').strip() if followup else ''
     if followup and not frame_contact.valid_email(contact):
         raise ValueError('add your email address for follow-up questions, or untick that box')
+    started = time.time()  # a removal from now on (even while saving the address) is redacted from the log
+    # It becomes the contact email in Settings, where it's changed or removed like any other.
+    contact_id, contact_rev = frame_contact.from_report(contact) if followup else ('', 0)
     ref = uuid.uuid4().hex[:8].upper()
     props = {**frame_telemetry.common(), 'kind': kind, 'title': title, 'message': text,
              'contact': contact, 'contact_followup': followup, 'diagnostics': diag,
+             # Only with an address: a later change from this copy (higher rev) can take it back.
+             'contact_id': contact_id, 'contact_rev': contact_rev,
              'report_id': ref, 'steamos': str(frame.get('build') or '')[:120], 'level': 'report'}
     # Its own random id: a report can carry contact details, so it isn't linked to this copy's analytics.
     event = {'event': 'problem_report', 'distinct_id': str(uuid.uuid4()), 'uuid': str(uuid.uuid4()),
              'timestamp': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()), 'properties': props}
-    started = time.time()
     try:
         frame_telemetry.post([event], timeout=30)
     except frame_telemetry.SendError as e:
@@ -143,15 +323,50 @@ class ReportError(RuntimeError):
 
 def inbox(days=30):
     """The maintainer's recent reports from PostHog, newest first (needs the personal API key
-    frame_compat_db.sync uses)."""
+    frame_compat_db.sync uses). Column 10 is whether the person may be asked follow-up
+    questions now: 'withdrawn' when a later choice from the same copy took it back."""
     import frame_compat_db
+    days = int(days)
     res = frame_compat_db._posthog_query(
         "SELECT timestamp, properties.report_id, properties.kind, properties.title, properties.message, "
         "properties.contact, properties.app_version, properties.os, properties.steamos, properties.diagnostics, "
-        "properties.contact_followup "
-        f"FROM events WHERE event = 'problem_report' AND timestamp > now() - INTERVAL {int(days)} DAY "
+        "properties.contact_followup, properties.contact_id, properties.contact_rev "
+        f"FROM events WHERE event = 'problem_report' AND timestamp > now() - INTERVAL {days} DAY "
         "ORDER BY timestamp DESC LIMIT 200")
-    return res.get('results') or []
+    rows = [r for r in res.get('results') or [] if isinstance(r, list) and len(r) == 13]
+    if any(r[11] and _yes(r[10]) for r in rows):
+        later = frame_compat_db._posthog_query(
+            "SELECT distinct_id, properties.email, properties.followup, ifNull(toInt(properties.rev), 0) "
+            "FROM events WHERE event = 'contact_consent' LIMIT 100000")
+        mark_withdrawn(rows, later.get('results') or [])
+    return rows
+
+
+def mark_withdrawn(reports, consents):
+    """Mark reports whose follow-up permission was taken back: the newest contact choice from
+    the same copy made after the report (a higher rev than it carries, not a later clock) no
+    longer agrees to follow-up questions at that address."""
+    newest = {}
+    for c in consents:
+        if not isinstance(c, list) or len(c) != 4:
+            continue
+        cid, email, followup, rev = c
+        try:
+            rev = int(rev or 0)
+        except (TypeError, ValueError):
+            continue
+        if rev > newest.get(str(cid), (-1,))[0]:
+            newest[str(cid)] = (rev, str(email or ''), followup)
+    for r in reports:
+        if not (r[11] and _yes(r[10])):
+            continue
+        try:
+            sent_at = int(r[12] or 0)
+        except (TypeError, ValueError):
+            sent_at = 0
+        rev, email, followup = newest.get(str(r[11]), (-1, '', None))
+        if rev > sent_at and not (_yes(followup) and email.strip().lower() == str(r[5] or '').strip().lower()):
+            r[10] = 'withdrawn'
 
 
 def _yes(v):
@@ -204,14 +419,13 @@ def main():
     if cmd != 'inbox':
         sys.exit(USAGE)
     for row in inbox(*(args[:1] or [30])):
-        if not isinstance(row, list) or len(row) != 11:
-            continue
         ts, ref, kind, title, text, contact, version, osname, steamos, diag = (str(v or '') for v in row[:10])
         # Reports from before contact_followup existed only carried an address given for a reply.
         reply = contact and (row[10] is None or _yes(row[10]))
         print(f"== {ts[:16].replace('T', ' ')}  {ref}  [{kind}] {title}")
         print(f"   {version} on {osname}, SteamOS {steamos or 'unknown'}"
-              f"{', may follow up at ' + contact if reply else ''}")
+              f"{', may follow up at ' + contact if reply else ''}"
+              f"{', follow-up permission since withdrawn' if row[10] == 'withdrawn' else ''}")
         print('   ' + text.replace('\n', '\n   '))
         if diag:
             print('   --- diagnostics\n   ' + diag.replace('\n', '\n   '))

ui/frame_status.py

@@ -6,6 +6,7 @@ error. Sensor paths verified on SteamOS 0.3.0; OpenVR timing on 0.4.1
 """
 import ctypes as C
 import glob
+import hashlib
 import math
 import json
 import os
@@ -121,7 +122,16 @@ def os_release():
         k, _, v = line.partition("=")
         out[k] = v.strip('"')
     return {"version": out.get("VERSION_ID"), "build": out.get("BUILD_ID"),
-            "variant": out.get("VARIANT_ID")}
+            "variant": out.get("VARIANT_ID"), "headset": headset_id()}
+
+
+def headset_id():
+    """A one-way hash of the headset's /etc/machine-id: the same for this headset on every
+    computer, and the machine-id itself never leaves the headset. None without one."""
+    mid = read("/etc/machine-id")
+    if not mid:
+        return None
+    return hashlib.sha256(("frame-control-headset:" + mid).encode()).hexdigest()[:16]
 
 
 def volume():
@@ -292,6 +302,7 @@ def status():
         "disk": {"root": disk("/"), "home": disk("/home")},
         "memory": memory(),
         "temp": max_temp(),
+        "thermalAlerts": thermal_alerts(),
         "wifi": wifi(),
         "ip": ip_addr(),
         "volume": volume(),

ui/frame_telemetry.py

@@ -18,7 +18,9 @@ Report a problem dialog (frame_report.py) sends bug reports privately to the
 same project whatever is chosen here.
 
 Events are identified by a random id made on first run, not by the person or
-computer, and sent without person profiles or GeoIP. Nothing is sent without a
+computer, and sent without person profiles or GeoIP. Opens, installs and updates
+carry a country instead, worked out on this computer from its time zone setting
+(frame_timezones.py), to see roughly where Frame Control is used. Nothing is sent without a
 project key (ui/telemetry.json or $FRAME_CONTROL_POSTHOG_KEY), from a source
 checkout unless $FRAME_CONTROL_TELEMETRY=1, or when $DO_NOT_TRACK=1 or
 $FRAME_CONTROL_TELEMETRY=0.
@@ -43,6 +45,7 @@ from pathlib import Path
 from urllib.parse import urlsplit
 
 import frame_host
+import frame_timezones
 
 HERE = Path(__file__).resolve().parent
 STATE = frame_host.data_dir('telemetry')
@@ -50,16 +53,26 @@ SETTINGS = STATE / 'settings.json'
 OUTBOX = STATE / 'outbox.jsonl'
 SENT = STATE / 'sent.jsonl'
 SENT_KEEP = 200
+FRAMES_SEEN_KEEP = 100  # build/headset pairs already reported, enough for several headsets' updates
 OUTBOX_MAX = 2000  # events kept while offline; the oldest go first
 FLUSH_EVERY = 60
 REPEAT_WINDOW = 600  # the same diagnostic error is sent at most once in this many seconds
+# Not faults in Frame Control: the headset asleep, away or not set up yet, or ssh and the headset
+# not trusting each other (a host key that changed, a key not authorised): the page says what to do
+# about each (Devices tab, Set Up Connection). The status poll
+# meets these every few seconds, so each is sent at most once per session, whatever the wording,
+# but only for an error marked where ssh ran as ssh failing to reach the headset
+# (frame_host.link_failure). The message alone isn't evidence: a download's "Connection reset by
+# peer", or a file name with ssh's words in it, keeps the usual window.
+EXPECTED_CATEGORIES = ('frame_unreachable', 'frame_not_set_up', 'frame_auth')
 DEFAULT_HOST = 'https://us.i.posthog.com'
 
 LEVELS = ('usage', 'compat', 'diagnostics')
+NOTICE_VERSION = 2  # raise when the notice lists something new: it's shown again (2: country)
 # Events the page may send through /api/telemetry, and the properties each may carry.
 PAGE_EVENTS = {'tab_viewed': {'tab'}, 'update_offered': {'to_version'},
                'update_started': {'to_version'}, 'update_failed': {'to_version', 'error_category'}}
-TABS = {'home', 'games', 'android', 'tools'}
+TABS = {'home', 'games', 'android', 'tools', 'devices', 'control'}
 
 _lock = threading.RLock()
 _send_lock = threading.Lock()  # held while sending; consent changes wait for it
@@ -96,7 +109,7 @@ def blocked():
 
 def _defaults():
     return {'id': str(uuid.uuid4()), 'usage': True, 'compat': False, 'diagnostics': False,
-            'notice_shown': False, 'installed_sent': False, 'last_version': None, 'last_open_day': None,
+            'notice_shown': False, 'notice_version': 0, 'installed_sent': False, 'last_version': None, 'last_open_day': None,
             'frames_seen': [], 'compat_sent': []}
 
 
@@ -138,12 +151,12 @@ def update_settings(changes):
     under way finishes first, so nothing leaves after this returns."""
     with _send_lock, _lock:
         s = settings()
-        if 'noticeShown' in changes:
-            s['notice_shown'] = bool(changes['noticeShown']) or s['notice_shown']
+        if changes.get('noticeShown'):
+            s['notice_shown'], s['notice_version'] = True, NOTICE_VERSION
         for level in LEVELS:
             if level in changes:
                 s[level] = bool(changes[level])
-                s['notice_shown'] = True
+                s['notice_shown'] = True  # only the notice itself moves notice_version on
         _save(s)
         _drop_unwanted(s)
     if changes.get('compat'):
@@ -152,10 +165,16 @@ def update_settings(changes):
     return state()
 
 
+def _notice_current(s):
+    """Whether the notice this person saw lists everything that's sent now. If not, the page
+    shows it again, and what it added waits until it has been seen."""
+    return s['notice_shown'] and s['notice_version'] >= NOTICE_VERSION
+
+
 def state():
     """What the page shows: the choices, why sending is blocked, and what was sent."""
     s = settings()
-    return {'usage': s['usage'], 'compat': s['compat'], 'noticeShown': s['notice_shown'],
+    return {'usage': s['usage'], 'compat': s['compat'], 'noticeShown': _notice_current(s),
             'diagnostics': s['diagnostics'],
             'blocked': blocked(), 'id': s['id'], 'queued': len(_read_lines(OUTBOX)),
             'sent': list(reversed(_read_lines(SENT)))[:50]}
@@ -229,9 +248,16 @@ def scrub(text, limit=2000):
     home = str(Path.home())
     if len(home) > 3:
         t = t.replace(home, '~')
-    t = re.sub(r'(/Users/|/home/|[A-Za-z]:\\Users\\)[^/\\\s]+', r'\1<user>', t)
+    # A home folder's whole name ("C:\Users\Jane Doe", "/Users/O'Brien"), up to the next separator.
+    t = re.sub(r'''(?i)(/Users/|/home/|[A-Za-z]:[\\/]+Users[\\/]+)[^\\/\n"]+''', r'\1<user>', t)
+    # ssh's "user@host: ..." and "user@host's password:", the whole field: the user even with
+    # spaces or a DOMAIN\ prefix, the host even a full domain name. Before the email rule, which
+    # would otherwise take only the last word of the user.
+    t = re.sub(r'''(?m)(?:^|(?<=: )|(?<=\| ))[^@\n:|"<]{1,64}@[\w.\[\]%:<>-]+?(?=:(?:\s|$)|'s\s)''',
+               '<user>@<host>', t)
     for pattern, repl in SCRUBS:
         t = pattern.sub(repl, t)
+    t = re.sub(r'(?<![\w.+\\<-])[\w.+\\-]+@(?=[A-Za-z\[<])', '<user>@', t)  # any other word@host
     t = IPV6_RE.sub(_ipv6, t)
     for name in _user_names():
         t = re.sub(r'\b%s\b' % re.escape(name), '<user>', t)
@@ -240,17 +266,47 @@ def scrub(text, limit=2000):
 
 # From the most to the least specific; the first match wins.
 CATEGORIES = [
+    # A web-link download (frame_webinstall) that broke or didn't check out: not the headset,
+    # whatever the reason, and first so a file name in the message can't put it elsewhere.
+    ('download_failed', re.compile(r"\A(?:download failed: |download cut off at |downloaded \d+ bytes; |"
+                                   r"the server says \d+ bytes; )|doesn't match the manifest's sha256; "
+                                   r"not installing it\Z")),
     ('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')),
-    ('apk_unreadable', re.compile(r'(?i)not a zip|bad apk|AndroidManifest|ApkError|unexpected package name')),
+    ('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|'
+                                  r'not a readable APK|not an APK|APK manifest|in the APK (?:uses a compression|is )')),
     ('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')),
+    # The Frame-side scripts that talk to the Steam client's UI (frame/android/steam_shortcuts.py), which
+    # fail with their own words or a Python traceback, its last lines kept. Before frame_unreachable:
+    # "Connection refused" and "timed out" here are Steam's debug port on the Frame, not ssh.
+    ('steam_not_running', re.compile(r'SharedJSContext not found|'
+                                     r'URLError: <urlopen error \[Errno 111\] Connection refused>|'
+                                     r'ConnectionRefusedError: \[Errno 111\]')),
+    ('steam_not_responding', re.compile(r'websocket handshake failed|(?:socket\.timeout|TimeoutError): timed out|'
+                                        r'(?:\A|\n)EOFError\Z')),
+    ('steam_js_error', re.compile(r'JS error: ')),
+    ('artwork_failed', re.compile(r'incomplete artwork render|artwork renderer did not produce|'
+                                  r'render is \d+ bytes of|could not prepare artwork|all five Steam artwork slots')),
+    # Copying the APK (or its launcher) to the Frame: rsync or scp ran out of time.
+    ('copy_timeout', re.compile(r'to the Frame timed out\Z')),
     ('frame_not_set_up', re.compile(r'(?i)Could not resolve hostname|no "?frame"? (?:SSH )?alias')),
-    ('frame_auth', re.compile(r'(?i)Permission denied|Host key verification failed')),
+    ('frame_auth', re.compile(r'(?i)Permission denied|Host key verification failed|'
+                              r'REMOTE HOST IDENTIFICATION HAS CHANGED|host key is known for')),
+    # Anything ssh says about its own connection: "ssh: connect to host … port 22: <reason>" (Windows
+    # says "Unknown error"), a dropped shared connection (mux_client_…, client_loop), and Windows'
+    # "banner exchange: Connection to UNKNOWN port -1" (its ssh can't name a peer whose connect
+    # failed late). Not a bare "ssh exited 255": a command on the Frame can exit 255 too.
     ('frame_unreachable', re.compile(r'(?i)timed out|Connection (?:refused|reset|closed)|No route to host|'
-                                     r'Network is unreachable|Operation timed out|asleep|kex_exchange')),
+                                     r'Network is unreachable|Host is down|asleep|kex_exchange|banner exchange|'
+                                     r'ssh: connect to host |mux_client_|client_loop: ')),
     ('frame_disk_full', re.compile(r'(?i)No space left|disk full|ENOSPC')),
+    # rsync or scp failed for another reason ("connection unexpectedly closed", or no words at all).
+    ('copy_failed', re.compile(r'\Acopying .+ to the Frame failed: ')),
     ('download_failed', re.compile(r'(?i)HTTP (?:Error )?\d{3}|URLError|download|certificate verify failed')),
     ('flatpak', re.compile(r'(?i)flatpak|flathub')),
     ('cancelled', re.compile(r'(?i)cancel')),
@@ -258,8 +314,16 @@ CATEGORIES = [
 ]
 
 
+# Python's own errors for a mistake in Frame Control's code, whatever their message says.
+BUG_ERRORS = (KeyError, IndexError, TypeError, AttributeError, NameError, AssertionError,
+              ZeroDivisionError, RecursionError, UnicodeError, json.JSONDecodeError)
+
+
 def categorize(message):
-    """(category, detail): a fixed category name, plus an Android installer code when there is one."""
+    """(category, detail): a fixed category name, plus an Android installer code when there is one.
+    message may be the exception itself: one of BUG_ERRORS is internal_error."""
+    if isinstance(message, BUG_ERRORS):
+        return 'internal_error', None
     text = str(message or '')
     for name, pattern in CATEGORIES:
         m = pattern.search(text)
@@ -318,39 +382,64 @@ def page_event(body):
     return {'queued': capture(name, props)}
 
 
+def country():
+    """The two-letter country of the computer's time zone setting, or None. Only names in the
+    tz database's table count, so nothing else in the setting can be sent. The app passes the
+    zone from Electron, which knows it on every OS; from a checkout it's read from /etc/localtime."""
+    tz = os.environ.get('FRAME_CONTROL_TIMEZONE') or os.environ.get('TZ', '').lstrip(':')
+    if not tz:
+        try:
+            tz = os.path.realpath('/etc/localtime').split('/zoneinfo/', 1)[1]
+        except (OSError, IndexError):
+            return None
+    return frame_timezones.COUNTRY.get(tz)
+
+
 def app_started():
-    """Once per server start: first install, an update, and one open a day."""
+    """Once per server start: first install, an update, and one open a day, with the country
+    (left out when sending if the notice this person saw came before it: flush)."""
     if blocked():
         return
     with _lock:
         s = settings()
         version, today = app_version(), time.strftime('%Y-%m-%d')
+        cc = country()
+        where = {'country': cc} if cc else {}
         if not s['installed_sent']:
-            capture('app_installed')
+            capture('app_installed', where)
             s['installed_sent'] = True
         elif s['last_version'] and s['last_version'] != version:
-            capture('app_updated', {'from_version': s['last_version']})
+            capture('app_updated', {'from_version': s['last_version'], **where})
         if s['last_open_day'] != today:
-            capture('app_opened')
+            capture('app_opened', where)
             s['last_open_day'] = today
         s['last_version'] = version
         _save(s)
 
 
-def frame_seen(build, version):
-    """The Frame's SteamOS build, once per build (public build numbers)."""
-    key = f'{build}/{version}'
+def frame_seen(build, version, headset=None, saved=None):
+    """The Frame's SteamOS build (public build numbers), once per build for each headset.
+    headset: the anonymous hash from frame_status.headset_id; saved: how many headsets
+    this copy of the app has set up."""
+    headset = headset if isinstance(headset, str) and re.fullmatch(r'[0-9a-f]{16}', headset) else None
+    key = f'{build}/{version}' + (f'/{headset}' if headset else '')
     with _lock:
         s = settings()
         if not build or key in s['frames_seen']:
             return
-        s['frames_seen'] = (s['frames_seen'] + [key])[-20:]
+        s['frames_seen'] = (s['frames_seen'] + [key])[-FRAMES_SEEN_KEEP:]
         _save(s)
-    capture('frame_connected', {'steamos_build': str(build)[:40], 'steamos_version': str(version or '')[:40]})
+    p = {'steamos_build': str(build)[:40], 'steamos_version': str(version or '')[:40]}
+    if headset:
+        p['headset_id'] = headset
+    if isinstance(saved, int) and saved >= 0:
+        p['headsets_saved'] = saved
+    capture('frame_connected', p)
 
 
-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,21 +447,41 @@ 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)
 
 
+def link_failed(error):
+    """Whether an ssh helper marked this error (frame_host.link_failure) as ssh failing to reach the
+    headset: the error itself, or one it was re-raised from (`raise Failure(...) from e`)."""
+    for _ in range(10):  # a cause chain is short; never loop on a cycle
+        if error is None:
+            return False
+        if getattr(error, 'frame_link_failed', False):
+            return True
+        error = getattr(error, '__cause__', None)
+    return False
+
+
 def diagnostic(where, error, tb=None):
     """An error for the opt-in diagnostics level: scrubbed text, and a traceback if there is one."""
     if not enabled('diagnostics'):
         return
     message = scrub(error)
-    fingerprint = f'{where}|{message[:120]}'
+    category = categorize(error)[0]
     now = time.time()
     with _lock:
-        if now - _seen_errors.get(fingerprint, 0) < REPEAT_WINDOW:
-            return
+        if category in EXPECTED_CATEGORIES and link_failed(error):
+            fingerprint = f'expected|{category}'
+            if fingerprint in _seen_errors:
+                return
+        else:
+            fingerprint = f'{where}|{message[:120]}'
+            if now - _seen_errors.get(fingerprint, 0) < REPEAT_WINDOW:
+                return
         _seen_errors[fingerprint] = now
     exc_type = type(error).__name__ if isinstance(error, BaseException) else 'Error'
     frames = []
@@ -385,7 +494,7 @@ def diagnostic(where, error, tb=None):
                                                 'mechanism': {'handled': True, 'type': 'generic'},
                                                 'stacktrace': {'type': 'raw', 'frames': frames[-30:]}}],
                            '$exception_type': exc_type, '$exception_message': message,
-                           'where': scrub(where, 200), 'error_category': categorize(error)[0]},
+                           'where': scrub(where, 200), 'error_category': category},
             level='diagnostics')
 
 
@@ -497,10 +606,14 @@ def flush(timeout=20):
         if blocked() or not settings()['notice_shown']:
             return 0
         with _lock:
-            _drop_unwanted(settings())
+            s = settings()
+            _drop_unwanted(s)
             batch = _read_lines(OUTBOX)[:100]
         if not batch:
             return 0
+        if not _notice_current(s):  # what a newer notice added stays here until it's been seen
+            for e in batch:
+                e['properties'].pop('country', None)
         try:
             post(batch, timeout)
         except SendError:

ui/frame_timezones.py

@@ -0,0 +1,547 @@
+"""Time zone name -> two-letter country, from the IANA tz database 2026c (zone.tab, and
+the old names in tzdata.zi that link to its zones). Generated by scripts/timezones.py.
+Zones that aren't in one country, such as UTC, aren't here."""
+COUNTRY = {
+    'Africa/Abidjan': 'CI',
+    'Africa/Accra': 'GH',
+    'Africa/Addis_Ababa': 'ET',
+    'Africa/Algiers': 'DZ',
+    'Africa/Asmara': 'ER',
+    'Africa/Asmera': 'ER',
+    'Africa/Bamako': 'ML',
+    'Africa/Bangui': 'CF',
+    'Africa/Banjul': 'GM',
+    'Africa/Bissau': 'GW',
+    'Africa/Blantyre': 'MW',
+    'Africa/Brazzaville': 'CG',
+    'Africa/Bujumbura': 'BI',
+    'Africa/Cairo': 'EG',
+    'Africa/Casablanca': 'MA',
+    'Africa/Ceuta': 'ES',
+    'Africa/Conakry': 'GN',
+    'Africa/Dakar': 'SN',
+    'Africa/Dar_es_Salaam': 'TZ',
+    'Africa/Djibouti': 'DJ',
+    'Africa/Douala': 'CM',
+    'Africa/El_Aaiun': 'EH',
+    'Africa/Freetown': 'SL',
+    'Africa/Gaborone': 'BW',
+    'Africa/Harare': 'ZW',
+    'Africa/Johannesburg': 'ZA',
+    'Africa/Juba': 'SS',
+    'Africa/Kampala': 'UG',
+    'Africa/Khartoum': 'SD',
+    'Africa/Kigali': 'RW',
+    'Africa/Kinshasa': 'CD',
+    'Africa/Lagos': 'NG',
+    'Africa/Libreville': 'GA',
+    'Africa/Lome': 'TG',
+    'Africa/Luanda': 'AO',
+    'Africa/Lubumbashi': 'CD',
+    'Africa/Lusaka': 'ZM',
+    'Africa/Malabo': 'GQ',
+    'Africa/Maputo': 'MZ',
+    'Africa/Maseru': 'LS',
+    'Africa/Mbabane': 'SZ',
+    'Africa/Mogadishu': 'SO',
+    'Africa/Monrovia': 'LR',
+    'Africa/Nairobi': 'KE',
+    'Africa/Ndjamena': 'TD',
+    'Africa/Niamey': 'NE',
+    'Africa/Nouakchott': 'MR',
+    'Africa/Ouagadougou': 'BF',
+    'Africa/Porto-Novo': 'BJ',
+    'Africa/Sao_Tome': 'ST',
+    'Africa/Timbuktu': 'ML',
+    'Africa/Tripoli': 'LY',
+    'Africa/Tunis': 'TN',
+    'Africa/Windhoek': 'NA',
+    'America/Adak': 'US',
+    'America/Anchorage': 'US',
+    'America/Anguilla': 'AI',
+    'America/Antigua': 'AG',
+    'America/Araguaina': 'BR',
+    'America/Argentina/Buenos_Aires': 'AR',
+    'America/Argentina/Catamarca': 'AR',
+    'America/Argentina/ComodRivadavia': 'AR',
+    'America/Argentina/Cordoba': 'AR',
+    'America/Argentina/Jujuy': 'AR',
+    'America/Argentina/La_Rioja': 'AR',
+    'America/Argentina/Mendoza': 'AR',
+    'America/Argentina/Rio_Gallegos': 'AR',
+    'America/Argentina/Salta': 'AR',
+    'America/Argentina/San_Juan': 'AR',
+    'America/Argentina/San_Luis': 'AR',
+    'America/Argentina/Tucuman': 'AR',
+    'America/Argentina/Ushuaia': 'AR',
+    'America/Aruba': 'AW',
+    'America/Asuncion': 'PY',
+    'America/Atikokan': 'CA',
+    'America/Atka': 'US',
+    'America/Bahia': 'BR',
+    'America/Bahia_Banderas': 'MX',
+    'America/Barbados': 'BB',
+    'America/Belem': 'BR',
+    'America/Belize': 'BZ',
+    'America/Blanc-Sablon': 'CA',
+    'America/Boa_Vista': 'BR',
+    'America/Bogota': 'CO',
+    'America/Boise': 'US',
+    'America/Buenos_Aires': 'AR',
+    'America/Cambridge_Bay': 'CA',
+    'America/Campo_Grande': 'BR',
+    'America/Cancun': 'MX',
+    'America/Caracas': 'VE',
+    'America/Catamarca': 'AR',
+    'America/Cayenne': 'GF',
+    'America/Cayman': 'KY',
+    'America/Chicago': 'US',
+    'America/Chihuahua': 'MX',
+    'America/Ciudad_Juarez': 'MX',
+    'America/Coral_Harbour': 'CA',
+    'America/Cordoba': 'AR',
+    'America/Costa_Rica': 'CR',
+    'America/Coyhaique': 'CL',
+    'America/Creston': 'CA',
+    'America/Cuiaba': 'BR',
+    'America/Curacao': 'CW',
+    'America/Danmarkshavn': 'GL',
+    'America/Dawson': 'CA',
+    'America/Dawson_Creek': 'CA',
+    'America/Denver': 'US',
+    'America/Detroit': 'US',
+    'America/Dominica': 'DM',
+    'America/Edmonton': 'CA',
+    'America/Eirunepe': 'BR',
+    'America/El_Salvador': 'SV',
+    'America/Ensenada': 'MX',
+    'America/Fort_Nelson': 'CA',
+    'America/Fort_Wayne': 'US',
+    'America/Fortaleza': 'BR',
+    'America/Glace_Bay': 'CA',
+    'America/Godthab': 'GL',
+    'America/Goose_Bay': 'CA',
+    'America/Grand_Turk': 'TC',
+    'America/Grenada': 'GD',
+    'America/Guadeloupe': 'GP',
+    'America/Guatemala': 'GT',
+    'America/Guayaquil': 'EC',
+    'America/Guyana': 'GY',
+    'America/Halifax': 'CA',
+    'America/Havana': 'CU',
+    'America/Hermosillo': 'MX',
+    'America/Indiana/Indianapolis': 'US',
+    'America/Indiana/Knox': 'US',
+    'America/Indiana/Marengo': 'US',
+    'America/Indiana/Petersburg': 'US',
+    'America/Indiana/Tell_City': 'US',
+    'America/Indiana/Vevay': 'US',
+    'America/Indiana/Vincennes': 'US',
+    'America/Indiana/Winamac': 'US',
+    'America/Indianapolis': 'US',
+    'America/Inuvik': 'CA',
+    'America/Iqaluit': 'CA',
+    'America/Jamaica': 'JM',
+    'America/Jujuy': 'AR',
+    'America/Juneau': 'US',
+    'America/Kentucky/Louisville': 'US',
+    'America/Kentucky/Monticello': 'US',
+    'America/Knox_IN': 'US',
+    'America/Kralendijk': 'BQ',
+    'America/La_Paz': 'BO',
+    'America/Lima': 'PE',
+    'America/Los_Angeles': 'US',
+    'America/Louisville': 'US',
+    'America/Lower_Princes': 'SX',
+    'America/Maceio': 'BR',
+    'America/Managua': 'NI',
+    'America/Manaus': 'BR',
+    'America/Marigot': 'MF',
+    'America/Martinique': 'MQ',
+    'America/Matamoros': 'MX',
+    'America/Mazatlan': 'MX',
+    'America/Mendoza': 'AR',
+    'America/Menominee': 'US',
+    'America/Merida': 'MX',
+    'America/Metlakatla': 'US',
+    'America/Mexico_City': 'MX',
+    'America/Miquelon': 'PM',
+    'America/Moncton': 'CA',
+    'America/Monterrey': 'MX',
+    'America/Montevideo': 'UY',
+    'America/Montreal': 'CA',
+    'America/Montserrat': 'MS',
+    'America/Nassau': 'BS',
+    'America/New_York': 'US',
+    'America/Nipigon': 'CA',
+    'America/Nome': 'US',
+    'America/Noronha': 'BR',
+    'America/North_Dakota/Beulah': 'US',
+    'America/North_Dakota/Center': 'US',
+    'America/North_Dakota/New_Salem': 'US',
+    'America/Nuuk': 'GL',
+    'America/Ojinaga': 'MX',
+    'America/Panama': 'PA',
+    'America/Pangnirtung': 'CA',
+    'America/Paramaribo': 'SR',
+    'America/Phoenix': 'US',
+    'America/Port-au-Prince': 'HT',
+    'America/Port_of_Spain': 'TT',
+    'America/Porto_Acre': 'BR',
+    'America/Porto_Velho': 'BR',
+    'America/Puerto_Rico': 'PR',
+    'America/Punta_Arenas': 'CL',
+    'America/Rainy_River': 'CA',
+    'America/Rankin_Inlet': 'CA',
+    'America/Recife': 'BR',
+    'America/Regina': 'CA',
+    'America/Resolute': 'CA',
+    'America/Rio_Branco': 'BR',
+    'America/Rosario': 'AR',
+    'America/Santa_Isabel': 'MX',
+    'America/Santarem': 'BR',
+    'America/Santiago': 'CL',
+    'America/Santo_Domingo': 'DO',
+    'America/Sao_Paulo': 'BR',
+    'America/Scoresbysund': 'GL',
+    'America/Shiprock': 'US',
+    'America/Sitka': 'US',
+    'America/St_Barthelemy': 'BL',
+    'America/St_Johns': 'CA',
+    'America/St_Kitts': 'KN',
+    'America/St_Lucia': 'LC',
+    'America/St_Thomas': 'VI',
+    'America/St_Vincent': 'VC',
+    'America/Swift_Current': 'CA',
+    'America/Tegucigalpa': 'HN',
+    'America/Thule': 'GL',
+    'America/Thunder_Bay': 'CA',
+    'America/Tijuana': 'MX',
+    'America/Toronto': 'CA',
+    'America/Tortola': 'VG',
+    'America/Vancouver': 'CA',
+    'America/Virgin': 'VI',
+    'America/Whitehorse': 'CA',
+    'America/Winnipeg': 'CA',
+    'America/Yakutat': 'US',
+    'America/Yellowknife': 'CA',
+    'Antarctica/Casey': 'AQ',
+    'Antarctica/Davis': 'AQ',
+    'Antarctica/DumontDUrville': 'AQ',
+    'Antarctica/Macquarie': 'AU',
+    'Antarctica/Mawson': 'AQ',
+    'Antarctica/McMurdo': 'AQ',
+    'Antarctica/Palmer': 'AQ',
+    'Antarctica/Rothera': 'AQ',
+    'Antarctica/South_Pole': 'AQ',
+    'Antarctica/Syowa': 'AQ',
+    'Antarctica/Troll': 'AQ',
+    'Antarctica/Vostok': 'AQ',
+    'Arctic/Longyearbyen': 'SJ',
+    'Asia/Aden': 'YE',
+    'Asia/Almaty': 'KZ',
+    'Asia/Amman': 'JO',
+    'Asia/Anadyr': 'RU',
+    'Asia/Aqtau': 'KZ',
+    'Asia/Aqtobe': 'KZ',
+    'Asia/Ashgabat': 'TM',
+    'Asia/Ashkhabad': 'TM',
+    'Asia/Atyrau': 'KZ',
+    'Asia/Baghdad': 'IQ',
+    'Asia/Bahrain': 'BH',
+    'Asia/Baku': 'AZ',
+    'Asia/Bangkok': 'TH',
+    'Asia/Barnaul': 'RU',
+    'Asia/Beirut': 'LB',
+    'Asia/Bishkek': 'KG',
+    'Asia/Brunei': 'BN',
+    'Asia/Calcutta': 'IN',
+    'Asia/Chita': 'RU',
+    'Asia/Choibalsan': 'MN',
+    'Asia/Chongqing': 'CN',
+    'Asia/Chungking': 'CN',
+    'Asia/Colombo': 'LK',
+    'Asia/Dacca': 'BD',
+    'Asia/Damascus': 'SY',
+    'Asia/Dhaka': 'BD',
+    'Asia/Dili': 'TL',
+    'Asia/Dubai': 'AE',
+    'Asia/Dushanbe': 'TJ',
+    'Asia/Famagusta': 'CY',
+    'Asia/Gaza': 'PS',
+    'Asia/Harbin': 'CN',
+    'Asia/Hebron': 'PS',
+    'Asia/Ho_Chi_Minh': 'VN',
+    'Asia/Hong_Kong': 'HK',
+    'Asia/Hovd': 'MN',
+    'Asia/Irkutsk': 'RU',
+    'Asia/Istanbul': 'TR',
+    'Asia/Jakarta': 'ID',
+    'Asia/Jayapura': 'ID',
+    'Asia/Jerusalem': 'IL',
+    'Asia/Kabul': 'AF',
+    'Asia/Kamchatka': 'RU',
+    'Asia/Karachi': 'PK',
+    'Asia/Kashgar': 'CN',
+    'Asia/Kathmandu': 'NP',
+    'Asia/Katmandu': 'NP',
+    'Asia/Khandyga': 'RU',
+    'Asia/Kolkata': 'IN',
+    'Asia/Krasnoyarsk': 'RU',
+    'Asia/Kuala_Lumpur': 'MY',
+    'Asia/Kuching': 'MY',
+    'Asia/Kuwait': 'KW',
+    'Asia/Macao': 'MO',
+    'Asia/Macau': 'MO',
+    'Asia/Magadan': 'RU',
+    'Asia/Makassar': 'ID',
+    'Asia/Manila': 'PH',
+    'Asia/Muscat': 'OM',
+    'Asia/Nicosia': 'CY',
+    'Asia/Novokuznetsk': 'RU',
+    'Asia/Novosibirsk': 'RU',
+    'Asia/Omsk': 'RU',
+    'Asia/Oral': 'KZ',
+    'Asia/Phnom_Penh': 'KH',
+    'Asia/Pontianak': 'ID',
+    'Asia/Pyongyang': 'KP',
+    'Asia/Qatar': 'QA',
+    'Asia/Qostanay': 'KZ',
+    'Asia/Qyzylorda': 'KZ',
+    'Asia/Rangoon': 'MM',
+    'Asia/Riyadh': 'SA',
+    'Asia/Saigon': 'VN',
+    'Asia/Sakhalin': 'RU',
+    'Asia/Samarkand': 'UZ',
+    'Asia/Seoul': 'KR',
+    'Asia/Shanghai': 'CN',
+    'Asia/Singapore': 'SG',
+    'Asia/Srednekolymsk': 'RU',
+    'Asia/Taipei': 'TW',
+    'Asia/Tashkent': 'UZ',
+    'Asia/Tbilisi': 'GE',
+    'Asia/Tehran': 'IR',
+    'Asia/Tel_Aviv': 'IL',
+    'Asia/Thimbu': 'BT',
+    'Asia/Thimphu': 'BT',
+    'Asia/Tokyo': 'JP',
+    'Asia/Tomsk': 'RU',
+    'Asia/Ujung_Pandang': 'ID',
+    'Asia/Ulaanbaatar': 'MN',
+    'Asia/Ulan_Bator': 'MN',
+    'Asia/Urumqi': 'CN',
+    'Asia/Ust-Nera': 'RU',
+    'Asia/Vientiane': 'LA',
+    'Asia/Vladivostok': 'RU',
+    'Asia/Yakutsk': 'RU',
+    'Asia/Yangon': 'MM',
+    'Asia/Yekaterinburg': 'RU',
+    'Asia/Yerevan': 'AM',
+    'Atlantic/Azores': 'PT',
+    'Atlantic/Bermuda': 'BM',
+    'Atlantic/Canary': 'ES',
+    'Atlantic/Cape_Verde': 'CV',
+    'Atlantic/Faeroe': 'FO',
+    'Atlantic/Faroe': 'FO',
+    'Atlantic/Jan_Mayen': 'SJ',
+    'Atlantic/Madeira': 'PT',
+    'Atlantic/Reykjavik': 'IS',
+    'Atlantic/South_Georgia': 'GS',
+    'Atlantic/St_Helena': 'SH',
+    'Atlantic/Stanley': 'FK',
+    'Australia/ACT': 'AU',
+    'Australia/Adelaide': 'AU',
+    'Australia/Brisbane': 'AU',
+    'Australia/Broken_Hill': 'AU',
+    'Australia/Canberra': 'AU',
+    'Australia/Currie': 'AU',
+    'Australia/Darwin': 'AU',
+    'Australia/Eucla': 'AU',
+    'Australia/Hobart': 'AU',
+    'Australia/LHI': 'AU',
+    'Australia/Lindeman': 'AU',
+    'Australia/Lord_Howe': 'AU',
+    'Australia/Melbourne': 'AU',
+    'Australia/NSW': 'AU',
+    'Australia/North': 'AU',
+    'Australia/Perth': 'AU',
+    'Australia/Queensland': 'AU',
+    'Australia/South': 'AU',
+    'Australia/Sydney': 'AU',
+    'Australia/Tasmania': 'AU',
+    'Australia/Victoria': 'AU',
+    'Australia/West': 'AU',
+    'Australia/Yancowinna': 'AU',
+    'Brazil/Acre': 'BR',
+    'Brazil/DeNoronha': 'BR',
+    'Brazil/East': 'BR',
+    'Brazil/West': 'BR',
+    'Canada/Atlantic': 'CA',
+    'Canada/Central': 'CA',
+    'Canada/Eastern': 'CA',
+    'Canada/Mountain': 'CA',
+    'Canada/Newfoundland': 'CA',
+    'Canada/Pacific': 'CA',
+    'Canada/Saskatchewan': 'CA',
+    'Canada/Yukon': 'CA',
+    'Chile/Continental': 'CL',
+    'Chile/EasterIsland': 'CL',
+    'Cuba': 'CU',
+    'Egypt': 'EG',
+    'Eire': 'IE',
+    'Europe/Amsterdam': 'NL',
+    'Europe/Andorra': 'AD',
+    'Europe/Astrakhan': 'RU',
+    'Europe/Athens': 'GR',
+    'Europe/Belfast': 'GB',
+    'Europe/Belgrade': 'RS',
+    'Europe/Berlin': 'DE',
+    'Europe/Bratislava': 'SK',
+    'Europe/Brussels': 'BE',
+    'Europe/Bucharest': 'RO',
+    'Europe/Budapest': 'HU',
+    'Europe/Busingen': 'DE',
+    'Europe/Chisinau': 'MD',
+    'Europe/Copenhagen': 'DK',
+    'Europe/Dublin': 'IE',
+    'Europe/Gibraltar': 'GI',
+    'Europe/Guernsey': 'GG',
+    'Europe/Helsinki': 'FI',
+    'Europe/Isle_of_Man': 'IM',
+    'Europe/Istanbul': 'TR',
+    'Europe/Jersey': 'JE',
+    'Europe/Kaliningrad': 'RU',
+    'Europe/Kiev': 'UA',
+    'Europe/Kirov': 'RU',
+    'Europe/Kyiv': 'UA',
+    'Europe/Lisbon': 'PT',
+    'Europe/Ljubljana': 'SI',
+    'Europe/London': 'GB',
+    'Europe/Luxembourg': 'LU',
+    'Europe/Madrid': 'ES',
+    'Europe/Malta': 'MT',
+    'Europe/Mariehamn': 'AX',
+    'Europe/Minsk': 'BY',
+    'Europe/Monaco': 'MC',
+    'Europe/Moscow': 'RU',
+    'Europe/Nicosia': 'CY',
+    'Europe/Oslo': 'NO',
+    'Europe/Paris': 'FR',
+    'Europe/Podgorica': 'ME',
+    'Europe/Prague': 'CZ',
+    'Europe/Riga': 'LV',
+    'Europe/Rome': 'IT',
+    'Europe/Samara': 'RU',
+    'Europe/San_Marino': 'SM',
+    'Europe/Sarajevo': 'BA',
+    'Europe/Saratov': 'RU',
+    'Europe/Simferopol': 'UA',
+    'Europe/Skopje': 'MK',
+    'Europe/Sofia': 'BG',
+    'Europe/Stockholm': 'SE',
+    'Europe/Tallinn': 'EE',
+    'Europe/Tirane': 'AL',
+    'Europe/Tiraspol': 'MD',
+    'Europe/Ulyanovsk': 'RU',
+    'Europe/Uzhgorod': 'UA',
+    'Europe/Vaduz': 'LI',
+    'Europe/Vatican': 'VA',
+    'Europe/Vienna': 'AT',
+    'Europe/Vilnius': 'LT',
+    'Europe/Volgograd': 'RU',
+    'Europe/Warsaw': 'PL',
+    'Europe/Zagreb': 'HR',
+    'Europe/Zaporozhye': 'UA',
+    'Europe/Zurich': 'CH',
+    'GB': 'GB',
+    'GB-Eire': 'GB',
+    'Hongkong': 'HK',
+    'Iceland': 'IS',
+    'Indian/Antananarivo': 'MG',
+    'Indian/Chagos': 'IO',
+    'Indian/Christmas': 'CX',
+    'Indian/Cocos': 'CC',
+    'Indian/Comoro': 'KM',
+    'Indian/Kerguelen': 'TF',
+    'Indian/Mahe': 'SC',
+    'Indian/Maldives': 'MV',
+    'Indian/Mauritius': 'MU',
+    'Indian/Mayotte': 'YT',
+    'Indian/Reunion': 'RE',
+    'Iran': 'IR',
+    'Israel': 'IL',
+    'Jamaica': 'JM',
+    'Japan': 'JP',
+    'Kwajalein': 'MH',
+    'Libya': 'LY',
+    'Mexico/BajaNorte': 'MX',
+    'Mexico/BajaSur': 'MX',
+    'Mexico/General': 'MX',
+    'NZ': 'NZ',
+    'NZ-CHAT': 'NZ',
+    'Navajo': 'US',
+    'PRC': 'CN',
+    'Pacific/Apia': 'WS',
+    'Pacific/Auckland': 'NZ',
+    'Pacific/Bougainville': 'PG',
+    'Pacific/Chatham': 'NZ',
+    'Pacific/Chuuk': 'FM',
+    'Pacific/Easter': 'CL',
+    'Pacific/Efate': 'VU',
+    'Pacific/Enderbury': 'KI',
+    'Pacific/Fakaofo': 'TK',
+    'Pacific/Fiji': 'FJ',
+    'Pacific/Funafuti': 'TV',
+    'Pacific/Galapagos': 'EC',
+    'Pacific/Gambier': 'PF',
+    'Pacific/Guadalcanal': 'SB',
+    'Pacific/Guam': 'GU',
+    'Pacific/Honolulu': 'US',
+    'Pacific/Johnston': 'UM',
+    'Pacific/Kanton': 'KI',
+    'Pacific/Kiritimati': 'KI',
+    'Pacific/Kosrae': 'FM',
+    'Pacific/Kwajalein': 'MH',
+    'Pacific/Majuro': 'MH',
+    'Pacific/Marquesas': 'PF',
+    'Pacific/Midway': 'UM',
+    'Pacific/Nauru': 'NR',
+    'Pacific/Niue': 'NU',
+    'Pacific/Norfolk': 'NF',
+    'Pacific/Noumea': 'NC',
+    'Pacific/Pago_Pago': 'AS',
+    'Pacific/Palau': 'PW',
+    'Pacific/Pitcairn': 'PN',
+    'Pacific/Pohnpei': 'FM',
+    'Pacific/Ponape': 'FM',
+    'Pacific/Port_Moresby': 'PG',
+    'Pacific/Rarotonga': 'CK',
+    'Pacific/Saipan': 'MP',
+    'Pacific/Samoa': 'AS',
+    'Pacific/Tahiti': 'PF',
+    'Pacific/Tarawa': 'KI',
+    'Pacific/Tongatapu': 'TO',
+    'Pacific/Truk': 'FM',
+    'Pacific/Wake': 'UM',
+    'Pacific/Wallis': 'WF',
+    'Pacific/Yap': 'FM',
+    'Poland': 'PL',
+    'Portugal': 'PT',
+    'ROC': 'TW',
+    'ROK': 'KR',
+    'Singapore': 'SG',
+    'Turkey': 'TR',
+    'US/Alaska': 'US',
+    'US/Aleutian': 'US',
+    'US/Arizona': 'US',
+    'US/Central': 'US',
+    'US/East-Indiana': 'US',
+    'US/Eastern': 'US',
+    'US/Hawaii': 'US',
+    'US/Indiana-Starke': 'US',
+    'US/Michigan': 'US',
+    'US/Mountain': 'US',
+    'US/Pacific': 'US',
+    'US/Samoa': 'AS',
+    'W-SU': 'RU',
+}

ui/frame_touch.py

@@ -25,7 +25,9 @@ Standard library only (ctypes for libei), like the rest of what runs on the Fram
 import ctypes
 import json
 import os
+import re
 import select
+import shutil
 import subprocess
 import sys
 import time
@@ -53,14 +55,41 @@ def say(state, **more):
 
 # ---- which panel has focus -----------------------------------------------------
 
-def xprop_root(display, name):
+PROPS = ("GAMESCOPE_FOCUSABLE_WINDOWS", "GAMESCOPE_FOCUSED_WINDOW", "GAMESCOPE_FOCUS_DISPLAY")
+TOOL_TIMEOUT = 5.0  # seconds for any one xprop or xwininfo
+PANELS_DEADLINE = 12.0  # seconds for a whole `panels` run: well inside the server's 20 s for /api/panels
+DEADLINE = [None]  # when the current `panels` run must stop asking X tools (monotonic), if it has one
+
+
+class OutOfTime(Exception):
+    """The current run's deadline passed: stop and report what was found."""
+
+
+def budget(limit=TOOL_TIMEOUT):
+    """Seconds an X tool may take now: its own limit, cut to what's left of the run's deadline."""
+    if DEADLINE[0] is None:
+        return limit
+    left = DEADLINE[0] - time.monotonic()
+    if left <= 0:
+        raise OutOfTime()
+    return min(limit, left)
+
+
+def read_props(display, limit=TOOL_TIMEOUT):
+    """gamescope's root properties on one display, in one xprop call: {name: [values]} for
+    those the display has, {} if none (or xprop didn't answer)."""
     try:
-        out = subprocess.run(["xprop", "-root", name], env=dict(os.environ, DISPLAY=display),
-                             capture_output=True, text=True, timeout=5).stdout
+        out = subprocess.run(["xprop", "-root", *PROPS], env=dict(os.environ, DISPLAY=display),
+                             capture_output=True, text=True, timeout=budget(limit)).stdout
     except (OSError, subprocess.SubprocessError):
-        return []
-    values = out.split("=", 1)[1] if "=" in out else ""
-    return [int(v) for v in values.replace(",", " ").split() if v.isdigit()]
+        return {}
+    props = {}
+    for line in out.splitlines():
+        name, sep, values = line.partition("=")
+        name = name.split("(", 1)[0].strip()
+        if sep and name in PROPS:
+            props[name] = [int(v) for v in values.replace(",", " ").split() if v.isdigit()]
+    return props
 
 
 def window_info(display, window):
@@ -68,7 +97,7 @@ def window_info(display, window):
     try:
         which = ["-root"] if window == "root" else ["-id", str(window)]
         out = subprocess.run(["xwininfo", *which], env=dict(os.environ, DISPLAY=display),
-                             capture_output=True, text=True, timeout=5).stdout
+                             capture_output=True, text=True, timeout=budget()).stdout
     except (OSError, subprocess.SubprocessError):
         return None
     if "IsViewable" not in out:
@@ -86,13 +115,58 @@ def window_info(display, window):
 
 
 def displays():
-    return sorted(f":{n[1:]}" for n in os.listdir("/tmp/.X11-unix") if n[1:].isdigit())
+    """Every X display on the Frame: the sockets in /tmp/.X11-unix, and the abstract ones
+    X servers on Linux usually listen on as well (in /proc/net/unix), in case a SteamOS
+    build stops sharing /tmp/.X11-unix with SSH sessions."""
+    found = set()
+    try:
+        found.update(int(n[1:]) for n in os.listdir("/tmp/.X11-unix") if n[:1] == "X" and n[1:].isdigit())
+    except OSError:
+        pass
+    try:
+        with open("/proc/net/unix") as f:
+            found.update(int(n) for n in re.findall(r"@/tmp/\.X11-unix/X(\d+)", f.read()))
+    except OSError:
+        pass
+    return [f":{n}" for n in sorted(found)]
+
+
+# The input helper (`frame_touch.py` reading events) lives for a whole Control session and
+# reads focus often, so it remembers which display has gamescope's properties: found, for
+# good; not found, for ROOT_RETRY. A `panels` run is a fresh process each time, so this
+# saves it nothing; it costs nothing either while :0 has the properties.
+_ROOT = []  # [display, when it was given up on, or None if found]
+ROOT_PROBE_TIMEOUT = 2.0  # seconds for each display other than :0, so a stalled one can't use the run
+ROOT_RETRY = 30.0
+
+
+def gamescope():
+    """(display, properties): the X display whose root window carries gamescope's panel
+    properties (GAMESCOPE_FOCUSABLE_WINDOWS and friends), and what they say now.
+
+    That's :0 on every build seen so far (SteamOS 0.3.0 to 0.4.1), so :0 is read first and,
+    when it has them, used with no other probe. Only if it hasn't are the other displays
+    asked, briefly each; with none, :0 and no properties.
+    """
+    if _ROOT and (_ROOT[1] is None or time.monotonic() - _ROOT[1] < ROOT_RETRY):
+        return _ROOT[0], read_props(_ROOT[0])
+    props, found = read_props(":0"), ":0"
+    if not props:
+        found = None
+        for display in displays():
+            if display != ":0":
+                props = read_props(display, ROOT_PROBE_TIMEOUT)
+                if props:
+                    found = display
+                    break
+    _ROOT[:] = [found, None] if found else [":0", time.monotonic()]
+    return _ROOT[0], props
 
 
 def window_pid(display, window):
     try:
         out = subprocess.run(["xprop", "-id", str(window), "_NET_WM_PID"], env=dict(os.environ, DISPLAY=display),
-                             capture_output=True, text=True, timeout=5).stdout
+                             capture_output=True, text=True, timeout=budget()).stdout
     except (OSError, subprocess.SubprocessError):
         return None
     value = out.rsplit("=", 1)[-1].strip() if "=" in out else ""
@@ -120,20 +194,20 @@ def locate(window, pid):
             "root": [root.get("width", info["width"]), root.get("height", info["height"])]}
 
 
-def focusable():
-    """gamescope's focusable windows as (window, app id, pid)."""
-    t = xprop_root(":0", "GAMESCOPE_FOCUSABLE_WINDOWS")
+def focusable(props=None):
+    """gamescope's focusable windows as (window, app id, pid), from props if already read."""
+    t = (gamescope()[1] if props is None else props).get("GAMESCOPE_FOCUSABLE_WINDOWS", [])
     return [tuple(t[i:i + 3]) for i in range(0, len(t) - 2, 3)]
 
 
-def focus_display():
-    """The display of the focused window, from GAMESCOPE_FOCUS_DISPLAY on :0's root.
+def focus_display(props=None):
+    """The display of the focused window, from GAMESCOPE_FOCUS_DISPLAY on gamescope's root.
 
     gamescope writes the name (":1") as 32-bit items, so its first four bytes land,
     little-endian, in the first value: 12602 is 0x313A, ":1" (steamcompmgr.cpp;
     seen 2026-09-29).
     """
-    values = xprop_root(":0", "GAMESCOPE_FOCUS_DISPLAY")
+    values = (gamescope()[1] if props is None else props).get("GAMESCOPE_FOCUS_DISPLAY")
     if not values:
         return None
     name = (values[0] & 0xFFFFFFFF).to_bytes(4, "little").split(b"\0", 1)[0].decode("ascii", "replace")
@@ -141,19 +215,23 @@ def focus_display():
 
 
 def focus_now():
-    """Just which window and display have focus: two property reads, for checking a press."""
-    window = (xprop_root(":0", "GAMESCOPE_FOCUSED_WINDOW") or [0])[0]
-    return (window or None, focus_display() if window else None)
+    """Just which window and display have focus: one property read, for checking a press."""
+    props = gamescope()[1]
+    window = (props.get("GAMESCOPE_FOCUSED_WINDOW") or [0])[0]
+    return (window or None, focus_display(props) if window else None)
 
 
-def focus():
+def focus(props=None):
     """The panel that has focus in the headset: window, display, name and sizes (gamescope
-    publishes the window and its display on :0's root)."""
-    window = (xprop_root(":0", "GAMESCOPE_FOCUSED_WINDOW") or [0])[0]
+    publishes the window and its display on its root display, :0 so far). props: gamescope's
+    properties if already read."""
+    if props is None:
+        props = gamescope()[1]
+    window = (props.get("GAMESCOPE_FOCUSED_WINDOW") or [0])[0]
     if not window:
         return {"window": None}
-    app, pid = next(((a, p) for w, a, p in focusable() if w == window), (None, None))
-    display = focus_display()
+    app, pid = next(((a, p) for w, a, p in focusable(props) if w == window), (None, None))
+    display = focus_display(props)
     info = window_info(display, window) if display else None
     if info:
         root = window_info(display, "root") or {}
@@ -164,18 +242,77 @@ def focus():
     return {**panel, "app": app} if panel else {"window": None}
 
 
-def panels():
-    """Every app panel (gamescope's focusable windows), for watching one that hasn't focus."""
-    now = focus()
-    found = []
-    for window, app, pid in focusable():
-        panel = locate(window, pid)
-        if panel and panel["width"] > 1 and panel["height"] > 1 and \
-                not any(f["window"] == window and f["display"] == panel["display"] for f in found):
-            panel.pop("root", None)
-            found.append({**panel, "app": app, "focused": (window, panel["display"]) ==
-                          (now.get("window"), now.get("display"))})
-    return {"focus": now.get("window"), "focus_display": now.get("display"), "panels": found}
+def panels(limit=None):
+    """Every app panel (gamescope's focusable windows), for watching one that hasn't focus.
+
+    One deadline (PANELS_DEADLINE) covers the whole run, inside the server's timeout: past
+    it, the panels found so far come back with a "why" saying the headset was too slow.
+    """
+    DEADLINE[0] = time.monotonic() + (PANELS_DEADLINE if limit is None else limit)
+    now, found, unfound, late = {}, [], 0, False
+    try:
+        props = gamescope()[1]
+        now = focus(props)
+        for window, app, pid in focusable(props):
+            panel = locate(window, pid)
+            unfound += panel is None
+            if panel and panel["width"] > 1 and panel["height"] > 1 and \
+                    not any(f["window"] == window and f["display"] == panel["display"] for f in found):
+                panel.pop("root", None)
+                found.append({**panel, "app": app, "focused": (window, panel["display"]) ==
+                              (now.get("window"), now.get("display"))})
+        late = time.monotonic() >= DEADLINE[0]  # the last read may have been cut short
+    except OutOfTime:
+        late = True
+    finally:
+        DEADLINE[0] = None
+    out = {"focus": now.get("window"), "focus_display": now.get("display"), "panels": found}
+    if late:
+        out["why"] = ("The headset took too long to list its panels (its X tools didn't answer in time). "
+                      + ("Some may be missing. " if found else "") + "Try again, or use the Headset view.")
+    elif not found:
+        out["why"] = why_none(unfound)
+    return out
+
+
+# The headset's Linux desktop, by process name (docs/how-the-frame-works.md).
+DESKTOP = ("plasmashell", "kwin_wayland", "kwin_wayland_wrapper", "steamos-nested-desktop", "startplasma-wayland")
+
+
+def desktop_running():
+    """Whether the headset's Linux desktop (the nested Plasma session) is running."""
+    try:
+        pids = [p for p in os.listdir("/proc") if p.isdigit()]
+    except OSError:
+        return False
+    for pid in pids:
+        try:
+            with open(f"/proc/{pid}/comm") as f:
+                if f.read().strip() in DESKTOP:
+                    return True
+        except OSError:
+            continue
+    return False
+
+
+def why_none(listed):
+    """Why panels() found nothing, in words the person at the computer can act on.
+    listed: how many of the windows gamescope lists aren't X11 windows on any display."""
+    missing = [tool for tool in ("xprop", "xwininfo") if not shutil.which(tool)]
+    if missing:
+        return (f"This SteamOS build has no {' or '.join(missing)}, which Frame Control uses to find the "
+                "headset's panels. Use the Headset view instead, and please report your SteamOS version.")
+    if listed:
+        # gamescope lists windows, but none is an X11 window on any display: a Wayland
+        # window (a desktop drawn straight to gamescope, say) can't be found or captured this way.
+        return (f"The headset has {listed} panel{'s' if listed > 1 else ''} open, but Frame Control can't "
+                f"find {'its' if listed == 1 else 'their'} window. This SteamOS build may draw "
+                f"{'it' if listed == 1 else 'them'} in a way the Desktop view can't capture yet. "
+                "Use the Headset view instead, and please report your SteamOS version.")
+    if desktop_running():
+        return ("The headset's desktop is running, but SteamOS isn't listing it as a panel. Look at it in "
+                "the headset (or close and reopen it), then try again, or use the Headset view.")
+    return "No app panel is open in the headset. Open the desktop or an app in the headset, then try again."
 
 
 def to_root(panel, fx, fy):
@@ -369,10 +506,8 @@ def apply(gs, event, panel):
         say("ready", focus=panel.get("window"), display=panel.get("display"), stale=True)  # the page re-syncs
         STALE[0] = True
         return panel
-    release = event.get("down") is False and ("button" in event or "key" in event)
-    if STALE[0] and not stale and not (release and "window" not in event):
+    if STALE[0] and not stale:
         # Anything that goes through (a trackpad move names no panel) means caught up: stop re-syncing.
-        # A bare release doesn't: the page leaves the panel off releases, so it says nothing about focus.
         STALE[0] = False
         say("ready", focus=(panel or {}).get("window"), display=(panel or {}).get("display"))
     if "fx" in event and panel and panel.get("window"):

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

@@ -45,6 +45,7 @@ import frame_agent  # noqa: E402
 import frame_assistant  # noqa: E402
 import frame_android  # noqa: E402
 from apk_sources import search as apk_search, SourceError  # noqa: E402
+from apk_sources import fdroid as apk_fdroid  # noqa: E402
 import frame_apk_versions  # noqa: E402
 import frame_catalog  # noqa: E402
 import frame_devices  # noqa: E402
@@ -60,7 +61,6 @@ import frame_report  # noqa: E402
 import frame_store  # noqa: E402
 import frame_telemetry  # noqa: E402
 import frame_titles  # noqa: E402
-import frame_touch  # noqa: E402
 import frame_webinstall  # noqa: E402
 import frame_vr  # noqa: E402
 import frame_utilities  # noqa: E402
@@ -135,6 +135,7 @@ LINK = None  # the connector (frame_link.Link); None on the Frame itself
 # install's clean-up) to the other headset.
 _work_lock = threading.Lock()
 _work = [0]
+NOT_HEADSET_WORK = {"/api/devices", "/api/contact", "/api/contact/prompt"}
 
 
 @contextlib.contextmanager
@@ -210,9 +211,14 @@ UNREACHABLE = [
     (re.compile(r"port \d+: Connection refused"),
      "The Frame refused the connection. Check Developer Mode is still on."),
     (re.compile(r"Permission denied \(publickey"),
-     "The Frame didn't accept this computer's SSH key. Run Set Up Connection again."),
-    (re.compile(r"Host key verification failed"),
-     "The Frame's SSH identity changed (after a reinstall, or a different device). Run Set Up Connection again."),
+     "The Frame didn't accept this computer's SSH key. Set Up Connection pairs this computer with it "
+     "again (Developer Mode must be on)."),
+    # Before "Host key verification failed", which ssh prints after each of these.
+    (re.compile(r"No \S+ host key is known for "),
+     "The Frame's SSH identity isn't saved yet. Reconnecting saves it; or check and trust it on the Devices tab."),
+    (re.compile(r"REMOTE HOST IDENTIFICATION HAS CHANGED|Host key verification failed"),
+     "The Frame's SSH identity has changed: after SteamOS was reinstalled or reset, or a different device "
+     "answering at its address. Check the new key on the Devices tab before trusting it."),
     (re.compile(r"kex_exchange_identification|Connection closed by .* port \d+|Connection reset by .* port \d+"),
      "The connection to the Frame dropped. Try again."),
 ]
@@ -334,20 +340,51 @@ def ssh(remote, *, stdin=None, timeout=30, text=True):
         # Never let ssh inherit our stdin: under the app it's the pipe held open for
         # --exit-on-eof, and Windows' ssh.exe waits on it forever.
         feed = {"input": stdin} if stdin is not None else {"stdin": subprocess.DEVNULL}
-        r = subprocess.run([*SSH, FRAME, remote], capture_output=True, **feed,
-                           text=text, errors="replace" if text else None, timeout=timeout)
+        r = frame_host.run_ssh([*SSH, FRAME, remote], capture_output=True, **feed,
+                               text=text, errors="replace" if text else None, timeout=timeout)
     except subprocess.TimeoutExpired:
-        raise Failure(f"Timed out talking to {FRAME}")
+        raise frame_host.link_failure(Failure(f"Timed out talking to {FRAME}"))
     if r.returncode != 0:
         err = (r.stderr or r.stdout) if text else (r.stderr or r.stdout).decode(errors="replace")
+        if r.returncode == 255 and repair_ssh_config(err):
+            return ssh(remote, stdin=stdin, timeout=timeout, text=text)
         if r.returncode == 255 and LINK and unreachable(err):
             LINK.lost(err, route_gen)  # ssh itself failed: the connector reconnects
         failure = Failure(strip_ansi(err).strip() or f"ssh exited {r.returncode}")
         failure.stdout = r.stdout if text else r.stdout.decode(errors="replace")
+        # ssh never reached the Frame (see frame_telemetry.diagnostic): judged on ssh's stderr only,
+        # never on the command's output.
+        stderr = (r.stderr if text else (r.stderr or b"").decode(errors="replace")) or ""
+        if frame_host.ssh_link_failed(r.returncode, strip_ansi(stderr)):
+            frame_host.link_failure(failure)
         raise failure
     return r.stdout
 
 
+_config_repaired = False
+
+
+def repair_ssh_config(err):
+    """Windows' OpenSSH refused ~/.ssh/config for its ACL: give the file a private one,
+    once per run. -> True if it did, so the command is worth retrying."""
+    global _config_repaired
+    if _config_repaired or not frame_host.WINDOWS or frame_host.BAD_PERMISSIONS not in err:
+        return False
+    # ssh doubles the backslashes: "C:\\Users\\me/.ssh/config"
+    named = re.sub(r"[\\/]+", "/", err.split(frame_host.BAD_PERMISSIONS, 1)[1].splitlines()[0].strip())
+    config = frame_devices.ssh_config()
+    if not named.lower().endswith("/" + config.name.lower()):
+        return False  # a key or another file: not ours to rewrite
+    _config_repaired = True
+    try:
+        if frame_devices.repair_permissions(config):
+            print(f"Gave {config} a private ACL: ssh refused it ({named})", file=sys.stderr)
+            return True
+    except OSError as e:
+        print(f"Couldn't repair {config}'s permissions: {e}", file=sys.stderr)
+    return False
+
+
 def strip_ansi(s):
     return re.sub(r"\x1b\[[0-9;?]*[A-Za-z]|\r", "", s)
 
@@ -366,11 +403,38 @@ def status(_body):
     s = json.loads(ssh("python3 -", stdin=(HERE / "frame_status.py").read_text(), timeout=20))
     osr = s.get("os") if isinstance(s, dict) else None
     if isinstance(osr, dict):
-        frame_telemetry.frame_seen(osr.get("build"), osr.get("version"))
+        # The headset's hash is for usage statistics only; the page and MCP clients don't get it.
+        frame_telemetry.frame_seen(osr.get("build"), osr.get("version"), osr.pop("headset", None),
+                                   len(LINK.reg.devices()) if LINK else None)
         frame_report.frame.update(build=osr.get("build"), version=osr.get("version"))
     return s
 
 
+COMFORT_FILES = ("frame_comfort.py", "frame_status.py", "frame_steam.py")
+COMFORT_MISSING = {"comfort": "missing"}  # what COMFORT_RUN prints when the cached copy isn't complete
+# Runs frame_comfort.py from ~/.cache/frame-control/comfort/<version>, first writing any of
+# `files` that aren't there (none: just check they all are). Private, and each file written
+# whole or not at all, so a copy cut short is finished by the next call.
+COMFORT_RUN = """import json, os, pathlib, subprocess, sys
+os.umask(0o077)
+files = %r
+root = pathlib.Path.home() / '.cache/frame-control/comfort' / %r
+if files:
+    root.mkdir(parents=True, exist_ok=True)
+for name, source in files.items():
+    path = root / name
+    if not path.exists():
+        tmp = root / (name + '.' + str(os.getpid()))
+        tmp.write_text(source)
+        tmp.replace(path)
+if not all((root / name).is_file() for name in %r):
+    print('{"comfort": "missing"}')
+    sys.exit()
+r = subprocess.run([sys.executable, str(root / 'frame_comfort.py'), %r], capture_output=True, text=True)
+print(r.stdout, end='')
+"""
+
+
 def comfort(body):
     try:
         frame_comfort.validate(body)
@@ -378,25 +442,14 @@ def comfort(body):
         raise Failure(str(e), 400)
     # Content-addressed, user-only helper bundle. Desktop and phone use the same
     # on-headset state/lock; no listener, service registration or third-party app.
-    import hashlib
-    files = {name: (HERE / name).read_text() for name in
-             ("frame_comfort.py", "frame_status.py", "frame_steam.py")}
+    # The page polls this every few seconds, so run the copy already on the headset and
+    # send the sources only when that version isn't there yet.
+    files = {name: (HERE / name).read_text() for name in COMFORT_FILES}
     version = hashlib.sha256(json.dumps(files, sort_keys=True).encode()).hexdigest()[:16]
-    script = """import json, os, pathlib, subprocess, sys
-os.umask(0o077)
-files = %r
-root = pathlib.Path.home() / '.cache/frame-control/comfort' / %r
-root.mkdir(parents=True, exist_ok=True)
-for name, source in files.items():
-    path = root / name
-    if not path.exists():
-        tmp = root / (name + '.' + str(os.getpid()))
-        tmp.write_text(source)
-        tmp.replace(path)
-r = subprocess.run([sys.executable, str(root / 'frame_comfort.py'), %r], capture_output=True, text=True)
-print(r.stdout, end='')
-""" % (files, version, json.dumps(body))
-    out = json.loads(ssh("python3 -", stdin=script, timeout=65))
+    out = json.loads(ssh("python3 -", stdin=COMFORT_RUN % ({}, version, COMFORT_FILES, json.dumps(body)), timeout=65))
+    if out == COMFORT_MISSING:
+        out = json.loads(ssh("python3 -", stdin=COMFORT_RUN % (files, version, COMFORT_FILES, json.dumps(body)),
+                             timeout=65))
     if out.get("error") and "active" not in out:
         raise Failure(out["error"], 409)
     return out
@@ -505,8 +558,8 @@ def save_shots(body):
         incoming = Path(tempfile.mkdtemp(prefix=".incoming-", dir=SHOTS_DIR))
         try:
             try:
-                r = subprocess.run(["scp", "-p", *SSH[1:], *(f"{FRAME}:{p}" for p in todo), str(incoming)],
-                                   capture_output=True, stdin=subprocess.DEVNULL, text=True, timeout=300)
+                r = frame_host.run_ssh(["scp", "-p", *SSH[1:], *(f"{FRAME}:{p}" for p in todo), str(incoming)],
+                                       capture_output=True, stdin=subprocess.DEVNULL, text=True, timeout=300)
             except subprocess.TimeoutExpired:
                 raise Failure("Copying screenshots timed out")
             if r.returncode != 0:
@@ -646,9 +699,14 @@ def set_volume(body):
     # Validate everything before touching the headset.
     level = None
     if "level" in body:
-        level = float(body["level"])
-        if not 0 <= level <= 1:
+        value = body["level"]
+        if type(value) not in (int, float) or not 0 <= value <= 1:
             raise Failure("level must be 0..1", 400)
+        level = float(value)
+    if not body or set(body) - {"level", "muted"}:
+        raise Failure("Provide level or muted", 400)
+    if "muted" in body and type(body["muted"]) is not bool:
+        raise Failure("muted must be true or false", 400)
     if "muted" in body:
         ssh(f"wpctl set-mute @DEFAULT_AUDIO_SINK@ {1 if body['muted'] else 0}")
     if level is not None:
@@ -665,7 +723,7 @@ PASTE = r"""set -u
 text=$(cat; printf x); text=${text%x}
 pid=$(pgrep -u "$(id -u)" -x plasmashell | head -n 1)
 if [ -z "$pid" ]; then
-  echo "plasmashell is not running: open the desktop in the headset first." >&2
+  echo "The headset's desktop isn't open (plasmashell is not running). Open the desktop in the headset, then try again." >&2
   exit 2
 fi
 bus=$(tr '\0' '\n' < "/proc/$pid/environ" | sed -n 's/^DBUS_SESSION_BUS_ADDRESS=//p')
@@ -677,6 +735,7 @@ else
   exit 2
 fi
 """
+DESKTOP_CLOSED = "plasmashell is not running"  # what PASTE says when the headset's desktop isn't open
 # base64 keeps the script intact through every local shell's quoting rules.
 PASTE_CMD = 'bash -c "$(echo %s | base64 -d)"' % base64.b64encode(PASTE.encode()).decode()
 
@@ -693,7 +752,13 @@ def clipboard(body):
         text = body.get("text")
         if not isinstance(text, str) or not text:
             raise Failure("nothing to send", 400)
-    return {"message": ssh(PASTE_CMD, stdin=text, timeout=30).strip()}
+    try:
+        return {"message": ssh(PASTE_CMD, stdin=text, timeout=30).strip()}
+    except Failure as e:
+        if DESKTOP_CLOSED in str(e):
+            # The headset's state, for the person to change, not a fault: a 409 isn't reported as one.
+            raise Failure(str(e), 409) from None
+        raise
 
 
 # ---- keyboard and pointer (KDE Connect on the Frame, see frame_input_agent.py) ----
@@ -1006,274 +1071,12 @@ def licenses():
     return notices
 
 
-# KDE Connect's specialKey numbers -> Linux key codes (KEY_BACKSPACE, KEY_TAB, ...).
-PAD_KEYS = {1: 14, 2: 15, 4: 105, 5: 103, 6: 106, 7: 108, 8: 104, 9: 109, 10: 102, 11: 107, 12: 28, 13: 111, 14: 1,
-            **{21 + i: code for i, code in enumerate([59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 87, 88])}}
-PAD_MODS = (("ctrl", 29), ("alt", 56), ("shift", 42), ("super", 125))
-PAD_CLICKS = {"singleclick": "left", "rightclick": "right", "middleclick": "middle"}
-PAD_NOTCH = 15  # scroll units for one wheel notch
-
-
-def typed_in_kde(events):
-    """Whether these events must go the KDE Connect way: they hold an accent or emoji, or
-    earlier ones are queued, being sent or still being typed there (typing must stay in
-    order, so it can't be split between the two ways)."""
-    with _kde_lock:
-        waiting = bool(_kde_queue) or time.time() < _kde_until
-    return waiting or any(ch not in frame_touch.ASCII for e in events for ch in e.get("key", ""))
-
-
-def pad_events(events, kde=False):
-    """The trackpad's and key row's events as (gamescope events, KDE Connect events).
-
-    Gamescope's own input reaches every panel and needs nothing installed, but types only
-    US-keyboard characters. With kde, the keyboard goes to KDE Connect as it was sent, so
-    text stays in order; the pointer always goes through gamescope.
-    """
-    ascii_keys = frame_touch.ASCII
-    out, slow = [], []
-
-    def tap(code, mods):
-        down = [{"key": c, "down": True} for c in mods]
-        out.extend(down + [{"key": code, "down": True}, {"key": code, "down": False}]
-                   + [{"key": c, "down": False} for c in reversed(mods)])
-    for e in events:
-        mods = [code for name, code in PAD_MODS if e.get(name)]
-        if "dx" in e or "dy" in e:
-            if not e.get("scroll"):
-                out.append({k: e[k] for k in ("dx", "dy") if k in e})
-        if e.get("scroll"):
-            out.append({"scroll": [0, -(e.get("dy") or 0) * PAD_NOTCH]})
-        for flag, button in PAD_CLICKS.items():
-            if e.get(flag):
-                out += [{"button": button, "down": True}, {"button": button, "down": False}]
-        if e.get("doubleclick"):
-            out += [{"button": "left", "down": d} for d in (True, False, True, False)]
-        if e.get("singlehold"):
-            out.append({"button": "left", "down": True})
-        if e.get("singlerelease"):
-            out.append({"button": "left", "down": False})
-        if kde and ("key" in e or "specialKey" in e):
-            slow.append({k: e[k] for k in ("key", "specialKey", "ctrl", "alt", "shift", "super") if k in e})
-            continue
-        if "specialKey" in e and e["specialKey"] in PAD_KEYS:
-            tap(PAD_KEYS[e["specialKey"]], mods)
-        if "key" in e:
-            for ch in e["key"]:
-                if ch not in ascii_keys:
-                    continue  # only reached when kde is wrong; the caller checks typed_in_kde first
-                elif mods:
-                    code, shifted = ascii_keys[ch]
-                    tap(code, mods + ([42] if shifted and 42 not in mods else []))
-                else:
-                    if out and "text" in out[-1] and len(out[-1]["text"]) < 100:
-                        out[-1]["text"] += ch
-                    else:
-                        out.append({"text": ch})
-    return out, slow
-
-
 def remote_input(body):
-    """{"events": [...]} sends keyboard and pointer events; {} (or none yet) just starts the agent.
-
-    "sent" in the answer means the whole batch is taken (the page keeps it and tries again
-    if not), so the keyboard's share is queued only once that's so.
-    """
+    """{"events": [...]} sends keyboard and pointer events; {} (or none yet) just starts the agent."""
     events = body.get("events", [])
     if not isinstance(events, list) or len(events) > INPUT_BATCH_LIMIT:
         raise Failure(f"events must be a list of at most {INPUT_BATCH_LIMIT}", 400)
-    events = [input_event(e) for e in events]
-    touch, slow = pad_events(events, typed_in_kde(events))
-    status = _touch.send(touch)
-    if touch and not status.get("sent"):
-        return status
-    if touch:
-        _note_typed(touch)
-    if slow:
-        _queue_for_kde(slow)
-    return {**status, "sent": True}
-
-
-# Typing KDE Connect is to do: it starts the first time it's needed, so this waits for it.
-# Nothing on the Frame says when typed text has landed, so each way holds the other back
-# for as long as what it was given should take (a short margin on a time estimate).
-_kde_queue = []
-_kde_lock = threading.Lock()
-_kde_worker = [None]
-_kde_until = 0.0     # keys typed through KDE Connect should have landed by then
-_typed_until = 0.0   # when gamescope's agent will have typed everything it's been given
-KDE_QUEUE_LIMIT = 200
-KDE_WAIT = 90  # seconds to wait for KDE Connect before giving up on what's queued
-TYPING_SETTLE = 0.6  # seconds past the estimate, once
-
-
-def typing_seconds(touch):
-    """How long gamescope's agent takes over these: it sleeps 8 ms after every key transition."""
-    transitions = 0
-    for e in touch:
-        if "text" in e:
-            transitions += sum(2 + 2 * frame_touch.ASCII[ch][1] for ch in e["text"] if ch in frame_touch.ASCII)
-        elif "key" in e:
-            transitions += 1
-    return transitions * 0.008
-
-
-def _note_typed(touch):
-    global _typed_until
-    seconds = typing_seconds(touch)
-    if seconds:
-        with _kde_lock:  # the end of the work, which queues up; the margin is added once, where it's checked
-            _typed_until = max(_typed_until, time.time()) + seconds
-
-
-def _queue_for_kde(events):
-    with _kde_lock:
-        _kde_queue.extend(events)
-        del _kde_queue[:-KDE_QUEUE_LIMIT]
-        if _kde_worker[0] is None:
-            _kde_worker[0] = threading.Thread(target=_drain_kde, daemon=True)
-            _kde_worker[0].start()
-
-
-def _drain_kde():
-    """The only sender, in order. A batch leaves the queue while it's being sent (the queue
-    can be trimmed meanwhile) and goes back to the front if it didn't go."""
-    global _kde_until
-    deadline = time.time() + KDE_WAIT
-    while True:
-        with _kde_lock:
-            batch = _kde_queue[:INPUT_BATCH_LIMIT]
-            del _kde_queue[:len(batch)]
-            if not batch:
-                _kde_worker[0] = None  # retired under the lock, so a new request starts another
-                return
-            wait = _typed_until + TYPING_SETTLE - time.time()
-            _kde_until = time.time() + 3600  # held while in flight
-        if wait > 0:
-            time.sleep(wait)  # gamescope's typing, from just before, goes first
-        status = _input.send(batch)
-        with _kde_lock:
-            if status.get("sent"):
-                _kde_until = time.time() + len(batch) * 0.03 + TYPING_SETTLE
-                deadline = time.time() + KDE_WAIT
-                continue
-            _kde_until = 0.0
-            if status.get("state") == "error" or time.time() > deadline:
-                _kde_queue.clear()  # not coming; don't hold it forever
-                _kde_worker[0] = None
-                return
-            _kde_queue[:0] = batch
-            del _kde_queue[:-KDE_QUEUE_LIMIT]  # as when queuing: the oldest go first
-        time.sleep(0.4)
-
-
-# ---- touch: the headset's panels, through gamescope's own input (frame_touch.py) ----
-
-PANEL_WINDOW = re.compile(r"^\d{1,10}$")
-PANEL_DISPLAY = re.compile(r"^:\d{1,2}$")
-TOUCH_BUTTONS = ("left", "right", "middle")
-
-
-def panels():
-    """The headset's app panels (window, display, name, size) and which has focus."""
-    return json.loads(ssh("python3 - panels", stdin=(HERE / "frame_touch.py").read_text(), timeout=20))
-
-
-def panel_target(q):
-    window, display = (q.get("window") or [""])[0], (q.get("display") or [""])[0]
-    if not PANEL_WINDOW.match(window) or not PANEL_DISPLAY.match(display):
-        raise Failure("window must be a window id and display an X display such as :1", 400)
-    return window, display
-
-
-def panel_capture(query):
-    """One frame of a panel's own window, as PNG (its pixels, without the room around it)."""
-    window, display = panel_target(parse_qs(query))
-    return ssh(f"DISPLAY={display} timeout 10 ffmpeg -hide_banner -loglevel error -nostdin -f x11grab "
-               f"-window_id {window} -i {display} -frames:v 1 -f image2pipe -c:v png -", timeout=20, text=False)
-
-
-def touch_event(event):
-    """A frame_touch.py event with only the fields it knows, in range."""
-    if not isinstance(event, dict):
-        raise Failure("each touch event must be an object", 400)
-
-    def num(name, limit):
-        value = event.get(name)
-        if isinstance(value, bool) or not isinstance(value, (int, float)) or value != value:
-            raise Failure(f"{name} must be a number", 400)
-        return max(-limit, min(limit, round(float(value), 4)))
-    out = {}
-    if "fx" in event or "fy" in event:
-        if "window" not in event:
-            raise Failure("a position needs the panel's window and display", 400)
-        out.update(fx=num("fx", 1), fy=num("fy", 1))
-    # Any event can name the panel it's meant for; the Frame drops it if another has focus.
-    if "window" in event:
-        window, display = event.get("window"), event.get("display")
-        if isinstance(window, bool) or not isinstance(window, int) or window <= 0:
-            raise Failure("window must be the panel's window id", 400)
-        if not isinstance(display, str) or not PANEL_DISPLAY.match(display):
-            raise Failure("display must be an X display such as :1", 400)
-        out.update(window=window, display=display)
-    for name in ("dx", "dy"):
-        if name in event:
-            out[name] = num(name, INPUT_MOVE_LIMIT)
-    if "button" in event:
-        if event["button"] not in TOUCH_BUTTONS:
-            raise Failure(f"button must be one of {', '.join(TOUCH_BUTTONS)}", 400)
-        out["button"], out["down"] = event["button"], event.get("down") is not False
-    if "scroll" in event:
-        sc = event["scroll"]
-        if not isinstance(sc, list) or len(sc) != 2:
-            raise Failure("scroll must be [dx, dy]", 400)
-        out["scroll"] = [num_value(v, 5000) for v in sc]
-    if "key" in event:
-        key = event["key"]
-        if isinstance(key, bool) or not isinstance(key, int) or not 0 < key < 768:
-            raise Failure("key must be a Linux key code", 400)
-        out["key"], out["down"] = key, event.get("down") is not False
-    if "text" in event:
-        text = event["text"]
-        if not isinstance(text, str) or not 0 < len(text) <= INPUT_TEXT_LIMIT:
-            raise Failure(f"text must be 1 to {INPUT_TEXT_LIMIT} characters", 400)
-        out["text"] = text
-    if not set(out) - {"window", "display"}:
-        raise Failure("touch event has nothing to do", 400)
-    return out
-
-
-def num_value(value, limit):
-    if isinstance(value, bool) or not isinstance(value, (int, float)) or value != value:
-        raise Failure("scroll values must be numbers", 400)
-    return max(-limit, min(limit, round(float(value), 2)))
-
-
-class TouchAgent(InputAgent):
-    """frame_touch.py on the Frame, fed events over one long-lived ssh. Nothing to install:
-    it uses gamescope's own input socket and the libei that's on the image."""
-
-    def __init__(self):
-        super().__init__(source=HERE / "frame_touch.py", packages=[])
-
-    def deliver(self, report, force=False):
-        return ""
-
-    def command(self, folder=""):
-        code = base64.b64encode(self.source.read_bytes()).decode()
-        return "python3 -u -c " + shlex.quote(
-            f"import base64;exec(compile(base64.b64decode('{code}'),'frame_touch','exec'))")
-
-
-_touch = TouchAgent()
-
-
-def remote_touch(body):
-    """{"events": [...]} points, clicks, scrolls and types into the focused panel."""
-    events = body.get("events", [])
-    if not isinstance(events, list) or len(events) > INPUT_BATCH_LIMIT:
-        raise Failure(f"events must be a list of at most {INPUT_BATCH_LIMIT}", 400)
-    return _touch.send([touch_event(e) for e in events])
+    return _input.send([input_event(e) for e in events])
 
 
 # ---- touch: the headset's panels, through gamescope's own input (frame_touch.py) ----
@@ -1462,6 +1265,8 @@ def open_thing(body):
                 raise Failure("That screenshot isn't saved on this computer yet", 404)
             frame_host.reveal_path(saved)
             return {"message": f"Showed {saved.name} in {frame_host.FILE_MANAGER}"}
+    except frame_host.Unreachable as e:
+        raise Failure(str(e), 400)  # theirs to turn on; nothing failed here
     except frame_host.HostError as e:
         raise Failure(str(e), 500)
     raise Failure("unknown target", 400)
@@ -1489,8 +1294,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"):
@@ -1521,7 +1326,7 @@ def android(body):
                      " and shared it" if frame_telemetry.enabled("compat") else " on this computer")
             return {"message": f"Saved your report for {name}{where}", "report": r}
     except frame_android.FrameError as e:
-        raise Failure(str(e))
+        raise Failure(str(e)) from e  # from e: keeps frame_host.link_failure's mark for diagnostics
     raise Failure("unknown action", 400)
 
 
@@ -1538,8 +1343,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"))
@@ -1658,7 +1467,7 @@ def titles(body):
     try:
         m = getattr(frame_titles, action)(gid)
     except frame_android.FrameError as e:
-        raise Failure(str(e))
+        raise Failure(str(e)) from e  # from e: keeps frame_host.link_failure's mark for diagnostics
     return {"message": f"{'Launching' if action == 'launch' else 'Removed'} {m['id']}"}
 
 
@@ -2078,8 +1887,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)
@@ -2156,23 +1969,36 @@ def _pid_alive(pid):
     return True
 
 
-def sweep_tmp():
-    """Delete download and title staging folders left by a server killed mid-install.
+def _tmp_places():
+    """Where each kind of staging folder goes, and its name before the server's PID."""
+    tmp = Path(tempfile.gettempdir())
+    return [(tmp, WEB_TMP_PREFIX), (tmp, frame_titles.TMP_PREFIX), (tmp, frame_android.TMP_PREFIX),
+            (tmp, frame_agent.TMP_PREFIX), (frame_host.cache_dir("apk-sources"), apk_fdroid.TMP_PREFIX)]
 
-    Folders carry the server's PID, so only a dead server's are taken.
+
+def sweep_tmp(own=False):
+    """Delete staging folders (downloads, unzipped titles, patched APKs, staged files,
+    app-index downloads) left by a server that stopped mid-way.
+
+    Folders carry the server's PID, so only a dead server's are taken; own=True (on
+    the way out, see main) takes this server's too.
     """
-    for prefix in (WEB_TMP_PREFIX, frame_titles.TMP_PREFIX):
-        for d in Path(tempfile.gettempdir()).glob(f"{prefix}*"):
-            _sweep_one(prefix, d)
+    for folder, prefix in _tmp_places():
+        try:
+            found = list(folder.glob(f"{prefix}*"))
+        except OSError:
+            continue
+        for d in found:
+            _sweep_one(prefix, d, own)
 
 
-def _sweep_one(prefix, d):
+def _sweep_one(prefix, d, own=False):
     m = re.fullmatch(re.escape(prefix) + r"(\d+)-.*", d.name)
     if not m:
         return
     pid = int(m[1])
     try:
-        if pid != os.getpid() and not _pid_alive(pid) and d.is_dir():
+        if (own if pid == os.getpid() else not _pid_alive(pid)) and d.is_dir():
             shutil.rmtree(d, ignore_errors=True)
     except OSError:
         pass
@@ -2353,11 +2179,14 @@ def source_search(query):
     q = args.get('q', [''])[0]
     vr = args.get('vr', [''])[0]
     installable = args.get('installable', [''])[0]
-    if len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '0'):
+    category, phone = args.get('category', [''])[0], args.get('phone', [''])[0]
+    if (len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '0')
+            or phone not in ('', 'true', 'false', '1', '0') or len(category) > 40):
         raise Failure('Invalid search filters', 400)
     try:
         return apk_search.search(q, vr=None if not vr else vr in ('true', '1'),
-                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'))
+                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'),
+                                 category=category or None, phone=phone in ('true', '1'))
     except SourceError as e:
         raise Failure(str(e), 400)
 
@@ -2475,6 +2304,10 @@ def connection_state():
 
 # ---- HTTP ------------------------------------------------------------------
 
+# POST reads the page repeats on a timer, as (path, action).
+POLLS = {("/api/comfort", "status")}
+
+
 def action_of(body):
     """The action a request asked for, for diagnostics: a short word, never user data."""
     a = body.get("action") if isinstance(body, dict) else None
@@ -2517,7 +2350,7 @@ def push_file(path, dest="Downloads/"):
         else:
             # Modern scp uses SFTP, so the remote path isn't parsed by a shell.
             cmd = ["scp", *SSH[1:], "-r", str(path), f"{FRAME}:{dest}"]
-        r = subprocess.run(cmd, capture_output=True, stdin=subprocess.DEVNULL, text=True, errors="replace", timeout=3600)
+        r = frame_host.run_ssh(cmd, capture_output=True, stdin=subprocess.DEVNULL, text=True, errors="replace", timeout=3600)
     except subprocess.TimeoutExpired:
         raise Failure(f"Copying {name} timed out")
     if r.returncode != 0:
@@ -2525,6 +2358,11 @@ def push_file(path, dest="Downloads/"):
     return f"Sent {name} to ~/{dest}"
 
 
+class ClientGone(Exception):
+    """The page went away (a reload, the app quitting) before its reply was written:
+    nobody to answer, and nothing went wrong here."""
+
+
 class Handler(BaseHTTPRequestHandler):
     server_version = "FrameControl/1"
     timeout = 60  # per socket operation, so a stalled client can't hold a thread
@@ -2557,8 +2395,11 @@ class Handler(BaseHTTPRequestHandler):
         # Nobody may frame the UI (clickjacking).
         self.send_header("X-Frame-Options", "DENY")
         self.send_header("Content-Security-Policy", "frame-ancestors 'none'")
-        self.end_headers()
-        self.wfile.write(data)
+        try:
+            self.end_headers()
+            self.wfile.write(data)
+        except ConnectionError as e:  # Windows says ConnectionAbortedError, others BrokenPipeError
+            raise ClientGone() from e
 
     def send_json(self, obj, status=200):
         self.send_bytes(json.dumps(obj).encode(), "application/json", status)
@@ -2577,10 +2418,17 @@ class Handler(BaseHTTPRequestHandler):
         try:
             if path in ("/", "/index.html"):
                 self.send_bytes((HERE / "index.html").read_bytes(), "text/html; charset=utf-8")
+            elif path == "/store":
+                # The Android store as a headset panel (scripts/store-on-frame.sh).
+                self.send_bytes((HERE / "store.html").read_bytes(), "text/html; charset=utf-8")
             elif path == "/api/settings/artwork":
                 self.send_json(frame_steamgriddb.settings())
             elif path == "/artwork-settings.js":
                 self.send_bytes((HERE / 'artwork-settings.js').read_bytes(), 'text/javascript; charset=utf-8')
+            elif path == "/control-center.js":
+                self.send_bytes((HERE / 'control-center.js').read_bytes(), 'text/javascript; charset=utf-8')
+            elif path == "/control-center.css":
+                self.send_bytes((HERE / 'control-center.css').read_bytes(), 'text/css; charset=utf-8')
             elif path == "/assistant":
                 page = (HERE / "assistant.html").read_text().replace("__FRAME_KEY__", json.dumps(UI_KEY).replace("<", "\\u003c"))
                 self.send_bytes(page.encode(), "text/html; charset=utf-8")
@@ -2601,6 +2449,8 @@ class Handler(BaseHTTPRequestHandler):
                 from apk_sources import _images
                 try:
                     self.send_bytes(*_images.image(path.rsplit("/", 1)[-1]))
+                except ClientGone:
+                    raise
                 except Exception:
                     self.send_json({"error": "Artwork unavailable"}, 404)
             elif path == "/api/sources/details":
@@ -2620,7 +2470,12 @@ class Handler(BaseHTTPRequestHandler):
                 ensure_master()
                 apps = frame_android.list_apps()
                 backfill_art(apps=apps)
-                self.send_json({"apps": apps})
+                try:  # store artwork for the library's cards, from saved indexes only
+                    art = apk_search.artwork_for(apps)
+                except Exception:
+                    art = {}
+                self.send_json({"apps": [dict(a, store_art=art[a['package']]) if a.get('package') in art else a
+                                         for a in apps]})
             elif path == "/api/titles":
                 ensure_master()
                 titles_list = frame_titles.list_titles()
@@ -2635,7 +2490,7 @@ class Handler(BaseHTTPRequestHandler):
             elif path == "/api/touch":
                 self.send_json(_touch.send([]) if parse_qs(url.query).get("start") == ["1"] else dict(_touch.status))
             elif path == "/api/input":
-                self.send_json(_touch.send([]) if parse_qs(url.query).get("start") == ["1"] else dict(_touch.status))
+                self.send_json(_input.send([]) if parse_qs(url.query).get("start") == ["1"] else dict(_input.status))
             elif path == "/api/job":
                 self.send_json(job_status(url.query))
             elif path == "/api/android/displays":
@@ -2678,6 +2533,8 @@ class Handler(BaseHTTPRequestHandler):
                                 headers=[("X-Capture-Source", "gamescope")])
             else:
                 self.send_json({"error": "not found"}, 404)
+        except ClientGone:
+            raise
         except Failure as e:
             self.send_error_json(str(e), e.status, e.apk)
         except ValueError as e:
@@ -2709,11 +2566,17 @@ class Handler(BaseHTTPRequestHandler):
             body = json.loads(self.rfile.read(length) or b"{}")
             if not isinstance(body, dict):
                 raise Failure("request body must be a JSON object", 400)
-            with (contextlib.nullcontext() if path == "/api/devices" else working(meant)):
+            # Not headset work: switching headsets mustn't wait for (or refuse) these.
+            with (contextlib.nullcontext() if path in NOT_HEADSET_WORK else working(meant)):
                 result = handler(body)
             self.send_json(result)
+        except ClientGone:
+            raise
         except Failure as e:
-            if e.status >= 500:
+            # A poll that couldn't reach the headset is the headset asleep or away, which the page
+            # already shows; like GET /api/status, not an error to report.
+            polled = (path, action_of(body)) in POLLS and frame_telemetry.link_failed(e)
+            if e.status >= 500 and not polled:
                 frame_telemetry.diagnostic(f"POST {path} {action_of(body)}", e)
             self.send_error_json(str(e), e.status, e.apk)
         except (ValueError, TypeError) as e:
@@ -2887,6 +2750,10 @@ class LoopbackServer(ThreadingHTTPServer):
         socketserver.TCPServer.server_bind(self)
         self.server_name, self.server_port = "127.0.0.1", self.server_address[1]
 
+    def handle_error(self, request, client_address):
+        if not isinstance(sys.exc_info()[1], ClientGone):
+            super().handle_error(request, client_address)
+
 
 _ONE_SERVER = None
 
@@ -2925,6 +2792,8 @@ def main():
         LINK = frame_link.Link(frame_devices.Registry(), env_alias=FRAME if FRAME_FROM_ENV else None,
                                mux_base=MUX_BASE, control=CONTROL, apply=route, explain=unreachable)
         LINK.work_lock, LINK.work = _work_lock, lambda: _work[0]
+        frame_report.link = LINK  # its connection summary goes in every report's diagnostics
+        frame_report.start_ssh_check()  # ...with which ssh this is, found once in the background
         LINK.start()
     if not frame_host.WINDOWS:
         signal.signal(signal.SIGTERM, lambda *_: (_ for _ in ()).throw(KeyboardInterrupt))
@@ -2957,6 +2826,22 @@ def main():
             if proc.poll() is None:
                 proc.terminate()
         _purge_titles(now=float("inf"))  # unconfirmed title uploads
+        # Staging folders of work still running (a patched APK mid-copy, an index
+        # download): leaving below skips the cleanup their TemporaryDirectory would
+        # get at interpreter exit. sweep_tmp at the next start catches any missed.
+        sweep_tmp(own=True)
+    # Stopped as asked, and everything above is cleaned up. Leave now, without
+    # Python's interpreter teardown: daemon threads are still running (app index
+    # downloads, the stdin watcher, telemetry, the headset link, request handlers)
+    # and none can be stopped promptly. Tearing the interpreter down under them
+    # occasionally crashed the process (SIGSEGV, seen on Python 3.13 on Linux):
+    # OpenSSL's exit cleanup freed state those threads were using. That teardown
+    # also runs atexit handlers and weakref finalizers; nothing here registers
+    # atexit work, the only finalizers are TemporaryDirectory cleanups (swept
+    # above), and the OS frees the one-server lock with the process.
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(0)
 
 
 if __name__ == "__main__":

ui/store.html

@@ -0,0 +1,489 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>APK Store</title>
+<!-- Frame Control's Android store as a panel in the headset (docs/apks.md →
+     "The store in the headset"). Served by ui/server.py running on the Frame
+     (FRAME_LOCAL=1), opened by scripts/store-on-frame.sh at 1280×800. The same
+     sources, categories and artwork as the Store in Frame Control (/api/search,
+     ui/apk_sources/_categories.py), drawn for the laser: big targets, pages
+     instead of drag-scrolling (the panel gets mouse clicks, so a drag would
+     select text), the thumbstick (a mouse wheel) turns pages, and an on-screen
+     keyboard for search. -->
+<style>
+  :root {
+    --bg: #0f1722; --rail: #131d2a; --card: #1b2938; --card-hi: #23364a; --line: #ffffff14;
+    --text: #e3e8ee; --bright: #fff; --dim: #93a4ba; --blue: #1a9fff; --link: #66c0f4;
+    --good: #8ed36b; --bad: #ef7a64;
+    --action: linear-gradient(to right, #47bfff 5%, #1a44c2 95%);
+    --play: linear-gradient(to right, #75b022 5%, #588a1b 95%);
+  }
+  * { box-sizing: border-box; }
+  [hidden] { display: none !important; }
+  html, body { margin: 0; height: 100%; background: radial-gradient(ellipse at 70% -20%, #1d3a5a 0%, transparent 60%), var(--bg);
+    color: var(--text); font: 19px/1.35 "Motiva Sans", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    overflow: hidden; user-select: none; -webkit-user-select: none; }
+  button { font: inherit; color: inherit; background: #ffffff0d; border: 1px solid var(--line); border-radius: 12px;
+    min-height: 52px; padding: 0 20px; cursor: pointer; }
+  button:hover { background: #ffffff1c; }
+  button:disabled { opacity: .45; cursor: default; }
+  button.primary { background: var(--action); border: 0; font-weight: 600; color: #fff; }
+  button.play { background: var(--play); border: 0; font-weight: 600; color: #fff; }
+  button.danger { color: var(--bad); }
+  svg { width: 22px; height: 22px; flex: none; }
+  .app { display: grid; grid-template-columns: 236px 1fr; height: 100%; }
+  /* Rail */
+  .rail { background: #0c131ccc; border-right: 1px solid var(--line); padding: 18px 12px; display: flex; flex-direction: column; gap: 3px; }
+  .rail h1 { font-size: 22px; margin: 2px 10px 12px; display: flex; align-items: center; gap: 10px; color: var(--bright); }
+  .rail h1 svg { width: 28px; height: 28px; color: var(--blue); }
+  .rail button { display: flex; align-items: center; gap: 12px; width: 100%; min-height: 47px; text-align: left; border: 0;
+    background: transparent; color: #b5c0cb; font-size: 17px; font-weight: 500; padding: 0 12px; border-radius: 10px; }
+  .rail button:hover { background: #ffffff10; color: var(--bright); }
+  .rail button[aria-pressed="true"] { background: #1a9fff2e; color: var(--bright); box-shadow: inset 4px 0 0 var(--blue); }
+  .rail .sep { height: 1px; background: var(--line); margin: 6px 8px; }
+  .rail .n { margin-left: auto; font-size: 13px; color: #c6e2f5; background: #1a9fff2e; border-radius: 10px; padding: 1px 8px; }
+  .rail .n:empty { display: none; }
+  .rail label { margin-top: auto; display: flex; align-items: center; gap: 10px; padding: 10px 12px; font-size: 15px; color: var(--dim); cursor: pointer; }
+  .rail input { width: 22px; height: 22px; accent-color: var(--blue); margin: 0; }
+  /* Main */
+  main { display: flex; flex-direction: column; min-width: 0; padding: 18px 22px; gap: 12px; }
+  .bar { display: flex; gap: 12px; align-items: center; }
+  .search { flex: 1; display: flex; align-items: center; gap: 12px; background: #0c1520; border: 1px solid var(--line);
+    border-radius: 12px; min-height: 54px; padding: 0 18px; color: var(--dim); }
+  .search input { flex: 1; background: none; border: 0; color: var(--text); font: inherit; outline: none; min-width: 0; }
+  .search input::placeholder { color: var(--dim); }
+  .heading { display: flex; align-items: baseline; gap: 14px; min-height: 30px; }
+  .heading b { color: var(--bright); font-size: 25px; letter-spacing: -.4px; }
+  .heading span { color: var(--dim); font-size: 16px; }
+  .heading .note { margin-left: auto; font-size: 14px; color: var(--dim); max-width: 520px; text-align: right; }
+  .content { flex: 1; min-height: 0; display: flex; flex-direction: column; gap: 14px; }
+  .grid { flex: 1; min-height: 0; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); grid-template-rows: repeat(2, minmax(0, 1fr)); gap: 14px; }
+  .grid.one-row { grid-template-rows: minmax(0, 1fr); }
+  .card { display: flex; flex-direction: column; padding: 0; overflow: hidden; text-align: left; min-height: 0; border-radius: 14px;
+    background: var(--card); border: 1px solid var(--line); }
+  .card:hover { background: var(--card-hi); border-color: #66c0f480; }
+  .card .art { flex: 0 0 52%; }
+  .card .body { display: flex; flex-direction: column; gap: 6px; padding: 10px 12px 12px; min-height: 0; flex: 1; width: 100%; }
+  .card .title { display: flex; align-items: center; gap: 10px; min-width: 0; }
+  .card .title strong { font-size: 17px; color: var(--bright); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
+  .card .sum { color: var(--dim); font-size: 14px; line-height: 1.35; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+  .card .foot { margin-top: auto; display: flex; justify-content: space-between; align-items: center; gap: 6px; font-size: 13px; color: var(--dim); }
+  /* Artwork: a banner, else screenshots side by side, else the icon over its own blur, else an initial. */
+  .art { position: relative; display: block; overflow: hidden; width: 100%;
+    background: radial-gradient(ellipse at 75% 10%, hsl(var(--hue) 50% 40%), transparent 70%), linear-gradient(140deg, hsl(var(--hue) 35% 18%), #101827); }
+  .art > img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+  .art .initial { position: absolute; inset: 0; display: grid; place-items: center; font-size: 64px; font-weight: 700; color: #ffffff45; }
+  .art.shots { display: flex; gap: 6px; justify-content: center; padding: 8px 8px 0; }
+  .art.shots > img { position: relative; inset: auto; width: auto; max-width: 31%; height: 100%; object-position: top; border-radius: 6px 6px 0 0; box-shadow: 0 4px 14px #0008; }
+  .art.iconart > .backdrop { position: absolute; inset: -30%; width: 160%; height: 160%; object-fit: cover; filter: blur(28px) saturate(1.4) brightness(.55); }
+  .art.iconart > .mark { position: absolute; left: 50%; top: 50%; width: 36%; height: auto; aspect-ratio: 1; transform: translate(-50%, -50%); border-radius: 22%; box-shadow: 0 8px 24px #0009; object-fit: cover; }
+  .art.shots .initial, .art.iconart .initial { display: none; }
+  .art .vr { position: absolute; z-index: 2; top: 8px; left: 8px; }
+  .icon { position: relative; display: inline-grid; place-items: center; width: 38px; height: 38px; border-radius: 9px; overflow: hidden; flex: none;
+    background: hsl(var(--hue) 35% 28%); color: #fff; font-size: 18px; font-weight: 600; }
+  .icon img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+  .vr { font-size: 12px; font-weight: 700; letter-spacing: .8px; color: #0e141b; background: #c2e7ff; border-radius: 5px; padding: 2px 7px; }
+  .fit { font-size: 12px; font-weight: 600; border-radius: 5px; padding: 2px 8px; white-space: nowrap; }
+  .fit.works { color: #c3efb2; background: #59bf4029; } .fit.ready { color: #bfe3fa; background: #1a9fff26; } .fit.blocked { color: #f3b2a6; background: #d9412629; }
+  .tag { font-size: 12px; font-weight: 600; color: #d6f5c8; background: #2d5a1f; border-radius: 10px; padding: 2px 9px; white-space: nowrap; }
+  /* Home */
+  .hero { position: relative; flex: 0 0 42%; padding: 0; border: 0; border-radius: 16px; overflow: hidden; text-align: left; isolation: isolate; }
+  .hero .art { position: absolute; inset: 0; height: 100%; }
+  .hero::after { content: ""; position: absolute; inset: 0; z-index: 1; background: linear-gradient(90deg, #081421f0 0%, #08142180 50%, #08142100 85%); }
+  .hero .copy { position: relative; z-index: 2; padding: 26px 30px; max-width: 560px; display: flex; flex-direction: column; gap: 10px; align-items: flex-start; }
+  .hero .eyebrow { display: flex; gap: 10px; align-items: center; font-size: 13px; font-weight: 700; letter-spacing: 1.6px; text-transform: uppercase; color: #c2e7ff; }
+  .hero strong { font-size: 38px; color: #fff; line-height: 1.05; letter-spacing: -.8px; }
+  .hero .blurb { color: #e0e8ef; font-size: 17px; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+  .hero .cta { margin-top: 4px; background: #ffffff22; border: 1px solid #ffffff44; border-radius: 10px; padding: 9px 18px; font-size: 16px; color: #fff; }
+  /* Pager */
+  .pager { display: flex; justify-content: space-between; align-items: center; gap: 12px; }
+  .pager button { min-width: 180px; }
+  .dots { display: flex; gap: 8px; align-items: center; color: var(--dim); font-size: 15px; }
+  .empty { grid-column: 1 / -1; grid-row: 1 / -1; display: grid; place-items: center; align-content: center; gap: 14px; color: var(--dim); text-align: center; padding: 30px; }
+  .empty h2 { margin: 0; color: var(--bright); font-size: 24px; }
+  .skeleton { border-radius: 14px; background: linear-gradient(100deg, #1b2938 30%, #24364a 50%, #1b2938 70%); background-size: 300% 100%; animation: shimmer 1.4s infinite; }
+  @keyframes shimmer { to { background-position: -150% 0; } }
+  /* Detail sheet and keyboard sit over everything. */
+  .overlay { position: fixed; inset: 0; background: #000b; display: grid; place-items: center; z-index: 10; }
+  .sheet { background: #16212e; border: 1px solid var(--line); border-radius: 22px; width: 1000px; max-height: 740px; overflow: hidden;
+    display: flex; flex-direction: column; box-shadow: 0 30px 80px #000c; }
+  .sheet > .art { flex: 0 0 250px; }
+  .sheet .gallery { flex: 0 0 250px; display: flex; gap: 10px; padding: 14px 14px 0; background: #0c131c; justify-content: center; overflow: hidden; }
+  .sheet .gallery img { height: 100%; width: auto; max-width: 32%; object-fit: cover; object-position: top; border-radius: 10px 10px 0 0; }
+  .sheet .inner { padding: 20px 28px 22px; display: flex; flex-direction: column; gap: 12px; flex: 1; min-height: 0; }
+  .sheet .top { display: flex; gap: 18px; align-items: center; }
+  .sheet .top .icon { width: 72px; height: 72px; border-radius: 16px; font-size: 32px; }
+  .sheet h2 { margin: 0; font-size: 30px; color: var(--bright); line-height: 1.1; }
+  .sheet .meta { color: var(--dim); font-size: 16px; }
+  .sheet .text { font-size: 17px; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+  .sheet .why { background: #ffffff0a; border-radius: 12px; padding: 10px 16px; font-size: 15px; color: #c5d0db; }
+  .sheet .why ul { margin: 4px 0 0; padding-left: 22px; }
+  .sheet .acts { display: flex; gap: 12px; flex-wrap: wrap; margin-top: 8px; align-items: center; }
+  .sheet .acts .close { margin-left: auto; }
+  .progress { flex: 1; min-width: 260px; display: flex; flex-direction: column; gap: 6px; font-size: 15px; color: var(--dim); }
+  .progress .track { height: 8px; border-radius: 4px; background: #ffffff14; overflow: hidden; }
+  .progress .fill { height: 100%; background: var(--blue); width: 30%; transition: width .3s; }
+  .progress.busy .fill { animation: busy 1.2s ease-in-out infinite; }
+  @keyframes busy { from { margin-left: -30%; } to { margin-left: 100%; } }
+  .kbd { position: fixed; left: 0; right: 0; bottom: 0; background: #131d2af5; border-top: 1px solid var(--line);
+    padding: 12px; display: grid; gap: 8px; z-index: 20; box-shadow: 0 -20px 50px #0009; }
+  .kbd .row { display: flex; gap: 8px; justify-content: center; }
+  .kbd button { min-width: 76px; min-height: 60px; padding: 0 10px; font-size: 21px; }
+  .kbd .wide { min-width: 320px; }
+  .toast { position: fixed; left: 50%; top: 18px; transform: translateX(-50%); background: #0d2236; border: 1px solid var(--blue);
+    border-radius: 14px; padding: 12px 20px; z-index: 30; max-width: 900px; box-shadow: 0 10px 30px #0008; }
+  .toast.bad { background: #3a1416; border-color: var(--bad); }
+</style>
+</head>
+<body>
+<div class="app">
+  <div class="rail" role="navigation" aria-label="Store">
+    <h1><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><path d="M4 7h16l-1.5 12.5a1 1 0 0 1-1 .9H6.5a1 1 0 0 1-1-.9z"/><path d="M8.5 9V6a3.5 3.5 0 0 1 7 0v3"/></svg>APK Store</h1>
+    <div id="cats"></div>
+    <div class="sep"></div>
+    <button data-view="installed" aria-pressed="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true"><rect x="3.5" y="4" width="7" height="7" rx="1.5"/><rect x="13.5" y="4" width="7" height="7" rx="1.5"/><rect x="3.5" y="14" width="7" height="7" rx="1.5"/><rect x="13.5" y="14" width="7" height="7" rx="1.5"/></svg>Installed<span class="n" id="instN"></span></button>
+    <label title="Apps built around a phone: calls and SMS, launchers, keyboards, widgets, fitness, system tools. Searching always finds them."><input type="checkbox" id="phone"> Show phone-only apps</label>
+  </div>
+  <main>
+    <div class="bar">
+      <label class="search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 5 5"/></svg><input id="q" placeholder="Search games and apps" autocomplete="off" spellcheck="false" aria-label="Search games and apps"></label>
+      <button id="kbdBtn" title="On-screen keyboard">⌨︎ Keyboard</button>
+    </div>
+    <div class="heading"><b id="title">Home</b><span id="count"></span><span class="note" id="note"></span></div>
+    <div class="content" id="content"></div>
+    <div class="pager">
+      <button id="prev">◀ Previous</button>
+      <span class="dots" id="page"></span>
+      <button id="next">Next ▶</button>
+    </div>
+  </main>
+</div>
+
+<div class="overlay" id="detail" hidden><div class="sheet" id="sheet"></div></div>
+<div class="kbd" id="kbd" hidden></div>
+<div class="toast" id="toast" hidden></div>
+
+<script>
+const UI_KEY = new URLSearchParams(location.search).get("key") || "1";
+const $ = id => document.getElementById(id);
+const esc = s => String(s ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+const PER_PAGE = 8;
+// Same ids and order as STORE_CATS in index.html and ui/apk_sources/_categories.py.
+const CATS = [
+  ["", "Home", '<path d="M4 11.5 12 5l8 6.5V19a1 1 0 0 1-1 1h-4.5v-5h-5v5H5a1 1 0 0 1-1-1z"/>'],
+  ["vr", "VR", '<path d="M3.5 8.5A1.5 1.5 0 0 1 5 7h14a1.5 1.5 0 0 1 1.5 1.5v6A1.5 1.5 0 0 1 19 16h-3.5l-2-2.5h-3l-2 2.5H5a1.5 1.5 0 0 1-1.5-1.5z"/><circle cx="8" cy="11.5" r="1.5"/><circle cx="16" cy="11.5" r="1.5"/>'],
+  ["games", "Games", '<path d="M7 9h10a4 4 0 0 1 3.9 4.9l-.6 2.6a2 2 0 0 1-3.4.9L14.5 15h-5l-2.4 2.4a2 2 0 0 1-3.4-.9l-.6-2.6A4 4 0 0 1 7 9z"/><path d="M8 11.5v3M6.5 13h3"/>'],
+  ["emulators", "Emulators", '<rect x="4" y="5" width="16" height="11" rx="1.5"/><path d="M9 20h6M12 16v4M8 10.5h3M9.5 9v3"/>'],
+  ["watch", "Watch & listen", '<rect x="3.5" y="5.5" width="17" height="11" rx="1.5"/><path d="m10.5 8.5 4 2.5-4 2.5z"/><path d="M8 20h8"/>'],
+  ["read", "Read & learn", '<path d="M12 7c-2-1.5-5-2-8-1.5v12c3-.5 6 0 8 1.5 2-1.5 5-2 8-1.5v-12c-3-.5-6 0-8 1.5zM12 7v12"/>'],
+  ["create", "Create", '<path d="m14.5 5.5 4 4L9 19H5v-4z"/><path d="m12.5 7.5 4 4"/>'],
+  ["work", "Work", '<rect x="4" y="7" width="16" height="12" rx="1.5"/><path d="M9 7V5.5A1.5 1.5 0 0 1 10.5 4h3A1.5 1.5 0 0 1 15 5.5V7M4 12h16"/>'],
+  ["web", "Web & chat", '<circle cx="12" cy="12" r="8"/><path d="M4 12h16M12 4c2.5 2.5 2.5 13.5 0 16M12 4c-2.5 2.5-2.5 13.5 0 16"/>'],
+  ["tools", "Tools", '<path d="M14.5 6.5a4 4 0 0 0-5.3 5.3L4.5 16.5l3 3 4.7-4.7a4 4 0 0 0 5.3-5.3l-2.4 2.4-2.6-.4-.4-2.6z"/>'],
+];
+const catLabel = id => (CATS.find(c => c[0] === id) || [])[1] || "";
+const FIT = { works: "Works on the Frame", ready: "Fits the Frame", blocked: "Won't run" };
+// view: "" (home), a category id, or "installed"; jobs: offer key -> {stage, percent, done, result, error}
+// installedFrom: offer key -> package it installed as (GitHub listings have no package);
+// needsData: installed packages still waiting for their game data (any view, while installed)
+const st = { view: "", q: "", phone: false, page: 0, apps: [], installed: new Map(), jobs: new Map(), installedFrom: new Map(),
+             needsData: new Set(), request: 0, loading: false, retry: 0 };
+
+async function api(path, body) {
+  const opts = body === undefined ? { headers: { "X-Frame-UI": UI_KEY } } : {
+    method: "POST", headers: { "Content-Type": "application/json", "X-Frame-UI": UI_KEY }, body: JSON.stringify(body) };
+  const r = await fetch(path, opts);
+  const j = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(j.error || `HTTP ${r.status}`);
+  return j;
+}
+let toastTimer;
+function toast(msg, bad = false) {
+  const t = $("toast");
+  t.textContent = msg; t.className = "toast" + (bad ? " bad" : ""); t.hidden = false;
+  clearTimeout(toastTimer); toastTimer = setTimeout(() => t.hidden = true, bad ? 8000 : 4500);
+}
+
+// ---- Artwork (only the server's /source-image/ handles are ever used as an image) ----
+const hue = name => [...String(name)].reduce((n, c) => (n * 31 + c.charCodeAt(0)) >>> 0, 7) % 360;
+const initial = name => [...String(name || "?")][0].toUpperCase();
+const valid = u => /^\/source-image\/[\w-]+$/.test(u || "");
+const img = (u, cls = "") => valid(u) ? `<img${cls ? ` class="${cls}"` : ""} src="${esc(u)}" alt="" decoding="async">` : "";
+function art(name, a = {}, extra = "") {
+  const base = `style="--hue:${hue(name)}"`, ini = `<span class="initial" aria-hidden="true">${esc(initial(name))}</span>`;
+  if (valid(a.banner)) return `<span class="art" ${base}>${ini}${img(a.banner)}${extra}</span>`;
+  const shots = (a.screenshots || []).filter(valid).slice(0, 3);
+  if (shots.length) return `<span class="art shots" ${base}>${ini}${shots.map(u => img(u)).join("")}${extra}</span>`;
+  if (valid(a.icon)) return `<span class="art iconart" ${base}>${ini}${img(a.icon, "backdrop")}${img(a.icon, "mark")}${extra}</span>`;
+  return `<span class="art" ${base}>${ini}${extra}</span>`;
+}
+const icon = (name, a = {}) => `<span class="icon" style="--hue:${hue(name)}" aria-hidden="true">${esc(initial(name))}${img(a.icon)}</span>`;
+document.addEventListener("error", e => {
+  const el = e.target;
+  if (!el.matches?.(".art img, .icon img")) return;
+  if (!el.dataset.retried) { el.dataset.retried = "1"; setTimeout(() => { el.src = el.getAttribute("src").split("?")[0] + "?retry=1"; }, 1500); return; }
+  const box = el.closest(".shots, .iconart"); el.remove();
+  if (box && !box.querySelector("img")) box.classList.remove("shots", "iconart");
+}, true);
+const text = s => String(s || "").replace(/<[^>]*>/g, " ").replace(/&nbsp;/g, " ");
+
+// ---- Data ----
+async function loadInstalled() {
+  try {
+    st.installed = new Map((await api("/api/android")).apps.map(a => [a.package, a]));
+    for (const pkg of st.needsData) if (!st.installed.has(pkg)) { st.needsData.delete(pkg); st.jobs.delete("data:" + pkg); }  // removed
+  } catch (e) { toast(`Couldn't list installed apps: ${e.message}`, true); }
+  $("instN").textContent = st.installed.size || "";
+}
+async function search(quiet) {
+  const request = ++st.request;
+  clearTimeout(st.retry);
+  if (st.view === "installed") { st.loading = false; st.page = 0; return render(); }  // a pending search is now stale
+  st.loading = !quiet; if (!quiet) render();
+  const params = new URLSearchParams({ q: st.q, category: st.view, phone: String(st.phone) });
+  try {
+    const result = await api("/api/search?" + params);
+    if (request !== st.request) return;
+    st.apps = result.apps; st.loading = false;
+    const loading = result.sources.filter(s => s.status === "loading").map(s => s.name);
+    $("note").textContent = loading.length ? `Still fetching ${loading.join(" and ")}; more apps will appear.` : "";
+    if (loading.length) st.retry = setTimeout(() => request === st.request && search(true), 6000);
+    if (!quiet) st.page = 0;
+    render();
+  } catch (e) {
+    if (request !== st.request) return;
+    st.loading = false; st.apps = []; render(`Couldn't reach the app shelves: ${e.message}`);
+  }
+}
+const offerKey = app => `${app.offers[0].source}:${app.offers[0].id}`;
+// Always the latest state: an Installed card's own copy goes stale after Stop or Remove.
+function installedOf(app) {
+  const pkg = app.installed?.package || app.package || st.installedFrom.get(offerKey(app));
+  return pkg ? st.installed.get(pkg) : undefined;
+}
+
+// ---- Pages ----
+function list() {
+  if (st.view === "installed") {
+    const q = st.q.toLowerCase();
+    return [...st.installed.values()].filter(m => !q || `${m.label} ${m.package}`.toLowerCase().includes(q))
+      .map(m => ({ installed: m, name: m.label || m.package, package: m.package, summary: m.version ? `v${String(m.version).replace(/^v/i, "")}` : "",
+                   offers: [{ name: m.label, artwork: m.store_art || {}, vr: m.vr && !m.flatscreen }] }));
+  }
+  return st.home ? st.home.rest : st.apps;
+}
+function card(app, i) {
+  const o = app.offers[0], m = installedOf(app), job = st.jobs.get(offerKey(app));
+  const state = m ? `<span class="tag">${m.running ? "Running" : "Installed"}</span>`
+    : job && !job.done ? `<span class="tag">Installing…</span>`
+    : FIT[o.verdict?.tone] ? `<span class="fit ${o.verdict.tone}">${FIT[o.verdict.tone]}</span>` : "";
+  const kind = o.phone_only ? "Phone app" : catLabel(app.category || o.category) || (m ? (o.vr ? "VR app" : "Android app") : "Android app");
+  return `<button class="card" data-i="${i}" aria-label="${esc(app.name)}">${art(app.name, o.artwork, o.vr ? '<span class="vr">VR</span>' : "")}
+    <span class="body"><span class="title">${icon(app.name, o.artwork)}<strong>${esc(app.name)}</strong></span>
+    <span class="sum">${esc(text(app.summary))}</span><span class="foot"><span>${esc(kind)}</span>${state}</span></span></button>`;
+}
+function render(error) {
+  const home = st.view === "" && !st.q;
+  $("title").textContent = st.q ? `Results for “${st.q}”` : st.view === "installed" ? "Installed" : st.view ? catLabel(st.view) : "Home";
+  document.querySelectorAll("[data-view]").forEach(b => b.setAttribute("aria-pressed", String(b.dataset.view === st.view)));
+  const content = $("content");
+  if (st.loading) {
+    content.innerHTML = `<div class="grid">${Array.from({ length: PER_PAGE }, () => '<div class="skeleton"></div>').join("")}</div>`;
+    $("count").textContent = ""; $("page").textContent = ""; $("prev").disabled = $("next").disabled = true; return;
+  }
+  // Home: a featured VR app and four picks, then pages of one app from each category in turn.
+  st.home = null;
+  if (home && st.apps.length) {
+    const ok = st.apps.filter(a => a.offers[0].verdict?.tone !== "blocked");
+    const heroes = ok.filter(a => a.offers[0].vr && valid(a.offers[0].artwork?.banner));
+    const featured = heroes[Math.floor(Date.now() / 864e5) % (heroes.length || 1)] || ok.find(a => valid(a.offers[0].artwork?.banner));
+    const queues = CATS.slice(1).map(([id]) => ok.filter(a => a.category === id && a !== featured));
+    const mixed = [];
+    for (let i = 0; queues.some(q => q[i]); i++) queues.forEach(q => q[i] && mixed.push(q[i]));
+    st.home = { featured, rest: mixed.slice(0, 4 + 5 * PER_PAGE) };  // six pages of picks; the categories have the rest
+  }
+  const items = list();
+  const first = st.home?.featured ? 4 : PER_PAGE;  // the first home page shares its space with the banner
+  const pages = Math.max(1, items.length <= first ? 1 : 1 + Math.ceil((items.length - first) / PER_PAGE));
+  st.page = Math.min(st.page, pages - 1);
+  const start = st.page === 0 ? 0 : first + (st.page - 1) * PER_PAGE;
+  const shown = items.slice(start, start + (st.page === 0 ? first : PER_PAGE));
+  $("count").textContent = home ? "" : `${items.length.toLocaleString()} app${items.length === 1 ? "" : "s"}`;
+  $("page").textContent = `Page ${st.page + 1} of ${pages}`;
+  $("prev").disabled = st.page === 0; $("next").disabled = st.page >= pages - 1;
+  const empty = error ? `<div class="empty"><h2>No connection</h2>${esc(error)}</div>`
+    : st.view === "installed" && !st.q ? `<div class="empty"><h2>Nothing installed yet</h2>Pick an app in the store and press Install.<button class="primary" data-view="">Browse the store</button></div>`
+    : `<div class="empty"><h2>No apps here</h2>Try another category${st.phone ? "" : ", or show phone-only apps"}.</div>`;
+  let html = "";
+  if (st.page === 0 && st.home?.featured) {
+    const f = st.home.featured, o = f.offers[0];
+    html += `<button class="hero" data-feature="1" aria-label="${esc(f.name)}">${art(f.name, o.artwork)}<span class="copy">
+      <span class="eyebrow">${o.vr ? '<span class="vr">VR</span>' : ""}Featured</span><strong>${esc(f.name)}</strong>
+      <span class="blurb">${esc(text(f.summary))}</span><span class="cta">See ${esc(f.name)} ›</span></span></button>`;
+  }
+  html += `<div class="grid${st.page === 0 && st.home?.featured ? " one-row" : ""}">${shown.length ? shown.map((a, i) => card(a, start + i)).join("") : empty}</div>`;
+  content.innerHTML = html;
+}
+function turn(by) {
+  if (by < 0 ? $("prev").disabled : $("next").disabled) return;
+  st.page += by; render();
+}
+
+// ---- Detail sheet ----
+let current = null;  // {app, installed}
+const ver = v => String(v || "").replace(/^v/i, "");
+const size = n => n >= 1e9 ? (n / 1e9).toFixed(1) + " GB" : n >= 1e6 ? Math.round(n / 1e6) + " MB" : Math.max(1, Math.round(n / 1e3)) + " KB";
+function openDetail(app) {
+  current = app; drawDetail(); $("detail").hidden = false;
+  const o = app.offers[0];
+  if (o.source && o.id && !app.detailed) {  // the full entry has all the screenshots
+    api(`/api/sources/details?source=${encodeURIComponent(o.source)}&id=${encodeURIComponent(o.id)}`)
+      .then(full => { if (current === app) { app.offers[0] = { ...o, ...full }; app.detailed = true; drawDetail(); } }).catch(() => {});
+  }
+}
+function drawDetail() {
+  const app = current; if (!app) return;
+  const o = app.offers[0], m = installedOf(app), key = offerKey(app), job = st.jobs.get(key), data = m && st.jobs.get("data:" + m.package);
+  if (app.installed && !m) return closeDetail();  // removed
+  const shots = (o.artwork?.screenshots || []).filter(valid);
+  const top = valid(o.artwork?.banner) ? art(app.name, { banner: o.artwork.banner })
+    : shots.length ? `<div class="gallery">${shots.slice(0, 3).map(u => img(u)).join("")}</div>` : art(app.name, o.artwork || {});
+  const meta = [o.developer, o.source_name, o.version ? `v${ver(o.version)}` : m?.version ? `v${ver(m.version)}` : "", o.size ? size(o.size) : ""].filter(Boolean).join(" · ");
+  const reasons = (o.fit?.reasons || []).filter(Boolean);
+  let acts;
+  const progress = j => {
+    const pct = typeof j.percent === "number" ? Math.max(3, Math.min(100, j.percent)) : null;
+    return `<div class="progress${pct === null ? " busy" : ""}"><span>${esc(j.stage || "Downloading")}${pct === null ? "…" : ` ${Math.round(pct)}%`}</span><div class="track"><div class="fill" style="${pct === null ? "" : `width:${pct}%`}"></div></div></div>`;
+  };
+  const gameData = !(m && st.needsData.has(m.package)) ? "" : data && !data.done ? progress(data)
+    : `<button class="primary" data-act="game-data">Add game data</button><span class="meta">Open it once on the Frame first.</span>`;
+  if (job && !job.done) {
+    acts = progress(job);
+  } else if (m) {
+    acts = gameData + (m.running ? `<button data-act="stop">■ Stop</button>` : `<button class="play" data-act="launch">▶ Open</button>`)
+      + `<button class="danger" data-act="remove">Remove</button>`;
+  } else if (!o.source) {
+    acts = "";
+  } else if (o.downloadable === false) {
+    acts = `<button disabled>Get it from the developer's page</button>`;
+  } else if (o.verdict?.tone === "blocked") {
+    acts = `<button disabled>Won't run on the Frame</button>`;
+  } else {
+    acts = `<button class="primary" data-act="install">Install</button>`;
+  }
+  const blurb = o.description || o.summary || (app.installed ? "" : app.summary);  // an Installed card's summary is its version, already in meta
+  const failed = data?.error || job?.error;
+  const note = failed ? `<div class="meta" style="color:var(--bad)">${esc(failed)}</div>` : "";
+  $("sheet").innerHTML = `${top}<div class="inner">
+    <div class="top">${icon(app.name, o.artwork)}<div><h2>${esc(app.name)}</h2><div class="meta">${esc(meta)}</div></div>
+      ${o.vr ? '<span class="vr" style="margin-left:auto">VR</span>' : ""}</div>
+    ${blurb ? `<div class="text">${esc(text(blurb))}</div>` : ""}
+    ${o.verdict ? `<div class="why"><b>${esc(o.verdict.label)}</b>${reasons.length ? `<ul>${reasons.slice(0, 3).map(r => `<li>${esc(r)}</li>`).join("")}</ul>` : ""}</div>` : ""}
+    ${note}<div class="acts">${acts}<button class="close" data-act="close">Close</button></div></div>`;
+}
+function closeDetail() { current = null; $("detail").hidden = true; }
+
+async function runJob(key, start) {
+  const job = { stage: "Downloading", percent: null, done: false };
+  st.jobs.set(key, job); drawDetail(); render();
+  try {
+    const { job: id } = await start();
+    for (let misses = 0; ;) {
+      await new Promise(ok => setTimeout(ok, 1500));
+      let j;
+      try { j = await api(`/api/job?id=${encodeURIComponent(id)}`); misses = 0; }
+      catch (e) { if (++misses >= 20 || /no such job/.test(e.message)) throw e; continue; }
+      Object.assign(job, { stage: j.stage || job.stage, percent: j.percent ?? null });
+      if (!j.done) { drawDetail(); continue; }
+      if (j.error) throw new Error(j.error);
+      toast(j.message); job.result = j.result || {};
+      break;
+    }
+  } catch (e) { job.error = e.message; toast(e.message, true); }
+  finally {
+    job.done = true;
+    if (!job.error) st.jobs.delete(key);  // a failure stays, so the sheet can say why
+    await loadInstalled(); render(); drawDetail();
+  }
+  return job;
+}
+$("sheet").onclick = async e => {
+  const b = e.target.closest("[data-act]"); if (!b || !current) return;
+  const app = current, o = app.offers[0], m = installedOf(app), act = b.dataset.act, key = offerKey(app);
+  if (act === "close") return closeDetail();
+  if (act === "install") {
+    toast(`Installing ${app.name}. The first time takes a minute…`);
+    const job = await runJob(key, () => api("/api/sources/install", { source: o.source, id: o.id, version_code: o.version_code ?? null }));
+    if (job.result?.package) {
+      st.installedFrom.set(key, job.result.package);
+      if (job.result.game_data) st.needsData.add(job.result.package);
+    }
+    return render(), drawDetail();
+  }
+  if (act === "game-data" && m) {  // its own job, by package: a failed copy keeps the pending data, so it can be tried again
+    const job = await runJob("data:" + m.package, () => api("/api/sources", { action: "game-data", package: m.package }));
+    if (!job.error) st.needsData.delete(m.package);
+    return render(), drawDetail();
+  }
+  const pkg = m?.package; if (!pkg) return;
+  if (act === "remove" && b.dataset.sure !== "1") {
+    b.dataset.sure = "1"; b.textContent = "Remove it and its data?"; return;  // no confirm(): a separate window the laser has to find
+  }
+  b.disabled = true;
+  try {
+    const r = await api("/api/android", { action: act, package: pkg });
+    toast(r.message);
+    if (act === "remove") { st.needsData.delete(pkg); st.jobs.delete("data:" + pkg); }
+    if (act === "launch") closeDetail();
+  } catch (err) { toast(err.message, true); }
+  await loadInstalled(); render();
+  if (current === app) drawDetail();
+};
+$("detail").onclick = e => { if (e.target === $("detail")) closeDetail(); };
+
+// ---- Navigation ----
+$("cats").innerHTML = CATS.map(([id, label, path]) => `<button data-view="${id}" aria-pressed="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round" stroke-linecap="round" aria-hidden="true">${path}</svg>${esc(label)}</button>`).join("");
+document.addEventListener("click", e => {
+  const v = e.target.closest("[data-view]");
+  if (v && !e.target.closest("#sheet")) {
+    st.view = v.dataset.view; st.q = ""; $("q").value = "";
+    if (st.view === "installed") loadInstalled().then(() => search()); else search();
+    return;
+  }
+  if (e.target.closest("[data-feature]")) return openDetail(st.home.featured);
+  const c = e.target.closest(".card[data-i]");
+  if (c) openDetail(list()[+c.dataset.i]);
+});
+$("phone").onchange = e => { st.phone = e.target.checked; search(); };
+$("prev").onclick = () => turn(-1);
+$("next").onclick = () => turn(1);
+// The thumbstick arrives as a mouse wheel: one notch, one page.
+let wheelAt = 0;
+document.querySelector("main").addEventListener("wheel", e => {
+  e.preventDefault();
+  if (!$("detail").hidden || Date.now() - wheelAt < 350 || Math.abs(e.deltaY) < 4) return;
+  wheelAt = Date.now(); turn(e.deltaY > 0 ? 1 : -1);
+}, { passive: false });
+let qTimer;
+$("q").oninput = e => { clearTimeout(qTimer); qTimer = setTimeout(() => { st.q = e.target.value.trim(); search(); }, 250); };
+document.addEventListener("keydown", e => { if (e.key === "Escape") { closeDetail(); $("kbd").hidden = true; } });
+
+// ---- On-screen keyboard (a text field on a panel may not bring up Steam's) ----
+const ROWS = ["1234567890", "qwertyuiop", "asdfghjkl", "zxcvbnm"];
+$("kbd").innerHTML = ROWS.map(r => `<div class="row">${[...r].map(k => `<button data-k="${k}">${k}</button>`).join("")}</div>`).join("")
+  + `<div class="row"><button data-k="clear">Clear</button><button class="wide" data-k=" ">space</button><button data-k="back">⌫</button><button data-k="done" class="primary">Done</button></div>`;
+$("kbd").onclick = e => {
+  const b = e.target.closest("[data-k]"); if (!b) return;
+  const k = b.dataset.k, q = $("q");
+  if (k === "done") { $("kbd").hidden = true; return; }
+  q.value = k === "clear" ? "" : k === "back" ? q.value.slice(0, -1) : q.value + k;
+  q.dispatchEvent(new Event("input"));
+};
+$("kbdBtn").onclick = () => $("kbd").hidden = !$("kbd").hidden;
+
+loadInstalled().then(() => search());
+</script>
+</body>
+</html>